A practical breakdown of the XMLTV format every IPTV player uses for its EPG — what's inside the file, why your tvg-id has to match the channel id exactly, and the timezone offset bug that puts your shows on the wrong day.
Most IPTV setups break the same way. The streams play. The channels show up. The Electronic Program Guide is empty. The user assumes the provider is broken when in reality the EPG file loaded fine — but the channel IDs in the M3U do not match the channel IDs in the XMLTV file. Two text strings off by one character and the entire guide displays as "No information available."
XMLTV is the format every modern IPTV player uses for the EPG. It is XML, it is open, and it is older than most of the players that consume it. Once you understand the actual file structure and the matching rules, EPG troubleshooting moves from frustrating guesswork to mechanical fixes. This article walks through the format, the channel-ID matching rule that breaks more setups than anything else, the timezone offset bug, the .xml.gz compression question, the player-specific quirks, and how to edit a file by hand to fix one stubborn channel.
What XMLTV actually is in plain terms #
XMLTV is a specification that defines an XML file format for TV listings. The original project started in the early 2000s as part of community-built TV guide tooling and predates the modern streaming era. Every major IPTV player — firestick/”>tivimate-on-firestick/”>TiVimate, IPTV Smarters Pro, Perfect Player, GSE Smart IPTV, IBO Player, Tivico — reads XMLTV for its EPG.
The file is a single XML document with two sections: a list of channels (each with an ID and a display name) and a list of program entries (each tied to one channel ID, with a start time, an end time, a title, and optional metadata).
The file can be served from any web URL. Many providers package the XMLTV alongside the M3U playlist URL. EPG-only services (free or paid) provide standalone XMLTV URLs that any player can pull from. The file refreshes on whatever schedule the source updates it, typically once or twice a day.
The XML structure — channel and programme blocks #
An XMLTV file opens with the XML declaration and the root element <tv>. Inside that, every channel gets a <channel> block and every show gets a <programme> block.
A channel block looks like this in the source:
<channel id="espn.us"><display-name>ESPN</display-name></channel>
A programme block looks like this:
<programme start="20260501100000 +0000" stop="20260501110000 +0000" channel="espn.us"><title>SportsCenter</title><desc>Daily sports news.</desc></programme>
The two key fields that drive everything: the channel's id attribute and the programme's channel attribute. They have to match exactly, character for character, including case. "ESPN.us" and "espn.us" are different strings as far as XMLTV is concerned and a player will not link them.
The start and stop times are in UTC by default and follow the YYYYMMDDHHMMSS format with a space and a timezone offset. "20260501100000 +0000" means May 1, 2026 at 10:00:00 UTC.
The tvg-id ↔ channel id matching rule #
The M3U playlist has a parallel field for each channel called tvg-id. A typical M3U entry looks like this:
#EXTINF:-1 tvg-id="espn.us" tvg-name="ESPN" tvg-logo="https://example.com/espn.png" group-title="USA Sports",ESPN
https://stream.example.com/espn.m3u8
The player reads the M3U, sees that the channel ESPN has tvg-id="espn.us", then opens the XMLTV file and looks for a channel with id="espn.us". If found, it pulls the matching <programme> blocks and displays them in the EPG for that channel.
If the tvg-id is empty, missing, or does not match any channel id in the XMLTV, the EPG is empty for that channel. This is the single most common cause of "my EPG isn't showing" complaints in the IPTV world.
Common reasons for mismatches: tvg-id is blank in the M3U because the provider did not populate it; the M3U uses a different ID convention than the XMLTV (e.g., "ESPNHD" in M3U, "espn.hd.us" in XMLTV); the XMLTV is from a third-party EPG service and its IDs follow a different scheme than the provider's M3U.
Why your EPG shows but on the wrong channel #
A subtler version of the same problem: the EPG appears, but the show titles correspond to the wrong channels. ESPN's lineup is showing on Fox Sports 1, and Fox Sports 1's lineup is on TNT.
This happens when the M3U has tvg-ids that match XMLTV channel ids by luck — the strings are the same, but they refer to different real-world channels. Provider A's tvg-id "sport1" is ESPN. EPG service B's channel id "sport1" is a German Sky Sport channel. Both strings match, the player happily wires them together, and your guide shows German football schedules for ESPN.
The fix is to use an EPG source that is explicitly aligned with your M3U. Most reputable providers ship their own XMLTV alongside the M3U, with IDs that match exactly. Third-party EPG services list their ID schemes and document which channels each ID refers to.
Timezone offsets — the +0000 vs local time bug #
The most common time-related XMLTV bug: shows display in the EPG at the wrong time, often shifted by 5 to 8 hours.
Cause: the player and the XMLTV disagree on the timezone interpretation. XMLTV times are stored with an explicit timezone offset, e.g., "20260501100000 +0000" means 10:00 UTC. The player should convert to the user's local time when displaying — 10:00 UTC is 6:00 AM Eastern, 5:00 AM Central, etc.
Two failure modes: (1) The XMLTV omits the timezone offset entirely and the player guesses. Different players guess differently — some assume UTC, some assume local time, some assume the source's timezone. (2) The XMLTV offset is wrong because the source generates the file in local time but mislabels it as UTC.
Fix: check whether the player has a timezone-correction setting. TiVimate has one buried in EPG settings called "EPG time shift" that lets you add or subtract hours. Apply the offset that matches the apparent shift. If shows are 5 hours late, set the shift to -5. This is a workaround, not a fix to the underlying file, but it gets the guide right.
.xml vs .xml.gz — when each is used #
XMLTV files are large. A multi-day EPG for a few thousand channels can run 50 to 200 MB uncompressed. Gzip compression cuts that to roughly 8 to 20 MB.
.xml.gz is the gzipped XML file. Players that support .xml.gz pull the smaller compressed file and decompress it locally. This saves bandwidth and download time.
Most modern IPTV players auto-detect the file extension or content-encoding header and handle both. Older or simpler players may require uncompressed .xml only. If you see EPG download errors with a .xml.gz URL, check whether the player supports compressed feeds and switch to a .xml URL if not.
Manual editing requires uncompressed .xml. The fix workflow is: download the .xml.gz, decompress to .xml, edit, recompress to .xml.gz, host the result. Most editors cannot open .gz files directly.
EPG provider URLs and how players fetch them #
An EPG URL is just an HTTP or HTTPS link to the XMLTV file. A typical URL looks like https://provider.example.com/epg/all.xml.gz or https://epg.iptv-provider.com/xmltv?user=abc&pass=xyz.
Some providers use authenticated EPG URLs that include user credentials in query parameters. Others serve the EPG publicly, no auth needed. Free EPG services like EPG-Best or iptv-org.io provide standalone XMLTV URLs for popular channels worldwide.
The player fetches the URL on a schedule (configured per-player), parses the XML, builds an internal database, and displays the EPG. Fetch failures cause the EPG to fall back to whatever was last cached, which is why a stale EPG sometimes hangs around showing yesterday's schedule.
Fetch frequency matters. Fetching every hour is wasteful — XMLTV files do not change that often. Fetching once every 24 hours is the standard. Some players default to once at startup, which can leave the EPG stale if the user keeps the player running for days.
TiVimate's XMLTV handling #
TiVimate is the most-used third-party IPTV player on Android-based devices in 2026 and its XMLTV handling is reasonably mature. Add an EPG URL through the Settings menu, set the auto-update interval (default 12 hours), and enable EPG time shift if needed. TiVimate caches the parsed EPG locally and refreshes per the schedule.
TiVimate Premium adds multi-EPG support — load two or three XMLTV URLs and the player merges them, preferring the first source for any channel and falling back to the second source if the first does not have data for that channel. This is useful for households with one provider feed for live channels and a free EPG service for catch-up data.
Common TiVimate EPG issues: the file is too large and the parsing fails silently, leaving the EPG empty; the channel IDs do not match (the most common cause); the time shift is misconfigured. The fixes are size-the-file-down (use a per-region EPG instead of a global one), align IDs, and adjust the time shift.
IPTV Smarters Pro's XMLTV handling #
IPTV Smarters Pro is the second-most-common player and its EPG handling is similar in concept but with quirkier UI. The EPG URL is added per-playlist in Smarters, not globally. Smarters auto-fetches on app launch and caches.
Smarters has a known issue with very large XMLTV files where the parser slows substantially or chokes. The workaround is to use a smaller, more curated XMLTV. Some users run an intermediate proxy (a self-hosted script that filters the global XMLTV down to only their subscribed channels) before pointing Smarters at the result.
Smarters does not have the same multi-EPG capability as TiVimate Premium. If you want to combine sources, you have to merge them externally before pointing Smarters at the merged file.
Editing an XMLTV file by hand for one channel #
Sometimes the only fix is manual. The EPG for one specific channel is wrong, missing, or the source XMLTV does not cover it.
Workflow: download the XMLTV (or the decompressed version of .xml.gz). Open it in a text editor that handles large files (VS Code, Notepad++, BBEdit). Search for the channel id. If the <channel> block is missing, add one. If the <programme> blocks are wrong, edit them with corrected start/stop times and titles.
Save the file with UTF-8 encoding. Recompress to .xml.gz if the player needs that. Host the resulting file somewhere your player can reach (a local web server, a free hosting service, a Dropbox direct link).
Point the player at the new URL. Re-fetch the EPG. The edited channel should now show correctly while the rest of the channels remain unaffected.
This is tedious for more than a few channels but is the right tool when an entire EPG service is fine except for one stubborn outlier.
Multi-EPG sources — when you need them #
Some setups need EPG data from multiple sources. Examples: a US household with American sports plus international news where the provider's EPG only covers the sports; a household using multiple IPTV subscriptions where each provider ships its own XMLTV.
TiVimate Premium handles multi-source natively. For other players, the merge has to happen upstream. Tools like xTeVe and Threadfin (mentioned in our multi-room article) can ingest multiple XMLTV feeds and present a single merged file to downstream players. EPG-Manager Docker containers do similar work.
The merging logic decides which source wins when both have data for the same channel. Most tools default to first-source-wins. Configure source priority based on which feed has the higher-quality data for which channels.
How often does EPG actually need to refresh #
Once every 24 hours is plenty for most setups. The XMLTV file typically covers 7 to 14 days of programming and the source updates daily. Refreshing more often wastes bandwidth without surfacing new data.
Edge case: same-day program changes (sports overruns, breaking news preemption). These do not show in the EPG anyway because the XMLTV is built from advance schedules, not real-time corrections. No refresh frequency fixes this — the underlying data does not include the change.
If the EPG is going stale (showing yesterday's schedule today), the issue is usually that the player has not refreshed since startup or the source URL has gone down. Check the player's last-refresh timestamp first.
Common errors and fixes #
"EPG not showing for any channel": tvg-ids in M3U do not match channel ids in XMLTV. Open both files, compare IDs for the same channel, fix the mismatch.
"EPG times are off by 5 hours": timezone offset is wrong or missing. Set the EPG time shift in the player to compensate.
"EPG is empty for some channels but works for others": the XMLTV is missing data for those channels. Check the source URL — some EPG services cover only major channels and skip smaller ones.
"EPG download fails": player cannot reach the URL or cannot parse the file. Test the URL in a browser. If it loads, the parsing is the issue, often related to file size or .xml.gz compatibility.
"EPG shows wrong programs on every channel": the M3U tvg-ids and XMLTV channel ids match by string but refer to different real-world channels. Switch to an EPG source aligned with your M3U.
"EPG used to work, suddenly stopped": source URL went down or the source changed format. Check the URL, look for an updated URL from the provider or EPG service.
Frequently Asked Questions #
Why is my IPTV showing programs at the wrong time? #
The XMLTV file's timezone offset is misconfigured or the player is interpreting it incorrectly. XMLTV times are stored with an explicit offset like "20260501100000 +0000" for UTC, and the player should convert to local time. Some players misinterpret the offset, and some XMLTV sources omit it entirely. Fix by enabling the EPG time shift setting in your player (TiVimate has one in EPG settings) and applying the correction that matches the apparent shift. A 5-hour-late EPG needs a -5 time shift.
What's the difference between EPG and XMLTV? #
EPG (Electronic Program Guide) is the concept — the on-screen guide showing what is playing now and later. XMLTV is the file format that delivers the EPG data to your player. Every modern IPTV player uses XMLTV files (or a derivative format) to populate its on-screen guide. So the EPG is what you see, and XMLTV is what the player reads to build that view. The two terms get used interchangeably in casual conversation but refer to different layers.
Can I use a free XMLTV URL? #
Yes. Several free XMLTV services cover popular channels worldwide — iptv-org.io, EPG-Best, and others publish freely-accessible XMLTV URLs. The trade-off is coverage and reliability. Free services typically focus on major channels and may not cover every niche or regional channel in your IPTV provider's lineup. They also occasionally change URLs or go down without warning. For setups beyond a basic channel list, a paid or provider-shipped XMLTV is more reliable.
Why does my EPG show on some channels but not others? #
The most common cause is missing channel matching — the M3U tvg-id for the affected channels does not match any channel id in the XMLTV. Open the M3U, find the tvg-id for a broken channel, then search the XMLTV for that string. If it is not there, either the EPG source does not cover that channel or the IDs use different conventions. Fix by changing the tvg-id in the M3U to match an existing XMLTV channel id, or use an EPG source that covers all the channels you care about.
How do I edit an XMLTV file? #
Download the file (decompress if it is .xml.gz). Open it in a text editor that handles large XML — VS Code, Notepad++, or BBEdit work well. Find the channel id you want to fix. Edit the <channel> block or the <programme> blocks for that ID with corrected information. Save with UTF-8 encoding. Recompress to .xml.gz if your player requires that. Host the edited file at a URL your player can reach and update the EPG URL in the player. Re-fetch the EPG to load the changes.
Disclosure: This article may contain affiliate links to apps or services discussed. We may earn a commission for qualifying purchases at no additional cost to you. We recommend tools we have tested or that have strong independent user feedback.
