# NeX-Up - Trailer Integration Guide

NeX-Up brings the authentic movie theater "Coming Soon" experience to your Plex server. Automatically download trailers for upcoming movies and TV shows from Radarr and Sonarr, generate custom intro videos and Coming Soon lists, and build professional sequences that play before your content.

## Overview

NeX-Up combines five powerful features:

1. **Radarr & Sonarr Integration** — Automatically discovers and downloads trailers for upcoming releases
2. **Coming Soon List Generator** — Creates dynamic video prerolls showcasing upcoming content with poster grids or text lists
3. **Dynamic Preroll Generator** — Creates custom "Coming Soon to [Your Server]" intro videos
4. **Sequence Builder Presets** — Quick templates for assembling trailers and intros
5. **Smart Cleanup** — Automatically removes trailers when content is released

## Getting Started

### Step 1: Navigate to NeX-Up

Click **NeX-Up** in the main navigation menu. You'll see four tabs:
- **Connections** — Configure Radarr and Sonarr
- **Your Trailers** — Manage downloaded trailers
- **Settings** — YouTube cookies, storage, TMDB, and Coming Soon List settings
- **Generator** — Create dynamic intros, Coming Soon lists, and sequences

### Step 2: Connect Radarr

1. Go to the **Connections** tab
2. In the Radarr section, enter:
   - **Radarr URL**: Your Radarr server address (e.g., `http://localhost:7878` or `http://192.168.1.100:7878`)
   - **API Key**: Found in Radarr → Settings → General → API Key
3. Click **Connect**
4. If successful, you'll see a green checkmark

### Step 3: Connect Sonarr (Optional)

1. In the Sonarr section, enter:
   - **Sonarr URL**: Your Sonarr server address (e.g., `http://localhost:8989`)
   - **API Key**: Found in Sonarr → Settings → General → API Key
2. Click **Connect**

### Step 4: Configure Settings

Go to the **Settings** tab to configure:

