CinemaTrailers4Jellyfins/README.md

# 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](https://www.themoviedb.org/settings/api)
- `ffmpeg` available on the system PATH (used to generate the placeholder video once)
- *(Optional)* [yt-dlp](https://github.com/yt-dlp/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

```sh
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