tvg-chno: channel numbers in IPTV playlists, and what every player does with them

tvg-chno="1"      107 entries
tvg-chno="2"       92
tvg-chno="3"       80
tvg-chno="4"       72
tvg-chno="5"       68
tvg-chno="#"        4
tvg-chno="22.1"     1

That is the head of one real playlist's channel-number histogram, with two of its stranger values pinned underneath. The file holds 1,895 entries. 1,355 of them carry the attribute, and those 1,355 numbers cover 263 distinct values, a mean of 5.15 entries per value. The single most popular number in the file is claimed by 107 unrelated channels.

No standard defines what any of that means. There is no specification for tvg-chno, no registry, and no owner. The reference implementation documents it in one line of a README, and the applications that read it disagree about the spelling, the type, the fallback and whether to show the value at all.

Where the attribute came from, as far as anyone can show#

RFC 8216 is an Informational submission rather than a standards-track document. It defines EXTM3U in section 4.3.1.1, EXTINF in section 4.3.2.1, and the #EXT-X- family, and the string tvg does not appear in it anywhere. Its attribute-list grammar is comma-separated with a fixed name form, which the space-separated tvg- convention does not follow, and the same section tells clients to ignore names they do not recognize. That instruction is what lets the convention live beside the RFC: everything below is a private agreement between one program and the playlists it happened to be shown.

The earliest appearance of tvg-chno I can point at is pull request #92 against Kodi's IPTV Simple add-on, opened 2016-11-24 and merged 2016-12-17. I cannot prove it is the first, only that nothing earlier is public. It adds one marker constant, and its author's stated motivation was syncing channel numbers with a backend. The negative evidence around it is stronger than the commit: an issue on the same tracker from 2015-07-20 says plainly that the M3U format has no tag for a channel number and proposes packing the number into the channel name instead. The author of #92 found that issue five minutes after opening his pull request, and the maintainer later closed it as fixed by his patch. As of mid-2015 the add-on's own community did not know of any such attribute.

The tvg- prefix is almost four years older than the number. tvg-name, tvg-logo and group-title sit in the add-on's initial project commit of 2013-01-17, tvg-id lands the same day, and tvg-shift four days after that. What tvg abbreviates is folklore: everyone reads it as "TV guide" and the sibling attributes that carry the guide address support that reading, but no first-party source states the expansion, and the accounts tracing the attribute set to an earlier Windows player ecosystem are second-hand. The negative is firmer. XMLTV is where these attributes point, not where they came from.

Adoption after Kodi runs Tvheadend emitting it in March 2018, Emby documenting it during 2018, Jellyfin in February 2019. The most irritating detail in the harvest is that the Tvheadend commit message says it adds a tvg-chnum attribute while the code it lands writes tvg-chno=, and on the way back in it reads tvh-chnum first, falling back to tvg-chno. At least five spellings carry a channel number in real files: tvg-chno, channel-number, ch-number, tvh-chnum, and a channel-id some readers treat as a number.

1,176 of the 1,355 numbers are shared with another row#

We measured three sample playlists we hold locally, 2,209 entries in total. Two of the three number nothing at all: zero of their 314 entries carry the attribute. Everything here is the third file.

The values are lopsided. 179 of the 263 distinct values are used exactly once, so most of the mass sits in a short head: 107 entries on number 1, then 92, 80, 72 and 68. The range runs from 1 to 4,999, so the parser's ceiling of 99,999 has never fired. 1,176 of the 1,355 rows, 86.8 percent, share their number with at least one other row, and a unique key laid over the file would drop 1,092 of them. Counting only the values our parser accepts, the sharing figure is 1,172 of 1,299, or 90.2 percent.

Why nothing in one of these files is a stable key is settled in the extended M3U article, and I will not re-argue it here. What that article does not do is kill the obvious repair: if numbers duplicate across a file, scope them to the group they sit in and each group gets a clean sequence.

It does not work.

33 of the 85 groups that carry any number at all contain at least one duplicated number inside the group. 69 of those 85 contain a channel numbered 1. One group holds 7 entries all numbered 1, and inside the largest group of the file, 79 numbered entries cover 74 distinct numbers. Grouping reduces the collision count without removing it, and a fix that works for two thirds of your groups fails silently on the other third.

