Add chapter markers to a video asset so viewers can jump between sections.
Chapters break a long video into named sections, like "Introduction" or "Q&A," that a viewer can jump between instead of scrubbing blindly through the timeline. They're useful for lectures, podcasts, product demos, or any video where viewers want to join or re-join to watch a specific part of it.
Mux stores chapters as a track on the asset, the same way subtitles and alternate audio tracks work. You can add them yourself through the API, or generate the chapter data automatically with Mux Robots.
The Mux Robots Generate chapters job returns a simple list of start_time and title pairs. However, with either the Generate chaptersAPI or Analyze structureAPI job (which also generates chapters) when you set update_asset_chapters to true the workflow adds this chapter information to the asset as a track that is accessible in the HLS JSON format.
Include a chapters track alongside your video input when you create an assetAPI. Set type to text and text_type to chapters, and point url at a JSON file in the format described below.
{
"inputs": [
{
"url": "{VIDEO_INPUT_URL}"
},
{
"url": "https://example.com/my-video-chapters.json",
"type": "text",
"text_type": "chapters",
"language_code": "en",
"name": "English"
}
],
"playback_policies": ["public"],
"video_quality": "basic"
}You can also add chapters after the asset is created, using create an asset trackAPI. The asset must be in the ready state first.
curl https://api.mux.com/video/v1/assets/{ASSET_ID}/tracks \
-X POST \
-d '{
"url": "https://example.com/my-video-chapters.json",
"type": "text",
"text_type": "chapters",
"language_code": "en",
"name": "English"
}' \
-H "Content-Type: application/json" \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}An asset can only have one chapters track at a time.
Mux expects chapters in the same format the HLS spec uses for JSON chapters: an array of chapter entries, each with a start time and one or more titles.
[
{
"chapter": 1,
"start-time": 0,
"titles": [{ "language": "en", "title": "Introduction" }]
},
{
"chapter": 2,
"start-time": 42.5,
"titles": [{ "language": "en", "title": "Getting started" }]
},
{
"chapter": 3,
"start-time": 210,
"titles": [{ "language": "en", "title": "Wrap-up" }]
}
]A few things worth knowing about this format:
start-time is in seconds and marks where the chapter begins. A chapter runs until the next one starts, unless you set an explicit duration.titles is an array so you can give each chapter a title in more than one language. Every title needs a language and a title.images (artwork for the chapter) and metadata (arbitrary key and value pairs) entries per chapter. See the HLS spec for the full set of fields.When an asset has a chapters track, Mux adds an EXT-X-SESSION-DATA tag to the HLS manifest that points players at the chapters file.
You can also fetch the chapters JSON directly:
https://stream.mux.com/{PLAYBACK_ID}/chapters/{TRACK_ID}.jsonReplace {PLAYBACK_ID} with the asset's playback ID and {TRACK_ID} with the ID returned when you created the chapters track.
If the asset uses signed playback, sign the request with the same token you use for that asset's HLS manifest and segments.
There's no endpoint to edit a chapters track in place. To replace the chapters on an asset, delete the existing track and create a new one:
curl https://api.mux.com/video/v1/assets/{ASSET_ID}/tracks/{TRACK_ID} \
-X DELETE \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}Then create the new chapters track the same way you did the first time.
Because chapters are stored and delivered like any other asset track, deleting an asset also deletes its chapters, and there's no separate charge for chapters storage or delivery.