EPG, XMLTV, TV Guide: How the Program Guide Really Works in IPTV

Open any IPTV player and the first thing you see next to a channel is what is on now, and what comes next. That column is the EPG, the electronic program guide, and it is the most fragile piece of the whole setup, because it depends on data that does not travel with the channels. Understanding where it comes from and how it gets attached to your channels explains almost every guide problem, and makes the fixes obvious.

The guide is not part of the stream

A channel stream carries video and audio. It does not carry its schedule. The schedule lives in a separate feed, updated a few times a day, that a player fetches and matches to the channels in your playlist. Two channels can play perfectly while their guide is empty, and a guide can be full for a channel whose stream is dead. They are independent.

That separation is why the guide is empty so often: the stream side worked, the data side had nothing, or could not be matched.

Where the data comes from

Three sources, from the most common to the rarest.

The provider's own feed. Xtream Codes servers can serve program data per channel, already matched to their channel list. This is the comfortable case: the player asks "what is on channel 1234 today", the server answers. Coverage depends on the provider: major channels almost always, small or foreign ones as they see fit.

An XMLTV file. A single file, often compressed, published at a URL, covering many channels over several days. Providers give one to M3U users; independent projects publish some too. It is the universal format of TV guides, the one other players take as an "EPG URL".

Metadata APIs. Services that answer questions about programs, movies and series on request, used to enrich what the feed says with posters, cast and descriptions. Our guide on XMLTV versus metadata APIs covers the difference.

What an XMLTV file contains

XMLTV is a plain text format from the early 2000s that everyone in the industry still uses because it is simple. Two kinds of entries:

• Channels: an identifier and a display name. The identifier is the key to everything, something like bbcone.uk or tf1.fr, chosen by whoever produces the file.
• Programs: for each one, the channel identifier, a start time, an end time, a title, and optionally a description, a category, an episode number, an image.

Times are written with an offset, for example 20260920210000 +0200, meaning the program starts at 21:00 in a zone two hours ahead of universal time. The player converts that to your device's clock. If the device's zone is wrong, every program shifts, which is cause number four of a wrong guide.

How a channel finds its programs

This is the step that fails silently. Your playlist names its channels and gives each one an identifier: tvg-id in an M3U, epg_channel_id in Xtream Codes. The EPG feed names its channels with its own identifiers. The player matches the two. When they are identical, the programs attach. When they are not, the player has no honest way to guess: "TF1 HD" in your playlist and tf1.fr in the feed are the same channel to you, and two strings to a machine.

Good providers keep identifiers consistent between their playlist and their feed. Hand-edited playlists, third-party feeds, and channel names with regional suffixes break the match. The symptom is a channel with no guide next to channels that have one, or, worse, the programs of another channel, when two identifiers collide.

Some players try fuzzy matching on names. It helps with obvious cases and creates wrong matches in the others. The reliable fix is on the data side: use the feed that goes with your playlist, which is what an Xtream Codes server does by construction.

What a player has to do

A guide that feels instant is a lot of work hidden well:

• Load in the background. A full feed for thousands of channels can weigh tens of megabytes. Fetching it before showing anything would mean a minute of spinner. The player shows the channels first and fills the guide behind, visible channels first.
• Cache. Programs do not change every minute. The player keeps what it fetched and refreshes on a schedule, so the second launch is instant.
• Retry quietly. Servers time out, especially at peak hours. A channel whose data did not arrive gets asked again later, without an error in your face.
• Say "Live" rather than spin. A channel with no program data is not broken. The player should say so and play it like any other.
• Convert times once, correctly. Using the device's zone, honoring daylight saving, with no manual offset to fiddle with.

That list is the difference between a guide you use and a guide you turn off.

What to remember

The guide is data on the side of the channels, not inside them. It needs a source (the provider's Xtream server, in IPTV Guard), matching identifiers on both sides, and the right clock on your device. When one of the three is missing, the guide is empty or wrong, and the channels play regardless. The six causes guide turns that into a checklist; this one explains why the checklist looks the way it does.