Skip to content

Auto-generated chapters

This guide shows how to generate chapter markers for an on-demand HeapStream video from its captions, so viewers can see and jump between sections on the player timeline.

Overview

HeapStream generates video chapters from an existing caption track using an LLM: it reads the timestamped captions, splits the content into logical sections at topic shifts, writes a short title for each, and saves them as a WebVTT chapters track. The chapters then appear on the player's timeline and in the video's SEO metadata. Generation runs in the background — the chapter track shows as processing until it's ready.

A video must already have a caption track (auto-generated or uploaded) before you can generate chapters — generation reads the captions, not the audio. A video can have one chapter track; delete the existing one to regenerate.

This works best on spoken-word content with clear sections (talks, tutorials, podcasts).

Generating chapters

  • Generate chapters for a video in the Video Edit -> Chapters page, in the Generate chapters with AI panel. You can optionally set the minimum and maximum number of chapters per hour of content (defaults: 3 and 8).
  • Or, in the same Chapters panel, use Upload a chapter file to add your own WebVTT (or SRT) chapters track instead of generating one. The upload is hidden once a chapter track exists (a video can have only one), so delete the existing one first to replace it.
  • Generate chapters through the "Generate chapters" endpoint in the API ⧉.
  • Or upload your own chapters file through the "Create text track" endpoint with the track type set to chapter.

FAQ

What do I need before generating chapters?

The video must be ready (processed) and have at least one caption track. If it has no captions, generate or upload captions first — see Auto-generated captions.

How many chapters are generated?

By default, between 3 and 8 per hour of content, scaled to the video's length. You can tune the minimum and maximum per hour when you generate.

Can I edit the generated chapters?

Yes. The chapters are stored as a standard WebVTT chapters track:

  1. Download the VTT file through the API or GUI
  2. Edit the titles or timings in a text editor
  3. Delete the generated chapter track
  4. Upload a new chapter track with the edited VTT file

The chapter titles aren't quite right

Chapter titles are generated from the caption text, so if the captions have mistakes the chapters may too — correct the captions and regenerate. Tuning the minimum/maximum chapters per hour also helps you get finer or coarser sections.