Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ErsatzTV/legacy/llms.txt

Use this file to discover all available pages before exploring further.

Block schedules bring a template-based approach to channel programming. Instead of a single linear list of items, you define reusable Blocks that encapsulate a fixed duration of programming content, organize them into Templates that describe a full day’s schedule, and attach those templates to your playouts with flexible date-range rules. A separate Deco system lets you layer watermarks, filler, fallback content, and break material on top of any block-based playout without modifying the underlying blocks. This design makes it easy to build consistent channel grids and swap seasonal themes independently of your content structure.

​
Core Concepts

Blocks

A named, duration-based programming unit that contains one or more content items (BlockItems). Blocks are the reusable building blocks of your schedule.

Templates

A daily schedule layout that maps blocks to specific start times. Templates describe what your channel looks like on any given day.

Playout Templates

The rule that connects a playout to a template. Defines which days of the week, days of the month, and months of the year — or a hard date range — a template is active.

Decos

A decorative overlay configuration attached to a playout or template. Controls watermarks, filler, dead-air fallback, and break content independently of block content.

​
Blocks

A Block is the fundamental unit of block scheduling. Each block has:
FieldDescription
NameA human-readable label for the block (e.g., Prime Time Drama, Morning Cartoons).
MinutesThe total duration of the block in minutes. ErsatzTV schedules content within this window.
BlockGroupAn organizational container grouping related blocks together (e.g., Kids Blocks, Evening Blocks).
StopSchedulingControls whether content stops before or after the block’s duration end. AfterDurationEnd lets the last item play out; BeforeDurationEnd hard-stops at the boundary.
ItemsThe ordered list of BlockItem objects that define the content to play.
DateUpdatedTimestamp of the last modification, used by the playout engine to detect changes.

​
Block Items

Each BlockItem within a block references a content source and a playback order:
FieldDescription
IndexThe position of this item within the block’s item list.
CollectionTypeThe type of content: Collection, MultiCollection, SmartCollection, MediaItem, SearchQuery, etc.
PlaybackOrderHow items are selected from the collection (Chronological, SeasonEpisode, Shuffle, etc.).
IncludeInProgramGuideWhen enabled, this item’s content appears as a distinct entry in the EPG.
DisableWatermarksSuppresses all watermark overlays for this specific block item.
Watermarks / GraphicsElementsPer-item override watermarks and graphics elements applied while this item is playing.
Block items use the same PlaybackOrder enum as classic schedule items: Chronological, SeasonEpisode, Shuffle, ShuffleInOrder, MultiEpisodeShuffle, Random, RandomRotation, and Marathon.

​
Block Groups

A BlockGroup is a simple container with a Name and a collection of Block objects. Use block groups to organize your blocks by theme, daypart, or channel — for example, Daytime Blocks, Evening Blocks, and Weekend Blocks.

​
Templates

A Template defines a full day’s programming grid by mapping blocks to start times:
FieldDescription
NameA descriptive label (e.g., Standard Weekday, Saturday Morning).
TemplateGroupAn organizational container grouping related templates.
ItemsThe list of TemplateItem objects, each assigning a block to a start time.
DateUpdatedTimestamp used to detect template changes during playout rebuilds.

​
Template Items

Each TemplateItem binds a Block to a StartTime (a TimeSpan from midnight): 
TemplateItem:
  Block:     "Prime Time Drama"   → the block to play
  StartTime: 20:00:00             → when it starts on this day's template
Multiple TemplateItem entries form the daily grid. ErsatzTV works through them in start-time order and fills any gaps between items with the deco’s default filler or offline time.

​
Template Groups

A TemplateGroup organizes templates just as BlockGroup organizes blocks. Group templates by programming season, day type, or content category.

​
Playout Templates

A PlayoutTemplate is the rule that activates a template for a playout on specific dates. It implements the same IAlternateScheduleItem interface used by classic schedule alternates:
FieldDescription
TemplateThe template to activate when this rule matches.
DecoTemplateAn optional DecoTemplate that overrides the playout’s default deco configuration for this rule.
IndexPriority order when multiple rules match the same date (lower index wins).
DaysOfWeekWhich days of the week this rule applies to (Monday–Sunday).
DaysOfMonthWhich calendar days (1–31) this rule applies to.
MonthsOfYearWhich months (1–12) this rule applies to.
LimitToDateRangeWhen true, additionally constrains the rule to the specified start/end date.
StartMonth / StartDayInclusive start of the date range (month and day).
StartYearOptional year for the range start. When null, the rule applies to any year.
EndMonth / EndDayInclusive end of the date range (month and day).
EndYearOptional year for the range end. When null, the rule applies to any year.
Block schedule alternates work through the PlayoutTemplate list in Index order. The first matching rule wins. You can stack many PlayoutTemplate entries on a single playout to model complex seasonal programming calendars — for example, a Christmas special template that only applies December 25th of a specific year.

​
Playout History

ErsatzTV tracks which content has been played within each block using PlayoutHistory records. Each record stores:
  • The Block and PlaybackOrder associated with the history entry.
  • A Key that uniquely identifies the collection within the block, and an optional ChildKey for sub-collections (e.g., individual playlist items).
  • The Index within the collection where playback was last left off.
  • When the item last aired and Finish (when it ended), used to prune stale history efficiently.
  • Details serialized as JSON for richer per-item state.
