XMLTV and EPG links: find one, check it, add it

An EPG link points to an XMLTV file, the listings that fill a player's TV guide. Here's where to find yours, what a working one looks like and how to add it in Vela, which includes no channels and no guide of its own.

What an XMLTV link is

EPG stands for electronic programme guide: the listings of what's on each channel. Most IPTV players read them in XMLTV, a plain XML format, and an EPG or XMLTV link is the address of that file. It has two parts:

Channels: one entry each, with an id and a name, such as <channel id="news.example"> and <display-name>Example News</display-name>.
Programmes: a start, a stop, the id of the channel it belongs to and a title, often with a description, as in <programme start="20261019200000 +0000" stop="20261019210000 +0000" channel="news.example">.

The playlist says what you can watch; the guide says when. A player matches the two by channel id, which is where most guide trouble starts.

Where to find yours

In the playlist's first line, as in #EXTM3U url-tvg="http://example.com/epg.xml.gz". Some playlists say x-tvg-url or tvg-url, and some name several, separated by commas.
In your provider's welcome email, often next to the playlist link.
On an Xtream server, at xmltv.php, with the same login (below).
On your own server. DVR software such as Tvheadend serves its own XMLTV; see HDHomeRun and Tvheadend on iPhone.

The guide on an Xtream login

Servers that speak the Xtream API usually publish their whole guide as one XMLTV file, on the same address and port as the login, with the same username and password in the link:

http://example.com:8080/xmltv.php?username=YOURNAME&password=YOURPASS

If you sign in to Vela with the Xtream login itself, you don't need it: Vela asks the server for each channel's listings as the channels come on screen, with no link to enter and no large file to download. If a channel's guide is empty that way, the provider has no listings for it, and its xmltv.php usually won't either.

The xmltv.php link is for using the account as a plain playlist, in a player that only reads M3U or in Vela with Read it as a plain playlist instead turned on. If it's all you have, paste it into Vela's Playlist Link (M3U or M3U8): Vela finds the login inside and signs in with it.

Telling a good guide link from a bad one

It returns a guide

Paste the link into Safari. A guide either downloads or shows XML that starts with <?xml or <tv. A web page, a sign-in form or an error means the link is wrong, has expired, or is missing the login it needs.

Gzip is fine

Full guides are big, so many are served gzipped, usually ending in .gz. That's normal. Vela reads plain and gzipped guides and tells them apart by what's inside, so a gzipped guide without .gz in its address works too. Some players only read plain XML; if one stays blank on a .gz link, ask for the plain one.

The times carry a time zone

Each programme's start and stop should end with an offset from UTC, like +0000 or +0200, and the player converts that to your iPhone's time. Vela reads +HHMM, +HH:MM and Z, and treats a time with no offset as UTC. When every programme is out by the same whole number of hours, the guide's offsets are wrong, or the iPhone's own time zone is; IPTV guide (EPG) not showing goes through both.

The channel ids match the playlist

The id of each guide channel has to equal the tvg-id of a channel in the playlist:

Playlist: #EXTINF:-1 tvg-id="news.example" group-title="News",Example News
Guide: <channel id="news.example">

A guide for another line-up or region can be valid and still match almost nothing. Vela compares ids ignoring capitals, uses tvg-name when a channel has no id, and also accepts a guide channel whose display name matches the channel's name once both are tidied up. When nothing matches, Account says “The guide has no listings for these channels.”

It reaches the days ahead

A useful guide runs at least a day or two past today. Vela keeps listings from a few hours back to two days ahead, and fetches the guide again with the playlist every 12 hours, unless you change Auto-refresh in Account.

Adding a guide link in Vela

A separate guide goes with an M3U playlist. At sign-in:

Choose M3U Playlist and paste the playlist into Playlist Link (M3U or M3U8).
If the playlist names its own guide, Vela fills in TV Guide Link (XMLTV, optional) and says “Named by the playlist.” If it names several, Vela reads them all.
Otherwise paste your guide link there. It has to be a web address, http:// or https://; Vela doesn't take a guide from Files.
Tap Sign In.

With a playlist file, paste the guide link first and then tap Import from Files. Leave it empty and Vela uses the guide the file names in its first line, if it names one.

Later, in Account, Listings shows how many programmes and channels the last read found. Change TV guide link takes a new one; Use the Playlist's Own goes back to the playlist's; Refresh playlist and guide reads both again now. A large guide on a slow connection can take a few minutes.

Keep the link to yourself

An xmltv.php link carries your username and password, the same as the login, so leave it out of forum posts and screenshots when you ask for help. Vela's Account screen shows only the server and the file name of a guide link, never the part with the password.

Vela includes no channels or content. Use it only with a subscription or playlist you're entitled to use.