feat: add genre, rating, and avoid-repeats trailer filters

Trailer selection now supports three optional filters:
- Genre match: prefer trailers whose fake-movie genre overlaps with the
  feature being played (requires TMDB genres in NFO)
- Age rating ceiling: exclude trailers rated higher than the feature
  (requires TMDB certification in NFO)
- Avoid repeats: cycle through all trailers before replaying any;
  resets per-user once the pool is exhausted

Genre and certification are fetched from TMDB at download time via a
single /movie/{id}?append_to_response=release_dates call and written
into the fake-movie NFO as <genre> and <mpaa> tags. All filters fall
back to the full unfiltered pool when no match is found.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Jellyfin.Plugin.CinemaTrailers4Jellyfins/Services/FakeMovieService.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Diagnostics;
 using System.IO;
 using System.Threading;
@@ -55,7 +56,7 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
         /// Writes a minimal Jellyfin/Kodi-compatible movie NFO with <lockdata>true</lockdata>
         /// so Jellyfin never tries to refresh metadata for the fake entry from TMDB.
         /// </summary>
-        public void WriteNfo(string nfoPath, string title, int? year)
+        public void WriteNfo(string nfoPath, string title, int? year, IReadOnlyList<string>? genres = null, string? mpaa = null)
         {
             var settings = new XmlWriterSettings { Indent = true };
             using var writer = XmlWriter.Create(nfoPath, settings);
@@ -64,6 +65,11 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
             writer.WriteElementString("title", title);
             if (year.HasValue)
                 writer.WriteElementString("year", year.Value.ToString());
+            if (genres != null)
+                foreach (var genre in genres)
+                    writer.WriteElementString("genre", genre);
+            if (!string.IsNullOrWhiteSpace(mpaa))
+                writer.WriteElementString("mpaa", mpaa);
             writer.WriteElementString("lockdata", "true");
             writer.WriteEndElement();
             writer.WriteEndDocument();

Jellyfin.Plugin.CinemaTrailers4Jellyfins/Services/TmdbService.cs

@@ -19,6 +19,8 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
         public int? Year => DateTime.TryParse(ReleaseDate, out var d) ? d.Year : (int?)null;
     }
 
+    public record TmdbMovieMetadata(IReadOnlyList<string> Genres, string? Certification);
+
     public class TmdbService : IDisposable
     {
         private readonly HttpClient _httpClient;
@@ -187,6 +189,77 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
             return null;
         }
 
