feat: add Trailer Pre-Roll and Feature Pre-Roll bumpers
All checks were successful
Publish Release / release (push) Successful in 14s
All checks were successful
Publish Release / release (push) Successful in 14s
Adds two optional IIntroProvider bumper slots, mirroring CherryFloors' cinema mode plugin: a "Trailer Pre-Roll" played before the trailer block and a "Feature Pre-Roll" played right before the movie/episode. Each is configured by picking an existing Jellyfin Movie library, from which a random Movie is injected as the bumper. Bump version to 1.0.0.5. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Martin
80
README.md
80
README.md
@@ -1,30 +1,70 @@
|
||||
# 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.
|
||||
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
|
||||
|
||||
1. A daily scheduled task fetches candidate movies from TMDB (Now Playing, Upcoming, Popular,
|
||||
Top Rated — configurable), optionally skipping movies already in your library.
|
||||
### 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}/
|
||||
{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)
|
||||
{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 movie's
|
||||
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+
|
||||
@@ -58,15 +98,24 @@ Go to **Admin → Plugins → CinemaTrailers4Jellyfins**.
|
||||
|---|---|
|
||||
| **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 |
|
||||
| **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 trailers per run** | How many trailers to download per task run |
|
||||
| **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 already in my Jellyfin library** | Don't download trailers for movies you already own |
|
||||
| **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
|
||||
@@ -75,7 +124,8 @@ After configuring, go to **Admin → Scheduled Tasks → CinemaTrailers4Jellyfin
|
||||
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.
|
||||
library scan) so your Cinema Mode / trailer pre-roll plugin (or this plugin's own
|
||||
`IIntroProvider`) can use the trailers.
|
||||
|
||||
## Building from source
|
||||
|
||||
|
||||
Reference in New Issue
Block a user