EPG & XMLTV for IPTV: The Complete Guide

A TV without a guide is just a list of frequencies. The Electronic Program Guide (EPG) is what turns "channel 482" into "The Late Show with Stephen Colbert — 11:35 PM". For IPTV, the EPG is delivered through a standard called XMLTV, and the way you hook it up makes the difference between a polished, modern living-room and a frustrating spreadsheet of URLs. Here's everything you need to know.

What is XMLTV, exactly?

XMLTV is an open XML format from the early 2000s describing what is on, where, and when. A typical entry looks like this:

<programme start="20260425200000 +0200" stop="20260425210000 +0200" channel="france2.fr">
  <title lang="fr">Le 20 Heures</title>
  <desc>Journal télévisé présenté par Anne-Sophie Lapix.</desc>
  <category>News</category>
</programme>

Each <programme> ties a slot of time to a channel id. The matching <channel> tag at the top of the file maps that id to a display name. If your channel name in the playlist does not match the XMLTV tvg-id, you get an empty guide — that is the #1 source of "EPG not working" complaints.

Where the EPG comes from

Setting up EPG in StreamVision

Path A — Xtream Codes (zero config)

If you connected with Xtream credentials, the EPG is already on. The app calls get_short_epg per channel on demand and a full data table once a day. There is nothing else to do.

Path B — M3U + external XMLTV

Time zones: the silent killer

Half of all "wrong EPG" reports come down to time zone math. XMLTV times are absolute (20260425200000 +0200), but some XMLTV files are produced with the wrong offset, or worse, with no offset at all. StreamVision applies, in order:

1. The offset embedded in the XMLTV entry, if present and valid.
2. A per-source override you can set in the app (useful for stripped feeds).
3. Your phone's current zone as a last resort.

If your guide is two hours off, do not blame the player — open the XML file and check the offset on a few <programme> tags first.

Channel-to-EPG mapping (the tvg-id trick)

In an M3U, each line should declare a tvg-id that matches a channel id in your XMLTV file:

#EXTINF:-1 tvg-id="france2.fr" tvg-name="France 2" group-title="FR FTA",France 2
http://server.com/live/USER/PASS/123.ts

If the playlist uses tvg-id="FR2" but the XMLTV channel id is france2.fr, the guide will be blank. StreamVision lets you remap manually per channel — handy when a provider keeps changing its conventions.

Compressed XMLTV (.xml.gz, .xz)

A full week of EPG for 2,000 channels easily reaches 80 MB raw. Most public sources serve a gzipped version (.xml.gz), often 10× smaller. StreamVision auto-detects the extension and decompresses on the fly — no extra step required.

Troubleshooting checklist

• Empty guide on every channel. tvg-id mismatch — open one channel info and check the assigned id.
• Guide loads then disappears. URL returns HTTP 200 with HTML (a login page) instead of XML.
• Now/next OK but no future shows. XMLTV file only contains today; switch to a 7-day source.
• Special characters look broken. XML declared as iso-8859-1 while the file is UTF-8 — re-export from the source.
• EPG eats battery. Lower the refresh frequency to every 24 hours; a week-long guide rarely needs more.

Why bother with EPG at all?

Beyond pretty grids, a real EPG enables: recording timers (Xtream catch-up), "now playing" voice search on Android TV, parental control by age rating, smart notifications when your team kicks off, and the simplest thing of all — knowing what's on without scrubbing through 8,000 channels. It's the single feature that makes IPTV feel like real TV.