EPG and XMLTV Guide: How TV Listings Work in IPTV Players

An EPG (electronic programme guide) is the on-screen TV listing that shows what is on now and next. In most IPTV player apps the guide comes from a separate file in the XMLTV format, which the player matches to your channels. If the match works, you see programme names and times; if not, you get blank rows.

This guide explains the XMLTV format, how matching works, how to load a guide in a player and how to troubleshoot it.

Quick answer: XMLTV is an XML file containing <channel id="..."> entries and <programme start stop channel> entries. A player shows guide data for a playlist channel when the channel's tvg-id equals a channel id in the XMLTV file.

What is XMLTV?

XMLTV is an XML-based format for describing TV listings, introduced in 2002 and maintained by the XMLTV project. A file has a <tv> root element holding <channel> records and <programme> records. The structure is defined by a DTD (a formal description of the allowed elements) that the project publishes.

What does an XMLTV file look like?

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="example-generator">
  <channel id="ExampleNewsHD.uk">
    <display-name>Example News HD</display-name>
    <icon src="https://example.com/logos/example-news.png"/>
  </channel>
  <programme start="20261024180000 +0100" stop="20261024183000 +0100" channel="ExampleNewsHD.uk">
    <title lang="en">Example Evening Bulletin</title>
    <desc lang="en">A fictional news programme used for this example.</desc>
  </programme>
</tv>

Key points:

• Each <channel> has an id that programmes refer to, plus one or more <display-name> entries.
• Each <programme> has start, stop and channel attributes.
• Times are written YYYYMMDDhhmmss followed by a space and a UTC offset. In the example, +0100 means one hour ahead of UTC, which is British Summer Time. In winter UK times use +0000.
• <title> and <desc> carry the programme text, with a lang attribute for language.

If a file omits the offset, readers may assume UTC, which is a common source of wrong times; see EPG showing the wrong time.

How does a playlist channel match the guide?

Matching is done on the id. In your M3U playlist the channel carries tvg-id="ExampleNewsHD.uk"; the XMLTV file has <channel id="ExampleNewsHD.uk">. They must be identical, including case, punctuation and any suffix. If they differ by even one character the player will find no data. Some players fall back to matching by name, but that is less reliable.

How do I load an EPG in a player?

The exact menus differ between apps, but the steps are usually the same:

1. Open the player's settings and find the EPG, guide or XMLTV section.
2. Paste the guide address, or let the playlist's url-tvg / x-tvg-url header supply it.
3. Choose how often to update it.
4. Trigger a refresh and wait; large files take time to process.
5. Check that channels now show programme information.

If the player offers manual mapping, match unmatched channels to guide channels yourself. See the player guides, such as TiviMate setup.

How often should the EPG refresh?

Guide data usually covers several days ahead, so refreshing once or twice a day is normally enough. Refreshing every few minutes puts needless load on the host and can get your device blocked. Choose the schedule the app suggests, and if the app lets you pick a time, pick off-peak.

What is an .xml.gz file?

Guide files can be large, so they are often gzip-compressed and end in .xml.gz. Most players read compressed guides directly. If yours does not, decompress the file on a computer, or use an uncompressed address if the source provides one.

Where can guide data come from?

Guide data needs a source with permission to distribute it. Open-source grabber projects exist, such as iptv-org/epg, which is a command-line tool that downloads programme information from various websites and writes a guide.xml file. Its own readme says nothing about the terms of the websites it reads, so check each source's terms before using it. Broadcasters and some platforms also publish listings under their own conditions. Our forum can point you to community tools in the EPG and guides category.

How do I troubleshoot a blank or incomplete EPG?

You can open an XMLTV file in a text editor and search for your channel id to confirm it exists. Check against the XMLTV project's published DTD if the player complains about validity.

How big can an XMLTV file get?

A guide covering hundreds of channels for many days can run to many megabytes uncompressed, and parsing it takes memory and time. On weaker devices this is a common reason for slow loading or a player that appears to freeze after you add a guide. Compression helps the download but not the parsing. If the player is slow, use a guide limited to the channels you actually watch, which some tools can produce from a channel list.

What other elements can XMLTV contain?

Beyond title and description, the format allows more detailed fields. Which of them a player shows depends on the app:

Players generally ignore elements they do not use, so a rich file does no harm. See the XMLTV project's published DTD for the exact structure.

Can I build my own guide file?

For a handful of channels you can write XMLTV by hand, as in the example above, and host it on a local server. Add each channel and then its programmes, keep times in the correct offset, and make sure the XML is well formed, with every element closed. For anything larger, a generator or grabber saves a lot of effort. Always check that you have the right to use and distribute the data you include.