M3U8 tags reference for HLS playlists

HLS playlists are UTF-8 text documents. Lines beginning with #EXT are tags, URI lines identify another playlist or media resource, and other lines beginning with # are comments. The tag name tells you which scope and object the following attributes describe. Reading that relationship is more useful than searching the file for a single keyword.

This guide summarizes commonly encountered directives from RFC 8216, HTTP Live Streaming. The RFC remains the normative reference for the tags it defines. Implementations and later specifications may add capabilities, so validate unusual playlists against the requirements of the players and delivery platforms you actually support.

First identify the playlist type

A master playlist describes available variants and renditions. It usually contains #EXT-X-STREAM-INF followed by a child-playlist URI, plus optional #EXT-X-MEDIA entries for alternate audio, subtitles, or video. A media playlist describes a sequence of media segments and normally contains #EXTINF, segment URIs, and timing or sequence directives.

Do not mix tags that apply only to master playlists with tags that apply only to media playlists. When debugging, first determine whether the URL you opened is the master or one selected child. A player can parse the master successfully and still fail on a media playlist, segment, initialization section, subtitle, or key.

Basic tags found across playlists

#EXT-X-VERSION is not a marketing label and is not simply the encoder version. It communicates compatibility needs created by playlist features. Avoid increasing it without understanding the client support you may exclude, and avoid declaring a lower value than the syntax requires.

Master playlist tags

#EXT-X-STREAM-INF

This tag describes a variant stream. Its required BANDWIDTH attribute gives peak segment bitrate for the variant under the RFC definition. Common optional attributes include AVERAGE-BANDWIDTH, CODECS, RESOLUTION, FRAME-RATE, and group references such as AUDIO or SUBTITLES. The next URI line identifies the media playlist for that variant.

When only one quality fails, open that following URI directly. Check that its declared codecs match the actual segments, its relative path resolves from the master URL, and its referenced audio or subtitle groups exist. A bandwidth value should describe the stream accurately enough for adaptive selection; it is not the viewer's recommended connection speed.

#EXT-X-MEDIA

This tag declares an alternative rendition. TYPE identifies audio, video, subtitles, or closed captions; GROUP-ID associates the rendition with variant entries; and NAME gives a human-readable label. Depending on type, attributes such as LANGUAGE, DEFAULT, AUTOSELECT, FORCED, CHARACTERISTICS, and URI describe selection behavior.

Group references must be consistent. If a stream entry says AUDIO="stereo", the corresponding media group must exist. Duplicate names inside the same group, an inaccessible URI, or a default choice that does not satisfy the RFC's constraints can produce confusing track behavior.

Other master directives

• #EXT-X-I-FRAME-STREAM-INF describes an I-frame-only variant and carries its URI as an attribute rather than on the next line.
• #EXT-X-SESSION-DATA carries session data that applies to the master playlist. Do not place secrets in public playlist metadata.
• #EXT-X-SESSION-KEY allows clients to preload encryption keys used by variants, subject to method and format requirements.

Media segment and timing tags

#EXTINF

#EXTINF supplies the duration of the media segment represented by the URI that follows it. The optional text after the comma is a title. Every media segment in a media playlist needs an #EXTINF tag. If durations are wrong, the player timeline, seeking, live-edge behavior, or buffer calculations can become unreliable even when the files themselves load.

#EXT-X-TARGETDURATION

This tag defines the maximum media-segment duration under the RFC's rounding rule and appears once in a media playlist. Clients use it when deciding how often to reload a live playlist. A segment duration that violates the target duration is a packaging error, while an unnecessarily large target can slow refresh behavior.

#EXT-X-MEDIA-SEQUENCE

This value is the media sequence number of the first segment currently listed. It does not have to start at zero. In a sliding live playlist, the value normally advances as older segments leave the window. If a CDN serves stale playlist versions out of order, clients may request segments that are already removed or misread the live edge.

#EXT-X-DISCONTINUITY

This tag marks a boundary where relevant encoding parameters, timestamp sequence, or other media characteristics change. Typical causes include an ad insertion, source switch, or timestamp reset. Place it at the actual boundary. Missing discontinuities can break decoding or timing; unnecessary ones can force avoidable resets.

#EXT-X-DISCONTINUITY-SEQUENCE lets clients align discontinuity sequence numbers across playlist updates or renditions. It belongs before the first media segment and must remain coherent as a live window slides.

