CinemaTrailers4Jellyfins

A Jellyfin plugin that automatically downloads movie and TV show trailers from TMDB/YouTube and packages each one as a self-contained "fake movie" folder, ready to be picked up by a Cinema Mode / trailer pre-roll plugin. It can also act as a Cinema Mode pre-roll source itself, via Jellyfin's IIntroProvider interface (compatible with Wholphin and similar clients).

How it works

Downloading trailers

1. A daily scheduled task fetches candidate movies and/or TV shows from TMDB (Now Playing, Upcoming, Popular, Top Rated for movies; Airing Today, On The Air, Popular, Top Rated for TV shows — all configurable), optionally skipping titles already in your library.
2. For each candidate, it fetches the official trailer(s) from TMDB, which point to YouTube.
3. It downloads the trailer video and builds a folder for it:

   {OutputFolder}/
     {Title} ({Year})/
       {Title} ({Year}).mp4          ← placeholder "fake movie" (copy of a master file)
       {Title} ({Year})-trailer.mp4  ← the actual downloaded trailer
       {Title} ({Year}).nfo          ← minimal NFO (title, year, genres, rating, locked metadata)
   

   TV show trailers are tagged (<tag>ct4j-tvshow</tag>) in their NFO so they can be told apart from movie trailers.
4. Jellyfin scans the placeholder file as a normal movie (its metadata locked via the NFO so it never queries TMDB for it) and picks up the adjacent -trailer.mp4 as that item's local trailer — which a Cinema Mode / trailer pre-roll plugin can then play.

The placeholder "fake movie" is a few seconds of black video with silent audio — just enough for Jellyfin to treat the file as a valid video. It's generated once via ffmpeg and reused by copying, not regenerated for every trailer.

Movie and TV show downloads each have their own TMDB sources and their own "max trailers per run" setting — set either to 0 to skip that category entirely.

Playing trailers (Cinema Mode integration)

The plugin also registers as an IIntroProvider, so Jellyfin clients with cinema mode support (and clients like Wholphin) can play the downloaded trailers as pre-rolls directly, without a separate trailer plugin:

• Before a movie, it injects movie trailers from the output folder.
• Before a TV episode (if enabled), it injects TV show trailers — but only before the first episode a user watches each day. If you binge several episodes in one sitting, only the first one gets trailers; the next day it resets.
• Movie and TV trailers are kept in separate pools, so movies only ever get movie trailers and episodes only ever get TV show trailers.
• Optional filters can restrict trailers to those matching the genre and/or age rating of the movie/show you're about to watch (falling back to the full pool if nothing matches), and an "avoid repeats" mode cycles through all trailers before repeating any.

The output folder still needs to be added as a Jellyfin Movies library and scanned for any of this to work, since that's how Jellyfin discovers the trailer files in the first place.

Pre-roll bumpers

Optionally, you can also bookend the trailer block with bumper videos picked at random from your own existing Jellyfin Movies libraries:

• Trailer Pre-Roll: plays before the trailer block (e.g. a "Now Playing" bumper).
• Feature Pre-Roll: plays after the trailer block, right before the movie/episode itself (e.g. a "Feature Presentation" bumper).

Each is independent, disabled by default, and picks a plain random Movie item from the configured library every time (no genre/rating filtering or repeat-avoidance).

Requirements

• Jellyfin 10.11+
• A free TMDB API key
• ffmpeg available on the system PATH (used to generate the placeholder video once)
• (Optional) yt-dlp for higher quality (1080p+) trailer downloads

Installation

Via Jellyfin Plugin Catalogue

1. In your Jellyfin dashboard go to Admin → Plugins → Repositories.
2. Add a new repository with this URL:

   https://www.git.quarantinedstudio.com/mvezina/CinemaTrailers4Jellyfins/raw/branch/main/manifest.json
   

3. Go to Catalog, find CinemaTrailers4Jellyfins under General, and click Install.
4. Restart Jellyfin.

Manual

1. Download the latest Jellyfin.Plugin.CinemaTrailers4Jellyfins.dll (and dependencies) from Releases.
2. Copy them to your Jellyfin plugins/ directory.
3. Restart Jellyfin.

Configuration

Go to Admin → Plugins → CinemaTrailers4Jellyfins.

Setting	Description
TMDB API Key	Your TMDB Read Access Token (JWT) or v3 API key
Trailer Languages	Restrict downloads to specific trailer languages
Movie Trailer Sources	Which TMDB lists to pull movie candidates from (Now Playing, Upcoming, Popular, Top Rated)
TV Show Trailer Sources	Which TMDB lists to pull TV show candidates from (Airing Today, On The Air, Popular, Top Rated)
Date Range	Only consider titles released (or first-aired) within the last N months
Output Folder	Where the fake-movie folders are created
Max movie trailers per run	How many movie trailers to download per task run. 0 = don't download movie trailers
Max TV show trailers per run	How many TV show trailers to download per task run. 0 = don't download TV show trailers
Pages per source	How many TMDB pages to fetch per source
Video quality	720p / 480p (built-in) or 1080p (requires yt-dlp)
Skip movies/shows already in my Jellyfin library	Don't download trailers for movies/shows you already own
Skip trailers already downloaded	Don't re-download a trailer if its folder already exists
Max trailers to keep	Oldest trailer folders are deleted first once this cap is exceeded
Trailers per movie	How many trailers to play before each item via Cinema Mode (IIntroProvider). 0 = disabled
Match genre to the movie being played	Only pick trailers whose genre overlaps with what you're about to watch
Limit to same age rating or lower	Never play a trailer rated higher than what you're about to watch
Avoid repeating trailers	Cycle through all available trailers before repeating any
Also play trailers before TV episodes	Plays before only the first episode a user watches each day
Trailer Pre-Roll library	Movie library to pick a random "Now Playing" style bumper from, played before the trailer block. None = disabled
Feature Pre-Roll library	Movie library to pick a random "Feature Presentation" style bumper from, played after the trailer block. None = disabled
yt-dlp path	Optional path to yt-dlp for 1080p+ downloads

Running the task

After configuring, go to Admin → Scheduled Tasks → CinemaTrailers4Jellyfins and click Run to do an immediate download pass. The task then runs automatically once per day.

After the task completes, add the output folder as a Jellyfin Movies library (and run a library scan) so your Cinema Mode / trailer pre-roll plugin (or this plugin's own IIntroProvider) can use the trailers.

Building from source

git clone https://www.git.quarantinedstudio.com/mvezina/CinemaTrailers4Jellyfins
cd CinemaTrailers4Jellyfins
dotnet publish --configuration Release --output bin

Place Jellyfin.Plugin.CinemaTrailers4Jellyfins.dll and its dependencies in your Jellyfin plugins/ directory.

Licence

MIT