Skip to main content

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.

ErsatzTV Legacy generates a full Electronic Program Guide (EPG) in XMLTV format and serves it at /iptv/xmltv.xml. IPTV clients use this feed to display program titles, descriptions, start and end times, and other scheduling metadata in their guide grids. ErsatzTV builds the XMLTV data from active playout schedules and caches the result for fast delivery.

​
EPG Endpoint

The XMLTV guide is served at: 
GET /iptv/xmltv.xml
HEAD /iptv/xmltv.xml
Both GET and HEAD are supported. The HEAD method is useful for verifying that the endpoint is reachable before subscribing a client.

​
Query Parameters

ParameterDefaultDescription
access_token(none)JWT bearer token passed as a query parameter when authentication is enabled.
When authentication is enabled and an access_token is provided, ErsatzTV embeds the token inside the logo URLs within the XMLTV document so that clients that fetch artwork do not need a separate auth step.

​
XMLTV Document Structure

The XMLTV document is a standard XML file with a root <tv> element. It contains one <channel> element per enabled channel followed by <programme> elements representing scheduled items.
Example XMLTV Response
<?xml version="1.0" encoding="utf-8"?>
<tv generator-info-name="ersatztv">
  <channel id="C2.0.148.ersatztv.org">
    <display-name>Movies 24/7</display-name>
    <icon src="http://ersatztv.local:8409/iptv/logos/abc123.jpg" />
  </channel>
  <channel id="C5.0.95.ersatztv.org">
    <display-name>News Loop</display-name>
    <icon src="http://ersatztv.local:8409/iptv/logos/gen?text=News%20Loop" />
  </channel>
  <programme start="20240315140000 +0000" stop="20240315160000 +0000" channel="C2.0.148.ersatztv.org">
    <title>The Grand Illusion</title>
    <desc>A French classic from Jean Renoir.</desc>
  </programme>
  <programme start="20240315160000 +0000" stop="20240315175500 +0000" channel="C2.0.148.ersatztv.org">
    <title>Casablanca</title>
    <desc>Humphrey Bogart and Ingrid Bergman in a timeless romance.</desc>
  </programme>
</tv>

​
Channel Identifiers

The id attribute on each <channel> element uses the same stable identifier format as tvg-id in the M3U playlist. The format is: 
C{channelNumber}.{checksum}.ersatztv.org
When the ETV_INSTANCE_ID environment variable is set, the instance ID is inserted before ersatztv.org: 
C{channelNumber}.{checksum}.{instanceId}.ersatztv.org
This id must match the tvg-id in the M3U playlist for clients to link programs to the correct channel. ErsatzTV guarantees they always match as long as ETV_INSTANCE_ID is consistent.

​
XMLTV Settings

Guide generation is controlled from Settings > XMLTV in the ErsatzTV web UI at /settings/xmltv.

​
Days to Build

The Days to Build setting controls how many days of future guide data are generated. ErsatzTV rebuilds guide data whenever playout schedules change, and serves the pre-built cache from disk. The default is a small number of days; increasing this gives clients a longer schedule lookahead at the cost of more disk activity during rebuilds.

​
Time Zone

The XMLTV Time Zone setting controls how timestamps are written into the XMLTV document:
ValueBehavior
LocalTimestamps are expressed in the server’s local time zone with the appropriate UTC offset
UTCAll timestamps are expressed as UTC (+0000)
Choose UTC if your IPTV client displays incorrect times, which can happen when a client applies its own time zone conversion on top of a local-time timestamp.

​
Block Behavior

When a playout schedule contains content blocks (multiple items grouped together in a block), the XMLTV Block Behavior setting controls how their guide times are represented:
ValueBehavior
Split Time EvenlyThe block’s total duration is divided evenly among all items in the block
Use Actual TimesEach item’s real start and finish time is used directly
Split Time Evenly produces cleaner guide grids when items in a block have varying durations. Use Actual Times reflects the true schedule precisely.

​
Channel EPG Flags

Individual channels have two EPG-related properties that can be configured per-channel:

​
ShowInEpg

When Show in EPG is disabled on a channel, that channel’s <programme> elements are omitted from the XMLTV output. The channel still appears in the M3U playlist and streams normally — it simply has no guide data. This is useful for channels that serve as stream-only sources with no meaningful schedule to display. The <channel> definition element itself is also omitted from the XMLTV output for hidden channels.

​
PlayoutOffset

The Playout Offset per-channel setting shifts all guide times for that channel by the specified duration. A positive offset moves all guide entries later in time; a negative offset moves them earlier. This compensates for slight timing mismatches between the actual stream start and the scheduled time displayed in a guide grid.

​
EPG Data and Playout Requirements

XMLTV program data is generated from active playout schedules. A channel must have an active playout assigned and running for its <programme> entries to appear in the guide. Channels with no playout, or channels where the playout has not yet been built, will have a <channel> definition but no associated <programme> elements.
ErsatzTV builds guide data incrementally as playouts execute and caches the results to disk. The XMLTV endpoint reads these cached fragments and assembles the complete document on each request. If the cache files are missing (for example after a fresh install before any playout has run), the endpoint returns an error.

​
Configuring Clients

Most IPTV clients pick up the XMLTV URL automatically from the url-tvg and x-tvg-url attributes embedded in the #EXTM3U header of the M3U playlist. For clients that require manual configuration:
  1. Go to Dashboard > Live TV > TV Guide Data Providers.
  2. Click Add and select XMLTV.
  3. Enter the guide URL: 
    http://ersatztv.local:8409/iptv/xmltv.xml
  4. Save and trigger a guide refresh.
Replace ersatztv.local:8409 with the actual hostname or IP address and port where your ErsatzTV Legacy instance is running.

​
Multi-Instance Setup

When running multiple ErsatzTV instances, each instance must have a unique ETV_INSTANCE_ID environment variable. This value is embedded in all channel identifiers in both the M3U playlist and the XMLTV feed. Without distinct instance IDs, two instances sharing a client would have conflicting channel IDs and the guide data would be attributed to the wrong channels. See the IPTV M3U Playlist page for more detail on the ETV_INSTANCE_ID variable and the channel identifier format.

Build docs developers (and LLMs) love

Get started for freeTalk to us