Tags that change how a resource is fetched

#EXT-X-BYTERANGE

This directive says that the next media segment is a byte range inside the following URI rather than necessarily a separate object. It provides a length and optional offset. If the offset is omitted, the specification defines it relative to the previous sub-range under required conditions. Origins and CDNs must handle range delivery correctly, and caches must not return the wrong bytes.

#EXT-X-MAP

This tag identifies the media initialization section needed to parse later segments, commonly for fragmented MP4. Its URI can be accompanied by a BYTERANGE. A playlist and media segments may all return successfully while playback fails because the initialization resource is missing, blocked, stale, or encrypted inconsistently.

#EXT-X-KEY

This directive specifies how following media segments are encrypted. Attributes include METHOD and, depending on the method, a key URI, initialization vector, key format, or format versions. The setting applies until another key directive changes it. METHOD=NONE indicates that subsequent segments are not encrypted.

Debug key requests without exposing key material. Check the request status, authorization, token lifetime, hostname, and CORS behavior where a browser must fetch the key. DRM license workflows are not interchangeable with plain AES-128 key retrieval.

Playlist lifecycle tags

#EXT-X-ENDLIST

This tag indicates that no more media segments will be added. It is expected for completed video-on-demand playlists and may appear when an event finishes. A live playlist without it can continue to update. Adding it prematurely freezes the available content; omitting it from completed media can make a client continue polling.

#EXT-X-PLAYLIST-TYPE

The values EVENT and VOD describe mutability constraints. An event playlist can grow while preserving earlier entries. A VOD playlist does not change. A sliding live playlist commonly omits this tag because older entries may be removed as the media sequence advances.

#EXT-X-PROGRAM-DATE-TIME

This tag associates the first sample of a following media segment with an absolute date and time. It can help align streams, program guides, server logs, and timed metadata. Ambiguous or non-monotonic values make incident timelines difficult to reconstruct, so emit accurate timestamps and include a time-zone designator.

Annotated master and media examples

A small master playlist can connect two variants to one alternate-audio group:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="English",DEFAULT=YES,AUTOSELECT=YES,URI="audio/en.m3u8"
#EXT-X-STREAM-INF:BANDWIDTH=1800000,AVERAGE-BANDWIDTH=1500000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2",AUDIO="audio"
video/720p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=850000,AVERAGE-BANDWIDTH=700000,RESOLUTION=854x480,CODECS="avc1.4d401e,mp4a.40.2",AUDIO="audio"
video/480p.m3u8

The following on-demand media playlist uses an initialization map and three segments. The durations must satisfy the target-duration rules, and the end marker says the list is complete.

#EXTM3U
#EXT-X-VERSION:7
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6.000,
segment-000.m4s
#EXTINF:6.000,
segment-001.m4s
#EXTINF:4.500,
segment-002.m4s
#EXT-X-ENDLIST

Examples show relationships, not a universal encoding recipe. The required version, codec strings, segment durations, and packaging choices must match the generated media and target clients.

Read a failing playlist in this order

1. Confirm the body is UTF-8 playlist text beginning with #EXTM3U, not an HTML error page.
2. Classify it as a master or media playlist and check that type-specific tags are not mixed incorrectly.
3. Resolve each relative URI against the URL of the playlist containing it.
4. For a master, verify every variant and rendition group reference, codec declaration, and child URI.
5. For media, verify target duration, segment durations, sequence movement, discontinuities, maps, keys, and end state.
6. Request the first failing child resource and compare status, body, MIME type, CORS headers, cache age, and authorization.
7. Compare manifest declarations with the actual media instead of assuming a valid-looking tag makes the encoding valid.

Common manifest mistakes

• A master playlist references a child path relative to a different directory than the packager expected.
• A variant declares codecs that do not match its audio or video samples.
• An alternate rendition group is referenced but missing, duplicated, or inaccessible.
• A live target duration is smaller than an allowed segment duration.
• The media sequence advances while old playlist responses remain cached too long.
• A fragmented MP4 stream omits or loses access to its initialization map.
• A key URL expires earlier than the playlist and segment URLs.
• A source switch changes timestamps or encoding parameters without a required discontinuity.
• A VOD playlist keeps polling because its end state is not declared correctly.

Our M3U8 manifest inspector summarizes playlist type, variants, codecs, hostnames, keys, and warnings. Use this reference to interpret those findings, then test the exact URL in the browser player.