YAML Schedules: Declarative Playout Definition

YAML schedules — also called Sequential schedules — let you define a playout’s entire programming logic as a plain-text YAML file. Instead of configuring items through the ErsatzTV UI, you write a structured document that declares content sources, sequences, and playback instructions. ErsatzTV reads the file when building the playout, executes the instructions in order, and loops back to the start each cycle. Because the schedule lives in a file on disk, it can be version-controlled alongside the rest of your media server configuration.

YAML schedule files are plain text. Store them in a Git repository to track changes over time, roll back accidental edits, and collaborate with others on your channel programming.

File Location and Playout Setup

To use a YAML schedule, create a playout in the ErsatzTV UI and set its Schedule Kind to Sequential. Then point the playout’s Schedule File field to the absolute path of your YAML file on the server. ErsatzTV reads this file each time the playout is rebuilt; any change to the file is picked up on the next rebuild without restarting the application.

YAML File Structure

A YAML schedule file (YamlPlayoutDefinition) has four top-level sections:

# Optional: import definitions from other YAML files
# import:
#   - other-file.yaml

# Declare content sources with short keys
content: []

# Define reusable named sequences
sequence: []

# Instructions run once when the playout is reset
reset: []

# The main playback loop — repeated each cycle
playout: []

# Optional: date-range-based alternate playout lists
schedules: []

Only the content and playout sections are required. The others are optional.

Content Section

The content section declares every media source your schedule references. Each entry gets a short key that subsequent instructions use to refer to that source. ErsatzTV resolves keys to real media collections at build time.

content:
  - show: ~
    key: simpsons
    order: chronological
    guids:
      - source: imdb
        value: tt0096697

  - show: ~
    key: futurama
    order: chronological
    guids:
      - source: tvdb
        value: "73871"

content:
  - collection: "80s Movies"
    key: eighties_movies
    order: shuffle

  - smart_collection: "Recent Comedies"
    key: recent_comedies
    order: chronological

content:
  - search: "Short Clips"
    key: filler
    query: "type:other_video duration:<5m"
    order: shuffle

  - playlist: "Friday Night Playlist"
    key: friday_night
    playlist_group: "Weekly Playlists"

content:
  - multi_collection: "Sci-Fi Block"
    key: scifi
    order: shuffle

  - marathon: ~
    key: anime_marathon
    group_by: show
    shuffle_groups: true
    item_order: chronological

Content Item Fields

Field	Applies To	Description
`key`	All	Short identifier referenced by instructions. Must be unique within the file.
`order`	Most types	Playback order: `chronological` or `shuffle`. These are the two values supported in YAML schedule content definitions.
`guids`	`show`, `marathon`	List of external ID sources (`imdb`, `tvdb`, `tmdb`) for reliable show matching.
`query`	`search`	A search query string (same syntax as ErsatzTV’s search interface).
`playlist_group`	`playlist`	The group name containing the referenced playlist.
`group_by`	`marathon`	Groups marathon content by `show`, `season`, `artist`, or `album`.
`shuffle_groups`	`marathon`	Shuffles the order of groups in a marathon.
`item_order`	`marathon`	Order of items within each group: `chronological` or `shuffle`.

Sequence Section

The sequence section defines reusable named instruction blocks that can be called from the playout section (or from other sequences via the pre_roll, mid_roll, and post_roll instructions). This avoids repeating the same filler logic in multiple places.

sequence:
  - key: bumpers
    items:
      - count: 1
        content: channel_bumper

  - key: promo_block
    items:
      - count: 2
        content: promos
        filler_kind: postroll

Reset Section

Instructions in the reset section run once when the playout is rebuilt from scratch (reset mode). A typical use is inserting a wait_until instruction so the playout always starts at a known wall-clock time, rather than wherever the previous cycle ended.

reset:
  - wait_until: "8:00am"
    tomorrow: false
    rewind_on_reset: true

rewind_on_reset: true allows the playout’s current time to move backward to the specified time when a reset occurs, so a playout that was ahead of schedule doesn’t create a gap.

Playout Section (Instructions)

The playout section is the main program loop. ErsatzTV executes these instructions in order and repeats them from the top each cycle. Every instruction can optionally reference a content key and set shared fields such as filler_kind, custom_title, and disable_watermarks.

Playback Instructions

playout:
  - count: 2
    content: simpsons

  - count: 1
    content: eighties_movies
    custom_title: "Tonight's Feature Film"

playout:
  - duration: "30 minutes"
    content: simpsons
    discard_attempts: 2
    offline_tail: false
    trim: false
    stop_before_end: true

playout:
  - all: ~
    content: simpsons

playout:
  - pad_to_next: 30
    content: filler
    filler_kind: postroll
    trim: true
    offline_tail: true

playout:
  - pad_until: "6:00am"
    content: filler
    tomorrow: true
    offline_tail: false

playout:
  - wait_until: "20:00"
    tomorrow: false
    rewind_on_reset: false

Instruction Reference

Instruction Key	Description
`count`	Play a specific number of items from the referenced content.
`duration`	Play content until a specified duration is filled (e.g., `"30 minutes"`, `"2 hours"`). Supports `trim`, `offline_tail`, `discard_attempts`, and `stop_before_end`.
`all`	Play every item in the referenced content collection once.
`pad_to_next`	Fill with content until the playout clock reaches the next multiple of the specified minute interval.
`pad_until`	Fill with content until a specific time of day. Set `tomorrow: true` to target that time on the next day if it has already passed.
`wait_until`	Insert unscheduled (offline) time until the specified time of day. Does not play any content.
`repeat`	When `repeat: true`, marks the end of the loop — ErsatzTV restarts the `playout` list from the top.
`rewind`	Resets the position of the specified content enumerator to its starting point.
`skip_items`	Advances the position of a content enumerator by a specified number of items without playing them.
`skip_to_item`	Advances a show’s enumerator to a specific `season` and `episode` number.

