Set voiceover scripts
voiceover_batchSet voiceover text and/or trigger speech generation for any number of clips in a single call.
Each entry chooses its own action:
"set_text" — set transcript for a clip (clip_index + text)
"generate_speech" — async TTS for a clip (returns immediately; wait: true blocks until it lands)
"set_and_generate" — set text and kick off TTS in one entry (+ text)
Emotion tags: put ElevenLabs emotion/audio tags in square brackets in the text, e.g. "[excited] And it just works." or "[whispers] Here's the trick." — the voice performs them and they're never spoken or shown. Use them sparingly, before the phrase they colour.
Pauses: pause:1.5s in the text is exact silence of that length, anywhere including the very start (a lead-in before the first word) and the very end (a hold after the last); word timings account for it, and get_clip's voiceover_text shows existing pauses the same way, so keep them when you rewrite. Unlike the [pause] emotion tag, which is a performed beat of no set length.
Sizing a script: narration runs roughly 2–2.5 words per second depending on the voice — size the script to the target length, generate the voiceover, then read the real clip durations back (get_clip, once busy is empty) before timing visuals.
Address a clip the same way as everywhere else: clip_index. Pass clip_id instead if you already have it — it survives clips being inserted or reordered mid-build — but you never need both; whichever you omit is looked up once for the whole call.
Entries within one call are applied in order. Returns one result object per input entry. All text-set actions land in ONE save; the TTS for generate/set_and_generate runs async per clip after.
Sync points: if get_clip's voiceover_text for the clip contains <SYNC_MARKER N> tokens (a screen recording's on-screen actions), your new text must carry every one of them, each exactly once and in order, placed where that action is narrated. Otherwise the entry is refused and nothing is written. Rephrase the words between the tokens freely.
IMPORTANT — generating speech RESCALES the whole clip, it does not clamp it: when audio is generated (generate_speech / set_and_generate), the clip's duration is reset to the spoken audio length, and then EVERY element on that clip is retimed proportionally by (new duration ÷ old duration). start_time, end_time and every keyframe timestamp are multiplied by that factor. Nothing is merely truncated — on a 6s clip that becomes 1.02s, an animation you placed at [0, 1.6] ends up at [0, 0.27]. Zoom elements whose window falls under the minimum after scaling are DROPPED entirely. Generation is async, so this lands AFTER this call has already returned success. So: generate speech BEFORE placing time-sensitive elements — then re-read the clip and check what your elements actually became, not just the clip duration.
Concurrency: parallel-safe (conflict domain: a clip's voiceover). The server merges each clip's voiceover under a per-guide lock and preserves that clip's elements, so you can fan voiceover work out across subagents by clip — and it's safe to run alongside element edits. Two concurrent edits to the SAME clip's voiceover do not last-write-win — both claim that clip's voiceover path, so the later one is REJECTED and nothing is written; re-read and re-apply. Do NOT run concurrently with whole-clip/whole-project mutations on the same guide (update_clips on that clip, structural clip ops, add_audio, update_project).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | true blocks until the speech this call starts has landed, so the clip durations, voiceover_words and element times you read next are the real ones: `ready` lists each landed clip with its new duration. Bounded by wait_seconds; clips still generating then come back under durations_pending (poll get_clip(select:['busy']) for those). Use it whenever the next step times anything to the voiceover. Inside run_script the wait counts against the script's time. | |
| entries | Yes | Voiceover entries — at least one. | |
| project_id | Yes | Project ID | |
| wait_seconds | No | With wait: the most to wait, default 50s. |