plex-prerolls/README.md

Plex Preroll Scheduler

A script to automate management of Plex pre-rolls.

Define when you want different pre-rolls to play throughout the year. For example:

• Holiday pre-roll rotations
• Special occasions
• Seasonal rotations
• Breaking up the monotony
• Keeping your family on their toes!

---

Installation and Usage

Run Script Directly

Requirements

• Python 3.8+

Clone the repo:

git clone https://github.com/nwithan8/plex-schedule-prerolls.git

Install Python requirements:

pip install -r requirements.txt

Copy config.ini.sample to config.ini and complete the [auth] section with your Plex server information.

Copy schedules.yaml.sample to schedules.yaml and edit your schedule.

Run the script:

python schedule_preroll.py

Advanced Usage

$ python schedule_preroll.py -h

usage: schedule_preroll.py [-h] [-v] [-l LOG_CONFIG_FILE] [-c CONFIG_FILE] [-s SCHEDULE_FILE]

Automate scheduling of pre-roll intros for Plex

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show the version number and exit
  -lc LOG_CONFIG_FILE, --logconfig-path LOG_CONFIG_FILE
                        Path to logging config file. [Default: ./logging.conf]
  -c CONFIG_FILE, --config-path CONFIG_FILE
                        Path to Config.ini to use for Plex Server info. [Default: ./config.ini]
  -s SCHEDULE_FILE, --schedule-path SCHEDULE_FILE
                        Path to pre-roll schedule file (YAML) to be use. [Default: ./schedules.yaml]

Example

python schedule_preroll.py \
    -c path/to/custom/config.ini \
    -s path/to/custom/schedules.yaml \
    -lc path/to/custom/logger.conf

Run as Docker Container

Requirements

• Docker

Docker Compose

Complete the provided docker-compose.yml file and run:

docker-compose up -d

Docker CLI

docker run -d \
  --name=plex_prerolls \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e CRON_SCHEDULE="0 0 * * *" \
  -v /path/to/config:/config \
  -v /path/to/logs:/logs \
  --restart unless-stopped \
  nwithan8/plex_prerolls:latest

Paths and Environment Variables

Path	Description
/config	Path to config files (config.ini and schedule.yaml should be in this directory)
/logs	Path to log files (schedule_preroll.log will be in this directory)

Environment Variable	Description
PUID	UID of user to run as
PGID	GID of user to run as
TZ	Timezone to use for cron schedule
CRON_SCHEDULE	Cron schedule to run script (see https://crontab.guru for help)

---

Schedule Rules

Schedules follow the following priority:

1. misc: Items listed in always_use will always be included (appended) to the preroll list

2. date_range: Schedule based on a specific date/time range

3. weekly: Schedule based on a specific week of the year

4. monthly: Schedule based on a specific month of the year

5. default: Default item to use if none of the above apply

For any conflicting schedules, the script tries to find the closest matching range and highest priority.

Advanced Scheduling

Date Range Section Scheduling

date_range entries can accept both dates (yyyy-mm-dd) and datetimes (yyyy-mm-dd hh:mm:ss, 24-hour time).

date_range entries can also accept wildcards for any of the date/time fields. This can be useful for scheduling recurring events, such as annual events, "first-of-the-month" events, or even hourly events.

date_range:
  enabled: true
  ranges:
    # Each entry requires start_date, end_date, path values
    - start_date: 2020-01-01 # Jan 1st, 2020
      end_date: 2020-01-02 # Jan 2nd, 2020
      path: /path/to/video.mp4
    - start_date: xxxx-07-04 # Every year on July 4th
      end_date: xxxx-07-04 # Every year on July 4th
      path: /path/to/video.mp4
    - start_date: xxxx-xx-02 # Every year on the 2nd of every month
      end_date: xxxx-xx-03 # Every year on the 3rd of every month
      path: /path/to/video.mp4
    - start_date: xxxx-xx-xx 08:00:00 # Every day at 8am
      end_date: xxxx-xx-xx 09:30:00 # Every day at 9:30am
      path: /path/to/holiday_video.mp4

You should adjust your cron schedule to run the script more frequently if you use this feature.

---

Scheduling Script

NOTE: Scheduling is handled automatically in the Docker version of this script via the CRON_SCHEDULE environment variable.

Linux

Add to system scheduler:

crontab -e

Place desired schedule (example below for every day at midnight)

0 0 * * * python /path/to/schedule_preroll.py >/dev/null 2>&1

You can also wrap the execution in a shell script (useful if running other scripts/commands, using venv encapsulation, customizing arguments, etc.)

0 0 * * * /path/to/schedule_preroll.sh >/dev/null 2>&1

Schedule as frequently as needed for your schedule (ex: hourly, daily, weekly, etc.)

---

Shout out to places to get Pre-Roll

• https://prerolls.video