XMLTV EPG Format Explained: How Electronic Program Guides Work

What is an Electronic Program Guide (EPG)?

An Electronic Program Guide (EPG) is the digital equivalent of a printed TV schedule. It provides viewers with information about current and upcoming programs for each channel, including titles, descriptions, start times, and sometimes additional metadata like categories or episode numbers. EPGs are built into most modern TVs, set-top boxes, and streaming apps, and they are essential for features like recording (PVR/DVR) and catch-up TV.

In legal IPTV services and streaming platforms, the EPG is typically delivered as a data feed that the app parses and displays in a grid or list format. The quality and accuracy of this data directly affect the user experience, making the underlying format an important topic for enthusiasts and cord-cutters.

Introduction to XMLTV: The Standard Format

XMLTV is an XML-based format designed specifically for describing TV listings. It emerged in the early 2000s as a community-driven effort to create a machine-readable way to exchange program schedule data. Because XML is a widely used and flexible markup language, XMLTV quickly became a de facto standard among hobbyists, developers, and eventually commercial services.

Today, many legitimate streaming applications and IPTV players support XMLTV feeds. The format allows a service provider or broadcaster to publish schedule information in a structured way that any compatible app can read. This interoperability is a key reason why XMLTV remains relevant even as newer technologies have appeared.

Anatomy of an XMLTV File

An XMLTV file is essentially a text document with a <tv> root element that contains two main types of child elements: <channel> and <programme>.

Channel Elements

Each <channel> element defines a single TV channel. It has a required id attribute that uniquely identifies the channel within the feed. Inside the channel element, you typically find one or more <display-name> elements, which provide the channel name in different languages or formats. For example:

<channel id="bbc1">
  <display-name>BBC One</display-name>
</channel>

Programme Elements

Each <programme> element describes a single program or show. It must have start and stop attributes that specify the broadcast time in UTC, using the format YYYYMMDDHHMMSS (e.g., 20250321190000 for March 21, 2025, at 19:00 UTC). The channel attribute references the channel ID. Inside the element, you typically find a <title>, a <desc> (description), and optionally <category> and <episode-num> elements. A simple example:

<programme start="20250321190000 +0000" stop="20250321200000 +0000" channel="bbc1">
  <title>News at Six</title>
  <desc>The latest national and international news.</desc>
  <category>News</category>
</programme>

Note that the timezone offset (+0000) is often included to avoid ambiguity. The XMLTV specification also supports many other optional elements, such as <icon> for channel logos and <rating> for content ratings.

How XMLTV Data is Used in Streaming Apps

Streaming applications like Plex, Jellyfin, and many IPTV players (e.g., TiviMate, IPTV Smarters) can ingest XMLTV data to populate their electronic program guide. The process typically involves three steps:

Fetching: The app retrieves the XMLTV file from a URL that the user provides or that is configured by the service provider. This URL might point to a file hosted on a web server or a dynamic feed generated by a backend service.
Parsing: The app reads the XML data and extracts the channel and programme information. It maps the channel IDs in the XMLTV file to the actual channels in the user's playlist or tuner.
Displaying: The app renders the schedule in a grid or list view, allowing the user to browse current and upcoming programs, set recordings, or schedule reminders.

Most apps allow users to manually configure the XMLTV URL in their settings. This flexibility is useful for users who have a custom playlist or who want to use a third-party EPG provider. Some apps also support automatic updates, refreshing the data periodically to keep the guide current.

Creating or Obtaining XMLTV Feeds

There are several legitimate ways to obtain XMLTV data:

Official broadcaster feeds: Some broadcasters publish their own EPG data in XMLTV format or provide APIs that generate it. This is the most reliable source, as the data is authoritative.
TV guide services: Third-party services aggregate schedule data from multiple sources and offer XMLTV feeds, often for a subscription fee. These are commonly used by IPTV providers and enthusiasts who need comprehensive coverage.
Self-generated feeds: If you have access to schedule data (e.g., from a broadcaster's API or a CSV file), you can create your own XMLTV file using scripting languages like Python or Perl. The XMLTV project provides a set of grabber tools (e.g., tv_grab_uk_rt) that can fetch data from specific regions and output XMLTV format.

Creating a custom feed is a good option for users who have a small set of channels and want full control over the data. However, it requires some technical knowledge and regular updates to keep the schedule accurate.

Common Issues and Troubleshooting

Even with a well-formed XMLTV feed, users may encounter issues. Here are some common problems and how to address them:

Timezone mismatches: If the start and stop times are not in UTC or the app does not correctly apply the timezone offset, programs may appear at the wrong times. Always ensure your feed uses UTC and includes the offset, and check your app's timezone settings.
Incorrect channel IDs: The channel attribute in <programme> elements must exactly match the id of a <channel> element. If they don't match, the program will not appear in the guide. Verify that your playlist's channel identifiers align with the XMLTV channel IDs.
Missing program data: If the feed has gaps or incomplete entries, the guide may show empty slots. This can happen if the source data is incomplete or if the feed is not updated frequently. Check the feed's update schedule and consider using a more reliable source.
XML validation errors: A malformed XML file (e.g., missing closing tags, illegal characters) can cause the app to fail to parse the feed. Use an XML validator to check the file for errors before loading it into your app.

Debugging often involves inspecting the raw XMLTV file, checking the app's logs, and ensuring that the URL is accessible and returns the expected content.

Conclusion: The Future of EPG Data

XMLTV has been a cornerstone of electronic program guides for over two decades. Its simplicity and flexibility have made it the go-to format for exchanging TV schedule data, and it remains widely supported in legal streaming applications. While newer standards and APIs are emerging, XMLTV's ease of use and community support ensure it will continue to play a role in the streaming ecosystem for the foreseeable future.

Understanding how XMLTV works empowers users to troubleshoot issues, customize their EPG experience, and make the most of their legal IPTV subscriptions. Whether you're a casual viewer or a dedicated enthusiast, knowing the structure and purpose of XMLTV is a valuable skill in the world of modern television.