Guide

How to find and add a TV guide (EPG) to your IPTV

The EPG, the electronic programme guide, is what puts “now” and “next” beside every channel. It is an XMLTV file at an address of its own. Here is what that address looks like, where to find it, how to add it in Aina, and what to check when the guide shows nothing.

Updated · By the Aina IPTV team

Where your EPG URL comes from

  • An Xtream Codes login has one built in, at the same server, with the same username and password: http://server:port/xmltv.php?username=…&password=…. It is the get.php link with xmltv.php in its place. Aina fetches it by itself, so there is nothing to type.
  • An M3U playlist often names its own, in its first line: #EXTM3U x-tvg-url="https://…/guide.xml.gz" (or url-tvg). Some name several, separated by commas, one per country; Aina loads every one without being asked.
  • Otherwise your provider sends one: a link ending in .xml, or .xml.gz when it is compressed. Both work.
  • A MAC portal brings its own guide, which Aina reads as a set-top box does. A portal that publishes none can be given a guide link in Settings, then TV guide sources.

What is in an XMLTV file

XMLTV is the format almost every IPTV guide uses: a plain text file, often gzipped, with a list of channels and then their programmes. These are the parts that matter:

The parts of an XMLTV guide that a player reads.
PartWhat it holds
<channel id="…">One channel and the id its programmes are filed under, such as mychannel.uk. The guide’s channel list is all of these.
<display-name>The channel’s name, sometimes in more than one language.
<programme start="…" stop="…" channel="…">One programme, its start and end with their time zone, and the channel id it belongs to.
<title>, <desc>, <category>What the programme is called, what it is about, and its kind.

A week of guide for a big line can run to hundreds of megabytes, which is why providers gzip it. Aina writes the file to storage as it downloads and reads it a piece at a time, so a guide that size does not run a phone or a TV stick out of memory.

If your provider has no guide

  • Ask for one first. A guide made for your line matches its channels best, and most providers have one even when they do not mention it.
  • Look in the playlist. Open it in a text editor and check its first line for x-tvg-url.
  • Make one yourself. iptv-org/epg is an open project on GitHub that builds an XMLTV file from the schedules TV sites publish, for the channels you choose. It is a tool you run on a computer, not a ready link, and the file it writes needs to sit at an address your devices can reach.

Open it in a computer’s browser. A working .xml link shows text that begins with <?xml or <tv; a .xml.gz link downloads a file. A login page, an error or an empty page means the link is wrong or has expired: ask your provider for a new one. An Xtream Codes xmltv.php link that comes back empty usually means the provider publishes no guide for that line.

Add a guide to an M3U playlist

  1. 1

    Start adding the playlist

    In Aina, choose M3U playlist on Add your subscription, or go to Settings, then Subscriptions, then Add a subscription.

  2. 2

    Paste the playlist link

    Into Playlist URL, as usual.

  3. 3

    Paste the guide link

    Into Guide URL (optional): the .xml or .xml.gz link. Leave it empty if the playlist names its own guide.

  4. 4

    Connect

    The channels come first and the guide follows. A big guide can take a minute.

Add another guide later

Settings, then TV guide sources, works for any subscription, Xtream Codes and MAC portals included. Add a guide by its XMLTV address to fill in the channels your provider’s guide leaves out, give each guide its own time, and switch any of them off. Update the guide now applies a change at once.

How the guide finds your channels

A playlist gives each channel the id it should have in the guide, tvg-id="mychannel.uk", and the guide files programmes under <channel id="mychannel.uk">. Aina matches the two. Where a channel has no id, or the guide uses a different one, Aina tries the channel’s name, so a guide from another source can still fill much of your line.

Why the guide looks empty or wrong

  • The guide does not cover those channels. A guide is published for a set of channels; ask your provider for the one made for your line.
  • The ids and names do not match. Channels the guide calls something else stay empty. Your provider’s own guide matches best.
  • The guide has run out. Guides cover a few days ahead. If a provider stops updating its guide, the schedule ends where the file does.
  • It is still loading. Aina fills the schedule in once the whole file has arrived, which for a big guide can take a minute or two.
  • The times are off. A guide carries its own time zone for every programme, and Aina shows them in yours. If every programme is out by the same hours, the provider’s guide is labelled wrong: in TV guide sources, move it later or earlier by the hour or half hour until it fits.

What you get once it is in

Now and next under every channel, the guide of what is on now and tonight with a programme search, a week per channel, and catch-up where your provider keeps an archive.

Questions and answers

With an Xtream Codes login it is your server’s xmltv.php with your username and password, and Aina uses it by itself. With an M3U playlist, look for x-tvg-url in its first line, or ask your provider for its .xml or .xml.gz guide link.

The file format almost every IPTV provider uses for its guide: a list of channels, each with an id, and of programmes with their channel, start and end times, titles and descriptions.

Only in being compressed, which makes it much smaller to download. Aina reads both.

Yes, any XMLTV link works in Aina. A guide from another source fills only the channels whose ids or names match, so your provider’s own guide is the best place to start, and a free one can fill the gaps beside it in TV guide sources.

No. The guide comes from your provider’s panel by itself. You can still add guides of your own in Settings, then TV guide sources, for channels it does not cover.