EPG matching for M3U playlists

How a player matches an XMLTV guide to an M3U playlist

The playlist and the guide are two separate files. The M3U playlist lists your streams and their addresses. The XMLTV guide lists programmes, each with a start time, filed under an id.

The tvg-id on each line of the playlist is what joins the two:

#EXTM3U
#EXTINF:-1 tvg-id="Stream1.uk" tvg-name="Stream 1" group-title="Group A",Stream 1
https://provider.example/stream/1001

The guide file must carry the same id. Make the two identical, letter for letter: a dot, a space or another case can be enough for a player to miss it. In the XMLTV format each id may appear only once, and it is looked up by the id, not by its place in the file.

When the tvg-id finds nothing, some players try the name next. One widely used open-source player add-on tries three things in order: the tvg-id, then the tvg-name against the names in the guide, then the stream’s own name. The first match wins, so a loose name can pick the wrong guide.

tvg-id, tvg-name and the other attributes

These are the parts of an M3U line that the guide uses:

• tvg-id: the id of the stream in the guide. The match uses it first.
• tvg-name: a name for the stream as the guide writes it. Some players fall back to it.
• tvg-logo: the address of the stream’s logo. The guide file can carry a logo of its own, so the two can differ.
• tvg-shift: moves the guide of one stream by a number of hours, in players that read it.
• x-tvg-url, also written url-tvg: goes once in the first line of the playlist and points to the guide file. Players differ in which name they read, so some tools write both.

M3UTool calls the tvg-id the Guide id. It is a column in the M3U playlist editor, and you can change it for one stream or for many at once.

Why the EPG is not showing

Almost every blank guide comes down to one of these:

• The ids do not match. The stream has no tvg-id, or one that is spelled a little differently from the guide. This is the most common cause.
• The guide has no programmes for that id from now on. The stream looks mapped, but there is nothing to show.
• The player cannot open the file. Guides are often packed as .xml.gz, and a player that does not unpack gzip shows no guide at all.
• The text encoding is wrong. A guide file in the wrong text encoding can be refused by the player, or show names that no longer match. XMLTV files are normally UTF-8.
• The player has not loaded the new guide yet. Players load the guide on their own schedule, so a change can take a few hours to show. Refreshing the guide in the player loads it straight away.

When the guide is a few hours off

XMLTV times can carry a time zone, for example 20261104183000 +0100. When a time has none, the format says it is UTC. A guide written in local time without its offset then runs early or late by the difference.

If one stream is off and the rest are right, it is often a "+1" or "+2" stream that uses the main stream’s guide. Shift that one stream by whole hours. More in Guide time shift in our guide.

If every stream is off by the same hours, check the time zone of the TV or box first. The guide itself usually carries the right times.

How to match an EPG to your M3U playlist

1. Add your provider login (server, username and password), an M3U link or an .m3u file as a new playlist.
2. In Guide sources, switch on the country guides you need, or add your own XMLTV link or file.
3. Run Map guide on the whole list. A big list maps in the background while you keep working.
4. Filter for streams that are still unmapped or have no guide data, and match those by hand. Browse guide shows a stream’s schedule before your users see it.
5. Give your users the M3U link and the guide link, or the M3UTool app, which loads the guide by itself.