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.php on 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="…" or x-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 do I turn on the guide in Opus on iPhone, iPad, Android and Mac?

The guide is off for a new playlist on a phone, tablet or Mac; you turn it on once per playlist. For an Xtream Codes login Opus already knows the guide address, so turning it on is enough.

  1. Open the playlist's guide settingsOn iPhone, iPad or Android open Settings, tap your playlist, then "Manage Playlist" and the "TV Guide (EPG)" row, which reads "Off" until you turn it on. On the Mac open Settings, "Player & Language", and "Edit" next to "EPG URL".
  2. Turn the switch onThe "EPG URL" field appears. For an Xtream Codes login, "Auto Fill" writes the server's xmltv.php address with your username and password; you can also paste another guide address.
  3. SaveOpus shows "EPG Updated" and downloads the guide. "Total EPG" then counts the channels in the file; 0 means the address returned no guide.
  4. Open the guideOn iPhone, iPad and Android open Live TV and tap "EPG" at the top right. On the Mac choose "EPG" in the sidebar. Live channels also show the programme that is on now.

For an M3U playlist you can add a guide address the same way and browse it in the "EPG" screen, but the playlist's channels do not show their programme: Opus does not read tvg-id or url-tvg yet. If your source issued an Xtream Codes login too, add that instead.

How does the guide work on Apple TV, Android TV, Fire TV and Windows?

There is nothing to turn on. For an Xtream Codes login the TV and the Windows PC ask the server for each channel's programmes directly, so the guide works even when it is off on the phone, and a guide address set on the phone is not used there. M3U playlists show no guide on these devices.

On Apple TV, Android TV and Fire TV, press Up on the remote while a channel plays to open the "Program Guide" panel, which lists earlier and upcoming programmes with the current one marked "LIVE"; Left and Right change the channel. The panel opens only when the server sends a programme for that channel. On Windows, open the "Program Guide" tab for a 7-day grid.

What the guide messages in Opus mean

MessageWhereWhat it means
"EPG is loading in the background. Please wait for a short time..."iPhone, iPad, Android, MacThe guide file is still downloading. A large file takes longer on a slow connection.
"There is no electronic program guide (EPG) for this playlist"iPhone, iPad, Android, MacThe guide is off for this playlist, or the guide address returned no channels. Check the "TV Guide (EPG)" row and "Total EPG".
"No Program Information"Apple TV, Android TV, Fire TV, Windows, Mac guide gridThe server sent no programme for this channel at this time. Other channels can still have a guide.

Why is the guide empty?

  1. Check that the guide is on in OpusOn a phone, tablet or Mac the "TV Guide (EPG)" row of the playlist must read "Active" and "Total EPG" must be above 0. On a TV or a Windows PC the playlist must be an Xtream Codes login.
  2. 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.
  3. 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.
  4. 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.
  5. Compare the channel IDsFind a channel's tvg-id or 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 and fixes wrong IDs by channel name.

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.

Opus shows programme times in your device's time zone, using the offset in the guide. It has no setting to shift guide times, so a guide with a wrong offset stays wrong in Opus until the source fixes it.

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.