Preroll Manager

The Preroll Manager lets you configure videos that play before your media content, with scheduling support for seasonal or event-based prerolls.

Preroll Presets

Presets store references to preroll media files on your server.

Creating a Preset

Navigate to Tools → Prerolls
Click Save as Preset
Enter a name (e.g., “Holiday 2024”, “Default Intro”)
Enter the file path to the preroll video on your server
Click Save — the path is stored as entered; it is checked when you apply it (see below)

Path Validation

When you Apply a preroll path (from Quick Set, a preset, or Apply Combined Preroll), Librariarr checks each path in it — a combined path is split on , and ; — in two ways:

Directory whitelisting — The path must fall within an allowed directory. By default, the allowed prefixes are /media, /data, /mnt, and /opt/prerolls. You can customize this with the PREROLL_ALLOWED_PATHS environment variable (comma-separated list of directory prefixes).
Read-only file access check — Librariarr verifies the file exists and is readable from inside the container. It only needs read access — preroll files are never modified.

A path that fails either check opens a File Not Found warning listing it; you can cancel or Continue to apply it anyway (useful when the media server sees the file but Librariarr’s container does not). Paths in presets and schedules are not checked when they are saved.

To enable path validation, mount your preroll files into the Librariarr container as a read-only volume. This gives Librariarr visibility to verify paths without granting write access to your media files.

services:
  librariarr:
    volumes:
      - ./config:/config
      - /path/to/your/prerolls:/media/prerolls:ro

The :ro flag ensures the mount is read-only. Librariarr will never write to or modify your preroll files.

If PREROLL_ALLOWED_PATHS is not set, the defaults are /media, /data, /mnt, and /opt/prerolls. To restrict or expand the allowed directories, set it in your environment:

environment:
  - PREROLL_ALLOWED_PATHS=/media/prerolls,/data/prerolls

Supported Formats

Preroll files can be any video format supported by your media server (MP4, MKV, AVI, etc.).

Preroll Schedules

Schedules control when specific preroll presets are active.

Schedule Types

Recurring

Set repeating schedules tied to specific days and times.

Days of week: Select which days the preroll should play. A recurring schedule with no day ticked never plays, and its row reads No days selected
Start/End time: 24-hour format time window
Example: Play holiday prerolls on weekends from 6:00 PM to 11:00 PM
A window whose end is before its start (22:00 to 06:00) runs past midnight and belongs to the day it starts: Monday 22:00–06:00 plays from Monday night into Tuesday morning

One-Time

Set a single window with specific start and end dates/times.

Example: Special event preroll from 2024-12-31 20:00 to 2025-01-01 03:00

Seasonal

Define an annual date range, or pick the Holiday schedule type to start from a built-in holiday.

Holiday: New Year’s Day, Valentine’s Day, St. Patrick’s Day, Easter, Mother’s Day, Father’s Day, Independence Day (US), Halloween, Thanksgiving (US), Christmas and New Year’s Eve. Picking one pre-fills a fixed date range (for example, Easter is all of April and Christmas is December 1–26), which you can adjust; it is saved as a seasonal schedule
Seasonal: Define your own annual date range
A seasonal schedule repeats every year; the year in its dates is ignored

Priority

Each schedule has a priority value. When multiple schedules are active simultaneously, the highest-priority schedule’s preroll path is used.

Overlapping Schedules

Saving an enabled schedule that would be active at the same time as another enabled schedule is refused, and the error names the schedule it collides with:

One-time and seasonal schedules conflict when their dates overlap. A seasonal schedule is compared on its month and day in every year, so a seasonal December window conflicts with a one-time schedule in any December.
Recurring schedules conflict when their weekly windows overlap. An overnight window counts on the day it starts and runs into the next morning, so Monday 22:00–06:00 conflicts with a Tuesday 05:00 window but not with a Monday 05:00 one.
Windows that only touch (one ends at the minute the other starts) do not conflict.
A recurring schedule is not compared with one-time or seasonal ones; when they are active together, priority decides.
A schedule saved disabled is not checked until it is enabled.

Combining Presets

The Preroll Manager includes a preset combination tool in the UI. Select multiple presets and combine their paths using:

Sequential (comma-separated) — play all selected prerolls in order
Random (semicolon-separated) — media server picks one at random

Click Apply Combined Preroll to set it on Plex now, or use the combined path in a schedule’s preroll path field. This leverages your media server’s native path separator support (Plex uses ; for random and , for sequential).

How It Works

The preroll enforcer checks every 30 seconds:

Evaluates which preroll schedules are currently active
Selects the highest-priority active schedule
Sets that schedule’s preroll path on every enabled Plex server — including one added or turned back on while the schedule is active
When no schedule is active, clears the preroll — including when no enabled schedule remains (the last one was deleted or turned off) after it had set one

The Active badge on the Preroll page uses the same rules, so it shows exactly the schedules the enforcer is applying.

Limitations

Plex: Preroll support works by setting the preroll path via the Plex API. Requires Plex Pass for the preroll feature.
Jellyfin/Emby: Not supported. The Preroll Manager only sets prerolls on enabled Plex servers; Jellyfin and Emby servers are ignored.
Changes to active prerolls take effect on the next playback start — currently playing content is not affected.