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.
A channel in ErsatzTV is a virtual TV station that plays back a continuous or on-demand stream of media items to clients. Each channel has a number, a name, and a set of configuration options that control everything from how the video is transcoded to what happens when no one is watching. Channels are the top-level object you interact with when setting up ErsatzTV — they hold references to playouts, watermarks, filler presets, and streaming settings.
Channel Identity
Every channel has a number, a name, an optional group, and optional categories. The number must match the regex pattern ^[0-9]+(\.[0-9]{1,2})?$, which means it can be a whole number (e.g. 1, 42) or a sub-channel with up to two decimal digits (e.g. 2.1, 4.10). Sub-channel numbering is useful for organizing thematic variants of a parent channel — for example, 5 for a main channel and 5.1 for its classic-movies variant.
The group field is surfaced in M3U playlists and XMLTV guide data and lets clients (like Plex or Jellyfin) categorize channels in their guide UI. The categories field provides additional freeform tagging.
Each channel carries a UniqueId (Guid) that remains stable across restarts and is used in API references, as well as an internal integer Id and a computed SortNumber (double) used for consistent ordering in the guide.
FFmpeg Profile
Every channel must be associated with an FFmpegProfile, referenced by FFmpegProfileId. The FFmpeg profile defines the transcoding parameters for that channel — codec selection, resolution, bitrate, audio settings, and more. A channel cannot stream without a valid FFmpeg profile assigned.
Streaming Engine
ErsatzTV supports two streaming engines, controlled by the StreamingEngine property:
| Value | Integer | Description |
|---|
Legacy | 0 | The original ErsatzTV streaming engine, used by default for all existing channels. |
Next | 1 | The newer ErsatzTV Next engine, which offers additional capabilities and is under active development. |
Next engine, the NextEngineTextSubtitleMode property controls how text-based subtitles are handled:
| Value | Description |
|---|
Burn | Burns (hardsubs) text subtitles directly into the video stream. |
Convert | Converts text subtitles to image-based subtitles for side-carriage. |
Streaming Mode
The StreamingMode enum determines the container format and protocol used to deliver the stream to clients:
| Mode | Value | Description |
|---|
TransportStream | 1 | Classic MPEG Transport Stream (MPEG-TS). Compatible with the widest range of IPTV clients and hardware tuners. |
HttpLiveStreamingDirect | 2 | HLS delivered directly from media files without re-segmenting. Lower overhead for compatible clients. |
HttpLiveStreamingSegmenter | 4 | HLS with active FFmpeg segmentation. Produces proper .m3u8 playlists and .ts segments at runtime. |
TransportStreamHybrid | 5 | A hybrid Transport Stream mode that blends TS delivery with adaptive behavior. |
The value 999 (HttpLiveStreamingSegmenterLegacy) existed in earlier releases but has been removed from active use. If you see it referenced in old configuration data, it can be safely migrated to HttpLiveStreamingSegmenter.
Subtitle Handling
The SubtitleMode property (type ChannelSubtitleMode) controls which subtitles ErsatzTV selects and passes through when playing media:
| Mode | Description |
|---|
None | No subtitles are selected or burned. |
Forced | Only subtitles marked as “forced” in the media file are used. |
Default | Selects the default subtitle track as flagged by the media file. |
Any | Selects any available subtitle track, using the preferred language code as a hint. |
PreferredSubtitleLanguageCode (a BCP-47 language code such as en, fr, or es) to specify which language to prefer when multiple subtitle tracks are available.
Audio Settings
Use PreferredAudioLanguageCode (e.g. en, ja) and PreferredAudioTitle to influence audio stream selection when a media item has multiple audio tracks. These are passed down to individual playout items and respected during FFmpeg stream selection.
Watermarks and Fallback Filler
A channel can have an optional watermark (WatermarkId / Watermark) — an on-screen graphic overlay applied during playback by FFmpeg. Watermarks are defined globally and referenced by ID.
A fallback filler (FallbackFillerId / FallbackFiller) is a FillerPreset that plays when the playout has a gap and no other filler is available. This prevents dead air on the channel.
For configuration details, see Watermarks and Filler.
Music Videos and Song Video Modes
Two additional display modes affect specialized media types:
-
MusicVideoCreditsMode (ChannelMusicVideoCreditsMode): Controls whether credits subtitles are generated for music videos.
None — no credits subtitles are generated.GenerateSubtitles — ErsatzTV generates subtitle overlays from the music video’s artist and title metadata, using MusicVideoCreditsTemplate as the display template string.
-
SongVideoMode (ChannelSongVideoMode): Controls how song items (audio files played with a visual) are displayed.
Default — standard display.WithProgress — adds a progress bar overlay to the video.
Slug Seconds
The SlugSeconds property (double?) inserts a short segment of black video between consecutive playout items. This simulates the brief dead air traditionally found between TV programming segments. Set it to null to disable slugging entirely, or supply a decimal value (e.g. 2.0) for a two-second black slug.
Stream Selector
The StreamSelectorMode (ChannelStreamSelectorMode) and StreamSelector string together form a custom FFmpeg stream selection expression:
| Mode | Description |
|---|
Default | ErsatzTV’s built-in automatic stream selection logic. |
Custom | A user-supplied FFmpeg stream selector expression stored in StreamSelector. |
Troubleshooting | A diagnostic mode that overrides selection for debugging purposes. |
Transcode Mode
TranscodeMode is currently typed as ChannelTranscodeMode with a single value:
| Value | Description |
|---|
OnDemand | Transcoding is triggered on-demand when a client connects, rather than running continuously. |
Idle Behavior
IdleBehavior (ChannelIdleBehavior) controls what happens to the FFmpeg process when no client is actively watching:
| Behavior | Description |
|---|
StopOnDisconnect | The FFmpeg transcode process is terminated when the last viewer disconnects. This saves CPU and memory at the cost of a brief startup delay for the next viewer. |
KeepRunning | The transcode continues even with no active viewers. Useful for maintaining a live buffer or for channels used with hardware tuners that expect continuous streams. |
EPG Controls
IsEnabled: If false, the channel is disabled and will not appear in M3U or stream requests.ShowInEpg: If false, the channel is excluded from XMLTV guide output while still being accessible for streaming.PlayoutOffset (TimeSpan?): Shifts the EPG display times for this channel by a fixed offset. Useful when your media timestamps don’t align with real-world broadcast times and you want guide data to reflect a corrected time.
Playout Source and Mirror
The PlayoutSource (ChannelPlayoutSource) enum determines where the channel’s playout data comes from:
| Value | Description |
|---|
Generated | The playout is built locally by ErsatzTV from a schedule. |
Mirror | The playout mirrors another channel, referenced by MirrorSourceChannelId. |
PlayoutSource is Mirror, the channel plays back the exact same items as the source channel, which is useful for creating duplicate streams of the same content (e.g. East/West coast feeds).
Playout Mode
PlayoutMode (ChannelPlayoutMode) controls the overall scheduling mode for the channel:
| Mode | Description |
|---|
Continuous | The channel plays items continuously in a loop, following the assigned schedule. |
OnDemand | Items are queued up and played only when a client connects; the playout advances in real time based on viewer demand. |
Summary of Key Channel Properties
| Property | Type | Purpose |
|---|
Number | string | Channel number shown in guides and M3U |
Name | string | Display name of the channel |
Group | string | M3U group-title grouping |
Categories | string | Additional freeform category tags |
FFmpegProfileId | int | Links to transcoding settings |
StreamingEngine | StreamingEngine | Legacy or Next streaming engine |
StreamingMode | StreamingMode | TS, HLS direct, HLS segmenter, or hybrid |
SlugSeconds | double? | Black video slug between items |
WatermarkId | int? | On-screen watermark overlay |
FallbackFillerId | int? | Gap-filling preset |
SubtitleMode | ChannelSubtitleMode | Subtitle selection behavior |
PreferredSubtitleLanguageCode | string | BCP-47 language code for subtitle preference |
PreferredAudioLanguageCode | string | BCP-47 language code for audio track preference |
PreferredAudioTitle | string | Audio track title hint for selection |
MusicVideoCreditsMode | ChannelMusicVideoCreditsMode | Credits subtitle generation for music videos |
SongVideoMode | ChannelSongVideoMode | Display mode for audio song items |
StreamSelectorMode | ChannelStreamSelectorMode | Default, custom, or troubleshooting stream selection |
TranscodeMode | ChannelTranscodeMode | On-demand transcoding mode |
PlayoutSource | ChannelPlayoutSource | Generated locally or mirrored from another channel |
PlayoutMode | ChannelPlayoutMode | Continuous or on-demand playout behavior |
IsEnabled | bool | Enable/disable the channel |
ShowInEpg | bool | Include/exclude from guide |
PlayoutOffset | TimeSpan? | EPG time offset |
IdleBehavior | ChannelIdleBehavior | Behavior when no viewer is connected |
