LounjyIPTV
EN

XMLTV EPG explained: how the TV guide works

Where the TV guide comes from, how a player knows which programme belongs to which channel, and what to do when the times are wrong.

What is an EPG?

EPG stands for Electronic Programme Guide. It is the list of programmes per channel, with a start time, an end time, a title and often a short description. It tells you what is on now and what comes next.

The guide is not part of the video stream. Your service delivers it separately, next to the channel list. A player downloads the guide, matches it to your channels and shows it on screen.

Lounjy provides no content. No channels, films, series, playlists or TV guide. Only use your own service, and only one that holds the rights to what it offers. Lounjy plays it and shows the guide that service provides.

Where the guide comes from depends on how you load your playlist:

  • Xtream Codes: your service’s server has a fixed address for the guide. Lounjy downloads it from there with the same login details. There is nothing to fill in.
  • M3U: the guide link sits in the very first line of the playlist, for example #EXTM3U url-tvg="http://service.example:8080/guide.xml.gz". Lounjy reads both url-tvg and x-tvg-url. If there is no link, the playlist has no guide. In that case, ask your service for a playlist that includes the guide link.

Once loaded, your playlist in Settings has a TV guide row. It shows how many channels have a guide and when it was last updated. Update guide downloads it again straight away. By default Lounjy updates the guide by itself every 12 hours, and never while you are watching.

The XMLTV file

XMLTV is the common format for these guides. It is a plain XML text file, often compressed as .xml.gz. Lounjy unpacks it automatically, even when the file name gives no hint that it is compressed.

The file contains two kinds of blocks:

  • Channels: <channel id="channel1.example"> with one or more names in <display-name>.
  • Programmes: <programme start="20261009200000 +0200" stop="20261009210000 +0200" channel="channel1.example"> with a <title> and sometimes a <desc>.

The channel attribute of a programme points to the id of a channel in the guide. That id is the key to everything else.

Lounjy keeps programmes from the past 24 hours up to three days ahead. Your old guide stays in place until the new one has fully arrived, so if a download fails, you still have your last guide.

Linking on tvg-id and name

The channels in your playlist and the channels in the guide are two separate lists, and a player has to link them. Lounjy does this in the following order:

  1. Your own link. If you linked a channel yourself, that link always wins.
  2. The tvg-id. In an M3U playlist, each channel often has tvg-id="channel1.example". With Xtream Codes, the server supplies a similar id. If it matches an id in the guide, the link is made. If the id has a suffix such as @SD, Lounjy also tries it without.
  3. The name. If the id doesn’t match, Lounjy compares the channel name with the names in the guide. It cleans up the name first: a country prefix, tags like HD, FHD or 4K, text in brackets and punctuation are ignored. So | UK | Channel 1 HD simply becomes channel1.

With real playlists, some channels are usually left over: the id is missing, or the name is too different. Those channels show No TV guide for this channel. That is what Link TV guide is for:

  1. Go to Settings and, in the TV guide row of your playlist, choose Link TV guide (the button may read Link (12)). The number shows how many channels have no guide.
  2. Each channel gets a suggestion from the guide, with how sure Lounjy is, for example 92% sure. Choose the Link TV guide button on that channel’s row to accept the suggestion, or Search to find the right channel in the guide yourself.
  3. Link all confident suggestions accepts every suggestion that is at least 85% sure and not torn between two equally good guide channels.
  4. Choose Apply now or Apply and close. Lounjy then downloads the guide again with your new links.

If a link is wrong, choose Remove link. Your own links survive when the channel list is updated, and they are included in a backup.

Time shift

In XMLTV, each time should say how far it is from world time (UTC), for example +0200. Lounjy converts everything to your device’s local time. When that information is right, the guide is right too, including around daylight saving changes.

Sometimes the source gets it wrong. The time zone is missing, or it is incorrect. If it is missing, Lounjy assumes the time is in UTC. The result is that every programme is a fixed number of hours too early or too late. The eight o’clock news shows up at ten, for example.

To fix it:

  1. Open the Link TV guide window.
  2. Under Guide times, use 30 min earlier or 30 min later until the difference is gone. If the guide is two hours late, choose 30 min earlier four times.
  3. Choose Apply now. The guide is downloaded again with the corrected times.

The shift applies to the whole playlist, not to single channels. You can see it in the TV guide row, for example as time +1:00 h. Does Lounjy tell you the guide only contains programmes outside the coming days? Then the guide is outdated, or the time shift is wrong.

Short guide as a fallback

Some Xtream Codes services include a channel list in their guide, but no programmes. Others leave some channels empty. If the guide has no usable programmes at all, Lounjy explains this in plain words in the TV guide row. If only some channels are missing, you can see that from the number of channels with a guide.

For those channels, Lounjy falls back on the short guide. This is a small list per channel that your service’s server provides separately: what is on now and what comes next. Lounjy only requests it for channels you have on screen and remembers it for ten minutes.

The short guide only exists with Xtream Codes. With an M3U playlist you depend on the XMLTV link in the playlist. If your service has no guide for a while, your last guide stays in place.

Read more

Want to try Lounjy with your own service? Go to the download page.