#EXT-X-SESSION-DATA Explained: Sharing Metadata Across HLS Variants

The HLS master playlist has one job everyone knows about: listing the video and audio renditions a player can choose from. But it has a second job that is rarely discussed: carrying metadata that applies to the whole presentation rather than to any one quality level. That is what #EXT-X-SESSION-DATA is for.

What the tag declares

A #EXT-X-SESSION-DATA line appears in the master playlist and can carry either an inline value or a pointer to an external JSON file. The required DATA-ID attribute is a quoted URI that names what the data represents — by convention written in reverse-DNS notation such as com.example.movie.title to avoid collisions when multiple parties add their own session data to the same playlist.

Either a VALUE attribute (an inline string) or a URI attribute (a URL pointing to a JSON file) must be present — not both. The optional LANGUAGE attribute is a BCP-47 language tag. The same DATA-ID can appear multiple times in the same master playlist as long as each instance carries a different LANGUAGE — which is how multilingual titles and descriptions are delivered inside one manifest.

What it is used for in practice

The spec deliberately leaves the semantics up to the publisher — any data the server wants to communicate to the player can go here, provided the DATA-ID is unique to that usage. Real-world deployments use it for:

• Content identifiers — a CMS or analytics ID embedded in the manifest so the player does not need a separate API call to know which asset it is playing.
• Chapter cue points — a URI pointing to a JSON array of time-and-title objects, giving the player enough information to render a chapter list without a separate fetch.
• Thumbnail sprite references — a URI to a VTT file or JSON describing the sprite sheet used for seek previews, so players can show frame thumbnails while scrubbing.
• Ad decision parameters — data the client-side ad layer needs to request the right ad for this viewer without a separate lookup.
• Localized titles and descriptions — the LANGUAGE attribute makes this the natural place for multilingual metadata without a separate API endpoint.

How a player is required to handle unknown DATA-IDs

The HLS specification (RFC 8216) is explicit: a client must ignore any #EXT-X-SESSION-DATA tag whose DATA-ID it does not recognise. This makes the format safely forward-compatible — a player built before a particular DATA-ID was invented keeps working correctly, it just cannot act on the data it does not understand. If the tag carries a URI instead of a VALUE, the player is not required to fetch the URI at all when it does not recognise the DATA-ID.

A player that does recognise a DATA-ID typically reads the value or fetches and parses the JSON during master-playlist processing, before any variant is selected. That early timing is what makes content identifiers for analytics practical — the player can fire its event with the right ID at the moment it starts buffering, with no extra round-trip.

The URI form and JSON payloads

When a tag carries a URI attribute, the master playlist gives only a pointer and the JSON at that URL can be any structure the publisher defines. The spec does not mandate a schema for the payload — only that it is valid JSON. The URI is resolved relative to the master playlist URL, the same way segment URIs in a media playlist are resolved relative to that playlist. CORS applies: the JSON host must send Access-Control-Allow-Origin headers if the player page and the CDN are on different origins.

What this site's converter does with it

This site's /convert page parses a master playlist to find variant URLs and select the highest-bandwidth rendition — see how the converter picks the highest HLS quality. It reads #EXT-X-STREAM-INF, #EXT-X-MEDIA, and #EXT-X-VERSION. It does not read #EXT-X-SESSION-DATA — the tag carries no bytes that belong in the output MP4, so ignoring it is exactly what the spec recommends for a client that does not recognise the DATA-ID. Any session-data lines in the source master playlist pass through the parser without error and without effect on the conversion.

That said, thumbnail sprite references embedded via SESSION-DATA are exactly the kind of information a future chapter-preview feature would use. The data is already in the manifest for any source that publishes it — a client that reads it gets chapter markers and seek thumbnails with no extra API call. See also #EXT-X-VERSION for the compatibility attribute that governs which tags a playlist is allowed to use.