ErsatzTV provides two complementary systems for polishing your virtual TV channels: watermarks add persistent or intermittent image overlays (channel logos, bug graphics, clocks) directly into the video stream, while filler presets define libraries of content — pre-rolls, post-rolls, bumpers, tail clips, and fallback loops — that fill the gaps between scheduled items. Together they let you create a broadcast-quality experience with branded visuals and seamless transitions even when your schedule has uneven content durations.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.
Watermarks require either a custom image file uploaded to ErsatzTV or a channel logo already configured on the channel. Without an image source the watermark overlay will not render.
Watermarks
AChannelWatermark is a named, reusable overlay configuration. A single watermark record can be assigned to a channel (applied to all content on that channel) or overridden on individual schedule items, block items, or Deco configurations.
Watermark Fields
A label for this watermark (e.g.
Channel 5 Bug, Network Logo). Used in dropdowns throughout the UI.Controls when the watermark is visible.
| Value | Behaviour |
|---|---|
None | Watermark is disabled; no overlay is rendered |
Permanent | Watermark is always visible for the entire duration of every item |
Intermittent | Watermark appears periodically; controlled by FrequencyMinutes and DurationSeconds |
OpacityExpression | Watermark opacity is driven by a custom expression (see OpacityExpression) |
Selects where the overlay image comes from.
| Value | Description |
|---|---|
Custom | Use the image file uploaded to ErsatzTV (stored in the Image field) |
ChannelLogo | Use the channel’s own logo artwork (configured on the channel record) |
Resource | Internal use; reserved for system-generated graphics (value 100) |
Relative path or identifier of the custom image file. Only used when
ImageSource is Custom. Supported formats: PNG, JPEG, GIF (static frame only).Screen position of the watermark overlay.
| Value | Position |
|---|---|
BottomRight | Bottom-right corner (default) |
BottomLeft | Bottom-left corner |
TopRight | Top-right corner |
TopLeft | Top-left corner |
TopMiddle | Top centre |
RightMiddle | Centre-right |
BottomMiddle | Bottom centre |
LeftMiddle | Centre-left |
MiddleCenter | Dead centre of the frame |
How the watermark image dimensions are interpreted.
| Value | Behaviour |
|---|---|
Scaled | The image is scaled relative to the video frame using WidthPercent |
ActualSize | The image is rendered at its native pixel dimensions |
When
Size is Scaled, this is the watermark width as a percentage of the output video width (e.g. 10.0 = 10% of frame width). The height is scaled proportionally.Distance from the nearest horizontal edge, expressed as a percentage of the frame width. Used to inset the logo away from the frame edge.
Distance from the nearest vertical edge, expressed as a percentage of the frame height.
For
Intermittent mode: the interval in minutes between watermark appearances.For
Intermittent mode: how many seconds the watermark remains visible each time it appears.Fixed opacity of the watermark as a percentage.
100 = fully opaque. 0 = invisible (but still processed). Overridden by OpacityExpression when Mode is OpacityExpression.A dynamic expression evaluated per frame to determine watermark opacity. Used with
Mode = OpacityExpression for fade-in/fade-out effects. Expressions follow FFmpeg’s enable expression syntax relative to the media item’s timestamp.When
true, the watermark is composited inside the active picture area of the source video (respecting letterbox/pillarbox padding). When false, it is placed over the full output frame including padding bars.Z-order for layering multiple watermarks. Higher values appear on top of lower values when two overlays occupy the same screen region.
Assigning Watermarks
Watermarks can be attached at multiple levels, with more specific assignments overriding broader ones:Channel-level watermark
Go to Channels, edit a channel, and set the Watermark field. This watermark applies to all content playing on that channel unless overridden.
Schedule item watermark
In a programme schedule, individual items can specify their own watermark. This overrides the channel-level watermark for the duration of that item.
Deco watermark
Deco configurations (see Decos below) can define a watermark that applies to all items in the Deco’s scope, with
DecoMode controlling whether it is inherited, disabled, or merged with other watermarks.Filler Presets
AFillerPreset defines a named collection of media content and rules for how ErsatzTV should select and insert that content to fill time gaps in the schedule. Filler can pad to exact minute boundaries, add a fixed number of clips, or play tail content after the main item finishes.
FillerPreset Fields
A label for this preset (e.g.
30-Second Commercials, Movie Bumpers, Dead Air Loop).The role this filler plays in the playout.
| Value | Description |
|---|---|
None | No specific role; generic filler |
PreRoll | Inserted before the main programme item begins |
MidRoll | Inserted at chapter markers or mid-points during the item |
PostRoll | Inserted immediately after the main programme item ends |
Tail | Short content appended to fill out a time slot to the next item’s start |
Fallback | Played when no scheduled content is available (dead air prevention) |
GuideMode | Internal guide generation mode (value 99); not for general use |
DecoDefault | Default filler for Deco configurations (value 100) |
Determines how much filler content is inserted each time the preset fires.
| Value | Description |
|---|---|
None | Mode is unset |
Duration | Insert filler until the total filler duration equals Duration |
Count | Insert exactly Count items from the collection |
Pad | Insert filler to pad the schedule to the next PadToNearestMinute boundary |
RandomCount | Insert a random number of items up to Count |
Target duration for
FillerMode.Duration. ErsatzTV inserts items from the filler collection until this total duration is reached.Number of items for
FillerMode.Count and upper bound for FillerMode.RandomCount.Used with
FillerMode.Pad. ErsatzTV pads to the nearest multiple of this many minutes (e.g. 5 pads to the next 5-minute boundary).When
true, the channel watermark is displayed during filler content. When false, the watermark is suppressed for filler items.The kind of media collection from which filler items are drawn.
A custom scripted expression for advanced filler selection logic.
When
true, individual chapter markers within a media file are treated as separate filler items, allowing fine-grained padding with a single multi-chapter file.Filler Attachment Points
Filler presets are attached to channels and schedule items at several levels:Channel Fallback Filler
Set on the Channel record (
FallbackFillerId). Plays continuously when there is no scheduled content — prevents dead air on the channel. Assign a looping collection or long-duration media as the fallback.Schedule Item Filler
Attached directly to individual programme schedule items. Controls pre-roll, post-roll, or tail content specific to that item’s time slot.
Create a Filler Preset
Go to Filler Presets and click Add Filler Preset. Choose
Fallback as the FillerKind, set the collection, and configure FillerMode (typically Pad or Duration).Decos
Decos are decoration configuration objects that can be applied to block-based playouts. A Deco bundles together a watermark, graphics elements, default filler, dead-air fallback, and break content into one reusable unit. Decos are organised into Deco Groups and assigned to block playouts.Deco Fields
| Section | Field | Description |
|---|---|---|
| Watermark | WatermarkMode | DecoMode — whether to inherit, disable, override, or merge the watermark |
UseWatermarkDuringFiller | Whether the Deco watermark should also appear during filler items | |
| Graphics | GraphicsElementsMode | DecoMode — controls graphics element overlay inheritance |
UseGraphicsElementsDuringFiller | Whether graphics elements show during filler | |
| Default filler | DefaultFillerMode | DecoMode — inherit, disable, override, or merge default filler |
DefaultFillerTrimToFit | Trim the filler item to fit exactly into the remaining gap | |
| Dead-air fallback | DeadAirFallbackMode | DecoMode — controls what plays on dead air within this Deco scope |
| Break content | BreakContentMode | DecoMode — controls break content insertion |
DecoMode Values
| Value | Description |
|---|---|
Inherit | Use the setting from the parent scope (channel or schedule default) |
Disable | Explicitly suppress this Deco feature |
Override | Replace any inherited setting with this Deco’s own value |
Merge | Combine this Deco’s value with the inherited value (e.g. merge watermark lists) |
Break Content
DecoBreakContent defines media inserted at break points within a block. Each break-content entry references a media collection and a DecoBreakPlacement:
DecoBreakPlacement | Description |
|---|---|
BlockStart | Insert break content at the very beginning of the block |
BlockFinish | Insert break content at the very end of the block |
BetweenBlockItems | Insert break content between every pair of block items |
ChapterMarkers | Insert break content at chapter marker points within items |
Graphics Elements
AGraphicsElement is an overlay asset (image, text, subtitle, motion graphic, or script) that can be composited on top of video output. Graphics elements are more flexible than watermarks — they support different rendering kinds and can be attached to schedule items, block items, or Deco configurations.
GraphicsElementKind Values
| Value | Description |
|---|---|
Image | Static image file overlay (PNG, JPEG) |
Text | Dynamic text rendered over the video |
Subtitle | Subtitle-styled overlay |
Motion | Animated overlay (motion graphic file) |
Script | Script-driven overlay with dynamic content |
ProgramScheduleItemGraphicsElements relationship, or with Decos via DecoGraphicsElements.
Slug Seconds
Slug seconds is a per-channel setting that inserts a brief black video segment between consecutive playout items. This mimics the brief cut-to-black seen between segments on traditional broadcast television.- Set on the
Channelrecord asSlugSeconds(typedouble?). - A value of
nullor0disables slug insertion. - Typical values:
0.5–2.0seconds. - During the slug, the channel produces silent black frames, so watermarks and graphics elements are suppressed.
FFmpeg Profiles
Configure the transcoding settings that apply watermark filters to the video stream.
Streaming Modes
Understand how watermarks and filler are included in each streaming output mode.