Scripted Schedule API — Programmatic Playout Building

The Scripted Schedule API is invoked by the ErsatzTV scripted schedule engine when building a playout for a channel that uses a Python script. Each playout build gets a unique buildId UUID, and all endpoints for that build are rooted at /api/scripted/playout/build/{buildId}/. The API mirrors the scripted playout’s operation sequence: first declare content sources, then place items into the schedule using timing controls, and optionally configure EPG grouping, graphics, and watermarks.

These endpoints are consumed by the etv_client Python library, which is imported inside a scripted schedule script. You do not typically call them directly. See Scripted Schedules for the Python-level API.

Common Path Parameter

Every endpoint below shares this path parameter as part of its base route:

string (uuid)

required

A UUID that uniquely identifies the current playout build session. Generated by ErsatzTV when the scripted schedule engine starts a build.

Context

GET /context

Returns the current state of the playout build. Operation ID: GetContext. Returns a PlayoutContext object.

curl "http://localhost:8409/api/scripted/playout/build/550e8400-e29b-41d4-a716-446655440000/context"

{
  "currentTime": "2024-11-15T08:00:00+00:00",
  "startTime": "2024-11-15T06:00:00+00:00",
  "finishTime": "2024-11-16T06:00:00+00:00",
  "isDone": false
}

string (date-time)

required

The current scheduling cursor position within the playout build. This advances as content is added.

string (date-time)

required

The start time of this playout build window.

string (date-time)

required

The end time of this playout build window. The build is complete when currentTime reaches finishTime.

boolean

required

true when currentTime has reached or passed finishTime, indicating the playout build is complete.

Content Addition

Content addition endpoints register a named content source (identified by a key) against a library object — a collection, show, smart collection, search query, or playlist. Once registered, the key is used in scheduling operations to reference that content.

POST /add_collection

Registers a manual collection as a named content source. Operation ID: AddCollection.

string

required

Unique name used to reference this content throughout the scripted schedule (e.g. "action_movies").

string

required

The name of an existing manual collection in ErsatzTV.

string

Playback order for items in the collection. Supported values: Chronological, Shuffle.

curl -X POST "http://localhost:8409/api/scripted/playout/build/{buildId}/add_collection" \
  -H "Content-Type: application/json" \
  -d '{"key": "action", "collection": "Action Movies", "order": "Shuffle"}'

POST /add_marathon

Registers a marathon content source that groups content from multiple GUIDs and/or search queries. Operation ID: AddMarathon.

string

required

Unique name used to reference this content.

string

required

How to group the combined content. Valid values: show, season, artist, album.

string

Playback order within each group. Supported values: Chronological, Shuffle.

object

Dictionary of external content identifiers ({ "imdb": ["tt0111161", "tt0068646"] }).

array of strings

List of search query strings to include in the marathon.

boolean

When true, plays all items from one group before advancing to the next. When false, plays one item from each group in rotation.

boolean

When true, randomizes the order of groups.

POST /add_multi_collection

Registers an existing multi-collection as a named content source. Operation ID: AddMultiCollection.

string

required

Unique name used to reference this content.

string

required

The name of the existing multi-collection in ErsatzTV.

string

Playback order. Supported values: Chronological, Shuffle.

POST /add_playlist

Registers an existing playlist as a named content source. Operation ID: AddPlaylist.

string

required

Unique name used to reference this content.

string

required

The name of the existing playlist in ErsatzTV.

string

required

The name of the playlist group that contains the named playlist.

POST /create_playlist

Creates a new ad-hoc playlist inline and registers it as a named content source. Unlike add_playlist, this endpoint constructs the playlist from a list of (content key, count) pairs rather than referencing an existing playlist by name. Operation ID: CreatePlaylist.

string

required

Unique name used to reference this content throughout the scripted schedule.

array of objects

required

Ordered list of playlist items. Each item specifies a content key and how many items to draw from it.Item fields:

content (string, required) — the key of a previously registered content source.
count (integer, required) — how many items to take from that content source per playlist cycle.

curl -X POST "http://localhost:8409/api/scripted/playout/build/{buildId}/create_playlist" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "rotation",
    "items": [
      {"content": "action_movies", "count": 2},
      {"content": "commercials", "count": 1}
    ]
  }'

Returns 200 OK on success, or 404 Not Found if the buildId is not active.

POST /add_search

Registers a search query as a named content source. Operation ID: AddSearch.

string

required

Unique name used to reference this content.

string

required

The ErsatzTV search query string (e.g. genre:Action year:>2010 type:movie).

string

Playback order. Supported values: Chronological, Shuffle.

POST /add_smart_collection

Registers an existing smart collection as a named content source. Operation ID: AddSmartCollection.

string

required

Unique name used to reference this content.

string

required

The name of the existing smart collection in ErsatzTV.

string

Playback order. Supported values: Chronological, Shuffle.

POST /add_show