+        /// <summary>
+        /// Returns the genre names and US theatrical certification (G, PG, PG-13, R, NC-17)
+        /// for a movie. Uses a single /movie/{id}?append_to_response=release_dates call.
+        /// </summary>
+        public async Task<TmdbMovieMetadata> GetMovieMetadataAsync(
+            string tmdbId,
+            string apiKey,
+            CancellationToken ct)
+        {
+            try
+            {
+                var url = $"{BaseUrl}/movie/{tmdbId}?append_to_response=release_dates&language=en-US";
+                using var request = new HttpRequestMessage(HttpMethod.Get, url);
+                ApplyAuth(request, apiKey);
+                using var response = await _httpClient.SendAsync(request, ct).ConfigureAwait(false);
+                response.EnsureSuccessStatusCode();
+                var json = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
+                using var doc = JsonDocument.Parse(json);
+
+                var genres = new List<string>();
+                if (doc.RootElement.TryGetProperty("genres", out var genreArr))
+                {
+                    foreach (var g in genreArr.EnumerateArray())
+                    {
+                        if (g.TryGetProperty("name", out var name))
+                        {
+                            var genreName = name.GetString();
+                            if (!string.IsNullOrEmpty(genreName))
+                                genres.Add(genreName);
+                        }
+                    }
+                }
+
+                string? certification = null;
+                if (doc.RootElement.TryGetProperty("release_dates", out var releaseDates)
+                    && releaseDates.TryGetProperty("results", out var rdResults))
+                {
+                    foreach (var country in rdResults.EnumerateArray())
+                    {
+                        if (!country.TryGetProperty("iso_3166_1", out var iso)
+                            || !string.Equals(iso.GetString(), "US", StringComparison.OrdinalIgnoreCase))
+                            continue;
+
+                        if (!country.TryGetProperty("release_dates", out var dates))
+                            break;
+
+                        foreach (var date in dates.EnumerateArray())
+                        {
+                            if (!date.TryGetProperty("certification", out var cert))
+                                continue;
+                            var certStr = cert.GetString();
+                            if (!string.IsNullOrWhiteSpace(certStr))
+                            {
+                                certification = certStr;
+                                break;
+                            }
+                        }
+                        break;
+                    }
+                }
+
+                return new TmdbMovieMetadata(genres.AsReadOnly(), certification);
+            }
+            catch (OperationCanceledException) { throw; }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "|CinemaTrailers4Jellyfins| GetMovieMetadata failed for TMDB ID {Id}", tmdbId);
+                return new TmdbMovieMetadata(Array.Empty<string>(), null);
+            }
+        }
+
         public async Task<List<TmdbVideo>> GetTrailersAsync(
             string tmdbId,
             string apiKey,

Jellyfin.Plugin.CinemaTrailers4Jellyfins/Services/TrailerIntroProvider.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
@@ -15,6 +16,12 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
     public class TrailerIntroProvider : IIntroProvider
     {
         private static readonly Random _rng = new();
+
+        // Per-user set of trailer IDs already shown in the current cycle.
+        // Resets automatically once every trailer in the active pool has been seen.
+        private static readonly ConcurrentDictionary<Guid, HashSet<Guid>> _seenByUser = new();
+        private static readonly object _seenLock = new();
+
         private readonly ILibraryManager _libraryManager;
         private readonly ILogger<TrailerIntroProvider> _logger;
 
@@ -40,15 +47,13 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
             if (string.IsNullOrEmpty(outputFolder))
                 return Task.FromResult(Enumerable.Empty<IntroInfo>());
 
-            // Break potential recursion: don't inject intros before items that live inside
-            // our output folder. This covers both the fake-movie files and their trailer
-            // extras, so Wholphin can't trigger a getIntros loop on the intro item itself.
+            // Break recursion: don't inject intros before items from our own output folder
+            // (covers both the fake-movie files and their trailer extras).
             if (item.Path?.StartsWith(outputFolder, StringComparison.OrdinalIgnoreCase) == true)
                 return Task.FromResult(Enumerable.Empty<IntroInfo>());
 
-            // Server-scoped query (no User parameter) so library visibility settings don't
-            // prevent trailer discovery even when the output library is hidden from users.
-            var fakeMovies = _libraryManager
+            // Server-scoped query so hidden libraries don't block trailer discovery.
+            var pairs = _libraryManager
                 .GetItemList(new InternalItemsQuery
                 {
                     IncludeItemTypes = new[] { BaseItemKind.Movie },
@@ -58,28 +63,100 @@ namespace Jellyfin.Plugin.CinemaTrailers4Jellyfins.Services
                 .Where(m =>
                     m.Path?.StartsWith(outputFolder, StringComparison.OrdinalIgnoreCase) == true
                     && m.LocalTrailers.Count > 0)
+                .SelectMany(m => m.LocalTrailers.Select(t => (Movie: m, Trailer: t)))
                 .ToList();
 
-            if (fakeMovies.Count == 0)
+            if (pairs.Count == 0)
             {
                 _logger.LogDebug(
-                    "|CinemaTrailers4Jellyfins| No indexed trailers found in {Folder}. "
+                    "|CinemaTrailers4Jellyfins| No indexed trailers in {Folder}. "
                     + "Ensure the output folder is added as a Jellyfin Movies library and scanned.",
                     outputFolder);
                 return Task.FromResult(Enumerable.Empty<IntroInfo>());
             }
 
-            var selected = fakeMovies
+            // Apply enabled filters. If nothing survives, fall back to the full pool.
+            var filtered = ApplyFilters(pairs, item, config);
+            var pool = filtered.Count > 0 ? filtered : pairs;
+
+            // Prefer unseen trailers within the pool; reset the cycle when all have been shown.
+            pool = ApplyAvoidRepeats(pool, user.Id, config.AvoidRepeats);
+
+            var selected = pool
                 .OrderBy(_ => _rng.Next())
                 .Take(config.TrailersPerMovie)
-                .Select(m =>
-                {
-                    var t = m.LocalTrailers.ElementAt(_rng.Next(m.LocalTrailers.Count));
-                    return new IntroInfo { ItemId = t.Id, Path = t.Path };
-                })
                 .ToList();
 
-            return Task.FromResult<IEnumerable<IntroInfo>>(selected);
+            if (config.AvoidRepeats)
+                MarkSeen(user.Id, selected.Select(p => p.Trailer.Id));
+
+            var intros = selected.Select(p => new IntroInfo { ItemId = p.Trailer.Id, Path = p.Trailer.Path });
+            return Task.FromResult<IEnumerable<IntroInfo>>(intros.ToList());
+        }
+
+        private static List<(Movie Movie, BaseItem Trailer)> ApplyFilters(
+            List<(Movie Movie, BaseItem Trailer)> pairs,
+            BaseItem feature,
+            Configuration.PluginConfiguration config)
+        {
+            var result = pairs;
+
+            if (config.FilterByGenre && feature.Genres.Length > 0)
+            {
+                var featureGenres = new HashSet<string>(feature.Genres, StringComparer.OrdinalIgnoreCase);
+                result = result
+                    .Where(p => p.Movie.Genres.Any(g => featureGenres.Contains(g)))
+                    .ToList();
+            }
+
+            if (config.FilterByRating)
+            {
+                result = result
+                    .Where(p =>
+                        // Unrated trailer: no restriction — include it.
+                        p.Movie.InheritedParentalRatingValue == null
+                        // Unrated feature: can't determine a ceiling — include everything.
+                        || feature.InheritedParentalRatingValue == null
+                        // Trailer rating must be at most the feature's rating.
+                        || p.Movie.InheritedParentalRatingValue <= feature.InheritedParentalRatingValue)
+                    .ToList();
+            }
+
+            return result;
+        }
+
+        private static List<(Movie Movie, BaseItem Trailer)> ApplyAvoidRepeats(
+            List<(Movie Movie, BaseItem Trailer)> pool,
+            Guid userId,
+            bool enabled)
+        {
+            if (!enabled)
+                return pool;
+
+            lock (_seenLock)
+            {
+                var seen = _seenByUser.GetOrAdd(userId, _ => new HashSet<Guid>());
+                var unseen = pool.Where(p => !seen.Contains(p.Trailer.Id)).ToList();
+
+                if (unseen.Count > 0)
+                    return unseen;
+
+                // All trailers in this pool have been seen — reset the cycle.
+                foreach (var p in pool)
+                    seen.Remove(p.Trailer.Id);
+
+                return pool.ToList();
+            }
+        }
+
+        private static void MarkSeen(Guid userId, IEnumerable<Guid> trailerIds)
+        {
+            lock (_seenLock)
+            {
+                var seen = _seenByUser.GetOrAdd(userId, _ => new HashSet<Guid>());
+                foreach (var id in trailerIds)
+                    seen.Add(id);
+            }
         }
     }
 }