Use this file to discover all available pages before exploring further.
ErsatzTV delivers its virtual TV channels over the network using one of four streaming modes. The mode you choose affects the URL clients use to tune in, how ErsatzTV manages the underlying FFmpeg process, and how well the stream will work with your specific media player or IPTV client. Each channel has its own streaming mode setting so you can mix and match across channels to suit different downstream clients.
Every channel also has a Streaming Engine setting separate from its streaming mode:
Value
Description
Legacy
The original ErsatzTV streaming engine. Default for all channels.
Next
The newer ErsatzTV Next engine. Opt-in per channel. Enables additional features such as configurable text subtitle handling (NextEngineTextSubtitleMode).
StreamingEngine.Next is an opt-in feature. Most channels should remain on Legacy unless you need a specific Next-engine capability such as subtitle conversion.
TransportStream (value 1) is the classic MPEG-TS over HTTP mode. ErsatzTV starts an FFmpeg concat process that stitches together scheduled media items into a continuous transport stream and pipes it directly to the HTTP response.URL:
When a client requests the .ts URL without an explicit mode query parameter, and the channel’s streaming mode is TransportStream, ErsatzTV uses the ts-legacy mode internally (the concat-based pipeline).Characteristics:
Single persistent FFmpeg process per active viewer
No session management overhead
Seamless playout continuity — the stream never pauses between items
Compatible with virtually all IPTV clients, HDHomeRun network tuners, and Plex Live TV
When to use:
Plex DVR / Live TV integration
HDHomeRun-style clients
Any IPTV client that does not support HLS
When you need maximum compatibility over adaptive bitrate features
TransportStreamHybrid (value 5) is a newer MPEG-TS mode that uses the same .ts URL but routes through ErsatzTV’s updated processing path (GetWrappedProcessByChannelNumber). It is the recommended TS mode for channels running the Next streaming engine.URL:
When a client requests the .ts URL without an explicit mode query parameter and the channel is configured as TransportStreamHybrid, ErsatzTV sets mode=ts internally (the wrapped / hybrid pipeline).Characteristics:
Same client-facing URL as TransportStream
Updated internal pipeline with improved filter graph handling
Compatible with the same IPTV clients as TransportStream
When to use:
Channels configured with StreamingEngine.Next
When you want TS output with the improved processing path
HttpLiveStreamingSegmenter (value 4) is ErsatzTV’s full HLS implementation. When a client connects, ErsatzTV starts a dedicated FFmpeg session that writes HLS .ts segments and a playlist to disk. The client receives a multi-variant .m3u8 playlist and downloads segments as they are produced.URLs:
# Entry point — starts or attaches to the sessionhttp://<host>:<port>/iptv/channel/{channelNumber}.m3u8# Live segment playlist (served once the session is running)http://<host>:<port>/iptv/session/{channelNumber}/hls.m3u8
ErsatzTV redirects clients from the entry-point URL to the live playlist once the session is up.Characteristics:
One shared FFmpeg session per channel (all viewers share the same transcode)
Supports pause, seek, and time-shift within the DVR window
Segments are stored temporarily on disk; disk I/O is required
Session starts when the first client connects and continues until the last client disconnects (or it is manually stopped)
Compatible with Apple HLS players, VLC, Jellyfin, Emby, web browsers
Session lifecycle:
1
Client connects
The client requests /iptv/channel/{number}.m3u8. ErsatzTV checks whether a session is already running for that channel.
2
Session starts
If no session exists, ErsatzTV starts an FFmpeg segmenter process. The client is redirected to the live playlist URL.
3
Segments consumed
FFmpeg writes .ts segments continuously. ErsatzTV trims the playlist to keep only recent segments (approximately 30 seconds of buffer).
4
Session ends
When no clients have requested the playlist for a configurable idle period, ErsatzTV stops the FFmpeg process and cleans up segments.
Managing sessions via API:
Method
Endpoint
Description
GET
/api/sessions
List all active HLS segmenter sessions
DELETE
/api/session/{channelNumber}
Stop a specific channel’s session
When to use:
Jellyfin, Emby, or Plex Media Server Live TV with HLS support
Web browser-based playback
When you need DVR-style time-shifting
Multi-client scenarios (one transcode serves all viewers)
HttpLiveStreamingDirect (value 2) is a low-overhead HLS passthrough mode. ErsatzTV serves the source media’s HLS playlist or remuxes to HLS without full transcoding. This mode is intended for scenarios where the source content is already in a compatible format and you want to minimise CPU load.URL:
When the channel is configured as HttpLiveStreamingDirect and a client requests the .m3u8 URL without a mode parameter, ErsatzTV sets mode=hls-direct automatically.Characteristics:
Minimal CPU usage — avoids full re-encode when possible
Lower latency than the segmenter (no write-to-disk pipeline)
Source codec compatibility required — the client must be able to decode whatever the source contains
No DVR time-shifting
When to use:
Source media is already H.264/AAC in a compatible container
You want the lowest possible CPU overhead
The downstream client supports HLS natively
HLS Direct mode does not apply the FFmpeg profile’s normalisation or transcoding settings when the source format is already compatible. If your source content uses incompatible codecs, ErsatzTV will still transcode to produce a valid HLS stream.
When a channel uses StreamingEngine.Next, the NextEngineTextSubtitleMode channel setting controls how text-based subtitles (SRT, ASS, WebVTT) are processed:
Value
Behaviour
Burn
Subtitles are burned (composited) into the video frames. Works with all players; cannot be toggled off by the viewer.
Convert
Subtitles are converted to a compatible passthrough format where possible. Players that support embedded subtitle tracks can display or hide them.
This setting is only relevant for the Next engine and has no effect on channels using StreamingEngine.Legacy.
