IPTV EPG Guide: How to Add an XMLTV Program Guide to an M3U Playlist

An EPG (electronic program guide) shows what is on now and next for each channel. This guide explains how IPTV playlists link to an XMLTV guide, where guides come from, and how to fix a guide that does not show up.

What an EPG is

An EPG (electronic program guide) is the TV listings for your channels: what is on now, what is next, and the schedule for the coming hours. IPTV players almost always read guides in the XMLTV format, a plain XML file with two kinds of entries:

  • <channel id="…"> entries that name each channel in the guide;
  • <programme start="…" stop="…" channel="…"> entries with a title, a description and the start and end time of each show.

Guides for hundreds of channels get large, so they are often served compressed as .xml.gz.

How an M3U playlist links to a guide

A playlist and its guide are two separate files. They are tied together in two places:

  1. The playlist header names the guide with url-tvg (some providers write x-tvg-url). Several guides can be listed, separated by commas.
  2. Each channel carries a tvg-id that must equal a <channel id> in the guide. That is how the player knows which listings belong to which channel.
#EXTM3U url-tvg="https://example.com/guide.xml.gz"
#EXTINF:-1 tvg-id="NewsChannel.us" tvg-logo="https://example.com/news.png" group-title="News",News Channel
https://example.com/live/news/index.m3u8

If the tvg-id is missing or spelled differently from the guide, the channel plays but shows no listings.

Where EPG URLs come from

  • Your IPTV provider. Most paid services publish a guide URL next to the playlist link, or include it in the playlist header already.
  • Community guides for public channels. Open-source projects such as iptv-org/epg collect listings for free-to-air and FAST channels. Doubo's own channel pages show schedules from i.mjh.nz, which publishes guides for free streaming services.
  • Public playlists that declare a guide. The Free-TV and iptv-org lists on the public playlists page already carry an x-tvg-url line, so their guide loads without any setup.

Using an EPG in Doubo

Doubo reads the guide declared in your playlist automatically. There is nothing to configure:

  1. Import an M3U / M3U8 link or file whose header has url-tvg, x-tvg-url or tvg-url.
  2. Doubo downloads the XMLTV guide (plain or gzip-compressed), matches channels by tvg-id and keeps it cached for six hours.
  3. Open a channel: the player page shows what is on now and the programs that follow. When the playlist also declares catch-up, past programs can be replayed from the guide.

See the setup guide for importing a playlist step by step.

Fixing a guide that does not show up

  • No guide at all: open the playlist in a text editor and look for url-tvg in the first line. If it is missing, ask your provider for the guide URL.
  • Some channels are empty: compare their tvg-id with the channel ids in the guide. The M3U tool shows how many entries have a tvg-id.
  • Times are shifted: the guide's time-zone offset is wrong for that channel; use another guide source.
  • Guide loads slowly: very large guides take a while on the first load. Prefer a .xml.gz guide, or one that covers only the countries you watch.

FAQ

What is an EPG URL?

It is the address of an XMLTV file (often ending in .xml or .xml.gz) that lists programs for many channels. A playlist points to it with url-tvg or x-tvg-url in its first line, and a player downloads it to fill the guide.

Why does my playlist show no program guide?

Usually the playlist has no url-tvg / x-tvg-url line, the guide URL no longer works, or the channels have no tvg-id that matches a channel id inside the guide. Check those three things first.

Why are the guide times wrong?

XMLTV times carry a time-zone offset such as +0000 or +0800, and players convert them to your local time. If every program is off by the same number of hours, the guide file itself has the wrong offset. Try a different guide for that channel.

Is an EPG free?

Many are. IPTV providers usually include one with the subscription, and community projects publish free guides for public channels. A guide only describes programs; it does not give you access to any channel.