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, then ready or error), and cdn_link, a signed URL to the track's VTT 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.

Editing a track's content

Fix a typo or a mistimed cue in place, keeping the track's id, title, lang_code, and default flag. The track keeps its position in the player's caption menu, and every viewer picks up the new text on their next request.

On the Video Edit page, open Captions (or Chapters) and use the Edit action on a track. The editor shows one row per cue next to a preview player:

Control What it does
The cue number Jumps the player to that cue.
⤓ next to a time Sets that time from the player's current position.
Add cue Adds a cue at the playhead. For chapters, splits the chapter you're inside.
Split Splits the highlighted cue in two — at the playhead when it sits inside the cue, otherwise down the middle.
−0.5s / +0.5s Shifts every cue, for a track that's uniformly early or late.
Undo Reverts the last add, split, delete, or shift.

The cue under the playhead is highlighted as the video plays. Problems (an empty cue, an end before its start, overlapping chapters) are flagged inline and Save stays disabled until they're fixed. The Edit action is only available once a track is ready.

Anyone you have given access to the project can use the editor, not only the project's owner. The same goes for the API endpoints below, with the owner's key or a member's own (see authentication).

  • Read the current WebVTT body with get text track content ⧉, which returns {"content": "WEBVTT\n\n…"}. It reads from storage, so it always reflects your most recent edit (cdn_link may still be serving a cached copy).
  • Write it back with edit text track content ⧉, sending {"content": "…"}. The body is validated exactly as an upload is: VTT or SRT (detected by content), up to 10 MB, with SRT converted to WebVTT. An invalid body is rejected with 422 and the stored track is left untouched.

Editing content replaces the whole file, so send the complete track, not just the cues you changed. Read, modify, write.

Caches

An edit invalidates every cached copy of the old body: the CDN URL, any progressive MP4 with burned-in subtitles, and the HLS caption playlist. You don't have to purge anything.