Edit captions
captionsRead and edit a clip's CAPTIONS (subtitles) — what they say, where one caption ends and the next begins, when each shows, captions not tied to the voiceover, and translation. Captions are built from the clip's voiceover words: each caption is a run of words, addressed by its start_word_index.
Start with action="list" on the clip — it returns blocks (voiceover captions: start_word_index, end_word_index, start/end in clip seconds, text, transcript_text, words, edited, retimed, mergeable), manual_captions ({caption_id, start, end, text}), active_language and translated_languages. Then:
edit (start_word_index, text) — change what ONE caption says on screen. The voiceover audio, its words and timing are untouched; to change what is SPOKEN use voiceover_batch. reset (start_word_index) restores the transcript text.
split (start_word_index, split_word_index) — cut a caption in two; split_word_index is the word that STARTS the second caption (block word i = start_word_index + i; not the first word). Edited text, per-caption style and custom timing are divided between the halves — re-check both and edit them if the cut landed badly. merge (start_word_index of the SECOND caption) only undoes a split (
mergeable: true); other boundaries come from the transcript's sentences and pauses.timing (start_word_index, start_time, end_time) — when one caption shows, in seconds from the START OF THE CLIP. timing_reset returns it to its words' own timing.
manual_add (start_time, end_time, text) → caption_id; manual_edit (caption_id, and text and/or start_time/end_time); manual_remove (caption_id). Manual captions have their own text and window — use them on clips with NO voiceover (list returns no blocks there) or to fill a gap. Adding/editing one turns captions on for the clip. They show without word highlighting.
translate (language: id like "fr" or name like "French") — translate caption TEXT (edited and manual captions included) using the workspace's translation rules and glossary (read or change them with translation_glossary). Omit clip_index for every clip. The new language becomes the one shown; earlier languages are kept. The voiceover stays in its language (use set_voice for that). One translation call per clip, so a long project takes a while — do one clip first if only one was asked about.
language (language: an already-translated id, or "original") — switch which translation is shown, instantly, without re-translating. Omit clip_index for every clip.
Rules: a caption lasts at least 0.1s, stays inside the clip, and never overlaps another caption; anything else is REFUSED with the allowed range — read it and retry. While a translation is shown, edit/manual_edit change the translated text and split is refused (switch to "original" first). Custom timing is tied to a caption's exact words and stops applying if the voiceover is regenerated.
To burn captions into an exported video use export_project(captions=true).
Concurrency: clip-scoped mutation (conflict domain: the clip's caption settings) — serialize calls on the SAME clip; different clips run in parallel. translate/language without clip_index touch every clip: run them alone.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | edit / manual_add / manual_edit — the caption text. | |
| action | Yes | What to do — see the tool description | |
| end_time | No | timing / manual_add / manual_edit — seconds from the start of the clip. | |
| language | No | translate — language id ("fr") or name ("French"). language — a translated id, or "original". | |
| caption_id | No | manual_edit / manual_remove — from list's manual_captions. | |
| clip_index | No | The clip. Required for every action except translate/language, where omitting it means every clip. | |
| project_id | Yes | The project ID | |
| start_time | No | timing / manual_add / manual_edit — seconds from the start of the clip. | |
| split_word_index | No | split — the word that starts the new second caption. | |
| start_word_index | No | edit/reset/split/merge/timing/timing_reset — the caption, exactly as list returned it. |