IPTV M3U Playlist Endpoint for ErsatzTV Legacy Channels

ErsatzTV Legacy exposes a standard M3U playlist at /iptv/channels.m3u that enumerates every enabled channel with its stream URL, channel number, name, group, logo, and a pointer to the XMLTV EPG feed. Any IPTV client that can consume an M3U URL — Plex, Jellyfin, Emby, Kodi, TiviMate, Infuse, VLC, or Channels DVR — can import this playlist and receive live, scheduled programming from ErsatzTV.

Playlist Endpoint

The playlist is served at:

GET /iptv/channels.m3u
HEAD /iptv/channels.m3u

Both GET and HEAD are supported. The HEAD method is useful for clients that check the playlist URL before importing it.

Query Parameters

Parameter	Default	Description
`mode`	`mixed`	Override the streaming mode for every channel in the playlist.
`access_token`	(none)	JWT bearer token passed as a query parameter when authentication is enabled.

Streaming Modes

The mode parameter controls which stream URL format appears for each channel entry. When mode=mixed (the default), ErsatzTV uses each channel’s individually configured streaming mode.

`mode` value	Stream URL format	Notes
`mixed`	Per-channel configured mode	Default; respects each channel’s own streaming mode setting
`ts`	`/iptv/channel/{number}.ts`	Transport Stream Hybrid (recommended TS mode)
`ts-legacy`	`/iptv/channel/{number}.ts?mode=ts-legacy`	Legacy concat-based Transport Stream
`segmenter`	`/iptv/channel/{number}.m3u8?mode=segmenter`	HLS segmenter (recommended HLS mode)
`hls-direct`	`/iptv/channel/{number}.m3u8?mode=hls-direct`	HLS direct passthrough

Use mode=ts or mode=segmenter to force all channels to a single streaming mode. This is helpful when your IPTV client handles one protocol better than another.

M3U Playlist Structure

The generated playlist begins with an #EXTM3U header that embeds the XMLTV EPG URL, then lists one entry per enabled channel, ordered by channel number ascending.

#EXTM3U url-tvg="http://ersatztv.local:8409/iptv/xmltv.xml" x-tvg-url="http://ersatztv.local:8409/iptv/xmltv.xml"
#EXTINF:0 tvg-id="C2.0.148.ersatztv.org" channel-id="ABC123==" channel-number="2.0" CUID="ABC123==" tvg-chno="2.0" tvg-name="Movies 24/7" tvg-logo="http://ersatztv.local:8409/iptv/logos/abc123.jpg" group-title="Movies" tvc-stream-vcodec="h264" tvc-stream-acodec="aac", Movies 24/7
http://ersatztv.local:8409/iptv/channel/2.0.ts
#EXTINF:0 tvg-id="C5.0.95.ersatztv.org" channel-id="DEF456==" channel-number="5.0" CUID="DEF456==" tvg-chno="5.0" tvg-name="News Loop" tvg-logo="http://ersatztv.local:8409/iptv/logos/gen?text=News%20Loop" group-title="News" tvc-stream-vcodec="h264" tvc-stream-acodec="aac", News Loop
http://ersatztv.local:8409/iptv/channel/5.0.m3u8?mode=segmenter

Per-Entry M3U Fields

Each #EXTINF line includes the following attributes:

Attribute	Description
`tvg-id`	Stable channel identifier, e.g. `C2.0.148.ersatztv.org`. Includes `ETV_INSTANCE_ID` when set.
`channel-id` / `CUID`	Base64-encoded channel UUID (URL-safe); stable across renames
`channel-number` / `tvg-chno`	Channel number (e.g. `2.0`, `5.1`)
`tvg-name`	Channel display name
`tvg-logo`	Logo URL (see Channel Logos below)
`group-title`	Channel group / category
`tvc-stream-vcodec`	Video codec reported to TiviMate and compatible clients
`tvc-stream-acodec`	Audio codec reported to TiviMate and compatible clients

Stream URLs

Each channel entry in the playlist points to one of the following stream endpoints depending on the streaming mode:

Transport Stream

TS Hybrid: /iptv/channel/{channelNumber}.tsTS Legacy: /iptv/channel/{channelNumber}.ts?mode=ts-legacyReturns an MPEG-2 Transport Stream (video/mp2t) via a spawned FFmpeg process. TS Hybrid uses a wrapped process for lower latency; TS Legacy uses the older concat playlist approach.

HTTP Live Streaming

Segmenter: /iptv/channel/{channelNumber}.m3u8?mode=segmenterHLS Direct: /iptv/channel/{channelNumber}.m3u8?mode=hls-directReturns an HLS multi-variant playlist (application/vnd.apple.mpegurl). The segmenter mode maintains a live HLS session. HLS Direct passes through source stream segments without re-encoding.

HDHomeRun Stream

/iptv/hdhr/channel/{channelNumber}.tsAlways delivers a Transport Stream regardless of channel configuration. Used by HDHomeRun-compatible clients that discover ErsatzTV via the HDHR emulation layer.

HLS Session Playlist

/iptv/session/{channelNumber}/hls.m3u8Internal endpoint used by segmenter sessions. The client is redirected here after a segmenter session starts. Not intended for direct use.

Channel Logos

Channel logos are served from:

GET /iptv/logos/{fileName}
GET /iptv/logos/{fileName}.jpg

If a channel has no logo artwork configured, ErsatzTV generates a text placeholder logo automatically:

