IPTV XMLTV Guide: What the EPG File Format Actually Contains

Our EPG guide covered what a program guide is and why it matters, along with a brief mention of the file format most guide data actually arrives in: XMLTV. This article goes one level deeper, opening up an XMLTV file the same way our M3U format guide opened up a playlist file, to show exactly what's inside and how it connects to the channels you're already watching.

You don't need to read this to use an EPG successfully, most people never look at a raw XMLTV file in their life. But if you've ever needed to troubleshoot missing or mismatched guide data, understanding this structure turns a vague problem into something specific and fixable, rather than a mysterious feature that "just doesn't work sometimes."

What Is XMLTV?

XMLTV is a structured file format for representing television schedule data, channels, program titles, air times and descriptions, written in XML, a widely used markup language designed for organizing structured information. It originated as an open-source project aiming to standardize how TV listings could be represented and shared, and that original format has since become the de facto standard EPG format across the IPTV world.

Like M3U, XMLTV's strength is its simplicity and openness. It's not tied to any single company or platform, which is exactly why so many independent, publicly available EPG sources exist today, all speaking the same structured format that any compatible IPTV app can read.

Why XML, Specifically

XML, short for Extensible Markup Language, is a general-purpose way of structuring data using nested, labeled tags, similar in spirit to HTML but designed for data rather than for visual page layout. It was a natural fit for TV schedule data because listings are inherently hierarchical: a source has channels, each channel has programs, each program has a title, a time range, and often a description, all of which nests cleanly into XML's tag structure.

Choosing an established, well-documented data format rather than inventing something proprietary meant that any programming language or piece of software with existing XML support could parse XMLTV data without needing custom tooling built specifically for television listings. That reuse of existing infrastructure is a big part of why the format spread so widely and why it's remained the standard for so long despite newer alternatives existing in other domains.

Anatomy of an XMLTV File

An XMLTV file is built around two main kinds of entries: channel definitions and program listings, both wrapped inside a single root element.

Channel Elements

Near the top of the file, a series of <channel> elements each define one channel, tagged with a unique identifier and typically including a readable display name and sometimes a logo. Here's a simplified example:

That id="sports1" value is the piece that matters most for matching purposes, covered in the next section. A file can also include an <icon> element nested inside a channel entry, pointing to a logo image, which some apps use to display a channel's artwork in the guide grid even if that same logo wasn't already supplied through the playlist's own tvg-logo attribute.

Programme Elements

Below the channel definitions, a much larger number of <programme> elements each describe a single scheduled broadcast: which channel it belongs to, when it starts and ends, its title, and often a short description. A simplified example:

A full file typically contains thousands of these programme entries, one for every scheduled broadcast across every channel the source covers, stretching from the present moment out to however far ahead that particular EPG source publishes.

Example: a source covering 500 channels with an average of twenty scheduled programs per channel per day, a conservative estimate once you count every show, movie and segment change, would produce roughly 10,000 programme entries just to cover a single day. Extend that same coverage out to a full week, which many sources do, and the file can easily contain tens of thousands of individual programme entries, which explains why complete XMLTV files are often several megabytes in size despite being plain, uncompressed text.

Timestamps and Timezones in XMLTV

Notice the timestamp format in that example: a compact date and time string followed by a timezone offset. This is where the timezone confusion covered in our EPG guide often originates. The raw data is unambiguous, it always specifies an explicit offset, but your app has to correctly convert that into your local display time. When that conversion goes wrong, either from a misconfigured app setting or an incorrectly parsed offset, the result is a guide that shows accurate underlying data at the wrong displayed time.

How XMLTV Connects to Your Playlist

An XMLTV file, on its own, knows nothing about your specific playlist. The connection happens through matching: your app compares each channel's tvg-id attribute, defined in your M3U playlist and covered in our M3U format guide, against the id attribute on each <channel> element in the XMLTV file. A match links that channel's stream to its corresponding schedule data.

Example: a playlist entry with tvg-id="sports1" will correctly display guide data only if the XMLTV source also defines a channel with id="sports1". If the XMLTV source instead used id="sportschannel-1" for the same real-world channel, the identifiers wouldn't match character-for-character, and your app would have no way to connect the two, resulting in a channel that plays fine but shows no schedule information.

XMLTV vs. Other EPG Delivery Methods

XMLTV isn't the only way guide data gets to an app. As covered in our Xtream Codes explainer, panel-based logins can deliver EPG data dynamically through the same API used for channels and content, without ever generating a standalone XMLTV file the way a standard M3U-plus-guide setup would.

Functionally, both approaches aim to deliver the same kind of information. XMLTV's advantage is portability: since it's a plain, openly documented file format, it can be sourced independently of your specific provider, layered on top of any playlist, and swapped out freely if a better source becomes available. A panel-delivered EPG is more tightly bound to that specific provider's system.

