IPTV programme guides: EPG and XMLTV explained

The programme guide is the part of IPTV people notice only when it breaks. Channels play, but the grid is empty. Or it is full, but everything is an hour early. Or half the channels show nothing at all. All three have ordinary explanations once you know what a guide is made of. This guide explains the pieces and gives you a checklist for fixing the common faults.

What an EPG is

EPG stands for electronic programme guide: the grid of channels and times that tells you what is on now and what is next. In IPTV, the guide is not part of the video stream. It is a separate piece of data that your player fetches on its own and then matches to your channel list.

That separation explains most guide problems. There are two independent things that must line up: the list of channels, and the schedule data. If they disagree about names or identifiers, or about the time, the guide looks wrong even though both are individually fine.

Where the guide data comes from

There are three common sources:

1. Your provider's server. Providers that offer an Xtream-style login usually also offer a guide from the same server, so the player can fetch it without being told another address.
2. An XMLTV address. The provider (or another guide source) gives you a web address for a guide file in the XMLTV format. You add it to your playlist as an extra field.
3. Embedded in the playlist. Some M3U playlists name the guide address in the first line, in an attribute such as url-tvg, so a player can pick it up automatically.

What XMLTV looks like

XMLTV is an open, plain-text format based on XML. A guide file has two kinds of entries: channels and programmes.

<tv generator-info-name="example">
  <channel id="harbour.news">
    <display-name>Harbour News</display-name>
  </channel>
  <programme start="20261004200000 +0200" stop="20261004203000 +0200" channel="harbour.news">
    <title lang="en">The Day Ahead</title>
    <desc lang="en">A look at tomorrow's headlines.</desc>
  </programme>
</tv>

Three details matter:

• The channel id is the identifier. Every programme says which channel it belongs to by repeating that id.
• The times are written as year, month, day, hour, minute, second, then the offset from UTC: 20261004200000 +0200 means 4 October 2026, 20:00:00, two hours ahead of UTC. A player converts these to your local time. If the offset is missing or wrong, times shift.
• The file is often compressed, with the extension .xml.gz, because a week of programmes for thousands of channels can be tens of megabytes of text. A good player unpacks it for you.

How channels and the guide get matched

This is the step that fails most often. The player looks at each channel in your playlist and tries to find the matching channel in the guide:

1. By identifier. In an M3U playlist, the tvg-id attribute on each channel line is compared with the id of each XMLTV channel. If they are equal, the match is exact and reliable.
2. By name. If there is no identifier, a player may compare names. That is less reliable, because "Harbour News", "Harbour News HD" and "HARBOUR NEWS (UK)" are all the same channel to a human and three different strings to a computer.
3. By hand. When neither works, you can choose the right guide channel for a playlist channel yourself.

A channel with no match shows no schedule. That is why a guide can be perfect for some channels and blank for others.

The usual faults and what causes them

Most guides are rebuilt once or twice a day, so a refresh does not help if the source itself is stale.

A checklist that works in order

1. Open the guide address in a browser on the same device. It should download a file or show XML. An error page means the address is wrong or expired.
2. Check the channel count. If the guide has a few hundred channels and your playlist has thousands, only the matches will show a schedule.
3. Look at one channel that has no schedule. Compare its tvg-id in the playlist with the id in the guide file. If the guide has no entry for it, the guide does not cover it.
4. Check the time. Compare the guide's start time of a programme you know with the real broadcast time. A whole-hour difference points to the offset.
5. Refresh once and wait. Large guides take a while to download and process.
6. Ask the provider for the correct guide address and whether it matches the playlist's tvg-id values. Give them an example channel.

On demand and catch-up are separate

A guide tells you what is scheduled. It does not tell the player whether an archive exists for a past programme. That information comes from the provider's channel settings. A channel can have a guide and no catch-up, or catch-up for a few days with a guide that goes back a week. If a programme in the past will not play, the archive probably does not cover that channel or that date.

Using other sources for the guide

Because the guide is a separate feed, you are not strictly tied to your provider's. Some people add a guide from a different source that covers the same stations. This can work well for well-known channels, and it can fail quietly when ids differ. If you do it, be prepared to match channels by hand, and be aware that a guide from another source is only as accurate as its maintainer.

How GridTV handles it

GridTV reads the guide your provider offers or the XMLTV address you add, and shows one merged grid across all your playlists. It shows plain explanations: if no guide source is set, it says so; if no channel is linked to a guide, it points you at Guide Mapping, where you can choose the right guide channel for each channel by hand and keep that choice after refreshes; and if the guide is out of date, it says when the newest programme ended. You can shift the guide in whole hours per playlist for time-zone problems. It also refreshes guides overnight when iOS allows it, so the guide is fresher by morning, though it cannot promise freshness within the hour.