jRay/Jellyfin.Plugin.JRay/Services/ManifestConverter.cs

using System;
using System.Globalization;
using Jellyfin.Plugin.JRay.Configuration;
using Jellyfin.Plugin.JRay.Models;

namespace Jellyfin.Plugin.JRay.Services;

/// <summary>
/// Converts a fetched manifest into the truth file the plugin stores.
/// </summary>
// TRACES: JR-030 | SR-002, SR-003
public static class ManifestConverter
{
    /// <summary>
    /// Builds a truth file from a manifest, shifting every window by
    /// <paramref name="offsetSec"/>.
    /// </summary>
    /// <remarks>
    /// <b>The offset is applied here, once, at store time.</b> The server returns
    /// it and the client applies it, so a single stored manifest serves every
    /// trim of the same cut without ever being rewritten upstream. Applying it on
    /// the way in means the stored truth is always in the local file's own
    /// timebase, so the overlay and the <c>jray?t=</c> query need no offset
    /// awareness at read time — the alternative would put the same correction in
    /// every reader, forever, and one of them would eventually forget.
    /// <para>
    /// Windows are shifted, never reshaped: a window is a claim about scene
    /// membership (SR-002), so merging or trimming would answer a different
    /// question than the one the extraction pipeline answered.
    /// </para>
    /// </remarks>
    /// <param name="manifest">The validated manifest.</param>
    /// <param name="offsetSec">Seconds to add to every window.</param>
    /// <param name="mediaPath">Local media path, recorded informationally.</param>
    /// <returns>The truth file to store.</returns>
    public static TruthFile ToTruthFile(Jmanifest manifest, double offsetSec, string mediaPath)
    {
        ArgumentNullException.ThrowIfNull(manifest);

        var truth = new TruthFile
        {
            SchemaVersion = TruthSchema.SupportedVersion,
            Movie = mediaPath ?? string.Empty,
        };

        // Provenance is carried across rather than flattened. The two blocks
        // have the same shape by design (JR-002), so anything the server knew
        // about how a manifest was produced survives into the stored truth.
        if (manifest.Extraction is { } extraction)
        {
            truth.Extraction = new TruthExtraction
            {
                SampleFps = extraction.SampleFps,
                ExtinctionSec = extraction.ExtinctionSec,
                PipelineVersion = extraction.PipelineVersion,
                GallerySize = extraction.GallerySize,
                GalleryScope = extraction.GalleryScope,
            };
        }

        // The cut is the *manifest's*, not the local file's: it records the
        // encode the timings were measured against, which is what makes the
        // applied offset interpretable later. Recording the local runtime here
        // instead would erase the very discrepancy the offset corrects.
        if (manifest.Cut is { } cut)
        {
            truth.Cut = new TruthCut
            {
                RuntimeSec = cut.RuntimeSec,
                AudioSignature = cut.AudioSignature,
            };
        }

        foreach (var actor in manifest.Actors)
        {
            var converted = new TruthActor
            {
                Name = actor.Name ?? string.Empty,
                ImdbId = actor.ImdbId ?? string.Empty,
                TmdbId = actor.TmdbId ?? string.Empty,
            };

            foreach (var scene in actor.Scenes)
            {
                // Clamped at zero: a negative offset on an early window would
                // otherwise produce a start before the file begins, which no
                // reader can index.
                var start = Math.Max(0, scene.Start + offsetSec);
                var end = Math.Max(start, scene.End + offsetSec);
                converted.Scenes.Add(new TruthScene
                {
                    Start = start,
                    End = end,

                    // Belief and route survive the conversion. They are what a
                    // consumer needs to know how far to trust a window, and
                    // dropping them here would silently downgrade every fetched
                    // manifest against a locally extracted one.
                    Belief = scene.Belief,
                    Route = scene.Route,
                });
            }

            truth.Actors.Add(converted);
        }

        return truth;
    }

    /// <summary>
    /// A short, human-readable description of how a manifest matched, for the
    /// UI to show as a caveat.
    /// </summary>
    /// <remarks>
    /// A <c>loose</c> match should surface as a caveat rather than being applied
    /// silently: it means the runtimes differ by up to 30 seconds, which is
    /// usually a different trim of the same cut but is not guaranteed to be.
    /// </remarks>
    /// <param name="tier">The tier achieved.</param>
    /// <param name="offsetSec">The offset applied.</param>
    /// <returns>A caveat string, or null when the match needs no explanation.</returns>
    public static string? DescribeCaveat(MatchTier tier, double offsetSec)
    {
        if (tier == MatchTier.Loose)
        {
            return "Matched loosely — the runtime differs from this server's copy, so timings may drift.";
        }

        if (Math.Abs(offsetSec) > 0.001)
        {
            return string.Create(
                CultureInfo.InvariantCulture,
                $"Matched by audio content and shifted by {offsetSec:0.##}s to align with this file.");
        }

        return null;
    }
}