The M3U / M3U8 Format Explained Line by Line

A text file, not content

The M3U format was born in the 1990s with desktop audio players, notably Winamp, to save a list of tracks to play in sequence. Its principle has not changed since: an M3U playlist is a plain text file containing a series of addresses (local paths or URLs) that the player opens in order. It contains no picture, no sound and no video. It simply tells the player where to fetch each stream and how to display it.

That explains two things that are often misunderstood. First, an M3U file of a few hundred kilobytes can "contain" thousands of entries: there is only text inside. Second, the playlist is only as good as the addresses it references: if the target server is offline, the file remains perfectly valid, but nothing plays. A player such as a multimedia video player only interprets these lines; the legality and availability of streams depend entirely on their source, and you must hold the rights to what you watch.

M3U playlists are found today in three main situations: lists of audio or video files stored on a disk or a NAS, lists of radios and channels broadcast online by their publishers, and lists supplied by a television service you subscribe to.

The minimal structure: #EXTM3U and #EXTINF

A so-called "extended" playlist (Extended M3U) must start with the #EXTM3U header on the very first line. Each entry then takes two lines: a description line beginning with #EXTINF, then the line with the address itself. Here is a complete, valid example with two fictional radios:

#EXTM3U
#EXTINF:-1,Example Radio News
https://stream.example.com/news/live.mp3
#EXTINF:-1,Example Radio Music
https://stream.example.com/music/playlist.m3u8

Let us break down the line #EXTINF:-1,Example Radio News:

• #EXTINF: announces the information for the entry that follows.
• -1 is the duration in seconds. For a music track, you would put for example 215; for a live stream, which has no end, the convention is -1 (some lists put 0, which most players tolerate).
• the comma separates the technical part from the display name. Everything after the last comma of the attributes is the title the user will see.

Lines that start with # and are not known directives are treated as comments and ignored. Blank lines are in principle tolerated, but it is better to avoid them between an #EXTINF and its address: some players then lose the association between the name and the stream.

Extended attributes: tvg-id, tvg-logo, group-title

For channel lists, a practice has become standard: adding attributes between the duration and the comma, in the form name="value". They are not part of any official standard, but almost all TV players recognize them.

#EXTM3U url-tvg="https://guide.example.com/epg.xml.gz"
#EXTINF:-1 tvg-id="example1.com" tvg-name="Example 1" tvg-logo="https://img.example.com/ex1.png" group-title="General",Example 1 HD
https://tv.example.com/live/ex1.m3u8

On the header line, the url-tvg attribute (or its variant x-tvg-url) gives the address of the XMLTV-format program guide. How this guide works is detailed in our article on EPG and the XMLTV format.