The absence rate matters as much as the duplication. 596 of the 1,895 entries, 31.5 percent, end with no usable number: 540 never carried the attribute, and 56 carried something the parser refuses. Cross-referencing with the id attribute, 398 rows carry neither a number nor an id, the population nothing in the file can address. A guide row with nothing to attach to surfaces as a schedule wrong on some channels and right on others, never as a numbering complaint.

Every decimal in the file is Argentine#

25 entries use major.minor numbering, over 24 distinct values running from 22.1 to 36.2, and only 32.1 repeats. Every one of the 25 carries country AR, an id ending .ar, and the group Argentina, which holds 26 entries and numbers all 26. Argentina broadcasts ISDB-Tb. ATSC and ISDB-Tb both use the major.minor shape, and the shape is all they share here. Our own source comment calls these values ATSC-style, which is true of the shape and false about the origin.

Those 25 rows are why the number is a floating point value rather than an integer. The type was cheap. The migration was not. The column cannot be backfilled, because the number lives in the source's payload and we do not retain the raw playlist. Every existing install would have carried a null on every row, and a list sorted by that number would have put an entire library in the unnumbered tail. The migration deletes the snapshot fingerprint and the materialized marker, forcing the next sync to rebuild the catalog. Every existing install paid a full re-materialization to display a badge.

Fifty-six values are not numbers at all#

56 of the 1,355 values, over 53 distinct spellings, are refused outright. They fall into four shapes:

• A bare # on 4 entries, a placeholder the emitter never filled in.
• 49 broadcast-system codes: a D011 to D081 run, a BS101 to BS4K101 family, a long CS055 to CS363 run, and a single JCOM307. This is a real national numbering scheme, and the attribute has no room for it.
• CH 106 and CH 108, the same number with a prefix and a space.
• One value that is a platform name written in Japanese with 527 on the end.

A refusal costs the row its number and never the row, so all 56 keep their place and sort into the unnumbered tail.

Several refusals are rules with no witness: a leading sign puts +5 and -5 outside the accepted styles, and zero is refused because an absent number is not channel zero. Neither shape occurs once in 1,355 values. Leading zeros are the lenient case: 007 parses to 7.

That split needs one caveat, because the measurement script emulates our parser in Python and float() is looser than the style set we pass. I checked the corpus for every shape where the two disagree, a leading plus or minus, exponents, underscores, whitespace padding and leading zeros, and found zero of each. The 1,299 against 56 split is the shipped parser's.

No two of these readers agree#

Nothing below comes from a specification, because there is not one. Each cell is read from that project's source or its own documentation.

Kodi's reader is the most permissive in the set and the most surprising in effect. Each entry is seeded from a running counter that resets to whatever number a channel claims, so a single tvg-chno="500" two thirds of the way down a file renumbers every later unnumbered channel from 501. One attribute on one row moves hundreds of others. And after all that parsing, Kodi core's setting to use backend channel numbers is off by default: the all-channels group renumbers itself 1 to n, other groups inherit that, and the playlist's number stays on the channel without being shown.

Jellyfin's is the strictest: its regex requires a double-quoted value, so tvg-chno=101 without quotes is invisible to it while Kodi reads it happily, and our own reader has the same restriction. Its fallback chain ends at the file name of the stream URL, the point where a channel number stops being data and starts being a guess about a path.

xTeVe is the interesting refusal. It parses the attribute into generic metadata and never uses it, allocating its own numbers from the first free slot at or above 1000, and a request to honor tvg-chno was closed as not planned. That is the only design here where two rows claiming one number cannot collide, because the playlist's opinion is never consulted, and the price is that a carefully numbered source arrives renumbered. Threadfin, its fork, went the other way and copies the value verbatim, so collisions come through intact; its deduplication hashes the URL, the tvg-id and the source id, never the number.

Plex is the odd row, because it has no first-party M3U ingestion and nothing inside it parses the attribute; its community-supported-tuners page asks for a Windows BDA or Linux DVB device. The usual route from a playlist is an HDHomeRun-style proxy, where the number arrives as GuideNumber in lineup.json, and which number that is depends on the proxy: xTeVe substitutes its own, Threadfin passes the string straight through.

Six rows produce four usable numbers#

Here is a fragment built to hit every path at once. Every host is a reserved example domain and every name is invented.

