tvg-id and tvg-name: how channel mapping really works

Almost every "my EPG does not work" report is really a mapping problem. The guide downloaded fine. It simply could not tell which of your channels each programme belongs to. Once you have seen how that decision is made, the fix is usually obvious — and often takes thirty seconds.

Two files that have to agree about names

An IPTV setup has two independent documents. The playlist lists your channels and where to stream them. The XMLTV guide lists channels and what is on them. Nothing connects the two except a shared identifier, and the two files are usually produced by different people who never coordinated.

A playlist entry looks like this:

#EXTINF:-1 tvg-id="TF1.fr" tvg-name="TF1 HD" tvg-logo="https://…/tf1.png" group-title="France",TF1 HD
https://example.com/live/user/pass/12345.m3u8

And the guide declares its channels like this:

<channel id="TF1.fr">
  <display-name>TF1</display-name>
</channel>
<programme start="20260804203000 +0200" stop="20260804220000 +0200" channel="TF1.fr">
  <title>Journal de 20h</title>
</programme>

Here tvg-id="TF1.fr" and id="TF1.fr" are identical, so the programme lands on the right channel. Change either side to TF1, tf1.fr or TF1.FR and, on a naive matcher, the guide goes blank for that channel while both files remain perfectly valid.

What each M3U attribute actually does

• tvg-id — the identifier that should match the XMLTV id. This is the only field designed for machine matching. When it is right, nothing else matters.
• tvg-name — a name used for matching when the identifier is missing or unknown. Often carries the noise: TF1 HD, TF1 FHD, |FR| TF1.
• tvg-logo — the channel logo. No effect on the guide whatsoever, despite how often it gets blamed.
• group-title — the category the channel appears under. Also unrelated to guide matching.
• The text after the final comma — the display name shown in the channel list. Used as a last-resort matching candidate when tvg-name is absent.

The matching chain, step by step

OneTV Connect walks these in order and stops at the first confident answer.

1. Exact identifier. The channel's tvg-id against the XMLTV id. Cheap, unambiguous, and how most channels resolve.
2. Normalised identifier. Same comparison with case and separators flattened, so TF1.fr and tf1.FR stop being two different channels.
3. Normalised name. Both sides are stripped of accents, punctuation, country prefixes and quality suffixes — HD, FHD, UHD, 4K, SD — then compared. This is what rescues a playlist with no usable identifiers at all.
4. Manual mapping. Anything you have mapped yourself wins over all of the above, permanently.

Several EPG sources can be active at once, and they stack rather than compete: the first source that has a programme for a given channel and time is used, the others fill the gaps. A source can also be tied to specific playlists, which matters when two providers use the same generic identifiers for different channels.

Why a match that looks obvious gets refused

Name matching is the step where a naive implementation does real damage. A wrong programme shown with confidence is worse than an empty slot: it makes people miss what they wanted to watch, and it silently poisons features built on top of the guide, like catch-up and sport detection.

So the name step is deliberately conservative. It refuses a match when:

• The numbers do not line up. "Sport 1" cannot match "Sport 2". Digits carry meaning in channel names and are never treated as noise.
• The candidate is not unique. If two guide entries normalise to the same name, neither is chosen — there is no way to know which one you meant.
• The best candidate is not clearly ahead. When the top two candidates are nearly as good as each other, that is a coin flip, and a coin flip is not a match.

This is why a channel that is obvious to you can stay unmapped: you know your provider's naming conventions, and the matcher only has two strings.

Mapping a channel by hand

Long-press the channel and choose Map to EPG. You get a searchable list of every channel the loaded guide declares — the raw catalogue from the source, not just the entries already matched to something, so you can find the entry the automatic pass rejected. Pick it and the guide fills in immediately.

Edit EPG mapping changes an existing choice, Remove EPG mapping hands the channel back to automatic matching. Mappings sync across your devices through iCloud, so an Apple TV and an iPhone stay in agreement, and they survive playlist refreshes.

The pragmatic approach: do not try to map two hundred channels. Map the ten you actually watch, leave the rest to the automatic pass, and revisit if you find yourself on an unmatched channel regularly.

Keeping a playlist matchable

If you build or edit your own M3U, three habits remove most of the pain:

• Set tvg-id to whatever your EPG source uses, exactly. Copy the id values out of the XMLTV file rather than inventing your own scheme.
• Keep quality markers out of tvg-id. TF1.fr, not TF1.fr.HD. Put the quality in the display name where it belongs.
• Pick the EPG source first, the playlist second. It is far easier to align identifiers to a guide you have chosen than to hunt for a guide that happens to match a playlist someone else generated.

Frequently asked questions

What is the difference between tvg-id and tvg-name?

tvg-id is meant to be a stable identifier shared with the EPG file, like TF1.fr or bbc-one.uk. tvg-name is a human-readable name used when no identifier matches. Matching on the id is exact and reliable; matching on the name is a best effort that has to survive HD suffixes, accents and regional variants.

My playlist has no tvg-id at all. Can I still get a guide?

Yes. Without an identifier the app falls back to comparing normalised channel names against the names declared in the XMLTV file, which resolves most mainstream channels. Anything ambiguous stays unmatched on purpose rather than being attached to the wrong channel, and you can map those by hand.

Why would a matcher refuse a channel that looks obviously right to me?

Because a wrong match is worse than no match. "Sport 1", "Sport 2" and "Sports 1" differ by a single character, and a guide showing the wrong match is misleading in a way an empty slot is not. The matcher requires the numbers in a name to line up and the best candidate to be clearly ahead of the runner-up.

Do manual mappings survive a playlist refresh?

Yes. A manual mapping is stored against the channel and synced through iCloud, so it survives a refresh, a reinstall and a second device. That is why it is worth fixing your ten important channels by hand once.

If your guide is still empty after mapping, the problem is upstream of matching — work through the EPG loading checklist first. Choosing a source with clean identifiers for your country makes all of this easier: XMLTV sources by country. And if your provider is Xtream, you may not need an XMLTV file at all — compare the two approaches.