Roll and Watermark Instructions

Instruction Key	Description
`pre_roll: true` / `pre_roll: false`	Activates or deactivates the named pre-roll sequence before each content item. Specify a `sequence` key.
`mid_roll: true` / `mid_roll: false`	Activates or deactivates mid-roll break insertion. Specify a `sequence` key and an optional `expression` (defaults to `"true"`).
`post_roll: true` / `post_roll: false`	Activates or deactivates the named post-roll sequence after each content item.
`watermark: true`	Turns on the named channel watermark (specify `name`).
`watermark: false`	Turns off the named watermark, or all watermarks if no `name` is given.
`graphics_on`	Activates a named graphics element. Optionally supply a `variables` map for template substitution.
`graphics_off`	Deactivates a named graphics element, or all active elements if no name is given.

EPG Grouping Instructions

Instruction Key	Description
`epg_group: true`	Starts a new EPG guide group. Set `advance: false` to continue the existing group rather than opening a new one.
`epg_group: false`	Ends the current EPG group.

Alternate Schedules (Schedules Section)

The schedules section defines named alternate playout lists that activate on specific date ranges. When the current date falls within a schedule’s range, ErsatzTV executes that schedule’s playout instructions instead of the default list.

schedules:
  - name: Christmas
    start_date: "12-24"
    end_date: "12-26"
    priority: 10
    playout:
      - count: 1
        content: christmas_movie
      - pad_until: "23:59"
        content: holiday_music
        tomorrow: false

  - name: NYE
    start_date: "2025-12-31"
    end_date: "2026-01-01"
    priority: 20
    playout:
      - wait_until: "23:00"
      - count: 1
        content: nye_special
      - repeat: true

Date values can be either MM-DD (repeats annually) or YYYY-MM-DD (one-time specific year). Higher priority values win when multiple schedules overlap. Alternate schedules maintain their own instruction position state, so switching back and forth does not lose either list’s progress.

Imports

The import section lets you split a large schedule across multiple files:

import:
  - content-library.yaml
  - sequences/filler-sequences.yaml

Imported files can contribute content, sequence, reset, and playout entries. Content keys defined in the importing file take precedence over keys from imported files, preventing accidental overrides.

A Complete Example

content:
  - collection: "Feature Films"
    key: movies
    order: shuffle

  - search: "Short Bumpers"
    key: bumpers
    query: "type:other_video duration:<90s"
    order: shuffle

sequence:
  - key: channel_bumper
    items:
      - count: 1
        content: bumpers
        filler_kind: preroll

reset:
  - wait_until: "6:00am"
    tomorrow: false
    rewind_on_reset: true

playout:
  - pre_roll: true
    sequence: channel_bumper

  - epg_group: true
    advance: true

  - count: 1
    content: movies

  - epg_group: false

  - pad_to_next: 30
    content: bumpers
    filler_kind: postroll
    trim: true
    offline_tail: true

  - repeat: true

content:
  - show: ~
    key: tng
    order: chronological
    guids:
      - source: tvdb
        value: "71470"

  - search: "Trek Promos"
    key: promos
    query: "type:other_video tag:trek-promo"
    order: shuffle

reset:
  - wait_until: "18:00"
    rewind_on_reset: true

playout:
  - duration: "2 hours"
    content: tng
    discard_attempts: 3
    offline_tail: false
    stop_before_end: true

  - pad_to_next: 30
    content: promos
    filler_kind: postroll
    trim: true

  - wait_until: "18:00"
    tomorrow: true

  - repeat: true

Validating YAML Schedules

ErsatzTV includes a built-in YAML validator accessible from the UI. Navigate to Troubleshooting → YAML Validator, paste your YAML content, and click Validate. The validator checks the file against the official JSON Schema (sequential-schedule.schema.json) and reports any structural errors before the file is used in a playout build.

Use the built-in YAML Validator whenever you make changes to a schedule file. Syntax errors or unknown keys are reported immediately, avoiding a failed playout build at runtime.

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

YAML Schedules: Declarative Playout Definition

File Location and Playout Setup

YAML File Structure

Content Section

Content Item Fields

Sequence Section

Reset Section

Playout Section (Instructions)

Playback Instructions

Instruction Reference

Roll and Watermark Instructions

EPG Grouping Instructions

Alternate Schedules (Schedules Section)

Imports

A Complete Example

Validating YAML Schedules

​File Location and Playout Setup

​YAML File Structure

​Content Section

​Content Item Fields

​Sequence Section

​Reset Section

​Playout Section (Instructions)

​Playback Instructions

​Instruction Reference

​Roll and Watermark Instructions

​EPG Grouping Instructions

​Alternate Schedules (Schedules Section)

​Imports

​A Complete Example

​Validating YAML Schedules

File Location and Playout Setup

YAML File Structure

Content Section

Content Item Fields

Sequence Section

Reset Section

Playout Section (Instructions)

Playback Instructions

Instruction Reference

Roll and Watermark Instructions

EPG Grouping Instructions

Alternate Schedules (Schedules Section)

Imports

A Complete Example

Validating YAML Schedules