M3U File Format: The Spec, Explained Line by Line

What an M3U file is

Winamp, late 1990s. The extension stood for MP3 URL, and the idea was modest: instead of one program remembering which tracks you wanted and in what order, write the list to a text file that any program can read. Thirty years on that is still the whole of it. Which is exactly why it outlived the software it was built for.

Being plain text has two consequences. Both matter. Any editor opens one, so nothing about a playlist is ever opaque to you, and if a player is behaving strangely you can always go and look at what it was actually handed rather than guessing. The second is less comfortable: the format says nothing at all about what it points at, so a perfectly valid file can list addresses that are dead, duplicated three times over, or that you have no right to open. It is an index. It makes no claims.

The format, line by line

There are two variants, and conflating them is the single most common misunderstanding.

A basic M3U is a list of paths, one per line, and nothing else at all. No header. Lines opening with # are comments and are skipped, which means a file containing three bare URLs and not one other character is a completely valid M3U that any compliant player will open without complaint, and that fact alone accounts for a great deal of the confusion people have when they open someone else’s playlist and find none of the tags they were expecting to see in it.

An extended M3U opens with #EXTM3U on the first line, which announces that the annotations below should be read rather than skipped as comments. Each entry then takes two lines: an #EXTINF directive carrying metadata, followed by the address it describes.

• #EXTM3U: first line of an extended file. Optional in the sense that a file without it is still valid, but required if any #EXTINF follows.
• #EXTINF:duration,title: duration in seconds, then a comma, then the display name. A duration of -1 means unknown or unbounded, which is what every live stream uses.
• The address line: an absolute URL, or a path relative to the playlist file itself. Relative paths break the moment the file moves, which is why exported playlists almost always use absolute URLs.
• #: anything else beginning with a hash is a comment and is ignored, which is how unknown directives degrade harmlessly instead of breaking older players.

Reading a real file

An M3U file format example, and a complete valid playlist at that. Four lines, one entry:

#EXTM3U
#EXTINF:-1 tvg-id="bbcone.uk" tvg-name="BBC One" tvg-logo="https://example.com/bbc1.png" group-title="News",BBC One
https://example.com/live/bbcone/index.m3u8

Reading it back. The file is extended. The entry has no fixed duration because it is live, it carries four optional attributes, its display name is everything following the final comma, and the address itself sits on the line beneath. Note that the display name comes after the comma while the attributes come before it. That comma is the delimiter, which is why a channel named News, Live breaks naive parsers.

A playlist of forty thousand channels is that, forty thousand times over. Nothing else is going on.

The attributes IPTV players added

The four attributes in that example are worth being precise about, because they are not part of any formal specification. They are a convention that IPTV players converged on, and they work only because unknown text inside an#EXTINF line is harmless to players that do not understand it.

• tvg-id: links the channel to an entry in an external programme guide. Useless on its own; essential if you want an EPG.
• tvg-name: the name used for guide matching, which is often not the same string as the display name after the comma.
• tvg-logo: a URL to an icon. It is fetched by the player at display time, so a broken logo URL costs you a request and an empty box, nothing more.
• group-title: the category a player files the channel under. This is the one that decides whether a large playlist is navigable or a wall.

None of it is standardised, so providers disagree constantly, which means two files describing the very same channel will routinely differ in capitalisation, in what they call the group, and occasionally in how they spell the attribute itself, with the result that merging two playlists hands you a pile of duplicates that no exact-match comparison will ever catch and that you will be left to find by eye unless something does the fuzzy work for you. Which is the whole reason deduplication tools exist.

The M3U8 file format

The 8 is the encoding, not a version. An M3U8 file is an M3U file whose text is UTF-8. That is the entire difference at the format level, and it exists because the original had no encoding declaration at all, so a channel named in Greek or Arabic rendered as whatever the reader guessed.

What makes the M3U8 file format interesting is what was built on top of it. HTTP Live Streaming, specified in RFC 8216, uses M3U8 as its manifest format, and adds its own directives beginning with #EXT-X-. Those are still comments to a plain M3U reader, which is how the same file type serves both jobs.

HLS uses two kinds of manifest. Telling them apart is the first useful diagnostic you have when a stream misbehaves, because a great many of the failures people describe as buffering are in fact a player being handed a single fixed rendition and having nothing whatsoever to fall back to when the connection dips for a moment. A master playlist lists variants with #EXT-X-STREAM-INF, each pointing at another manifest for a different bitrate and resolution. A media playlist lists the actual video segments in order. A player fetches the master, picks a variant, then follows the media playlist and keeps re-fetching it as new segments appear. A file with only one variant has no adaptive ladder, which is why it stalls on a weak connection rather than dropping quality. You can see which you have with the HLS stream analyzer, and there are public test streams published by Apple and Akamai if you need a known-good manifest to compare against.

How the file is encoded and served

Small details. They cause a surprising share of the problems people blame on their player.

• Extension. .m3u and .m3u8 are both common and mostly interchangeable in practice, though a server serving HLS should use .m3u8.
• MIME type. audio/x-mpegurl for plain M3U, application/vnd.apple.mpegurl for HLS. A server sendingtext/plain instead will make some players refuse a file that is otherwise perfectly valid.
• Line endings. Both LF and CRLF appear in the wild. Well-written parsers accept either; badly written ones leave a stray carriage return on the end of every URL.
• Byte order mark. A UTF-8 BOM at the start of the file will make a strict reader fail to match #EXTM3U on the first line, which presents as an entirely empty playlist rather than as an error.

Opening, creating and converting

Any editor opens one. Any editor can write one. In practice you want something that understands the structure rather than the characters, and those jobs already have their own pages here rather than being restated on this one.

• To play one, the playback guide covers the browser, VLC, phones and televisions.
• To build one from scratch, the playlist creator writes correct #EXTINF lines so you do not have to count commas.
• To turn one into JSON or CSV and back, use the format converter, which preserves every attribute on the round trip.
• To fix one that has rotted, the full set of tools covers checking, cleaning, deduplicating and merging.

Frequently asked questions