Registers a show (identified by external GUIDs) as a named content source. Operation ID: AddShow.

string

required

Unique name used to reference this content.

object

required

Dictionary mapping provider name to GUID value (e.g. {"imdb": "tt0903747"}).

string

Playback order. Supported values: Chronological, Shuffle.

POST /add_all

Adds all remaining items from the named content source into the schedule. Returns the updated PlayoutContext. Operation ID: AddAll.

string

required

The key of the content source to add.

string

Marks the scheduled items as a specific filler type, influencing EPG grouping. Valid values correspond to FillerKind enum entries.

string

Overrides the EPG title for all added items.

boolean

When true, disables watermarks for these scheduled items.

POST /add_count

Adds a specific number of items from the named content source. Returns the updated PlayoutContext. Operation ID: AddCount.

string

required

The key of the content source.

integer

required

Number of items to add from the content source.

string

Optional filler kind for EPG grouping.

string

Optional EPG title override.

boolean

Disable watermarks for these items.

POST /add_duration

Adds content from the named source until a specified duration is filled. Returns the updated PlayoutContext. Operation ID: AddDuration.

string

required

The key of the content source.

string

required

The amount of time to fill (e.g. "01:00:00" for one hour).

string

Content key used to fill remaining unscheduled time. One item is looped and trimmed to fit exactly.

boolean

When true, the last item is trimmed to fit exactly within the specified duration.

integer

When trim is false, the number of items to discard when searching for one that fits.

boolean

When false, allows the last item to run over the specified duration.

boolean

When true, remaining time after the last fitting item is left as offline (unscheduled).

string

Optional filler kind for EPG grouping.

string

Optional EPG title override.

boolean

Disable watermarks for these items.

Timing Control

Timing endpoints advance or hold the scheduling cursor to precise points in time, padding schedules with content or leaving gaps.

POST /pad_to_next

Adds content until the next occurrence of a specific minute interval (e.g. the next :00, :30, or :15 boundary). Returns the updated PlayoutContext. Operation ID: PadToNext.

string

required

The key of the content source to use for padding.

integer

required

The minute interval to pad to (e.g. 30 means pad to the next half-hour boundary).

string

Fallback content key for exact-fit filling.

boolean

Trim the last item to fit the interval boundary exactly.

integer

Number of items to discard when searching for a fitting item (when trim is false).

boolean

When false, allows overrun of the interval boundary.

boolean

Leave remaining time after fitting items as offline.

string

Filler kind for EPG grouping.

string

EPG title override.

boolean

Disable watermarks.

POST /pad_until

Adds content until a specified time of day. Returns the updated PlayoutContext. Operation ID: PadUntil.

string

required

The key of the content to use for padding.

string

required

Time of day to pad until (e.g. "22:00:00").

boolean

When true and the current time is already past when, pads until that time the following day. When false, no items are added.

string

Fallback content for exact-fit filling.

boolean

Trim the last item to fit exactly.

integer

Items to discard when searching for a fit.

boolean

Allow overrun of the target time.

boolean

Leave remaining time offline.

string

Filler kind for EPG grouping.

string

EPG title override.

boolean

Disable watermarks.

POST /pad_until_exact

Adds content until an exact datetime. Returns the updated PlayoutContext. Operation ID: PadUntilExact.

string

required

The key of the content to use for padding.

string (date-time)

required

The exact ISO 8601 datetime to pad until.

string

Fallback content for exact-fit filling.

boolean

Trim the last item to fit exactly.

integer

Items to discard when searching for a fit.

boolean

Allow overrun of the target time.

boolean

Leave remaining time offline.

string

Filler kind for EPG grouping.

string

EPG title override.

boolean

Disable watermarks.

POST /wait_until

Inserts unscheduled (offline) time until the specified time of day. Returns the updated PlayoutContext. Operation ID: WaitUntil.

string

required

The time of day to wait until (e.g. "06:00:00"). Parsed as TimeOnly.

boolean

When true, if when has already passed, wait until that time the next day.

boolean

When true, the playout cursor is allowed to move backward when the playout is reset.

POST /wait_until_exact

Inserts unscheduled time until an exact datetime. Returns the updated PlayoutContext. Operation ID: WaitUntilExact.

string (date-time)

required

The exact ISO 8601 datetime to wait until.

boolean

When true, allows the cursor to rewind on playout reset.

GET /peek_next/

Returns the duration of the next item from a named content source without advancing the scheduling cursor. Useful for making conditional scheduling decisions in a script. Operation ID: PeekNext.

string

required

The key of the content source to peek at.

curl "http://localhost:8409/api/scripted/playout/build/{buildId}/peek_next/action_movies"

{
  "content": "action_movies",
  "milliseconds": 6840000
}

string

required

The content key that was peeked.

integer (int64)

required

Duration of the next item in milliseconds.

Returns 404 Not Found if the content key does not exist or the collection is empty.

