HLS Master Playlist vs Media Playlist

An HLS URL does not always point directly to video segments. It may point to a multivariant playlist—historically called a master playlist—that describes several playable variants, or it may point to a media playlist that lists the segments for one rendition. Knowing which file you opened is the fastest way to understand the rest of the request chain.

RFC 8216 defines a playlist as one type or the other. A valid file must not mix multivariant tags with media-segment tags. That distinction is not just terminology: it determines what the next URI means, how a player chooses quality, and where an authorization or path error can occur.

The short version

Both are UTF-8 text files and both must begin with #EXTM3U.

A minimal multivariant playlist

#EXTM3U
#EXT-X-VERSION:7
#EXT-X-INDEPENDENT-SEGMENTS

#EXT-X-STREAM-INF:BANDWIDTH=900000,AVERAGE-BANDWIDTH=750000,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2"
360p/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2800000,AVERAGE-BANDWIDTH=2400000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2"
720p/index.m3u8

Each #EXT-X-STREAM-INF line describes a Variant Stream. The URI on the next line is required and identifies a media playlist. It does not identify a media segment.

The player can use these attributes to choose an initial variant and switch later:

• BANDWIDTH represents the peak aggregate bitrate required by a playable combination of renditions.
• AVERAGE-BANDWIDTH, when present, describes the average aggregate bitrate.
• RESOLUTION and FRAME-RATE help describe video characteristics.
• CODECS identifies the media sample formats used by the variant and referenced rendition groups.
• AUDIO, SUBTITLES, VIDEO, and CLOSED-CAPTIONS connect a variant to groups declared with #EXT-X-MEDIA.

An inaccurate BANDWIDTH value can cause a client to choose a rendition it cannot sustain. An incomplete CODECS list can make compatibility decisions unreliable or cause playback failure when an alternate rendition uses an undeclared sample format.

A minimal VOD media playlist

#EXTM3U
#EXT-X-VERSION:7
#EXT-X-TARGETDURATION:6
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MAP:URI="init.mp4"
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:6.000,
segment-0001.m4s
#EXTINF:6.000,
segment-0002.m4s
#EXTINF:4.240,
segment-0003.m4s
#EXT-X-ENDLIST

This file describes one media presentation. #EXTINF applies to the segment URI that follows it. #EXT-X-TARGETDURATION sets an upper bound used by clients when reloading and scheduling. For fragmented MP4, #EXT-X-MAP identifies the media initialization section needed before the fragments can be decoded. #EXT-X-ENDLIST tells the client that no more segments will be added.

A VOD playlist should remain stable. If it changes between requests, seeking, duration, caches, and offline validation become difficult to reason about.

A minimal live media playlist

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:48120
#EXTINF:6.000,
live-48120.ts
#EXTINF:6.000,
live-48121.ts
#EXTINF:5.840,
live-48122.ts

The absence of #EXT-X-ENDLIST indicates that the presentation may continue. A live client reloads the media playlist to discover newly published segments. #EXT-X-MEDIA-SEQUENCE identifies the sequence number of the first listed segment; it normally increases as older entries leave a sliding live window.

A common live failure occurs when the playlist advertises a segment before the origin or CDN can serve it. RFC 8216 requires a listed media segment to be immediately available. If the playlist request is 200 but the newest segments repeatedly return 404, inspect the publication order and cache behavior at the packager and CDN.

How alternate audio and subtitles fit

A multivariant playlist can declare rendition groups:

#EXTM3U
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="English",LANGUAGE="en",DEFAULT=YES,AUTOSELECT=YES,URI="audio/en.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",LANGUAGE="en",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,URI="subs/en.m3u8"

#EXT-X-STREAM-INF:BANDWIDTH=2800000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2",AUDIO="audio",SUBTITLES="subs"
video/720p.m3u8

The audio, subtitle, and video URIs can each lead to separate media playlists. Consequently, a successful video segment does not prove that the entire variant is healthy. Test every rendition group that users can select.

Group identifiers are exact strings. A typo between AUDIO="audio" and GROUP-ID="audio-en" leaves the intended relationship broken. Language metadata, default selection, auto-selection, and forced-subtitle flags should also match the product behavior you expect.

Relative URLs: the rule that prevents many false fixes

A relative URI is resolved against the URL of the playlist that contains it. Given:

Playlist: https://cdn.example.test/hls/event/master.m3u8
Child URI: 720p/index.m3u8
Resolved:  https://cdn.example.test/hls/event/720p/index.m3u8

