jRay/Jellyfin.Plugin.JRay/Configuration/PluginConfiguration.cs

using System.Collections.ObjectModel;
using MediaBrowser.Model.Plugins;

namespace Jellyfin.Plugin.JRay.Configuration;

/// <summary>
/// Plugin configuration.
/// </summary>
/// <remarks>
/// Every manifest-exchange switch here defaults to <b>off</b>, including the
/// pre-configured community server, so no traffic leaves an installation until
/// an admin acts. Fetching and contributing each reveal to a server operator
/// that some instance holds a given title; that is inherent to the exchange, so
/// the defaults bound the exposure rather than pretending to remove it.
/// </remarks>
// TRACES: JR-036, JR-038 | PR-005
public class PluginConfiguration : BasePluginConfiguration
{
    /// <summary>
    /// The community manifest exchange. Shipped pre-configured but
    /// <b>disabled</b>, so no traffic leaves an installation until an admin opts
    /// in (public server specification, §9).
    /// </summary>
    public const string CommunityServerUrl = "https://jray.tourolle.paris";

    /// <summary>
    /// Display name for <see cref="CommunityServerUrl"/>.
    /// </summary>
    public const string CommunityServerName = "JRay Community";

    /// <summary>
    /// Initializes a new instance of the <see cref="PluginConfiguration"/> class.
    /// </summary>
    public PluginConfiguration()
    {
        TruthFileSuffix = ".jray.json";
        CacheDurationMinutes = 60;
        EnableOverlay = true;

        // Manifest sharing is a network egress feature, so every part of it is
        // off by default (public server specification, §9 "Configuration").
        EnableManifestSharing = false;
        ContributeManifests = false;
        ComputeAudioSignatures = false;
        MinimumMatchTier = MatchTier.Runtime;

        // Pre-configured but disabled: the admin opts in by enabling it, rather
        // than by having to discover and type a URL.
        Servers.Add(new ManifestServer
        {
            Url = CommunityServerUrl,
            Name = CommunityServerName,
            Enabled = false,
            AllowContribute = false,
            TrustLevel = ServerTrustLevel.FetchOnly,
        });
    }

    /// <summary>
    /// Gets or sets the filename suffix used to find a scene-actor-extraction
    /// "truth" file for a media item. The plugin looks for a file named
    /// "&lt;media file basename&gt;&lt;TruthFileSuffix&gt;" next to the media file,
    /// e.g. "Movie.mkv" -&gt; "Movie.jray.json".
    /// </summary>
    public string TruthFileSuffix { get; set; }

    /// <summary>
    /// Gets or sets how long (in minutes) a loaded truth file is cached in
    /// memory before being re-read from disk.
    /// </summary>
    public int CacheDurationMinutes { get; set; }

    /// <summary>
    /// Gets or sets a value indicating whether JRay should inject its
    /// pause-overlay script into the web client's index.html. When disabled,
    /// any previously injected script is removed.
    /// </summary>
    public bool EnableOverlay { get; set; }

    /// <summary>
    /// Gets or sets a value indicating whether JRay may fetch actor-timeline
    /// manifests from the configured servers. Off by default — this is a network
    /// egress feature and must be opt-in.
    /// </summary>
    /// <remarks>
    /// Fetching reveals to a server operator that some instance holds a given
    /// title. That is inherent to the exchange, and each configured server
    /// multiplies the exposure, which the configuration page states plainly.
    /// </remarks>
    public bool EnableManifestSharing { get; set; }

    /// <summary>
    /// Gets or sets a value indicating whether locally generated manifests may be
    /// contributed back. A separate opt-in from downloading, and off by default.
    /// </summary>
    /// <remarks>
    /// Contribution additionally requires <see cref="ManifestServer.AllowContribute"/>
    /// on the specific server and a token for it. Uploads are never fanned out to
    /// every configured server.
    /// </remarks>
    public bool ContributeManifests { get; set; }

    /// <summary>
    /// Gets or sets the minimum cut-match tier a fetched manifest must reach
    /// before it is stored.
    /// </summary>
    /// <remarks>
    /// Defaults to <see cref="MatchTier.Runtime"/>. <see cref="MatchTier.Loose"/>
    /// admits manifests whose runtime differs by up to 30s, which may be a
    /// different trim of the same cut — usable, but it should be surfaced as a
    /// caveat rather than applied silently.
    /// </remarks>
    public MatchTier MinimumMatchTier { get; set; }

    /// <summary>
    /// Gets or sets a value indicating whether the plugin computes audio
    /// signatures for library items, enabling content-based cut matching and
    /// identification of files whose providence is unknown.
    /// </summary>
    /// <remarks>
    /// Off by default. Uses the FFmpeg binary Jellyfin already ships (via
    /// <c>IMediaEncoder.EncoderPath</c>), so there is no extra dependency, but it
    /// costs roughly a second or two of I/O per item and is therefore opt-in.
    /// </remarks>
    public bool ComputeAudioSignatures { get; set; }

    /// <summary>
    /// Gets the ordered list of manifest servers.
    /// </summary>
    /// <remarks>
    /// Order is the user's trust ranking: for a fetch, servers are tried in order
    /// and the first result clearing <see cref="MinimumMatchTier"/> wins. For a
    /// series, first-match applies per <i>episode</i>, so a later server is
    /// queried only for the episodes earlier ones lacked.
    /// </remarks>
    public Collection<ManifestServer> Servers { get; } = new();
}