jRay/Jellyfin.Plugin.JRay/Controllers/ActorsController.cs

using System;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Plugin.JRay.Models;
using Jellyfin.Plugin.JRay.Services;
using Jellyfin.Plugin.JRay.Services.Interfaces;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace Jellyfin.Plugin.JRay.Controllers;

/// <summary>
/// Exposes scene-actor-extraction "truth" data: which actors are present in
/// the scene at a given timestamp.
/// </summary>
/// <remarks>
/// Presence is <b>scene-scoped</b>, not instantaneous: a window is a claim about
/// scene membership, not a recognition event, so an actor who is off-camera
/// during a reverse shot is still present. Windows are served exactly as stored
/// — never merged, split or trimmed.
/// </remarks>
[ApiController]
[Route("Plugins/JRay/Items/{itemId}")]
[Authorize]
// TRACES: JR-004, JR-005, JR-010, JR-012, JR-013, JR-014 | SR-002
public class ActorsController : ControllerBase
{
    private readonly ITruthDataService _truthDataService;

    /// <summary>
    /// Initializes a new instance of the <see cref="ActorsController"/> class.
    /// </summary>
    /// <param name="truthDataService">The truth data service.</param>
    public ActorsController(ITruthDataService truthDataService)
    {
        _truthDataService = truthDataService;
    }

    /// <summary>
    /// Gets the full actor timeline (every actor with their scene-presence windows) for a movie.
    /// </summary>
    /// <param name="itemId">The Jellyfin item id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The truth file contents, or 404 if no truth data exists for this item.</returns>
    [HttpGet("Timeline")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<ActionResult<TruthFile>> GetTimeline(Guid itemId, CancellationToken cancellationToken)
    {
        var truth = await _truthDataService.GetTruthAsync(itemId, cancellationToken).ConfigureAwait(false);
        if (truth is null)
        {
            return NotFound();
        }

        return Ok(truth);
    }

    /// <summary>
    /// Gets how this item's truth data was obtained.
    /// </summary>
    /// <remarks>
    /// Separate from <c>Timeline</c> on purpose: provenance is metadata *about*
    /// the claim, and folding it into the truth file would mean the bytes served
    /// back are not the bytes the producer wrote (JR-004).
    /// </remarks>
    /// <param name="itemId">The Jellyfin item id.</param>
    /// <returns>The provenance, or 404 if no truth data exists for this item.</returns>
    [HttpGet("Provenance")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public ActionResult<TruthProvenance> GetProvenance(Guid itemId)
    {
        var provenance = _truthDataService.GetProvenance(itemId);
        return provenance is null ? NotFound() : Ok(provenance);
    }

    /// <summary>
    /// Gets the JRay context (currently: the actors in the scene) at a given timestamp.
    /// This is an extensible envelope — future fields (locations, trivia, etc.)
    /// will be added here without changing the route.
    /// </summary>
    /// <param name="itemId">The Jellyfin item id.</param>
    /// <param name="t">The timestamp, in seconds from the start of the movie.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The JRay context at <paramref name="t"/>, or 404 if no truth data exists for this item.</returns>
    [HttpGet("jray")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<ActionResult<JRayContext>> GetContext(Guid itemId, [FromQuery] double t, CancellationToken cancellationToken)
    {
        var truth = await _truthDataService.GetTruthAsync(itemId, cancellationToken).ConfigureAwait(false);
        if (truth is null)
        {
            return NotFound();
        }

        var context = new JRayContext();
        foreach (var actor in PresenceLookup.ActorsPresentAt(truth, t))
        {
            context.Actors.Add(new ActorInScene
            {
                Name = actor.Name,
                ImdbId = actor.ImdbId,
                TmdbId = actor.TmdbId,
                JellyfinId = actor.JellyfinId
            });
        }

        return Ok(context);
    }
}