| Setting | Description | Recommended |
|---------|-------------|-------------|
| **Storage Path** | Where trailers are saved (use the Browse button to select) | Default is fine |
| **Days Ahead** | How far in the future to look for releases | 30-90 days |
| **Max Trailers** | Maximum number of trailers to keep | 10-20 |
| **Max Trailer Duration** | Sync skips trailers longer than this. Most trailers run 2 to 3 minutes, so 1.5 minutes skips nearly all of them. The download button on the Upcoming tab ignores this limit | 3 minutes or No limit |
| **Quality** | Download quality (720p, 1080p, 4K) | 1080p |
| **Trailer language** | Download movie trailers in this language when TMDB has one: French, German, Spanish, Italian, Portuguese, Dutch and others, with regional versions such as French (Canada) and Spanish (Latin America). Applies to NeX-Up and Library Trailers; TV trailers stay English. See [Trailer languages](#trailer-languages) | English |
| **When there is none in that language** | Shown for languages other than English. **Use the English trailer**, or **Skip the movie for now** (checked again on every sync) | Use the English trailer |
| **Auto-Cleanup** | Remove trailers after content releases and lands in your library | Enabled |
| **Release Date to Use** | Which date a trailer follows: **Digital First** (default), **Digital Only** (skip movies with no digital date), **Physical First**, or **Theatrical**. Retention is measured from this date, so a trailer is never removed before the movie is out | Digital First |
| **Include Unmonitored** | Include unmonitored content from Radarr/Sonarr | Disabled |


### Trailer languages

Radarr's trailer link is the English trailer. With a **Trailer language** set, NeX-Up asks TMDB for that movie's trailers in the language and downloads one of those first:

1. A trailer in the language and region you chose (French (Canada) prefers trailers TMDB lists for Canada).
2. A trailer in the same language from another region.
3. Otherwise, Radarr's English trailer and the other English sources, unless the fallback is **Skip the movie for now**. Skipped movies show in the sync summary and are checked again on the next sync, so they pick up a localized trailer once TMDB lists one.

> **You need your own TMDB API key for this.** TMDB no longer accepts the key built into NeXroll. A key is free: create a TMDB account, request one under Settings → API, and paste the API key (v3) into **NeX-Up → Settings → Metadata and automation**. Without one, the English fallback still downloads Radarr's trailer, and **Skip the movie for now** reports that TMDB rejected the key.

Changing the setting affects new downloads only. To replace a trailer you already have, delete it and download it again.

When you search for an alternate trailer from Upcoming, TMDB's trailers in your language are listed first and tagged with the language, and the YouTube search uses that language's words for "trailer". A trailer you pick there downloads as-is, whatever the setting.

TMDB's coverage depends on the movie. Big releases usually have French, German and Spanish trailers; smaller ones often only have English.

## Upcoming Releases

**NeX-Up → Upcoming** lists what Radarr and Sonarr say is coming, and lets you decide what gets a trailer.

Three views, chosen with the toggle in the panel header:

- **List** — a dense row per title with its release date, trailer state and controls.
- **Posters** — the same set as artwork, which is faster to scan when you are picking by eye. Titles with no poster art fall back to a labelled placeholder.
- **Calendar** — a month grid showing what lands on which day.

Filter by search text, release window (30 days, 90 days, this year, all dates), trailer state (ready, missing, unavailable) and list state (included, excluded, all).

Each entry offers:

- **Download** — fetch that trailer now
- **Preview** — play the trailer once it has been downloaded
- **Include / exclude toggle** — keep a title out of Coming Soon lists without deleting its trailer

Switching between **Movies** and **TV shows** changes which service is queried.

## Downloading Trailers

### Sync Upcoming Releases

1. Go to the **Connections** tab
2. Click **Sync** next to Radarr or Sonarr
3. NeX-Up fetches upcoming releases within your configured timeframe

### View Upcoming Content

After syncing:
- **Upcoming Movies** — Shows movies scheduled for release with trailer availability
- **Upcoming TV** — Shows TV seasons with premiere dates

Each item shows:
- Title and release date
- Trailer availability (YouTube link found or not)
- Download status (pending, downloaded, or unavailable)

### Download Individual Trailers

1. Find the movie/show you want
2. Click the **Download** button
3. NeX-Up downloads the trailer from YouTube

### Bulk Download

1. Click **Download All Available**
2. NeX-Up downloads trailers for all upcoming content that has YouTube trailers available

### Add a Trailer Yourself

When NeX-Up can't get a trailer on its own (YouTube blocked the download, or Radarr has no trailer link), add it from **Your Trailers → Add trailer** (top right, or **Add a trailer** below the list):

1. **Which movie.** Pick it from **Radarr's upcoming movies**. That fills in the title, release date, poster and genres, and links the trailer to the movie in Radarr. A linked trailer counts as that movie's trailer: a sync won't download a second one, NeX-Up removes it when the movie arrives in your library, and genre matching works for it. Or type the title, and optionally the release date and TMDB ID.
2. **Where the trailer comes from.** Paste a **YouTube or web link** (a preview shows which video it is) or give the path to a **file on the server**, which NeX-Up copies into its trailer folder. On Docker, the path is inside the container.

The release date matters: NeX-Up removes a trailer the set number of days after the later of the download and the release date. Without one, a trailer for a movie months away could be removed before the movie is out. If YouTube access isn't set up, the window says so before you download.

Manual trailers are for movies only.

## Library Trailers

**NeX-Up > Library Trailers** keeps trailers for movies you **already own**, so a sequence can show them the way a cinema shows trailers before the feature.

It is separate from the rest of NeX-Up on purpose. Coming Soon trailers are for movies that aren't in your library yet, and are removed once a movie arrives. Library trailers are for movies that have arrived. They have their own settings, their own storage folder and their own limits, and nothing on this page is affected by Coming Soon's retention or cleanup.

### Turning it on

1. Connect Radarr under **NeX-Up > Connections**. Library Trailers reads your library from Radarr.
2. Open **NeX-Up > Library Trailers** and switch on **Keep trailers for movies in my library**
3. Choose which movies (below), then click **Save changes** and **Sync now**

After that, Library Trailers refreshes with NeX-Up's automatic refresh (**NeX-Up > Settings > Automatic refresh**).

### Which movies

Choose movies one of two ways, using the switch at the top of **Which movies**. Your filters and your picks are both kept when you switch.

#### Hand-pick movies

Browse your whole Radarr library as posters and click the ones you want trailers for. Search by title, narrow by genre, sort by title, newest in your library, highest rated or newest release, and switch between **All**, **Picked** and **Not picked**. **Pick all shown** picks everything in the current view, for example every horror movie rated highly.

Each poster shows whether the movie already has a trailer: **Next to movie**, **Downloaded**, **No trailer found**, or **No trailer link** when Radarr has none to download.

Hand-picked trailers don't rotate out; they stay until you unpick the movie. Unpicking keeps the trailer and marks it **Outside filters**, like any other trailer that no longer matches. If you pick more movies than your download limit allows, the page tells you, and the first ones by **Download first** are fetched.

#### Use filters

Every filter is optional. Filters you leave empty don't narrow anything, and the ones you set work together.

| Filter | What it does |
|--------|--------------|
| **Quick presets** | One-click starting points: Everything, Family night (G and PG), Critically acclaimed (85%+ on Rotten Tomatoes), Horror night, Classics (before 1990, rated 7+), New arrivals (last 60 days) |
| **Genres** | Click a genre once to **include** it, twice to **exclude** it, and again to clear it. Included genres match any of them; an excluded genre always wins |
| **Age ratings** | G, PG, PG-13, R, NC-17, or Unrated (movies with no rating or NR) |
| **Original language** | The movie's original language |
| **Release years** | From and to, inclusive |
| **Minimum scores** | IMDb and Rotten Tomatoes. Movies without that score are left out when it's set |
| **Recently added** | Only movies added to your library within a period |
| **Radarr tags** | Shown when your Radarr uses tags: movies with any of the chosen tags |
| **Specific movies** | Search your library and mark a movie **Always include** or **Never include**, whatever the other filters say |

Each chip shows how many movies in your library it covers. Below the filters, a summary says how many movies match and how many have a trailer link in Radarr, with posters of the first movies in line for a trailer. Nothing is saved or downloaded until you click **Save changes** and **Sync now**.

### Where trailers come from

1. **Trailers next to your movies.** Files named like `Movie (Year)-trailer.mp4`, `trailer.mp4`, or anything in a `Trailers` folder inside the movie's folder. This is the naming Plex, Jellyfin and Emby use for local trailers. NeXroll only reads these files and never moves or deletes them.
2. **Downloads from YouTube** for movies without a trailer file, using the trailer link Radarr has for the movie and NeX-Up's quality and YouTube settings. Downloads are kept in a `library` folder inside your NeX-Up storage folder.

Either can be switched off. With downloads off, only trailer files you already have are used.

**Folder mapping:** Radarr reports each movie's folder as Radarr sees it. If NeXroll sees the same folders under a different path, for example in Docker or over a network share, add a folder mapping such as `/movies` to `D:\Movies`, so NeXroll can find the trailer files.

To **play** those trailers, Plex needs to open them too, which may take a second mapping (NeXroll to Plex) under **Settings > Path Mappings**. **Find it for me** there finds your movie folder on the Plex side and adds it. See [Library Trailers beside your movies](Path-Mappings#library-trailers-beside-your-movies). Jellyfin and Emby need neither mapping for playback.

### Limits and rotation

- **Maximum downloaded trailers** and **Maximum download storage** apply to downloads only. Trailers next to your movies take no extra space and are always included.
- **Download first** decides which matching movies get downloads when more match than your limit allows: newest in your library, highest rated, most popular, or random. Movies you always include come first.
- Once a limit is reached, each sync swaps up to three downloads that have been kept for at least a week for movies that don't have a trailer yet, so the selection keeps changing.
- **Changing filters never deletes trailers you already have.** A trailer whose movie no longer matches is kept, still plays, and is marked **Outside filters**. Those are the first to be replaced when a limit is reached and new matches need room. To remove them straight away, use **Remove them** under Download limits.
- Turning off YouTube downloads keeps the trailers already downloaded.
- A trailer is removed on its own only when its movie leaves your library, or its file is deleted. A download is also replaced if a trailer file appears next to the movie.
- If a trailer can't be found for a movie, it is shown as **Not found** and retried after a few days.

### Sync progress

While a sync runs, a progress card shows each stage (reading your library, checking your folders, downloading, finished), a progress bar with the movie downloading now, running totals, and a live activity feed of what was found, downloaded, rotated out or couldn't be found. When it finishes the card stays as a summary until you hide it; **Last sync** brings it back.

### The trailer list

Every library trailer is shown as a poster card, marked **Next to movie** or **Downloaded**. Click play to watch it on the page, and use the switch to stop a trailer from playing without removing it.

### Playing library trailers

Add a **Library trailers** block in the [Sequence Builder](Sequences). Choose:

- **How many** trailers, **shuffled** or **newest in your library first**
- **Only these genres** (optional), to limit the block to, for example, horror
- **Restrict age ratings** (2.2.0 and later), to allow only selected ratings in this block
- **Same genre as the movie that's starting** (Jellyfin & Emby), to pick trailers that share a genre with the movie about to play. See [Matching the movie's genre](#matching-the-movies-genre).

Jellyfin/Emby can exclude the feature's own trailer when its TMDB identity is available. Plex does not provide the playing movie's identity. A Library trailers block can also be a condition's **Otherwise**; see [Advanced Sequences](Advanced-Sequences).

### Matching the movie's genre

> NeX-Up trailers can match genres from **2.2.2**. Library trailers could already; the **Play no trailers** choice is new in 2.2.2 for both.

Tick **Same genre as the movie that's starting** on a **NeX-Up trailers** or **Library trailers** block, then choose what happens **when no trailer shares its genre**:

- **Play trailers of any genre**: trailers sharing a genre come first; when none do, the block picks from all its trailers
- **Play no trailers**: the block plays only trailers sharing a genre, and nothing when none do

Only Jellyfin and Emby say which movie is starting. Plex applies one preroll list before every movie, so on Plex the first choice picks from all trailers and **Play no trailers** plays nothing.

A trailer matches when it shares any genre with the movie. TV genres such as **Action & Adventure** and **Sci-Fi & Fantasy** count as each of their parts, so a Stranger Things trailer can play before a science fiction movie. Source, age ratings and the Library block's **Only these genres** still apply first. Each genre keeps its own shuffle, so horror movies cycle through the horror trailers before repeating.

NeX-Up trailers take their genres from Radarr and Sonarr. Trailers downloaded before 2.2.2 have none until the next NeX-Up sync fills them in, without redownloading, and until then they never match. In Advanced mode, the Sequence Builder preview's genre setting shows whether a **Trailers available** condition that follows the block would hold for that genre; the trailer preview itself lists all of the block's trailers.

### Rating metadata after upgrading

> The sequence rating controls and source-specific availability conditions are new in **2.2.0**.

NeX-Up records movie/show certifications supplied by Radarr and Sonarr. Upgrading adds space for this metadata without changing existing sequences or redownloading files. Older trailers initially have no stored rating; their next normal provider-backed NeX-Up sync refreshes available metadata, including retained library trailers when downloads are disabled or the download limit is full.

If a restricted block unexpectedly plays nothing:

1. Sync the relevant upcoming or library trailer pool.
2. Confirm that its source title has a rating in Radarr/Sonarr.
3. Check the block's allowed ratings and that matching trailers are enabled, ready, and present on disk.

Missing ratings require explicitly selecting **Unrated**. Manual uploads and titles absent from the provider may remain unrated. Unsupported international certifications remain distinct from Unrated. Selecting no ratings while restriction is enabled intentionally matches nothing.

The certification describes the film or show, not a separately reviewed trailer. See [Sequences](Sequences#trailer-blocks-and-age-ratings) for the complete behavior.

### Download selection versus playback filters

Library Trailers' **Which movies** filters choose which movies enter the pool. A sequence block's rating filter chooses what can play from that pool. Different sequences can therefore use different ratings from the same pool.

Use **Minimum trailer targets** to try to keep that mixture. These targets are available for Library Trailers from 2.2.0; they do not change the Upcoming movie/TV downloader. To condition an intro on Jellyfin/Emby stored audio metadata, see [Stored audio format](Advanced-Sequences#stored-audio-format-jellyfin--emby). These sequence rules are independent of trailer download targets.

### Minimum trailer targets

Below **Which movies**, the full-width **Download limits & targets** section groups **Capacity & rotation** on the left and **Minimum trailer targets** on the right. On narrower screens they stack in that order. The outside-filter cleanup notice sits below both groups.

For example, to keep up to 25 downloaded trailers with at least two G/PG trailers and five horror trailers:

1. Open **NeX-Up > Library Trailers** and choose your movie selection.
2. Under **Download limits & targets > Capacity & rotation**, set **Maximum downloaded trailers** to **25 trailers** and choose a storage limit.
3. Click **Add minimum target**. Leave **Age ratings**, select **G** and **PG**, and set **At least** to **2**.
4. Add another target, choose **Genres**, select **Horror**, and set **At least** to **5**.
5. Click **Save changes**, then **Sync now**, or let the next automatic NeX-Up refresh apply it.

Each target matches **any** of its selected values. G/PG with minimum two means two combined, not two of each. A PG horror trailer counts toward both targets and is downloaded only once. Enabled, ready local trailers within your movie selection also count toward targets without consuming download slots.

Unmet targets take priority over **Download first**; overlapping and scarcer targets are preferred, and remaining slots use the chosen ordering. Targets never expand your filters or hand-picked selection. Disabled trailers, missing files, and trailers outside the current selection do not satisfy a target. The certification comes from Radarr; unknown international ratings are not treated as Unrated for targets.

**Current pool for these choices** shows available versus requested counts and matching movies before saving. **Targets at last sync** shows the actual result, including shortfalls. Counts refresh after syncs and trailer toggles. A movie matching a target does not guarantee that its trailer can be downloaded.

Targets are best effort. Download/storage limits take precedence; incompatible targets, missing trailers, retry delays, and protected downloads can leave a shortfall. A sync can finish successfully while some targets remain unmet. NeXroll reports that rather than exceeding your configured retained-download limits. Replacements are downloaded before old files are removed, so temporary disk space for the incoming file is still needed.

With targets enabled, NeXroll waits for a usable replacement that fits the limits before removing a working download. Routine weekly rotation preserves target counts already met. Repairing an unmet target may replace a newer download; pinned **Always include** movies remain protected from those replacements. Lowering a hard download/storage limit can still force removals, even if a target becomes unmet. Trailers next to movies are never deleted by quota replacement.

You can save up to 12 targets. With downloads off, targets only report existing availability and no downloads are rotated out. Remove all targets to restore the original rotation behavior. Existing installations start with no targets, and saved targets travel with Library Trailers settings in backups.

Pool targets are not playback restrictions. Use a sequence block's [age-rating filter](Sequences#trailer-blocks-and-age-ratings) when only certain ratings should play; do not rely on pool composition to enforce that selection.

## YouTube Downloads (Cookie-Free)

NeXroll downloads trailers from YouTube **without cookies** using a built-in **PO-token provider** — a small local helper that clears YouTube's "Sign in to confirm you're not a bot" wall.

1. Open the **YouTube Downloads** card (in NeX-Up, or **Settings → System → Dependencies**).
2. Click **Install** to set up the PO-token provider. It's bundled with the Windows app; on Docker it's already included.
3. Once it shows **healthy**, trailer downloads work with no cookie file.

The provider only accepts connections from the machine NeXroll runs on. **Updating from 2.2.0 or earlier on Windows:** the card shows **Update needed** and NeXroll no longer starts the old provider, because versions before 2.0.0 accepted connections from the whole network and had a security flaw reachable that way. Click **Update** once; YouTube downloads carry on as before. Docker images from 2.2.1 already include the fixed provider.

Trailers download in a **Plex-friendly H.264** format so they play correctly as prerolls (older builds could grab AV1, which silently failed on Plex).

> If a specific trailer is unavailable or blocked, NeX-Up offers a **pick-an-alternate-trailer** flow so you can choose a working one.

## YouTube Cookies (Fallback)

The PO-token provider handles most cases. If you still hit blocks (age-restricted or region-locked trailers), you can additionally supply a cookies file exported from your browser.

### Why Cookies?

- Bypasses age restrictions
- Avoids region locks
- Reduces rate limiting
- More reliable downloads

### How to Export Cookies

1. Install the "cookies.txt" browser extension:
   - [Firefox](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/)
   - [Chrome](https://chrome.google.com/webstore/detail/cookies-txt)
2. Open an **Incognito/Private** window
3. Go to YouTube and sign in
4. Click the extension icon → "Export cookies"
5. Save the `cookies.txt` file

### Upload to NeX-Up

1. Go to **NeX-Up → Settings**
2. Find "YouTube Cookies" section
3. Click **Upload Cookie File**
4. Select your `cookies.txt` file

### Tips for Avoiding Blocks

- **Refresh your VPN IP** if downloads fail repeatedly
- **Wait between downloads** — don't download 20 trailers at once
- **Use Incognito** when exporting cookies
- **Re-export cookies** if they expire (typically every few weeks)


## Generator Studio

**NeX-Up → Generator** is one workspace for both generators — Coming Soon lists and dynamic prerolls. Pick a mode at the top; everything below is shared.

The two generators are documented in detail in the sections that follow. What they have in common is described here.

### Render settings

| Setting | Options | Notes |
|---------|---------|-------|
| **Resolution** | 720p, 1080p, 4K | |
| **Frame rate** | 24, 30, 60 fps | 24 for a cinematic feel, 60 for smooth motion |
| **Encoding profile** | Draft, Balanced, High, Master | CRF 24 / 20 / 15 / 12 |

Draft renders fastest and produces the smallest file. Master is archival quality and several times larger. All three settings apply to both generators, and to both the still and animated render paths.

### Themes and typography

A **visual theme** drives the background and the three base colours together — pick one, or choose *Custom colors* to set background, text and accent by hand.

Coming Soon lists additionally expose **per-role colours** so each kind of text can be set independently: heading, titles, dates, and the "available now" marker. Each has an *Inherit* button to fall back to the theme.

**Text size** scales titles and dates. Row spacing follows it, and the list is capped so it always fits the frame no matter how many items you show.

### Logo and QR code

Upload a logo (PNG, JPG or WebP; a transparent PNG works best) and choose its placement:

- **Faded watermark** — low-opacity, behind the content
- **Right of heading** — beside the title
- **Below heading** — under the title, above the list

Add a **QR code link** to render a scannable code in the bottom-right corner — useful for pointing viewers at a request form or a "what's on" page. Leave it blank for none.

### Audio

Choose the bundled cinematic track, upload your own, or render silent. Uploaded audio is trimmed to the render length with fades applied at both ends.

If your track does not match the video length, **Match length to the soundtrack** appears once the file is uploaded. Turning it on sets the render duration to the track's length so it plays in full.

### Render confidence

Before rendering, the studio lists what it checked — FFmpeg present, template valid, assets readable, output writable — and blocks the render with a plain reason if something is missing, rather than failing part-way through.

## Coming Soon List Generator

Generate dynamic video prerolls that showcase your upcoming movies and TV shows from Radarr and Sonarr. These videos automatically display titles, release dates, and poster art.

### Layout Styles

| Layout | Description |
|--------|-------------|
| **Grid Mode** | Visual poster grid with movie/show artwork (220x330px posters) and titles |
| **List Mode** | Clean text-only layout with titles and release dates |

### Configuration

In the **Generator** tab, configure your Coming Soon List:

| Setting | Description | Default |
|---------|-------------|---------|
| **Layout** | Grid, List, or generate both | Grid |
| **Content Source** | Movies only, Shows only, or Both | Both |
| **Duration** | Video length in seconds | 10 |
| **Max Items** | How many titles to display | 8 |
| **Server Name** | Your server name, shown in the header | — |
| **Visual theme** | Drives background, text and accent together | Custom colors |
| **Background / Text / Accent** | Set by hand when no theme is chosen | #141428 / #ffffff / #00d4ff |
| **Heading / Titles / Dates / Available now** | Per-role colour overrides, each with Inherit | Inherit |
| **Text size** | Scales titles and dates; row spacing follows | 100% |
| **QR code link** | Rendered bottom-right; blank for none | — |
| **Logo** | Watermark, right of heading, or below heading | — |
| **Audio** | Bundled track, your own upload, or silent | Off |

Resolution, frame rate and encoding profile are shared with the dynamic generator — see [Render settings](#render-settings) above.

### Generating a Coming Soon List

1. Go to **NeX-Up → Generator**
2. Configure your layout settings
3. Click **Generate**
4. Preview the result in the built-in video player
5. The video is saved and registered to the "Coming Soon Lists" category

### Auto-Regeneration

Enable auto-regeneration to keep your Coming Soon List fresh:

1. In the Generator settings, toggle **Auto-regenerate on sync**
2. Choose which layouts to regenerate: Grid, List, or Both
3. When NeX-Up syncs with Radarr/Sonarr, the Coming Soon List automatically updates with new content

### Using Coming Soon Lists

Generated Coming Soon Lists can be used:
- In **Sequences** — Add as a fixed block
- As **Filler Category** — Set Coming Soon List as the filler type in Settings
- In **Schedules** — Add to a category and schedule it

## Dynamic Preroll Generator

Create custom "Coming Soon to [Your Server]" intro videos.

### Navigate to Generator

Go to **NeX-Up → Generator**

### Available Templates

| Template | Description |
|----------|-------------|
| **Coming Soon** | Cinematic intro with glow effects and dramatic animations |
| **Feature Presentation** | Classic theater-style with elegant text |
| **Now Showing** | Retro film-style with warm sepia tones |

### Color Themes

| Theme | Style |
|-------|-------|
| **Midnight** | Blue/purple cyberpunk feel |
| **Sunset** | Warm orange/red tones |
| **Forest** | Calming teal/green |
| **Royal** | Elegant gold/purple |
| **Monochrome** | Classic black and white |

### Generate an Intro

1. Select a **Template**
2. Choose a **Color Theme**
3. Enter your **Server Name** (e.g., "Smith Family Server")
4. Click **Generate**
5. Wait for FFmpeg to create the video (5-15 seconds)
6. **Preview** the result in your browser
7. Click **Save** to add it to your preroll library

### Requirements

- FFmpeg must be installed and in your PATH
- Windows: Install via `winget install ffmpeg` or download from ffmpeg.org
- Docker: FFmpeg is included in the container

## Building Sequences with Trailers

Sequences combine your dynamic intro, trailers, and other prerolls into a complete theater experience.

### Quick Sequence Presets

NeX-Up includes ready-made sequence templates:

| Preset | Content |
|--------|---------|
| **Coming Soon + Movie Trailers** | Your intro → 2-3 random movie trailers |
| **Coming Soon + TV Trailers** | Your intro → 2-3 random TV trailers |
| **Mixed: Movies + TV** | Your intro → 1 movie trailer → 1 TV trailer |
| **Theater Experience** | Your intro → 4 random trailers |

### Create a Sequence from Preset

1. Go to **NeX-Up → Generator**
2. Scroll to **Sequence Builder**
3. Select a preset
4. Click **Create Sequence**
5. The Sequence Builder opens with blocks pre-configured
6. Customize if needed
7. Save to your library

### Manual Sequence Building

For full control, use the Sequence Builder directly:

1. Go to **Schedules → Sequence Builder**
2. Click **Add Block**

#### Block Types

For trailers, use **NeX-Up trailers** for upcoming content and **Library trailers** for movies you own. Both support per-block rating restrictions from 2.2.0. Generic category blocks do not apply trailer-rating filters.

To condition a Coming Soon or Now Available intro on the appropriate filtered trailer block, follow the [four-block recipe](Advanced-Sequences#coming-soon-followed-by-now-available).

**Random Block**
- Pulls random prerolls from a category
- Perfect for: "Play 2 random movie trailers"
- Configure: Select category, set count

**Fixed Block**
- Specific prerolls in exact order
- Perfect for: "Always play my Coming Soon intro first"
- Configure: Select specific prerolls

### Example: Theater Experience Sequence

| Order | Type | Configuration |
|-------|------|---------------|
| 1 | Fixed | "Coming Soon to [Server Name]" dynamic intro |
| 2 | NeX-Up trailers | Movies only, count 2, optional rating restriction |
| 3 | NeX-Up trailers | TV only, count 1, optional rating restriction |

**Result**: Your custom intro plays, followed by 2 random movie trailers and 1 TV trailer.

### Save and Use

1. Enter a **Name**: "Theater Experience - Winter 2025"
2. Add a **Description**: "Coming soon intro + 3 trailers"
3. Click **Save**

Now use this sequence in any schedule!

## Using Sequences in Schedules

### Create a Schedule

1. Go to **Schedules → Schedules**
2. Click **Add Schedule**
3. Fill in:
   - **Name**: "Daily Theater Mode"
   - **Start/End Date**: Your desired date range
   - **Start/End Time**: When the sequence should be active (or leave blank for all day)
4. Enable **Use Sequence**
5. Select your saved sequence
6. Click **Save**

The schedule will automatically use your sequence during the configured time period.

### Schedule Examples

| Schedule Name | Use Case |
|---------------|----------|
| Coming Attractions - Weekends | Theater mode only on Sat/Sun |
| December Movie Magic | Holiday movie trailers in December |
| TV Premiere Season | September TV trailers during premiere season |

## Trailer Categories

NeX-Up automatically creates categories for your trailers:

| Category | Contents |
|----------|----------|
| **Movie Trailers** | All downloaded movie trailers from Radarr |
| **TV Trailers** | All downloaded TV trailers from Sonarr |
| **Coming Soon Lists** | Generated Coming Soon List videos |

These categories are used by:
- Sequence Builder random blocks
- Dashboard statistics
- Filler Category configuration
- Storage management


## NeX-Up Settings

**NeX-Up → Settings** holds everything the automation needs.

### Trailer storage

Where downloaded trailers are written. NeXroll suggests a folder inside your prerolls directory, and the suggestion is deliberate: that is the one location your media server is already able to open, because it is already mounted and already covered by whatever path mapping your prerolls use.

If you choose somewhere else, NeXroll tells you whether the server will actually be able to reach it. A trailer stored where the server cannot open it is the most common way this feature appears broken — the download succeeds, the schedule applies, and nothing plays.

This is also asked during first-run setup, on both Windows and Docker installs.

> The library scanner deliberately skips this folder, so trailers are not indexed a second time as ordinary prerolls.

Changing the path afterwards moves the existing trailers into the new location and updates their entries, so nothing is left behind in the old folder.

### Retention

Trailers are removed automatically once the film enters your library, or once the retention window passes — whichever comes first. Set the window in days, or set it to `0` to keep trailers until you delete them yourself.

### Download behaviour

| Setting | What it controls |
|---------|------------------|
| **Quality** | Maximum resolution to fetch |
| **Days ahead** | How far into the future to look for releases |
| **Max trailers** | Hard cap on how many are kept |
| **Max trailer duration** | Sync skips longer trailers; the Upcoming tab's download button ignores it |
| **Max storage** | Hard cap in GB |
| **Delay between downloads** | How politely requests are paced |
| **Max concurrent** | How many downloads run at once |
| **Include unmonitored** | Whether unmonitored Radarr/Sonarr items are eligible |
| **Release date preference** | Digital, physical or theatrical dates first |
| **Trailers per playback** | How many trailers a schedule plays at once |
| **Playback order** | Random or sequential |

### Categories

Choose which category downloaded movie trailers and TV trailers are filed under. NeXroll creates *NeX-Up Movie Trailers* and *NeX-Up TV Trailers* by default.

Every downloaded trailer is in its category, so a schedule can use the category directly, for example *NeX-Up Movie Trailers* in random mode to play one of your trailers before each movie. A trailer you switch off on Your Trailers stays out of it. For more control (how many trailers, ratings, genres, Library Trailers) use a NeX-Up Trailers block in a sequence. Before 2.2.5 a trailer downloaded by a sync wasn't added to the category, so a schedule on it played nothing.

## Managing Your Trailers

### View Downloaded Trailers

Go to **NeX-Up → Your Trailers**

You'll see:
- All downloaded movie trailers
- All downloaded TV trailers
- Storage usage per category
- Total storage used

### Delete Trailers

1. Find the trailer to remove
2. Click the **Delete** button
3. Confirm deletion

The trailer is removed from disk and the category.

### Trailer genres

From 2.2.2 each trailer lists its movie's or show's genres, taken from Radarr or Sonarr. They show under the title and in the preview panel, and the search box matches them, so searching **horror** lists horror trailers. Trailers downloaded earlier show **After the next sync** until a NeX-Up sync fills them in.

### Automatic Cleanup

When enabled (Settings → Auto-Cleanup):
- NeX-Up checks your Radarr/Sonarr during syncs
- When a movie/show is added to your library, its trailer is automatically deleted
- Keeps your trailer collection fresh and relevant

## Dashboard Integration

### Quick Actions

On the Dashboard, the **Quick Actions** panel includes:
- **NeX-Up Sync** — One-click sync for both Radarr and Sonarr
- Shows real-time download progress with trailer count
- No need to navigate to the NeX-Up page

### NeX-Up Tile

The Dashboard shows a NeX-Up summary:
- Number of movie trailers
- Number of TV trailers
- Connection status
- Quick link to full NeX-Up page

## Docker Setup

Running NeXroll in Docker requires extra configuration for NeX-Up trailers. Without it, trailers download successfully but fail to play with **"failed to load trailer. The file may not be accessible."**

### Why This Happens

When NeX-Up downloads a trailer, it writes the file to the **Storage Path** you configured in NeX-Up Settings. Inside Docker, this path lives inside the container. NeXroll then serves the file back to your browser using that same path.

If the path isn't volume-mounted to the host, one of two things happens:
- The file disappears on container restart (no persistence)
- The file exists but NeXroll can't serve it correctly to the browser

### Required Volume Mount

Add a dedicated volume for trailer storage in your `docker-compose.yml`:

```yaml
volumes:
  - ./nexroll-data:/data
  - /path/to/your/prerolls:/data/prerolls
  - /path/to/your/trailers:/data/nexup_trailers    # Required for NeX-Up
```

Replace `/path/to/your/trailers` with any host directory you want trailers saved to (e.g., `./nexroll-trailers` or `/mnt/user/media/trailers`).

### Match the Storage Path in Settings

After mounting the volume, open **NeX-Up → Settings** and set the **Storage Path** to match the container path exactly:

```
/data/nexup_trailers
```

This must match the right side of your volume mount (the container path). If they don't match, NeXroll writes files to one place and looks for them in another.

### Easier Option: Store Trailers Inside Your Prerolls Folder

If you'd rather not manage a second volume mount, point the Storage Path at a
subfolder inside your existing prerolls path instead, e.g. `/data/prerolls/nexup_trailers`.
Since that's already inside the volume your media server can see, no extra
mount or Path Mapping is needed. NeX-Up → Settings now suggests this path
automatically when Storage Path is unset — click **use this** to apply it in
one step (existing downloaded trailers are relocated automatically if you
change an already-configured path).

If NeXroll detects it's running in Docker and your configured Storage Path is
neither inside the prerolls folder nor covered by a Path Mapping, NeX-Up →
Settings also shows a dismissible warning with a one-click "Move to
recommended folder" fix, so this misconfiguration doesn't fail silently the
way it used to (trailers apply to your media server's preroll setting but the
file isn't reachable, so nothing plays).

### Verify It Works

1. Go to **NeX-Up → Your Trailers**
2. Download any trailer
3. Click play — it should load without the "file may not be accessible" error
4. Restart the container (`docker compose restart nexroll`) and confirm trailers still appear

### Full docker-compose Example with NeX-Up

```yaml
version: "3.8"
services:
  nexroll:
    image: jbrns/nexroll:latest
    container_name: nexroll
    ports:
      - "9393:9393"
    environment:
      - NEXROLL_PORT=9393
      - NEXROLL_DB_DIR=/data
      - NEXROLL_PREROLL_PATH=/data/prerolls
      - NEXROLL_SECRETS_DIR=/data
      - TZ=America/New_York
    volumes:
      - ./nexroll-data:/data
      - /path/to/your/prerolls:/data/prerolls
      - /path/to/your/trailers:/data/nexup_trailers
    restart: unless-stopped
```

### Path Mappings for Media Servers

Plex plays trailers straight from its own disk, so it must be able to reach the trailer files. With the storage folder inside your preroll folder (the suggested place), the preroll folder's mapping already covers them. Otherwise, mount the same host folder into your Plex container too:

```yaml
  plex:
    volumes:
      - /path/to/your/trailers:/media/trailers    # Same host path, different container path
```

Then use **Find it for me** in **Settings > Path Mappings**, which finds the trailer folder on the Plex side and adds the mapping, or add it yourself:

| Folder as NeXroll sees it | Same folder as Plex sees it |
|---|---|
| /data/nexup_trailers | /media/trailers |

Jellyfin and Emby need no mapping: their NeXroll Intros plugin downloads each trailer from NeXroll. See [Path Mappings](Path-Mappings).

---

## Troubleshooting

### Trailers Not Downloading

If the **Download** button on the Upcoming tab works but sync skips the same trailers, check **Max Trailer Duration** in NeX-Up settings. Sync skips trailers longer than it and says so in its summary and the log. Before 2.2.2 these skips were reported as a YouTube sign-in block.

1. **Check YouTube cookies** — Re-export if expired
2. **Verify VPN** — Try a different server/IP
3. **Wait between downloads** — YouTube rate limits
4. **Check the trailer URL** — Some trailers are region-locked
5. **Check Settings → Logs** for detailed error messages

### No Upcoming Content Found

1. **Verify Radarr/Sonarr connection** — Re-enter URL and API key
2. **Check "Days Ahead" setting** — Increase if needed
3. **Ensure upcoming content exists** — Check Radarr/Sonarr directly
4. **Check "Include Unmonitored"** — Enable if your content is unmonitored

### Coming Soon List Generation Fails

1. **Verify FFmpeg is installed** — Run `ffmpeg -version` in terminal
2. **Check FFmpeg in PATH** — NeXroll must be able to find it
3. **Sync first** — Coming Soon Lists need upcoming content from Radarr/Sonarr
4. **Check logs** — Settings → Logs for detailed error messages

### Dynamic Preroll Generation Fails

1. **Verify FFmpeg is installed** — Run `ffmpeg -version` in terminal
2. **Check FFmpeg in PATH** — NeXroll must be able to find it
3. **Sufficient disk space** — Generation needs temporary space

### Sequence Not Playing in Plex

1. **Check the schedule** — Is it enabled and within date range?
2. **Verify path mappings** — Settings → Path Mappings
3. **Ensure files exist** — Trailers might have been cleaned up
4. **Restart Plex** — Plex caches preroll settings

## Best Practices

### Trailer Count
- **Recommended**: 2-3 trailers per sequence
- Too many trailers = long wait before your movie

### Quality Settings
- **1080p** is ideal for most setups
- **720p** if bandwidth is a concern
- **4K** only if your network supports it

### Storage Management
- Set reasonable **Max Trailers** limit (10-20)
- Enable **Auto-Cleanup** to remove released content
- Monitor storage in the NeX-Up dashboard

### Coming Soon Lists
- Use **Grid** layout for visual impact with poster art
- Use **List** layout for a cleaner, text-based look
- Enable **Auto-regeneration** to keep lists current
- Customize colors to match your server's theme

### Regular Maintenance
- **Sync weekly** to catch new upcoming releases
- **Check for failed downloads** and retry
- **Update cookies** if YouTube blocks downloads

### Sequence Design
- Keep total preroll time under 2 minutes
- Lead with your custom intro or Coming Soon List
- Mix movie and TV trailers for variety
- Create seasonal sequences (holiday, summer blockbusters, etc.)

## Complete Setup Walkthrough

Here's a step-by-step guide to get the full theater experience:

1. **Connect Radarr/Sonarr** (Connections tab)
2. **Upload YouTube cookies** (Settings tab)
3. **Sync upcoming releases** (Connections tab → Sync)
4. **Download trailers** (Your Trailers tab → Download All)
5. **Generate a Coming Soon List** (Generator tab → Coming Soon List section)
6. **Generate a Coming Soon intro** (Generator tab → Dynamic Preroll section)
7. **Create a sequence** using a preset (Generator tab → Sequence Builder)
8. **Create a schedule** that uses your sequence (Schedules → Add Schedule)
9. **Enjoy!** Your Plex now has a real theater experience

---

*NeX-Up is designed to enhance your home theater experience. Trailers are downloaded from YouTube and are subject to YouTube's terms of service. Always ensure you have the right to download and use content in your jurisdiction.*