Skip to main content
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: When using the Next engine, the NextEngineTextSubtitleMode property controls how text-based subtitles are handled:

​
Streaming Mode

The StreamingMode enum determines the container format and protocol used to deliver the stream to clients:
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.
For a detailed guide on choosing the right mode for your setup, see Streaming Modes.

​
Subtitle Handling

The SubtitleMode property (type ChannelSubtitleMode) controls which subtitles ErsatzTV selects and passes through when playing media: Use 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:

​
Transcode Mode

TranscodeMode is currently typed as ChannelTranscodeMode with a single value:

​
Idle Behavior

IdleBehavior (ChannelIdleBehavior) controls what happens to the FFmpeg process when no client is actively watching:

​
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: When 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:

​
Summary of Key Channel Properties