Articles
XMLTV EPG: how programmes find the right channel
Understand XMLTV channel identifiers, programme references and schedule coverage with a fictional example, and learn why a guide download can succeed without listings.
Published by InoxTV · Published
Last updated
An XMLTV EPG is a programme schedule, not a video feed. It contains channel descriptions and programme records that refer to those channels. To display useful listings, a player must associate the guide's identifiers with the channels in your playlist and select programmes covering the relevant time. Each of those steps can fail independently even when the guide file downloads successfully.
Follow one identifier through the data
The fictional example below declares a channel with the identifier demo.news. Its programme points back to that identifier through the channel attribute. The display name is readable text; the identifier is the reference connecting the records. The dates, title and channel are illustrative and do not represent an actual broadcast schedule.
<tv>
<channel id="demo.news">
<display-name>Example News</display-name>
</channel>
<programme channel="demo.news"
start="20261102180000 +0000"
stop="20261102183000 +0000">
<title lang="en">Evening bulletin</title>
</programme>
</tv>
A corresponding catalogue entry might carry tvg-id="demo.news". Whether and how a particular player uses that attribute depends on its implementation and the source's conventions. A similar-looking channel name is not a universal matching rule. The safest starting point is a playlist and guide deliberately published to work together, followed by the application's documented configuration.
Separate four stages of an update
| Stage | Question | Example failure |
|---|---|---|
| Fetch | Could the guide resource be retrieved? | The host could not be reached |
| Parse | Could the response be read as the expected data? | An HTML error page arrived instead of XMLTV |
| Match | Can guide channels be associated with playlist channels? | The identifiers refer to a different regional feed |
| Display | Are there programmes for the selected time? | The source contains yesterday's schedule only |
Application status messages do not necessarily expose all four stages. A success message may establish that an update completed without an operational error, while still leaving a channel without entries. Interpret the message alongside a specific channel and time range. Do not repeatedly change the guide URL until the stage that needs attention is reasonably clear.
Identify a mismatch with a controlled example
If you are unfamiliar with catalogue attributes, first read the annotated M3U example. It separates the display name from the guide identifier and stream address, so you can compare the right field without changing the playback location.
Choose one channel whose expected programme you can identify. Note the exact feed or regional edition, not just the brand name. Compare its playlist identifier with the guide's channel declaration and programme references where you are authorised to inspect them. For example, demo.news and demo.news.west may describe different feeds even if both display Example News.
Changing every identifier to a simplified channel name can make matters worse. Two distinct feeds could collapse onto the same name, leaving one schedule attached to the wrong video. Keep a backup of any file you edit, test one entry first and preserve the source's intended distinctions. A broad search-and-replace operation is not a reliable substitute for understanding the mapping.
Check the time window as well as the channel
A guide may include a channel declaration without any programme records for tomorrow. It may also cover only a subset of the channels in a large playlist. Neither situation means the XML is malformed. Check the actual beginning and end of the programme coverage before treating an empty part of the grid as a download failure.
Programme times need careful interpretation. In the example, +0000 is an explicit UTC offset. Another source can describe the same instant with a different local clock time and offset. If the right programme appears at the wrong hour, investigate timestamps and conversion rather than changing the channel identifier. The EPG time-zone article walks through that calculation.
A bigger guide is not necessarily more useful
A guide covering many countries and weeks of listings may demand more memory, processing and download time than a focused source. Its size says nothing about whether your particular channels match. Prefer an authorised source with the right channels, appropriate schedule coverage and a predictable update process. Consider the capabilities of the actual television or streaming stick doing the work.
Compression can reduce transfer size, but the device still has to process the decompressed data. A small compressed download may therefore create a much larger workload during parsing. Reducing retained history can help in some applications, but it does not guarantee that an oversized source will become processable. Follow the documented settings and observe the resulting update rather than assuming a particular memory limit.
Turn observations into a useful report
Record whether the update reports success, which channels are affected, the selected date, the device time zone and one expected programme. Say whether all listings are absent or only a particular feed is wrong. That distinction helps separate a connectivity problem from a coverage or matching problem. Do not share private guide URLs containing account tokens.
For InoxTV, the TV guide setup instructions explain where guide sources are configured, and the missing guide troubleshooting page covers the application's status messages. Use this article to understand the data relationship, then use those pages for the exact interface actions. A successful repair should be checked against more than one programme and date.