Inside that child playlist:

Playlist: https://cdn.example.test/hls/event/720p/index.m3u8
Segment:  ../segments/part-001.m4s
Resolved: https://cdn.example.test/hls/event/segments/part-001.m4s

Do not resolve either path against m3u8online.com merely because that is where the player UI is hosted. Redirects can make this more subtle: relative references resolve from the final playlist URL returned after redirection.

Signed query strings are another frequent trap. Standard URL resolution does not automatically copy a master playlist's query parameters onto every child URI. If the CDN expects each resource to carry a signature, the packager or authorization design must provide valid signed child URLs or another supported authorization mechanism.

A controlled relative-path check

We verified this rule in the September 3, 2026 release candidate with a self-hosted fixture. The player was on http://localhost:3000; the playlist origin was http://127.0.0.1:4310, so a mistaken resolution against the player origin would be obvious.

The result is useful because the final player message was generic. The request chain—not the message—showed that playlist classification and both relative URL resolutions were correct, while the fixture itself failed at the segment.

Tags that reveal the playlist type

You can usually classify a file from the first screenful of text:

Multivariant indicators

• #EXT-X-STREAM-INF
• #EXT-X-I-FRAME-STREAM-INF
• #EXT-X-MEDIA
• #EXT-X-SESSION-DATA
• #EXT-X-SESSION-KEY

Media indicators

• #EXTINF
• #EXT-X-TARGETDURATION
• #EXT-X-MEDIA-SEQUENCE
• #EXT-X-DISCONTINUITY
• #EXT-X-BYTERANGE
• #EXT-X-MAP
• #EXT-X-ENDLIST

Some tags apply to both kinds of playlists, including #EXTM3U, #EXT-X-VERSION, #EXT-X-INDEPENDENT-SEGMENTS, and #EXT-X-START. They do not classify the file by themselves.

Invalid mixing and why it matters

This is not a valid shortcut:

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=900000
360p/index.m3u8
#EXTINF:6.0,
segment-0001.ts

The file contains both a multivariant tag and a media-segment tag. The specification requires clients to reject this mixture. Separate it into a multivariant playlist and a media playlist.

Other structural mistakes include:

• Placing a segment URI after #EXT-X-STREAM-INF.
• Omitting the URI line after #EXT-X-STREAM-INF.
• Listing a child playlist where a media segment must follow #EXTINF.
• Declaring fMP4 fragments without the required initialization information.
• Reusing a rendition group name inconsistently.
• Using a protocol version higher than needed or too low for the tags in the file.
• Returning HTML, JSON, or a CDN challenge at a URL that ends in .m3u8.

Debug the chain in the right order

When playback fails, trace the playlist graph rather than looking only at the URL entered into the player:

1. Open the top-level response and verify #EXTM3U.
2. Classify it as multivariant or media.
3. If it is multivariant, copy one child media-playlist URI and resolve it against the final master URL.
4. Open that media playlist and inspect initialization, key, and first segment URIs.
5. Verify status, CORS, content type, and response body for every level.
6. Test one low and one high variant directly.
7. Test each alternate audio and subtitle group.

If a direct media playlist works but the multivariant URL does not, investigate multivariant syntax, attributes, and rendition groups. If no media playlist works, move down to shared authorization, CORS, packaging, codec, or segment availability.

Choosing which URL to share with a player

Use the multivariant URL when you want adaptive bitrate and track selection. Use a direct media-playlist URL when isolating one rendition during diagnosis or when the stream intentionally has only one rendition.

A direct media playlist is not “more compatible” by definition. It simply removes the selection layer. The chosen segments still need valid packaging, supported codecs, correct authorization, and usable network delivery.

Validation checklist

Before publishing a stream:

• Validate playlists against RFC 8216 and the target-device authoring guidance.
• Confirm all URI paths after real production redirects.
• Test low and high variants under sustainable and constrained bandwidth.
• Verify audio, subtitles, discontinuities, seeking, and encryption keys.
• Confirm playlist and segment CORS from the actual web-player origin.
• Visually inspect playback; structural validation cannot judge video quality.

Apple's HLS validation tools can catch many authoring problems, but they do not replace playback tests on the browsers and devices you support.

Primary references

• RFC 8216: playlist definitions and tags
• Apple HLS authoring specification
• Apple HLS authoring appendixes and validation guidance