# Add chapters

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](/docs/guides/robots-generate-chapters).

<Callout type="info">
  The Mux Robots Generate chapters job returns a simple list of `start_time` and `title` pairs. However, with either the <ApiRefLink href="/docs/api-reference/robots/generate-chapters">Generate chapters</ApiRefLink> or <ApiRefLink href="/docs/api-reference/robots/analyze-structure">Analyze structure</ApiRefLink> 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.
</Callout>

## Add chapters to a new asset

Include a chapters track alongside your video input when you <ApiRefLink href="/docs/api-reference/video/assets/create-asset">create an asset</ApiRefLink>. Set `type` to `text` and `text_type` to `chapters`, and point `url` at a JSON file in the format described below.

```json
{
  "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"
}
```

## Add chapters to an existing asset

You can also add chapters after the asset is created, using <ApiRefLink href="/docs/api-reference/video/assets/create-asset-track">create an asset track</ApiRefLink>. The asset must be in the `ready` state first.

```bash
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.

## The chapters JSON format

Mux expects chapters in the same format the HLS spec uses for [JSON chapters](https://developer.apple.com/documentation/http-live-streaming/providing-javascript-object-notation-json-chapters): an array of chapter entries, each with a start time and one or more titles.

```json
[
  {
    "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`.
* You can add optional `images` (artwork for the chapter) and `metadata` (arbitrary key and value pairs) entries per chapter. See the HLS [spec](https://developer.apple.com/documentation/http-live-streaming/providing-javascript-object-notation-json-chapters) for the full set of fields.
* We validate the file you upload and reject it if it doesn't match this specification.

## How Mux delivers chapters

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}.json
```

Replace `{PLAYBACK_ID}` with the asset's playback ID and `{TRACK_ID}` with the ID returned when you created the chapters track.

<Callout type="info">
  If the asset uses signed playback, sign the request with the same token you use for that asset's HLS manifest and segments.
</Callout>

## Update or remove chapters

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:

```bash
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.

## Related

* [Generate chapters with Mux Robots](/docs/guides/robots-generate-chapters)
* [Analyze structure with Mux Robots](/docs/guides/robots-analyze-structure)
* [Create an asset track](/docs/api-reference/video/assets/create-asset-track)
* [Create an asset](/docs/api-reference/video/assets/create-asset)