IPTV guide

M3U playlists and XMLTV programme guides: how they work in Vireko

An IPTV service usually gives you two addresses: an M3U playlist with the channels and an XMLTV programme guide with the listings. In this guide we explain what the files contain, how Vireko matches channels to the guide and how to fix the most common problems, such as missing programme info and wrong times.

Written by Aleksi Kiltala, Kiltala Oy · Published 6 November 2026

Short answer

An M3U playlist is a text file in which each channel has an info line and an address. XMLTV is an XML programme guide with channels and their programmes, including start and end times. Vireko matches a channel to the guide when the playlist’s tvg-id equals the guide’s channel ID. If programme info is missing, match the channel manually. If the times are wrong, fix them with a time shift. By default the guide refreshes every six hours.

Vireko IPTV PlayeriOS · Mac · Apple TV · Android · Android TV
M3U

What is an M3U playlist?

M3U is a simple text-based playlist. IPTV services use it to list channels, movies and series.

Structure

An extended M3U file starts with the line #EXTM3U. Each channel has an #EXTINF line with the channel’s details and name, followed by a line with the stream address. The same format is also used in HLS streaming, whose specification is published as RFC 8216.

Channel details

IPTV playlists usually add details to the #EXTINF line, such as tvg-id, tvg-name, tvg-logo and group-title. Vireko uses tvg-id to match the guide, tvg-name as the channel name, tvg-logo as the logo and group-title as the category. If group-title is missing, Vireko uses an #EXTGRP line. Vireko also reads catch-up details, such as catchup, catchup-source and catchup-days.

Programme guide straight from the playlist

If the #EXTM3U line has a url-tvg or x-tvg-url attribute, Vireko uses it as the guide address automatically. A guide address you have entered yourself takes priority.

Movies and series

Vireko recognises movies and series in a playlist automatically, for example from the address path (/movie/, /series/), an episode name (S01E02), the file extension (such as .mp4 or .mkv) or the category name. Other entries are shown as live channels.

XMLTV

What is an XMLTV programme guide?

XMLTV is an XML file format for TV listings, maintained by the XMLTV project.

Channels and programmes

The file contains channel elements with an ID and a name, and programme elements with the channel ID, start and end time, title and description. Times are written for example as 20260106200000 +0200: the date and time followed by the time zone offset.

What Vireko reads

From channels Vireko uses the ID and the first name, and from programmes the title, subtitle and description. The time zone is read from the end of the time. If it is missing, the time is treated as the device’s local time.

Compressed files

The guide can be a plain XML file or gzip-compressed (.xml.gz or .gz). Vireko recognises compression from the file’s content. Vireko does not support ZIP files. A gzip-compressed playlist is also unpacked automatically.

Matching

How are channels matched to the programme guide?

Programme info only appears when a playlist channel and a guide channel have been matched. This is how Vireko does it.

  1. tvg-id firstWhen the playlist’s tvg-id is exactly the same as the guide’s channel ID, the channel is matched automatically.
  2. By name when the match is certainIf a channel has no guide, Vireko compares names, ignoring things like country tags, channel numbers, letter case and words such as HD or 4K. It only matches automatically when there is exactly one matching channel and it has programmes.
  3. Auto-matchThe auto-match screen also looks for matches in the guides of your other playlists and pre-selects the safe ones. Nothing changes until you confirm.
  4. Manual matchingChoose a channel and search the guide for the right one by name. A manual match stays until you change it.
  5. A guide of its own for one channelYou can give a channel its own XMLTV address. Use a small single-channel guide, because all its programmes are assigned to that channel.
Problems

Common problems and fixes

Vireko’s error messages tell you what went wrong when loading a playlist or guide. Here is how to fix the most common situations.

  • Programmes show at the wrong timeThe guide is usually in a different time zone. Fix the times with a time shift, which you can set for one channel or for all channels in half-hour steps, up to 12 hours either way. The channel and guide shifts are added together.
  • The guide loads but no programmes appearThe playlist’s channels probably lack a tvg-id, or it does not match the guide’s IDs. Use auto-match or match the channels manually.
  • The link returns a web pageIf the playlist or guide address opens a web page instead of a file, use a direct download link. Google Drive share links, for example, often open a web page.
  • The playlist is empty or the server returns an errorCheck the address, the login and that your subscription is active. Vireko shows the server’s HTTP error code, which tells you whether the problem is with the server or the address.
  • A favourite disappeared after a refreshFavourites, watch history and continue watching for M3U channels survive a refresh, because they are tied to the stream address. If the provider changes a channel’s address, the favourite is lost and you need to add it again.
  • Catch-up does not workCatch-up only works if the playlist has catch-up details and the service archives the channel. Vireko supports, among others, the flussonic, append, shift and Xtream types. If catchup-days is missing, an archive length of seven days is assumed.
Settings

Refreshes, extra guides and Xtream Codes

Playlist refresh

By default the playlist refreshes once a day. You can choose every launch, 6, 12, 24 or 48 hours, or manual only.

Guide refresh

By default the guide refreshes every six hours. You can choose every launch, every hour, 3, 6, 12 or 24 hours, or manual only. Vireko only downloads the guide again if it has changed.

Extra guides

You can add other XMLTV guides to a source, and they are merged with its own guide. A guide address you enter yourself replaces the provider’s guide.

Xtream Codes

For an Xtream Codes source, Vireko builds the guide address (xmltv.php) automatically with the same login, unless you have entered your own address. If there is no XMLTV guide, Vireko fetches a short guide for each channel from the server.

FAQ

Frequently asked questions

What is the difference between M3U and M3U8?

Both are the same playlist format. The M3U8 extension means the file uses UTF-8 encoding. HLS streaming uses .m3u8 files. Vireko accepts both .m3u and .m3u8 files as playlists.

Where do I get an XMLTV programme guide?

Usually from your IPTV service. The guide address may be at the start of the playlist as a url-tvg attribute, in which case Vireko uses it automatically. For an Xtream Codes source, Vireko builds the guide address itself.

Why does a channel have no programme info?

The channel has not been matched to the guide because the playlist’s tvg-id is missing or does not match the guide’s ID. Use auto-match or match the channel manually. It is also possible that the guide has no data for that channel.

Why are programmes shown at the wrong time?

The guide’s time zone is probably different from what you expected. Fix the times with a time shift for one channel or the whole guide in half-hour steps.

Does Vireko support compressed playlists and guides?

It supports gzip-compressed files, and recognises the compression from the file’s content. Vireko does not support ZIP files.

How often does the programme guide refresh?

Every six hours by default. You can choose every launch, every hour, 3, 6, 12 or 24 hours, or manual only.

Does catch-up work with an M3U playlist?

Yes, if the playlist has catch-up details and the service archives the channel. Vireko supports, among others, the flussonic, append, shift and Xtream types, and catchup-days tells how many days back the archive can be watched. Read more about setting up Vireko in our guide IPTV on Apple TV, iPhone and Mac.

Sources

The general information on the formats is based on these sources, checked on 6 November 2026. How Vireko works was checked against the source code of the app’s iPhone, iPad, Mac and Apple TV versions.

Contact

Let’s build something great together.

Need a website for your business, a review of your current site or help with an app idea? Tell us about it and we will get back to you soon.

Your message comes straight to us.