How to Parse and Use XMLTV for IPTV and PVR Applications

XMLTV: A Complete Beginner’s Guide to TV Listings and Scheduling

What is XMLTV?

XMLTV is an open XML-based file format and a set of tools for storing, exchanging, and processing TV listings (EPG — electronic program guide) data. It describes channels and programmes using structured XML so media players, PVRs, IPTV systems, and scheduling tools can import and display TV guide information.

Why use XMLTV?

• Interoperability: Standard XML structure makes it easy to share guide data between apps and services.
• Automation: Fetch and update guides regularly for recording, reminders, or EPG displays.
• Flexibility: Supports extended metadata (descriptions, categories, credits, episode numbers, durations, ratings, images).
• Open ecosystem: Multiple grabbers, converters, and viewers exist across platforms.

Key XMLTV concepts

• tv root element: Contains channel and programme entries.
• channel element: Identifies a broadcast source with a unique id and display-name(s). Includes optional icons and URLs.
• programme element: Describes a single airing with attributes start, stop, and channel (referencing a channel id). Child elements include title, desc (description), category, length, credits, rating, episode-num, icon, and previously-shown.
• Time formats: Times are usually in the format “YYYYMMDDhhmmss +0000” (UTC offset may be included) or similar variants. Correct timezone handling is vital.
• Grabbers: Scripts or programs that fetch guide data from web sources and output XMLTV files.

Basic XMLTV file structure (example)

xml
Copy CodeCopied
<?xml version=“1.0” encoding=“UTF-8”?>
<tv generator-info-name=“xmltv-example”>
<channel id=“channel-123”>
    <display-name>Example Channel</display-name>
    <icon src=“https://example.com/logo.png” />
  </channel>

  <programme start=“20260204T180000 +0000” stop=“20260204T190000 +0000” channel=“channel-123”>
    <title lang=“en”>Evening News</title>
    <desc lang=“en”>Top stories and live reports.</desc>
    <category lang=“en”>News</category>
    <length units=“minutes”>60</length>
  </programme>
</tv>

How to obtain XMLTV data

1. Use existing grabbers (xmltv project provides many), which scrape broadcaster web pages or APIs.
2. Download provider dumps — some broadcasters or third parties offer EPG exports.
3. Convert other EPG formats (JSON, CSV) to XMLTV using scripts or tools.
4. Use community-maintained services that produce XMLTV for specific regions or IPTV providers.

Popular tools and libraries

• xmltv (grabbers): The canonical set of scripts for many countries.
• WebGrab+Plus: Flexible EPG grabber with rule-based scraping.
• EPG Collector / EPG123: Tools for Windows users to obtain guides for Plex/NextPVR.
• python-xmltv / xmltv-tools: Libraries for parsing and manipulating XMLTV in Python.
• tvgrab scripts:* Country-specific grabbers included in the xmltv project.

Working with timezones and scheduling recordings

• Store times in UTC when possible; include offsets if using local times.
• When scheduling recordings on a PVR, allow padding (pre/post) to account for schedule shifts. Typical padding: 1–2 minutes pre, 2–5 minutes post; for live events use larger buffers.
• Use episode or unique IDs to avoid duplicate recordings of reruns if your recorder supports it.

Common fields and useful tags

• title / sub-title / desc — human-readable names and summaries.
• category — genre like News, Drama, Sports. Useful for filtering.
• episode-num / dvd-episode — episode numbering (XMLTV supports multiple systems).
• rating — parental guidance data.
• credits — director, actor, writer entries.
• previously-shown — indicates reruns.
• icon — program image or poster URL.

Best practices

• Validate XML with an XML parser and the xmltv DTD if available.
• Normalize channel ids consistently between guide and channel lists.
• Keep guide files reasonably sized — split by day or channel sets if needed.
• Automate regular updates (e.g., cron job) to keep schedules fresh.
• Test recordings with sample buffer settings to find reliable defaults.

Troubleshooting tips

• Missing channels: ensure channel id strings match exactly between channel and programme entries.
• Wrong times: check timezone handling and whether grabber outputs UTC or local times.
• Duplicate programmes: verify unique programme identifiers or filter by episode-num.
• Parsing errors: run through an XML linter to catch malformed tags or invalid characters.

Example workflow: Use XMLTV with a PVR (assumes basic defaults)

1. Choose a grabber for your region and configure channel list.
2. Run grabber to produce daily XMLTV file (e.g., epg.xml).
3. Configure PVR/mediacenter (Kodi/Plex/NextPVR) to import epg.xml and map channels.
4. Set recording rules or manual schedules; include padding.
5. Automate grabber runs (daily) and reload EPG in the PVR.

Resources to learn more

• xmltv project’s documentation and grabbers (search for “xmltv” + your country).
• WebGrab+Plus documentation for advanced scraping rules.
• Community forums for your PVR or media center (Kodi, Plex, NextPVR).