The XMLTV TV guide: what it is, how it’s matched and how to import it

5 min read

A TV guide (EPG, short for electronic program guide) tells you what’s on each channel now and what’s coming up next. For M3U lists, the most common way to distribute it is XMLTV, an open XML format that has been around for many years and that almost every player understands. Here you’ll see what it looks like inside, how it links to your channels and what to do when it doesn’t appear or shows the wrong times.

What an XMLTV file looks like

It has two parts: the list of channels and the list of programs. A cut-down example:

<?xml version="1.0" encoding="UTF-8"?>
<tv>
<channel id="CanalUno.es">
<display-name>Canal Uno</display-name>
<icon src="https://example.com/logos/canal-uno.png"/>
</channel>
<programme start="20261106210000 +0100" stop="20261106220000 +0100" channel="CanalUno.es">
<title>Informativo de la noche</title>
<desc>Resumen de la actualidad del día.</desc>
<category>Noticias</category>
</programme>
</tv>

channel id is the channel’s identifier. It has no fixed format, although something like ChannelName.es is common.
display-name is its readable name; there can be several.
programme holds the channel it belongs to and the start and end times, in the format YYYYMMDDhhmmss followed by the offset from universal time: +0100 is mainland Spain’s time in winter, and +0200, in summer.
Inside go the title and, if available, the subtitle, description, category and an image.

Full guides can weigh hundreds of megabytes, which is why they’re usually published compressed, as .xml.gz or .zip.

How the guide is matched to your channels

The guide and the list are separate files, often from different sources. To know which schedule goes with each channel, the player looks for matches. Whatplay does it in this order:

By the tvg-id of the channel in the M3U (or the epgId in W3U), compared with the guide’s channel id.
By name, if there’s no identifier or it doesn’t match: the channel’s name in your list against the guide’s display-name.

They don’t have to match letter for letter. Whatplay compares them ignoring capital letters, accents, spaces and punctuation; it removes quality tags from the end (HD, FHD, UHD, 4K) and, in identifiers, the country suffix, such as .es. So “Canal Uno HD” in your list finds “Canal Uno” in the guide. But “C1” and “Canal Uno” look nothing alike: that’s what tvg-id is for.

A channel properly set up for the guide looks like this in the M3U:

#EXTINF:-1 tvg-id="CanalUno.es" tvg-logo="https://example.com/logos/canal-uno.png",Canal Uno
https://example.com/emision/canal-uno.m3u8

How to import it into Whatplay

If your list already specifies it (in M3U, with url-tvg or x-tvg-url in the #EXTM3U line; in W3U, with epg), the Guide tells you with the notice “The list ‘…’ comes with its own TV guide” and a button to import it.
If not, go to the Guide and tap “Import guide”. Paste the address of an XMLTV guide (.xml, .xml.gz or .zip) or tap “From file” to pick one from your device.

The guide downloads in the background and fills in as it arrives. In “Imported guides” you’ll see how many channels and programs it has, and you can remove it from there. The Guide has two views: “Now”, with what’s on each channel right now, and “Grid”, with the whole day and a day picker. In the player, under the channel name, you’ll see “Now” and “Next”. Whatplay refreshes guides from time to time and, if they haven’t changed, doesn’t download them again. The help sums it up in How do I add a TV guide?

Common problems

“None of your lists’ channels appear in the imported guides”

The guide has been imported, but no identifier or name matches. Open the guide in a text editor, find what your channel is called in its channel id entries and put that value in your list’s tvg-id. Also check that the guide covers the same country or region as your channels.

Programs are an hour off

Usually the guide declares its time zone wrongly: local times marked as +0000, or an offset that doesn’t change with daylight saving time. Whatplay respects what each program says and converts it to your time, so if the guide is wrong, the fix is in the guide.

“This isn’t an XMLTV guide, or it has no programs for these days”

Either the address doesn’t lead to an XMLTV file (for example, it opens a web page), or the guide is out of date and only has past programs. Guides are regenerated often: an old copy quickly stops being useful.

You pasted the guide into “Add list”

Whatplay detects it, tells you it’s a TV guide and not a list, and shows you where to import it with the same address.

It takes a long time to load

Large guides take a while to download and read. Use the compressed version if there is one and, if the source allows it, a guide with only the channels you use.

The guide is on your home network

Since Android 17, to download a guide from a computer or NAS on your network, Whatplay needs the “Nearby devices” permission. The app asks you for it with a notice.

Making your own guide

If you broadcast something of your own on a fixed schedule, like a community association’s radio station or a school’s channel, you can write an XMLTV file by hand: all you need is a channel and its programme entries, with the time zone set correctly and the file in UTF-8. To link it to your channel, use the same identifier in the tvg-id of your M3U list or in the epgId of your W3U; both are explained in M3U, M3U8 and W3U.