HLS Tags - Everything you need to know

Let's take a deep dive into the HLS format and see what all of those #EXT tags, also known as directives, are for and why they are needed.

Here's a very short example HLS media playlist:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:5,
https://chunk-gcp-us-east1-vop1.fastly.mux.com/v1/chunk/XycqKjh00026zR5gJcIhREMs0101JahGDI7VHKpZaou4n01kQQAXC3M6QWgNftsD00Pi02XJOPVqpyEIgzp23c02UuxGhsPLeN01k002qTAKwQh00IyrSQ/0.ts?skid=default&signature=NjcwOTNkNzBfODE4NzJlZWExYzY5ZjAyZTdjOGE0NDEwZjEzYzBhYmZiMzE4NDFkYmU2NTI2ZDE3MDI0ZmY3NzlmMDgwN2M5Mw==&zone=0
#EXTINF:5,
https://chunk-gcp-us-east1-vop1.fastly.mux.com/v1/chunk/Qjd6SRi00Td6KEEjsU2qXDooj6suaHJRH92eaBtNI7NkQjfeVXOOEJIoAp6ab4hLSw1A42V02CnehDrfla2If87phpN2DZlIEc5F6Lz3ULeeo/1.ts?skid=default&signature=NjcwOTNkNzBfZjkwYjg0NTllZTBhNDU2OTgxOThlZmMwYzIwNTgxOGI0NWYwYWEyMDI0NTY5NWNlZTY5ZDkwNTEyNTZmYzU5NQ==&zone=0
#EXT-X-ENDLIST

This sample file has two media chunks of 5 seconds each that together make up a short 10 second video.

What is a HLS file?

Usually a text file with an .m3u8 file extension, an HLS playlist describes where all of the smaller pieces of media can be found that make up a video stream. A program that reads the manifest file grabs all of the smaller video chunks defined and stitches them back together for playback.

Originating from the .m3u file format - meaning mp3 url - the format quickly evolved into the format we are used to working with today called "extended m3u8". Apple defined the HLS spec on top of the extended m3u format which is where all of those #EXT-X-: directives come from.

What is the difference between a multi-variant playlist (master manifest) and a media playlist?

HLS streaming normally takes advantage of ABR (adaptive bitrate streaming) which means that instead of a single video there's actually many different copies of the same file in different resolutions. This means that the player, or the user if they want to manually switch, can jump seamlessly between different resolutions during playback.

A multi-variant playlist (what used to be called a master manifest) describes where media playlists can be found. These media playlists describe where the actual media chunks are located for a given resolution.

The multi-variant playlist is therefore just a list of "variants" of the same piece of media, it doesn't define where the video chunks themselves are, that's the job of the media playlists that it lists. Usually these variants describe different resolutions like 1080p, 4K, etc.

What do the HLS tags and directives mean?

Let's take a look at the most common tags that make up the HLS format and see why they are needed.

#EXT

The file header. Must be on the first line.

#EXTINF:

Defines track information. For example: #EXTINF:60,Big Buck Bunny describes a track that is 60 seconds long followed by a comma and the title of the track.

#PLAYLIST:

Defines the title of a playlist e.g. #PLAYLIST:My favorite ice cream flavors.

#EXT-X-START:

Defines where a playlist should start from e.g. #EXT-X-START:TIME-OFFSET:5 means that the playback should start from 5 second in.

#EXT-X-INDEPENDENT-SEGMENTS

This is a boolean directive (it doesn't have any paramaters). It indicates that each media segment can be decoded on it's own and played without needing to decode other segments in order to play it.

#EXT-X-PLAYLIST-TYPE:

Defines the type of playlist, possible values are "EVENT" or "VOD". Event is usually use for live streams and VOD for regular video playback e.g. #EXT-X-PLAYLIST-TYPE:VOD

#EXT-X-TARGETDURATION:

Defines the maximum duration that any individual media segment is expected to be e.g: #EXT-X-TARGETDURATION:5 specifies that no segment should exceed 5 seconds in duration.

#EXT-X-VERSION:

Which version of the HLS format is being used. Each version introduced new tags and directives so make sure you're only using directives specified by this version e.g. #EXT-X-VERSION:3

#EXT-X-MEDIA:

Used to associate different media playlists together that relate to the same content, like different renditions or different camera angles of the same recording.

#EXT-X-STREAM-INF:

Found in a multi-variant playlist and details information about a variant stream (media playlist) e.g: #EXT-X-STREAM-INF:BANDWIDTH=1123000, CODECS="avc1.64001f,mp4a.40.2" describes a renditions bandwidth in bits per second and the codecs that will be needed to decode the segments contained within the playlist once it has been fetched.

#EXT-X-ENDLIST

Indicates that no more media segments will be defined after this point. Usually found at the end of a media playlist file but can technically be placed anywhere to delineate that there's no more media segments to be found after it.

Find out more

If you're interested in learning more about the HLS format and the less common tags and directives that sometimes appear, you could go dive in to RFC spec document and go straight to the source.