XMLTV
XMLTV EPG Guide: How Guide Data Works
XMLTV is a widely supported format for exchanging television schedule data. You do not need to edit XML by hand to use it, but understanding its channel IDs, timestamps, and programme records makes EPG setup and troubleshooting much more predictable.
Published September 2, 2026
What an XMLTV file contains
An XMLTV document normally contains channel elements followed by programme elements. A channel record provides an internal ID and may include a display name or icon. Each programme record references a channel ID and includes start and stop timestamps, a title, and sometimes a description, category, episode number, or rating.
The format describes listings, not the live video. That separation is why a working M3U playlist can still show an empty guide and why replacing a video player does not repair incomplete XMLTV data.
Channel IDs connect XMLTV to M3U
A playlist often stores the guide identifier in its tvg-id attribute. The player compares that value with the id on an XMLTV channel element. Exact matches are the most reliable; display-name guesses can fail when names include regions, quality labels, punctuation, or provider-specific prefixes.
If only a few listings are missing, inspect those channel IDs before changing the global EPG configuration. One extra suffix or a blank tvg-id can explain a mismatch even when the rest of the guide works.
How XMLTV times are represented
Programme times may include a numeric UTC offset. The player interprets that timestamp, combines it with the device time zone, and displays a local time. Errors can originate in the source timestamp, the device clock, the player, or an unnecessary manual offset.
Daylight-saving changes expose weak configurations because a hard-coded shift may be correct for part of the year and wrong for the rest. Prefer accurate source timestamps and automatic device time before applying a fixed correction.
Compressed XMLTV URLs and updates
Guide providers often compress large feeds as .gz files. A compatible player downloads and decompresses the file automatically. A URL without an .xml extension can also be valid if the server returns XMLTV content after authenticating or redirecting the request.
An XMLTV feed is a snapshot, so it must be updated. If the provider has not published new programme records, refreshing the player will simply import the same stale information.
Validate a source without exposing it
Check the URL privately in a trusted client or browser and confirm that it returns XML, compressed data, or a download rather than an account error page. Never paste a credential-bearing guide URL into public validators, forums, screenshots, or support posts.
For a file you control, an XML parser can catch malformed tags. Successful XML parsing does not guarantee complete guide coverage, so also confirm that current programme records exist for the channel IDs you need.
FAQ
Frequently asked questions
Is XMLTV a playlist?
No. XMLTV contains programme-guide data. An M3U playlist normally contains channel or stream entries. A player connects them using channel identifiers.
Does an XMLTV URL have to end in .xml?
No. It can end in .xml or .xml.gz, or use another URL pattern, as long as the server returns compatible guide data.
Why is a valid XMLTV file still missing channels?
The file may not contain those channels, may lack current programme records, or may use IDs that do not match the playlist.