#EXTINF:-1 tvg-id="one.example" tvg-chno="1",Example One
https://example.com/live/one.m3u8
#EXTINF:-1 tvg-id="two.example" tvg-chno="1",Example Two
https://example.com/live/two.m3u8
#EXTINF:-1 tvg-chno=101,Example Three
https://example.com/live/three.m3u8
#EXTINF:-1 tvg-chno="22.1",Example Four
https://example.com/live/four.m3u8
#EXTINF:-1 tvg-chno="BS4K101",Example Five
https://example.com/live/five.m3u8
#EXTINF:-1 tvg-chno="007",Example Six
https://example.com/live/six.m3u8

One and Two both claim number 1, which is this file's normal case rather than its edge. Our comparator keeps both, ordered by a natural-order comparison of their names and then an ordinal comparison of their ids, so the pair is deterministic. Kodi keeps both too. xTeVe would hand them 1000 and 1001 and never read the attribute.

Three is unquoted, so Kodi reads 101 while we read nothing at all, as Jellyfin also would: the row lands in the unnumbered tail on our side and at channel 101 on Kodi's.

Four is the subchannel case. We keep 22.1 as a decimal, Kodi splits it into major 22 with subchannel 1, Jellyfin parses a double and keeps the original string for display, and any consumer with an integer column shows 22.

Five is refused by our number parser and keeps its row, so it joins Three in the tail. Kodi comes off worse than we do: its reader hands the value to atoi, which returns 0 for a string whose digits do not lead, and nothing guards the setter, so the row becomes channel 0 and the running counter is reset to 0 with it. The next unnumbered channel becomes 1. A junk value there does more damage than an absent one.

Six is the leading-zero case: 007 normalizes to 7 for us, and Jellyfin parses the same 7 while still displaying 007.

Sorted by the source's number, our list reads Example One, Example Two, Example Six at 7, Example Four at 22.1, then Example Five and Example Three in name order, because an absent number sorts after every present one rather than as zero.

A collision resolves differently depending on what the viewer is doing. It took us three mechanisms rather than one. For sorting, the collision is absorbed by the name tie-break. For keypad entry, typing 1 walks the matches: every row with that number is collected and repeated presses cycle through them, wrapping at the end, because pinning the first of 107 forever would make the other 106 unreachable. For aggregation, where several sources contribute one logical channel, the naming member's number wins, and failing that the first member in priority order that has one. Those same members are the queue a stalled stream fails over into, which has its own article.

The keypad path has a gap I do not like. It accumulates digit keys only, with a 1.2 second window between them and a reset after five digits, and it parses with no number styles enabled, so there is no way to type 22.1. A subchannel is reachable by search, where the query goes through the parser that accepts a decimal point, and unreachable by the remote. The honest reason that has not been fixed is that 25 rows in our corpus need it.

A number you assign is not the number the file sent#

The source's number is never rewritten. A reordering gesture writes a separate fractional key, and the two live side by side.

The mechanism is chosen by a constraint that has nothing to do with ordering. Our sync batch cap is 500 changes and a single rejected record fails the whole batch, taking every unrelated change traveling with it, so renumbering a group on every drop was never viable. Instead every channel gets an implicit key from its position in the fallback order, a placed channel uses its synced key, and a drop between two rows takes the midpoint, which writes exactly one row. Implicit keys sit one apart, so each drop into the same gap halves it: against a minimum gap of 1e-9 the thirtieth consecutive drop into one slot still lands, and the thirty-first rebalances the group to evenly spaced keys. That rebalance is the only path here that writes thousands of rows, and it is logged with its size instead of running quietly. Three comments in our own source say fifty. We got this wrong from intuition, the first draft of this article repeated it, and the figure only became thirty when someone did the arithmetic.

The badge shows the row's position rather than that key, because implicit keys shift whenever the source adds or removes channels, and a number that moves on its own after a sync is worse than none. An earlier version of this ordering lived in the view model, where a saved order applied to source category groups and silently did not apply to All channels, favorites or custom groups.

The Windows and Xbox apps parse all of this on your device, from the playlist you point them at, and you can create a free account to try either. Nothing about your channel numbers reaches us, because the file is never uploaded and the parse happens locally.

If you emit playlists, write tvg-chno on every row and keep it unique inside the file, because the consumers that honor it share no rule for what to do when you do not, and one of them will renumber everything downstream of your first numbered channel. If you read playlists, count the distinct values before you build anything on the attribute. In our corpus that count is the difference between 1,355 numbers and 263.