/iptv/logos/gen?text={channelName}

Logo endpoints are exempt from JWT authentication even when JWT is enabled, because logos are also displayed in the ErsatzTV management UI.

Multi-Instance Disambiguation (ETV_INSTANCE_ID)

When running multiple ErsatzTV instances, the tvg-id field in the M3U playlist — and channel IDs in the XMLTV feed — would otherwise clash if two instances have channels with the same number. Setting the ETV_INSTANCE_ID environment variable gives each instance a unique suffix:

# Without ETV_INSTANCE_ID
tvg-id="C2.0.148.ersatztv.org"

# With ETV_INSTANCE_ID=home
tvg-id="C2.0.148.home.ersatztv.org"

The tvg-id in the M3U and the id attribute of <channel> elements in the XMLTV feed must match. ErsatzTV ensures they always match as long as ETV_INSTANCE_ID is consistent between restarts.

Kodi Integration

When ErsatzTV detects a Kodi user-agent, it automatically prepends #KODIPROP directives before each channel entry to configure the inputstream.ffmpegdirect addon:

Kodi-Specific Playlist Entries

#KODIPROP:inputstream=inputstream.ffmpegdirect
#KODIPROP:mimetype=video/mp2t
#KODIPROP:inputstream.ffmpegdirect.open_mode=ffmpeg
#EXTINF:0 tvg-name="Movies 24/7" ..., Movies 24/7
http://ersatztv.local:8409/iptv/channel/2.0.ts

The MIME type is set to video/mp2t for Transport Stream channels and application/x-mpegURL for HLS channels.

Client Configuration

Plex supports live TV through the Live TV & DVR section using either HDHR emulation (recommended) or a direct M3U import via a Plex plugin.

Navigate to Settings > Live TV & DVR in Plex Web.
Click Set Up Plex DVR and choose Network Tuner.
Enter the ErsatzTV HDHR discovery address (see HDHomeRun).
Alternatively, use a Plex IPTV plugin and provide the M3U URL:
```
http://ersatztv.local:8409/iptv/channels.m3u
```

Jellyfin supports M3U playlists natively through the Live TV plugin.

In the Jellyfin dashboard, go to Dashboard > Live TV.
Under TV Sources, click Add.

Set Type to M3U Tuner and enter the playlist URL:

http://ersatztv.local:8409/iptv/channels.m3u

For the EPG, add an XMLTV source pointing to:

http://ersatztv.local:8409/iptv/xmltv.xml

Emby supports live TV via M3U tuners in the Live TV section.

Open Settings > Live TV in Emby.
Click + Add under TV Sources.

Select M3U Tuner and provide:

http://ersatztv.local:8409/iptv/channels.m3u

Add the XMLTV guide URL under TV Guide Data Providers:
```
http://ersatztv.local:8409/iptv/xmltv.xml
```

Kodi uses the PVR IPTV Simple Client addon for M3U streams.

Install the PVR IPTV Simple Client from the Kodi addon repository.
Open the addon settings and set M3U Playlist URL to:
```
http://ersatztv.local:8409/iptv/channels.m3u
```

Set XMLTV URL to:

http://ersatztv.local:8409/iptv/xmltv.xml

Kodi’s user-agent starts with kodi, so ErsatzTV automatically adds #KODIPROP directives for inputstream.ffmpegdirect compatibility.

TiviMate is a popular Android-based IPTV player that supports M3U playlists.

Open TiviMate and go to Settings > Playlists.
Tap Add Playlist and select M3U playlist.

Enter the playlist URL:

http://ersatztv.local:8409/iptv/channels.m3u

TiviMate reads the embedded url-tvg from the #EXTM3U header and loads the XMLTV EPG automatically.

Channels DVR can use ErsatzTV either via HDHomeRun emulation or as a custom TV app source.

In Channels DVR, go to Sources and click Add Source.
Choose M3U Playlist (or use the HDHR tuner option — see HDHomeRun).

Enter the playlist URL:

http://ersatztv.local:8409/iptv/channels.m3u

Channels DVR picks up the url-tvg EPG reference from the #EXTM3U header automatically.

Replace ersatztv.local:8409 with the actual hostname or IP address and port where your ErsatzTV Legacy instance is running. The default port is 8409.

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

IPTV M3U Playlist Endpoint for ErsatzTV Legacy Channels

Playlist Endpoint

Query Parameters

Streaming Modes

M3U Playlist Structure

Per-Entry M3U Fields

Stream URLs

Transport Stream

HTTP Live Streaming

HDHomeRun Stream

HLS Session Playlist

Channel Logos

Multi-Instance Disambiguation (ETV_INSTANCE_ID)

Kodi Integration

Client Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

Documentation Index

​Playlist Endpoint

​Query Parameters

​Streaming Modes

​M3U Playlist Structure

​Per-Entry M3U Fields

​Stream URLs

Transport Stream

HTTP Live Streaming

HDHomeRun Stream

HLS Session Playlist

​Channel Logos

​Multi-Instance Disambiguation (ETV_INSTANCE_ID)

​Kodi Integration

​Client Configuration

Build docs developers (and LLMs) love

Playlist Endpoint

Query Parameters

Streaming Modes

M3U Playlist Structure

Per-Entry M3U Fields

Stream URLs

Channel Logos

Multi-Instance Disambiguation (ETV_INSTANCE_ID)

Kodi Integration

Client Configuration