# CinemaTrailers4Jellyfins

A Jellyfin plugin that automatically downloads movie 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.

## How it works

1. A daily scheduled task fetches candidate movies from TMDB (Now Playing, Upcoming, Popular,
   Top Rated — configurable), optionally skipping movies 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}/
     {Movie Title} ({Year})/
       {Movie Title} ({Year}).mp4          ← placeholder "fake movie" (copy of a master file)
       {Movie Title} ({Year})-trailer.mp4  ← the actual downloaded trailer
       {Movie Title} ({Year}).nfo          ← minimal NFO (title, year, locked metadata)
   ```
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 movie'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.

## 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 |
| **Trailer Sources** | Which TMDB lists to pull candidates from (Now Playing, Upcoming, Popular, Top Rated) |
| **Date Range** | Only consider movies released within the last N months |
| **Output Folder** | Where the fake-movie folders are created |
| **Max trailers per run** | How many trailers to download per task run |
| **Pages per source** | How many TMDB pages to fetch per source |
| **Video quality** | 720p / 480p (built-in) or 1080p (requires yt-dlp) |
| **Skip movies already in my Jellyfin library** | Don't download trailers for movies 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 |
| **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 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