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

1. Navigate to Tools → Preroll Manager
2. Click Add Preset
3. Enter a name (e.g., “Holiday 2024”, “Default Intro”)
4. Enter the file path to the preroll video on your server
5. The path is validated server-side to confirm the file exists and is readable

Path Validation

When you enter a preroll file path, Librariarr validates it in two ways:

1. 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).
2. 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.

Tip

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.

docker-compose.yml (excerpt)

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.

Note

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
• Start/End time: 24-hour format time window
• Example: Play holiday prerolls on weekends from 6:00 PM to 11:00 PM

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

Use built-in holiday presets or define custom date ranges.

• Holiday presets: New Year, Valentine’s Day, Easter, Halloween, Christmas, and more (dates auto-calculated)
• Custom: Define your own annual date range

Priority

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

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

The combined path can then be used 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:

1. Evaluates which preroll schedules are currently active
2. Selects the highest-priority active schedule
3. Sets that schedule’s preroll path on the media server

Limitations

• Plex: Preroll support works by setting the preroll path via the Plex API. Requires Plex Pass for the preroll feature.
• Jellyfin/Emby: Preroll support varies by server version and may require plugins or specific configuration.
• Changes to active prerolls take effect on the next playback start — currently playing content is not affected.

Caution

The preroll file paths stored in presets must be valid from the media server’s perspective. Librariarr validates that the file exists inside its own container (via the read-only volume mount), but the media server must also be able to access the same file at the same path. Ensure both containers mount the preroll directory at the same path.