Two syntax rules avoid most problems: values are always in straight quotes (", never curly quotes), and the display name must not contain unescaped quotes. A comma inside a quoted value is accepted by good parsers, but a comma in the channel name itself can truncate the title in some players.

M3U or M3U8: what is the difference?

The .m3u8 extension originally denotes an M3U playlist encoded in UTF-8. The "8" comes from that. A classic .m3u file, on the other hand, was historically read in the system's local encoding (often Windows-1252 in Western Europe), which turned "Français" into "Français" when a file written on one machine was opened on another.

In 2009, Apple reused this extension for its HLS (HTTP Live Streaming) delivery protocol, later standardized in RFC 8216. An .m3u8 file can therefore mean two very different things:

• a list of channels or tracks, written by a human or a service, that you load into your player;
• an HLS manifest, generated automatically by a streaming server, listing the small video segments of a few seconds of a single channel or film.

The second contains HLS-specific directives, such as #EXT-X-TARGETDURATION or #EXT-X-STREAM-INF. If you open an address and see names like segment_10452.ts scrolling by, you are looking at an HLS manifest, not a channel playlist. Our article HLS, MPEG-TS and DASH explains this mechanism in detail.

In practice, current players read .m3u and .m3u8 interchangeably and detect UTF-8 in most cases. The safest approach remains to always save your playlists in UTF-8, whatever the extension.

Encoding, BOM and line endings: the invisible traps

Many playlists that "do not work" are perfectly written... but badly saved. Three details that are invisible on screen cause problems.

The UTF-8 BOM

Some editors, including older versions of Windows Notepad, add three invisible bytes at the start of the file called a BOM (Byte Order Mark: EF BB BF in hexadecimal). A strict player that checks the file starts exactly with #EXTM3U then sees #EXTM3U and rejects the list, or ignores the first entry. The fix: save as "UTF-8" and not "UTF-8 with BOM". In Notepad++, the Encoding menu explicitly offers both options; in Visual Studio Code, the encoding is shown at the bottom right of the window and can be changed with one click.

Badly converted accents

If names appear with sequences like é or diamonds �, the file was written in one encoding and read in another. Reopen it in an editor that lets you choose the reading encoding (Windows-1252 or ISO-8859-1 if the accents become correct again), then re-save it as UTF-8.

Line endings

Windows ends lines with two characters (CR LF), while Linux, macOS and Android use a single one (LF). Recent players accept both, but a leftover CR stuck to the end of a URL can make it invalid on a picky server. When in doubt, convert to LF, which code editors offer.

The most common syntax errors

Here are the faults most often found when opening a stubborn playlist, with their symptom and correction.

For very large lists, one last useful reflex: count the #EXTINF lines and the address lines. On Windows, PowerShell does it with (Select-String -Path playlist.m3u -Pattern '^#EXTINF').Count. The two numbers must be equal.

Creating and editing your own playlist

Building a playlist by hand is simple and lets you group, for example, the radios and channels that their publishers broadcast free on their own sites, or the videos on your NAS. The method:

1. Open a text editor that handles encoding well: Notepad++ or Visual Studio Code on Windows, TextEdit in "plain text" mode on Mac. Avoid word processors (Word, LibreOffice Writer), which insert typographic quotes.
2. Write the header #EXTM3U on the first line, optionally followed by url-tvg="..." if you have a guide.
3. Add each entry on two lines: #EXTINF:-1 group-title="Radios",Name then the full address, starting with http:// or https:// for a network stream, or with a path for a local file.
4. Save as UTF-8 without BOM, with the .m3u or .m3u8 extension.
5. Test the list in your player and fix the failing entries one by one.

For local files, prefer relative paths (Movies/holiday-2024.mp4) when the playlist is stored in the same folder as the videos: the list stays valid if you move everything to another drive. An absolute path such as C:\Users\... will only work on the original machine.

Finally, to load a list into a player, there are generally two options: give its web address (the player re-downloads it at each refresh, which reflects updates from the source) or import a local file (frozen until you replace it). In AICKO IPTV, both methods are described step by step on the Xtream Codes and M3U page.

In summary

• An M3U playlist is a text file that lists addresses; it contains no video.
• It starts with #EXTM3U, then alternates an #EXTINF line and an address line for each entry.
• The tvg-id, tvg-logo and group-title attributes handle the guide, logos and categories.
• .m3u8 means "M3U in UTF-8", but also denotes the manifests of the HLS protocol.
• Always save as UTF-8 without BOM, with straight quotes.

Frequently asked questions

Can I open an M3U file with Notepad?

Yes. It is a plain text file, readable and editable with any editor. To save it, choose the UTF-8 encoding; recent versions of Notepad in Windows 10 and 11 save as UTF-8 without BOM by default.

Why does my playlist load but no channel starts?

The file is read correctly, but the addresses it contains do not respond: server offline, expired link or access denied. Test a single address in a browser or another player to find out whether the problem comes from the source or the device.

Is an M3U file dangerous?

The file itself contains only text and cannot execute. The risk comes from its origin: a list obtained from a dubious source may point to illegally broadcast content. Load only lists from services you are a customer of or from official publishers.

What is the maximum size of a playlist?

The format sets no limit. The constraints come from the device: a list of several tens of thousands of entries can slow loading on an underpowered TV stick. Removing unneeded categories noticeably improves responsiveness.