This history allows block schedules to resume from the correct position in a collection across playout rebuilds, which is especially important for long-running series or shuffle-order collections that need to avoid repeating recent items.

​
Decos

A Deco is a named overlay configuration attached to a block-schedule playout. Decos separate the decoration of a channel (logos, bumpers, fallback content) from the programming (blocks and templates), allowing you to update the look and feel of a channel without touching any content items. Each Deco belongs to a DecoGroup and configures four overlay categories:

​
Watermarks

FieldDescription
WatermarkModeInherit, Disable, Override, or Merge — controls how this deco’s watermarks interact with item-level watermarks.
WatermarksThe list of ChannelWatermark overlays to display.
UseWatermarkDuringFillerWhen true, watermarks remain visible during filler content.

​
Graphics Elements

FieldDescription
GraphicsElementsModeInherit, Disable, Override, or Merge.
GraphicsElementsThe graphics elements (lower-thirds, bugs, tickers) to display.
UseGraphicsElementsDuringFillerWhen true, graphics remain active during filler.

​
Default Filler

The deco defines a default filler source that fills time gaps between block items and any unscheduled time in the template. This is controlled by a DefaultFillerMode (DecoMode) and configured with a DefaultFillerCollectionType, a reference to the filler collection, and a DefaultFillerTrimToFit flag that controls whether the filler clip is cut to exactly fit the gap.

​
Dead Air Fallback

A separate content source used when the channel would otherwise produce silence or a black screen. Controlled by a DeadAirFallbackMode (DecoMode) and configured with a DeadAirFallbackCollectionType and a reference to the fallback collection.

​
Break Content

Decos can insert break content between block items at configurable placement points. This section is governed by a BreakContentMode (DecoMode) field:
PlacementDescription
BlockStartBreak content plays at the beginning of a block.
BlockFinishBreak content plays at the end of a block.
BetweenBlockItemsBreak content is inserted between each item within the block.
ChapterMarkersBreak content is inserted at chapter marker boundaries within items.
Each DecoBreakContent entry specifies a collection source and a DecoBreakPlacement value.

​
Deco Mode Values

DecoMode controls how a deco’s configuration interacts with any configuration inherited from the playout or item level:
ModeBehavior
InheritUse the setting from the parent context (playout or item).
DisableExplicitly turn off this feature for this deco.
OverrideReplace the parent’s configuration entirely with this deco’s settings.
MergeCombine this deco’s settings with the parent’s configuration.

​
Deco Templates

A DecoTemplate defines a time-based deco schedule: it maps Deco objects to time windows within a day using DecoTemplateItem entries. Each DecoTemplateItem has a StartTime and EndTime, allowing you to, for example, apply a kids-channel deco from 6 AM to 7 PM and switch to an adult-oriented deco in the evening. DecoTemplate objects belong to a DecoTemplateGroup and are referenced by PlayoutTemplate records to activate a specific deco schedule alongside a content template.

​
Creating a Block Schedule

1

Create your blocks

Navigate to Scheduling → Blocks and click Add Block. Give it a name (e.g., Evening Movie) and set the Minutes (e.g., 120). Add one or more Block Items, each pointing to a collection and a playback order. Save the block.
2

Organize blocks into a group (optional)

Under Block Groups, create a group (e.g., Evening Blocks) and add your related blocks to it for easier navigation.
3

Create a template

Navigate to Scheduling → Templates and click Add Template. Name it (e.g., Standard Weekday). Add Template Items — for each item, select a block and a start time (e.g., Evening Movie at 20:00). Save the template.
4

Create a deco (optional)

Navigate to Scheduling → Decos and click Add Deco. Configure watermarks, default filler, dead-air fallback, and break content as needed. Save the deco.
5

Attach the template to your playout

Open your channel’s Playout configuration and switch to the Templates tab. Click Add Template Rule. Select your template, choose which days of the week it applies to, and optionally restrict it to a date range. If you created a deco or deco template, link it here as well. Set the Index (priority) if you have multiple rules.
6

Rebuild the playout

Save the playout configuration. ErsatzTV will rebuild the playout using your template and block definitions. The program guide will reflect the block-based schedule going forward.

​
Tips and Best Practices

Reuse blocks across templates

A single block (e.g., Morning News) can appear in multiple templates at different times. Changes to the block’s content immediately affect every template that references it.

Use BlockStopScheduling carefully

Set BeforeDurationEnd when you need hard time boundaries (e.g., a news block must end at the top of the hour). Use AfterDurationEnd for movie blocks where running a few minutes long is acceptable.

Layer decos for seasonal themes

Create separate decos for different seasons or holidays. Use PlayoutTemplate date-range rules to swap in the holiday deco without changing any block or template content.

Use DecoMode Merge for inherited watermarks

Set a channel-level watermark in the playout and use Merge in your deco to add a secondary logo on top, rather than replacing the base watermark entirely.

Build docs developers (and LLMs) love

Get started for freeTalk to us