There's a practical trade-off worth being honest about, though. A provider's own panel-delivered EPG is usually curated specifically to match that provider's exact channel lineup, meaning coverage and identifier matching tend to work correctly out of the box with minimal configuration. An independent XMLTV source offers more flexibility and often broader overall coverage, but puts the responsibility for correct identifier matching more squarely on you, since it was never built with your specific playlist in mind in the first place.

Where to Get an XMLTV Source

Most people get their XMLTV data from one of two places: bundled automatically with their IPTV provider's playlist, or from a separate, independently maintained public source added manually in their app's EPG settings, exactly as covered in our EPG guide.

When adding a source manually, you'll typically enter a direct URL pointing to an XMLTV file, similar in form to a playlist link. Your app fetches and re-parses that file periodically, the same refresh pattern used for M3U playlists, keeping schedule data current without requiring you to intervene once it's set up correctly.

It's worth testing a new source the same way we recommend testing a playlist link elsewhere on this site: open the URL directly in a browser first. A valid XMLTV source returns readable XML text beginning with a root tag, typically <tv>, followed by channel and programme elements. An error page or empty response tells you immediately that the problem is with the source itself, before you spend time troubleshooting your app's settings instead.

Combining Multiple XMLTV Sources

Because coverage varies so much between individual XMLTV sources, particularly for smaller or regional channels, many people end up using more than one at the same time. Apps that support this check each configured source in turn for a matching channel identifier, filling gaps a single source would otherwise leave behind.

Example: a primary XMLTV source might cover major international channels thoroughly but leave several regional channels blank. Adding a second, region-specific XMLTV source alongside it can fill in exactly those gaps, without affecting or duplicating the channels the first source already handles well.

How Apps Typically Prioritize Multiple Sources

When more than one configured EPG source contains data for the same channel identifier, apps handle the conflict in one of a few ways: some simply use whichever source is listed first in settings and ignore the rest for that specific channel, some attempt to merge entries, and a smaller number display both sets of data side by side, which usually looks like duplicated or conflicting program listings. Knowing which behavior your specific app follows is worth checking directly in its settings or documentation, since it changes how you'd go about ordering or prioritizing multiple sources deliberately.

A practical approach that works well regardless of exactly how an app prioritizes sources is to list your most complete, most reliable EPG source first, and treat any additional sources purely as gap-fillers rather than expecting them to override or improve on data the primary source already provides well.

Common XMLTV Problems

• Identifier mismatches between the playlist's tvg-id values and the XMLTV file's channel id values, the single most common cause of missing guide data.
• Large file sizes causing slow initial loading, particularly on lower-powered streaming devices parsing a very large combined source.
• Stale data, when a source hasn't refreshed recently and is still showing yesterday's schedule.
• Duplicate programme entries, when two active EPG sources both cover the same channel and the app doesn't prioritize or merge them cleanly.

Tips and Best Practices

• If a channel is missing guide data, check its tvg-id in your playlist against the XMLTV source's channel id list before assuming the source itself is broken.
• Prefer combining a couple of well-maintained EPG sources over piling on many low-quality ones, since duplicate or conflicting entries can create more confusion than missing data alone.
• Give a newly added XMLTV source time to fully load before troubleshooting further, especially on less powerful devices, given how large a complete file can be.
• If you're setting this up for the first time, our IPTV Smarters Pro guide and TiviMate setup guide both show exactly where an EPG source URL is entered.
• Revisit your EPG source occasionally even if it's working fine, since better-maintained alternatives do appear over time and coverage quality isn't static.

Common Mistakes

• Assuming a channel is broken when it's really just a tvg-id and XMLTV id mismatch preventing the schedule data from matching.
• Adding many overlapping EPG sources at once without checking whether they conflict, rather than starting with one reliable source and expanding only where gaps exist.
• Confusing an XMLTV source URL with a playlist URL and entering one into the field meant for the other.
• Assuming a stale-looking guide means the entire setup is broken, rather than simply triggering a manual refresh first.
• Overlooking timezone offset handling and blaming the raw schedule data for what's actually a display conversion issue.
• Piling on several EPG sources at once without understanding how your specific app prioritizes conflicting data, then being confused by duplicated or inconsistent listings.

Frequently Asked Questions

Conclusion

An XMLTV file is, at its core, no more mysterious than the M3U playlist it complements: structured plain text, channels and scheduled programs, connected to your streams through a shared identifier. Once that identifier-matching relationship clicks, most EPG troubleshooting stops being guesswork and starts being a specific, checkable thing.

Between this guide, our broader EPG guide, and our M3U format guide, you now have the full picture of how an IPTV channel guide actually comes together behind the scenes, from the playlist that defines your channels to the schedule data layered on top of them. Together, these three plain-text formats, M3U for channels, XMLTV for schedules, and the identifiers that tie them together, quietly do almost all of the structural work behind an IPTV app's interface, however polished that interface ultimately looks on screen.

If you're ready to add or troubleshoot an EPG source yourself, our IPTV Smarters Pro guide and TiviMate setup guide show exactly where that setting lives in each app.