Extract a clip's audio onto its own layer
extract_audioThe editor's "Extract Audio": a clip's own audio — the recording's sound on a video clip, or its generated voiceover — becomes a separate audio track (returns music_id), and the clip goes silent.
The track starts where the clip starts and plays at normal speed. Shape it with update_audio (trim music_start_time / music_end_time, move guide_start_time, fade, volume); analyze_audio(file_url=) reads it.
The track stays in sync through later edits — yours, and voiceover landing on other clips: clips before it moving or resizing, and cuts inside it (split_clip + remove_clip of a part re-cuts the track to what's left; removing a middle part splits it in two). Removing every clip it played under leaves the track where it was; a track you moved or trimmed out of sync stays where you put it.
While extracted, the clip's voiceover is locked: voiceover_batch skips it, and an update_clips voiceover_volume on it is not applied (that entry comes back as an error).
restore: true gives the clip its own audio back at 100%. The extracted track stays — remove it with remove_from_project(target='audio') if unwanted.
Keep-the-audio, swap-the-visual (e.g. a webinar segment over stock footage):
Cut the recording to the segment(s) with split_clip + remove_clip (before or after extracting).
extract_audio on the clip(s).
Cover, don't delete: add_elements a full-canvas, fully opaque visual on that clip for its whole duration — a stock video (find) with volume 0, an image, or a background shape + text. The recording keeps playing underneath unseen, and the clip's captions still follow the extracted audio's words.
Errors if the clip is already extracted, has no audio (a slide with no generated voiceover), or speech is generating on it.
Concurrency: whole-project mutation — serialize; do not run in parallel with other mutations on the same project_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| clip_id | No | Clip ID (preferred over clip_index). | |
| restore | No | true = undo: the clip plays its own audio again at 100%. | |
| clip_index | No | Zero-based clip index. Ignored if clip_id is provided. | |
| project_id | Yes | The project ID |