Guide · updated
IPTV EPG and XMLTV: How the TV Guide Works and How to Fix It
An IPTV guide (EPG) is a separate list of programmes that a player matches to your channels. The player does not create it: the source that issued your playlist either supplies guide data or it does not.
Most guide problems come down to three things: no guide link, channel IDs that do not match, or programme times written with the wrong time-zone offset.
What is XMLTV?
XMLTV is the file format most IPTV guides use. It is a plain XML file, often compressed as .xml.gz, with two parts: a list of channels and a list of programmes.
Each channel has an ID, such as <channel id="bbc1.uk">. Each programme names the channel ID it belongs to and its start and stop time, such as start="20261104200000 +0000". The last part is the time-zone offset of that time.
Where does the guide data come from?
- Xtream Codes login
- The server that issued the login usually serves the guide too, at
/xmltv.phpon the same address. Players fetch it with the same username and password. - M3U playlist
- The guide is a separate XMLTV link. Some playlists name it in the first line, as
url-tvg="…"orx-tvg-url="…"; others send it to you separately. - No guide link
- Then there is no guide to show. Every player using the same source shows the same empty guide.
How does a player match the guide to channels?
By ID, not by name. In an M3U playlist each channel line can carry a tvg-id attribute; in an Xtream login each live stream has an EPG channel ID. The player looks for an XMLTV channel with exactly that ID.
If the IDs differ even slightly, such as BBC1.uk in the playlist and bbc1.uk-hd in the guide, that channel shows no programmes. Use the M3U file viewer to see which channels in a playlist have a tvg-id and which do not.
How does the guide work in Opus?
For an Xtream Codes login, Opus loads the guide from the server that issued the login, on iPhone, iPad, Android, Apple TV, Android TV and Fire TV. There is nothing to set up. In the iPhone, iPad and Android app you can replace that guide address with another one in the playlist's EPG settings.
Opus does not show a guide for M3U playlists yet: the channels play, but the tvg-id and url-tvg values are not used. If your source issued both, add the Xtream Codes login to get the guide.
Why is the guide empty?
- Check that a guide existsAsk the source whether it supplies guide data and at which URL. If it does not, no player can show one.
- Open the guide link in a browserA working link downloads or shows XML that starts with
<tv. An error page, a login page or an empty file means the link itself is the problem. - Check the programme datesGuides only cover a few days. If every programme in the file ends before today, the file is stale and the source has to update it.
- Compare the channel IDsFind a channel's
tvg-idor EPG ID and search the XMLTV file for the same ID. A missing or different ID explains a single empty channel; the EPG viewer compares a whole playlist with a guide.
Why does the guide show the wrong times?
Usually because the times in the file carry the wrong offset. A programme that starts at 20:00 in London should be written as +0000 in winter and +0100 in summer. If the source writes +0000 all year, the guide is one hour off for half the year.
Check your device's time zone first, then look at a programme's start value in the file. If the offset is wrong there, ask the source to fix the guide, because the same guide is wrong in every player.
Frequently asked questions
What is an EPG URL?
It is the web address of an XMLTV guide file. A player downloads it and matches its programmes to your channels by ID.
Does Opus provide EPG data?
No. Opus shows the guide your source supplies. It does not provide guide data, channels or playlists.
Why do only some channels have a guide?
The guide only covers channels whose IDs appear in it. Channels without a matching ID stay empty even when the rest of the guide works.
Is an .xml.gz file different from .xml?
Only in size: .xml.gz is the same XMLTV file compressed with gzip. Most players accept both.