Preloader
Others
  • Estimated reading time: 5 Minutes

How EPG Data Works: XMLTV, Time Zones and Why TV Guides Break

How EPG Data Works: XMLTV, Time Zones and Why TV Guides Break

Anyone who has used an IPTV player knows the moment: the stream plays perfectly, but the TV guide is empty, shows the wrong programme, or is exactly one hour out. The video and the guide come from two separate pipelines, and most guide problems happen where those pipelines meet.

This article looks at how electronic programme guide (EPG) data is structured, how players join it to channel lists, and why time zones, especially in the UK and Ireland, cause so many bugs.

Two data sources, one screen

An IPTV player typically loads two things:

  1. A channel list, usually an M3U playlist or an Xtream Codes-style API response, containing stream URLs and channel metadata.
  2. Guide data, usually an XMLTV file, containing programme titles, descriptions and start and stop times.

The player has to link every channel in the first source to the right block of programmes in the second. If that join fails, the stream still plays but the guide stays blank. Providers such as One IPTV supply both pieces, but the matching itself happens inside the player on the viewer's device.

The XMLTV format

XMLTV is the de facto standard for guide data. A minimal file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<tv>
  <channel id="channel-101">
    <display-name>Example Channel</display-name>
  </channel>
  <programme start="20261120190000 +0000" stop="20261120200000 +0000" channel="channel-101">
    <title lang="en">Evening Documentary</title>
    <desc lang="en">A one-hour factual programme.</desc>
    <category lang="en">Documentary</category>
  </programme>
</tv>

Three details matter most:

  • The channel id is the key that everything else refers to.
  • Each programme points back to a channel through its channel attribute.
  • Times use the compact form YYYYMMDDhhmmss followed by a UTC offset such as +0000 or +0100.

Real guide files can be very large because they cover many channels over several days, so they are often served compressed as .xml.gz.

How players match channels to guide data

In an M3U playlist, each entry carries attributes on its #EXTINF line:

#EXTM3U url-tvg="https://example.com/guide.xml.gz"
#EXTINF:-1 tvg-id="channel-101" tvg-name="Example Channel" group-title="UK Entertainment",Example Channel
https://example.com/live/101.ts

The url-tvg header (some players read x-tvg-url) tells the player where to download the guide. The tvg-id on each entry must match a channel id in the XMLTV file exactly. Players differ in how forgiving they are: some fall back to matching on tvg-name or the display name, while others require an exact ID and show nothing otherwise.

With Xtream Codes-style logins, the player fetches the channel list from the API and usually downloads guide data from an XMLTV endpoint on the same server. The matching principle is identical: a shared channel identifier.

Why guides break

Mismatched IDs. The most common cause. A channel is renamed or re-numbered in the playlist, but the guide file still uses the old ID. The stream works; the guide is empty.

Stale cache. Players cache the guide to avoid downloading a large file on every launch. If the cache is several days old, listings run out or show yesterday's schedule. A manual EPG refresh in the player's settings usually fixes it.

Download or parsing failures. A timeout, a truncated gzip file or a malformed XML entity can stop the whole guide from loading. Robust parsers skip a bad programme rather than discarding the file.

Time zones. The subtle one, covered next.

Time zones and the UK clock change

The UK uses Greenwich Mean Time (UTC+0) in winter and British Summer Time (UTC+1) in summer, switching on the last Sunday of March and the last Sunday of October. Ireland follows the same offsets.

That creates two classic bugs:

  1. The one-hour shift. A guide written in local time but labelled +0000, or a player that ignores the offset entirely, will be exactly an hour out for half the year. Some players expose a manual shift setting, often called tvg-shift or "EPG time offset", to compensate, but that only hides the underlying error.
  2. Changeover nights. On the night the clocks change, one local hour either repeats or disappears. Code that builds timestamps from local wall-clock time can produce duplicate or overlapping programmes around 1am to 2am.

The reliable approach is to store and compare everything in UTC and convert to local time only for display. The device's own date, time and time zone settings must also be correct, because the player uses them to work out what is on now.

Parsing XMLTV safely in Python

Python's standard library is enough to parse XMLTV correctly, offsets included:

import gzip
import xml.etree.ElementTree as ET
from datetime import datetime, timezone

def parse_xmltv_time(value):
    # Example input: "20261120190000 +0000"
    return datetime.strptime(value, "%Y%m%d%H%M%S %z")

with gzip.open("guide.xml.gz", "rb") as f:
    root = ET.parse(f).getroot()

now = datetime.now(timezone.utc)
for programme in root.iter("programme"):
    start = parse_xmltv_time(programme.get("start"))
    stop = parse_xmltv_time(programme.get("stop"))
    if start <= now < stop:
        print(programme.get("channel"), programme.findtext("title"))

Because %z produces timezone-aware datetimes, the comparison with datetime.now(timezone.utc) is correct whatever offset each programme uses. For very large files, ET.iterparse lets you process programmes one at a time and clear elements as you go, keeping memory use low.

A practical checklist

When a guide misbehaves, work through these in order:

  1. Confirm the guide URL downloads and decompresses without errors.
  2. Check that each tvg-id exists as a channel id in the XMLTV file.
  3. Verify programme times carry a correct UTC offset.
  4. Check the device's date, time and time zone.
  5. Force a fresh EPG download in the player.

How this looks to viewers

All of this machinery is invisible when it works. Viewers simply see channels organised into groups with what is on now and next. For an end-user view of how channel groups and the TV guide appear to viewers, and a concrete example of configuring guide refresh in a popular Android player, see this TiviMate setup guide.

Conclusion

EPG data looks simple, a list of titles and times, but it sits at the junction of two independent data sources and the awkward reality of local time. Treat channel IDs as strict keys, keep all times in UTC until the last moment, and handle the UK and Irish clock changes explicitly. Do that, and most "the guide is wrong" reports disappear.

Related articles
Instagram Follower Tracker: What You Can and Can’t See (Nov 2026)
22 Nov, 2026
  • Estimated reading time: 7 Minutes
Building a Secure SDLC: What to Check at Each Stage
22 Nov, 2026
  • Estimated reading time: 5 Minutes
How to Track QR Code Scans for Free in 2027
22 Nov, 2026
  • Estimated reading time: 12 Minutes
6 Top QR Code Generators for Beauty and Skincare Brands in 2026
22 Nov, 2026
  • Estimated reading time: 11 Minutes
Weekly trending
How EPG Data Works: XMLTV, Time Zones and Why TV Guides Break
22 Nov, 2026
  • Estimated reading time: 5 Minutes
Instagram Follower Tracker: What You Can and Can’t See (Nov 2026)
22 Nov, 2026
  • Estimated reading time: 7 Minutes
Building a Secure SDLC: What to Check at Each Stage
22 Nov, 2026
  • Estimated reading time: 5 Minutes
Our Sponsors

Our blog is proudly supported by industry-leading sponsors.