POST /skip_items

Skips a specific number of items in a content source without scheduling them. Operation ID: SkipItems.

string

required

The key of the content source.

integer

required

The number of items to skip.

POST /skip_to_item

Advances the position in a content source to a specific season and episode. Operation ID: SkipToItem.

string

required

The key of the content source (must reference a show).

integer

required

The target season number.

integer

required

The target episode number within the season.

EPG & Overlays

POST /start_epg_group

Starts a new EPG group, causing subsequent scheduled items to be grouped together as a single logical program in the Electronic Programme Guide. Operation ID: StartEpgGroup.

boolean

When true, starts a new EPG group. When false, continues within the current group.

string

Custom title to apply to all items within this EPG group.

POST /stop_epg_group

Closes the current EPG group. Items scheduled after this call will start a new group in the EPG. Operation ID: StopEpgGroup. No request body required.

POST /graphics_on

Enables one or more named graphics elements (on-screen overlays) for subsequently scheduled items. Operation ID: GraphicsOn.

array of strings

required

List of graphics element names to activate.

object

Key-value pairs that are passed as variables to the graphics elements (e.g. for templated overlays).

POST /graphics_off

Disables one or more named graphics elements. Operation ID: GraphicsOff.

array of strings

List of graphics element names to deactivate. If null or empty, all graphics elements are turned off.

POST /watermark_on

Activates one or more named watermarks for subsequently scheduled items. Operation ID: WatermarkOn.

array of strings

required

List of existing watermark names to turn on.

POST /watermark_off

Deactivates one or more named watermarks. Operation ID: WatermarkOff.

array of strings

List of watermark names to turn off. If null or empty, all scripted watermarks are turned off.

POST /pre_roll_on

Activates a pre-roll playlist, causing the named playlist to play before each subsequent content item. Operation ID: PreRollOn.

string

required

The key of a scripted playlist to use as pre-roll.

POST /pre_roll_off

Deactivates the active pre-roll playlist. No request body required. Operation ID: PreRollOff.

PlayoutContext Fields (Shared Response)

Many scheduling endpoints return a PlayoutContext representing the updated build state after the operation:

string (date-time)

required

Updated scheduling cursor position after this operation completed.

string (date-time)

required

Start of the build window (unchanged by scheduling operations).

string (date-time)

required

End of the build window (unchanged by scheduling operations).

boolean

required

true when currentTime has reached finishTime.

Overview

Endpoints

Scripted Schedule API — Programmatic Playout Building

Common Path Parameter

Context

GET /context

Content Addition

POST /add_collection

POST /add_marathon

POST /add_multi_collection

POST /add_playlist

POST /create_playlist

POST /add_search

POST /add_smart_collection

POST /add_show

POST /add_all

POST /add_count

POST /add_duration

Timing Control

POST /pad_to_next

POST /pad_until

POST /pad_until_exact

POST /wait_until

POST /wait_until_exact

GET /peek_next/

Navigation

POST /skip_items

POST /skip_to_item

EPG & Overlays

POST /start_epg_group

POST /stop_epg_group

POST /graphics_on

POST /graphics_off

POST /watermark_on

POST /watermark_off

POST /pre_roll_on

POST /pre_roll_off

PlayoutContext Fields (Shared Response)

​Common Path Parameter

​Context

​GET /context

​Content Addition

​POST /add_collection

​POST /add_marathon

​POST /add_multi_collection

​POST /add_playlist

​POST /create_playlist

​POST /add_search

​POST /add_smart_collection

​POST /add_show

​POST /add_all

​POST /add_count

​POST /add_duration

​Timing Control

​POST /pad_to_next

​POST /pad_until

​POST /pad_until_exact

​POST /wait_until

​POST /wait_until_exact

​GET /peek_next/

​Navigation

​POST /skip_items

​POST /skip_to_item

​EPG & Overlays

​POST /start_epg_group

​POST /stop_epg_group

​POST /graphics_on

​POST /graphics_off

​POST /watermark_on

​POST /watermark_off

​POST /pre_roll_on

​POST /pre_roll_off

​PlayoutContext Fields (Shared Response)

Common Path Parameter

Context

GET /context

Content Addition

POST /add_collection

POST /add_marathon

POST /add_multi_collection

POST /add_playlist

POST /create_playlist

POST /add_search

POST /add_smart_collection

POST /add_show

POST /add_all

POST /add_count

POST /add_duration

Timing Control

POST /pad_to_next

POST /pad_until

POST /pad_until_exact

POST /wait_until

POST /wait_until_exact

GET /peek_next/

Navigation

POST /skip_items

POST /skip_to_item

EPG & Overlays

POST /start_epg_group

POST /stop_epg_group

POST /graphics_on

POST /graphics_off

POST /watermark_on

POST /watermark_off

POST /pre_roll_on

POST /pre_roll_off

PlayoutContext Fields (Shared Response)