Skip to content

Text tracks

Captions, subtitles, and chapters are all text tracks on a video. Four kinds exist:

type What it is How it's created
caption A caption/subtitle track. Uploaded by you (this page).
chapter Chapter markers on the player timeline. Uploaded by you, or generated with AI.
auto An AI-generated caption track. Auto-generated captions.
embedded_subtitle A subtitle stream that was inside the uploaded file. Extracted automatically.

Uploading a track

Use the Upload a text track panel on the Video Edit page (or the Upload a chapter file panel on the Chapters page for chapters).

Use the create text track ⧉ endpoint — a multipart form:

Field Meaning
file A VTT or SRT file (validated by content, not extension), up to 10 MB. SRT files are converted — the stored track is always WebVTT.
type caption or chapter.
title The track's label shown to viewers (up to 64 characters).
lang_code BCP 47 language code (e.g. en, pt-BR).

Constraints: a video can have only one chapter track (delete the existing one to replace it), and tracks can't be added to a fast clip or to a video whose processing failed.

Reading, editing, and deleting

  • List tracks by requesting the video with ?include=text_tracks. Each track carries id, type, title, lang_code, default, status (processing → ready, or error), and cdn_link — a signed URL to the track's VTT file.
  • Download the VTT from cdn_link — this is also the editing flow: download, fix the text or timings in a text editor, delete the track, and upload the corrected file.
  • Edit the track's title, lang_code, or make it the default with the edit text track ⧉ endpoint. The default track is pre-selected in the player; only caption-type tracks can be the default.
  • Delete with the delete text track ⧉ endpoint (returns 204). Deleting an audio track also deletes the captions that were generated from it.