Understand the JSON chapter formatting required for HTTP Live Streaming.
This document describes how to provide chapter markers and other per-chapter metadata used by iOS, tvOS, and macOS for HTTP Live Streaming (HLS). This metadata is provided by the content provider in JSON format, and is referenced through the use of the
EXT-X-SESSION-DATA tag in the HLS Master Playlist.
This document specifies:
What type of chapter metadata can be provided.
How to define the chapter metadata in JSON format.
How to declare the location of the chapter data in the HLS Master Playlist.
How to validate that the JSON data is in the correct format.
How the metadata appears in the API.
Chapter data is information that is provided to describe a chapter. Four different types of data can be provided for each chapter: timing, titles, images, and general metadata. Keep the following in mind when designing your chapter data:
Each chapter is required to have a start time and may have an optional duration.
Each chapter may have multiple titles, multiple images, and multiple metadata items.
Each title in a chapter has a unique BCP-47 language tag.
Each metadata item in a chapter has a unique key and language.
JSON is a format that uses human-readable text to define data objects. JSON is described in RFC7159. Here is a simple example of chapter data formatted as JSON:
The above example has three chapters. Only chapter titles and start-times are present. Each chapter title is presented in two different languages.
Chapter metadata is presented as an array of chapters. Each element in the array contains information about that chapter. The first array element describes the first chapter, the second element describes the second chapter, and so on.
Each element in the chapter array is a JSON object called a chapter entry. The chapter entry must contain a
start-time. The chapter entry should contain
images, and possibly
The chapter entry may contain an item named
chapter to promote human readability of the JSON. The chapter entry may contain
duration. Chapter entries are assumed to have a duration from
start-time to the
start-time of the next chapter entry, unless duration is specified. Chapter timing can overlap and nest, in which case both
duration must be specified.
Chapter entries may contain a
titles JSON array. Each element of a
titles array is a JSON object that must contain both a
language BCP-47 string and a
title string containing the title for that chapter, written in the language specified by the
language string. All strings must be encoded using UTF-8. Set the language to
"und" if the title strings are language-neutral, such as a numeric string.
Chapter entries may contain an
images JSON array. Each element of a
images array is a JSON object containing information about images for each chapter. For example, an
images array may contain an element for a thumbnail image and an element for an HD image.
Each element in an
images array is a JSON object and must contain an
image-category string, a
pixel-width number, a
pixel-height number and an
image-category string should be the same across chapters for images that are similar. In the case mentioned above you would use one string for the thumbnails (e.g. ‘thumbnail’) and a different string for the HD images (e.g. ‘hd’).
url string must be an absolute or relative URL to the image data associated with the chapter. Relative URLs are relative to the path that contained the JSON Chapter document.
images files themselves may be in a variety of image formats. For example, JPEG, PNG, and TIFF are all supported.
Chapter entries may also contain a metadata JSON array. Each element of a
metadata array is a JSON object containing metadata for that chapter. Each metadata array element contains a mandatory
value along with an optional
language BCP-47 string. The key element must be a string. The value element can be a string, number, array or object. If any
value is a URI, it is passed as is. The system has no way to interpret a relative URI in that context.
For use in HTTP Live Streaming, JSON formatted chapter data must be specified in a Master Playlist using the
The DATA-ID attribute of the
EXT-X-SESSION-DATA must be "com.apple.hls.chapters". The URI attribute must point to the JSON-formatted chapter data. The URI may be absolute, or relative to the path that contained the master playlist.
The following JSON schema can be used with a JSON schema validator to validate your chapter data:
Using Chapter Data in Your App
You can use QuickTime Player to quickly test your HLS streams with chapter data. QuickTime Player will display a chapter pop-up control (with images if you have them). In QuickTime Player, use File > Open Location… or ⌘L to open a URL.
QuickTime Player will display your chapters in the order they are in the JSON file, it does no sorting or rearrangement.
Accessing the data
The Media Playback Programming Guide (in the chapter “Refining The User Experience”) has a description of how to access chapter data. The methods described there return an array of
AVTimed objects, one object for each chapter. The order of the groups matches the order of the JSON file.
AVTimed object has a start time, end time, and a list of
AVMetadata. Every item from the titles, images, and metadata arrays in the JSON will be in the list of metadata items.
The images will have an
extra dictionary. This dictionary will contain a key
"i whose value is a dictionary that contains the pixel-width, pixel-height, and image-category from the JSON entry.
The metadata item keys will be placed in the key space
AVMetadata. This key space defines its key values to be expressed as reverse-DNS strings. This allows you to define your own keys in a well established way that avoids collisions.