IPTV EPG: how the programme guide works

1. Where the app gets the guide from

The XMLTV address can come from three places. The app checks them in this order:

• From the playlist header. Many M3U playlists carry a url-tvg or x-tvg-url entry on their first line. If yours does, there is nothing to type - the guide downloads on its own when you open the list. The list tile on the home screen then shows the EPG auto badge.
• From an address entered with the list. When adding or editing a list there is an "EPG address (XMLTV)" field. If you fill it in, it takes precedence over the header. Badge on the tile: Custom EPG.
• From the default address in Settings. You can set one guide address for every list that has none of its own. For a specific list you can also tick "Use the app's default EPG" to ignore the address in its header.

The channel list header states plainly which source is in use: "Guide from the provider list", "Guide from the address you entered" or "Guide from app settings". When something is off, that is the first place to look.

2. Supported file formats

The app accepts XMLTV as a plain .xml file and as gzip-compressed .xml.gz. Compression is detected from the content, not the file name, so an address without a .gz suffix works too as long as the server sends gzip.

Not supported: .xz, .zip and .7z archives. If your provider only offers the guide that way, ask for the .xml or .gz variant - most panels have both.

From the file the app reads: channel identifiers and names, station logos, and for each programme the start and end time, title, description, category, production year and age rating, where the provider supplies them.

Times in XMLTV should include a timezone offset, e.g. 20260904200000 +0200. If the file gives times without one, the app treats them as the device's local time - with a guide from another timezone the schedule will be shifted.

3. How channels are matched to the guide

The playlist and the guide are two separate files, often from two different sources. To know which schedule belongs to which channel, the app tries three rules, in order:

• Identifier - the channel's tvg-id attribute in the playlist must equal the channel id in XMLTV. This is the reliable method and the one every well-made playlist should support.
• Name - if the identifier is missing or does not match, the channel name is compared (case-insensitive).
• Simplified name - quality markers (HD, FHD, UHD, SD, 4K, PL), spaces and special characters are stripped from both names. That is how "TVP 1 HD" in the playlist finds "tvp1" in the guide.

One matching rule is enough. The channel list header shows how many programmes were loaded - if the number is near zero for a large list, the identifiers and names in the two files most likely do not line up (see section 7).

4. Where the guide shows up in the app

• Channel list - the current programme under each channel name.
• Player bar - time and title, a progress bar for the programme, "Next" underneath.
• Programme details - a window with the full description, times and progress.
• Channel schedule - days in tabs, every programme with its description, the current one highlighted. Future programmes have a bell: it sets a reminder, and the app switches to the channel by itself a minute before the start. Scheduled programmes are listed on the home screen.
• Archive - if your provider offers catch-up, programmes that have already ended are started from the same channel schedule (see section 5).

5. Guide history and catch-up

Providers usually include only 2-3 past days in the XMLTV file. Catch-up often reaches further back - 7 or 14 days - but without a guide for those days there is no way to pick a programme to play.

That is why IPappTV does not replace the guide on every download; it adds new data to what it already has. The future is overwritten with the fresh version (schedules change), the past is kept. After a few days of use the app holds more history than the provider ever sent at once.

How many days to keep is set by "Days of guide history to keep". Auto takes whatever your playlists declare in the catchup-days attribute. Settings also show how many days have been collected so far, with a reset button in case the data looks wrong.

Note: uninstalling the app or "Clear cache" in Settings deletes the collected history. It starts building again, one day at a time.

6. Refreshing: when a new file is downloaded

XMLTV files can be large - tens of megabytes uncompressed - and providers limit the number of downloads. The app does three things to avoid downloading needlessly:

• Conditional requests. Every check sends If-None-Match and If-Modified-Since headers. If the file on the provider's server has not changed, it answers 304 and nothing is transferred - the guide loads from local storage in a fraction of a second.
• Refresh interval. The "Refreshing lists and EPG" setting: 12, 24 or 48 hours. Less often means a lower risk of hitting provider limits.
• Background refresh. The guide can update while the app is closed. On phones and tablets this runs only on Wi‑Fi; on TV on any connection. When turned off, the guide still refreshes while the app is open.

A manual refresh is always available: "Refresh list and EPG" in the channel list menu.

7. When the guide does not work

The most common causes, most likely first:

• The list has no guide address. The channel list header says "no EPG". Check with your provider whether they offer an XMLTV file, then enter its address with the list or in Settings.
• The guide downloaded, but channels have no schedule. The tvg-id values in the list do not match the id values in XMLTV, and the names differ by more than "HD". The most effective fix: a guide from the same provider as the list - then the identifiers are consistent.
• Programmes are shifted by an hour or two. The file has times without a timezone, or in a different one. This has to be fixed at the source.
• "EPG - loading error". The address is unreachable, needs credentials that are not part of the URL, or the file is in an unsupported format (e.g. .xz).
• The guide reloads from scratch every time. The provider's server does not support conditional headers, so the whole file has to be downloaded. Raising the refresh interval to 48 h helps.

If none of this fits, write to kontakt@ipapptv.com - with the list name (no address or credentials) and what the channel list header shows.

8. Privacy

The guide is downloaded straight from the address you provided and stored only on your device. The app has no server of its own and sends nowhere any information about which lists, channels or programmes you watch.