You will learn#
- how to place audio on an audio track;
- how to set volume, fades and mute;
- how to lower music under speech (ducking) and mark the beats of a song;
- how the export mixes the audio and what the lint warns about.
The idea#
Sound comes from two places: the audio of a video clip, and audio items on an audio track. An audio item points to an audio asset, or to the audio of a video asset, and plays from source_in for a duration. The export mixes every audible item into one 48 kHz stereo track.
Each clip or audio item has a volume (linear gain from 0 to 4), a fade_in, a fade_out, and a clip can be muted with audio_muted. Volume can also be animated with a keyframe on the property volume. The project has a loudness_target in LUFS (from -30 to -5) that the export aims for.
There is no audio panel in the inspector yet: use the command palette (Ctrl+K, Cmd+K on macOS), the CLI or an agent.
Quick start#
vukem-video edit --project prj_7k2m9x4q1b audio.add track_id=trk_m1n2p3q4r5 \
asset_id=ast_4h6j8k2m3n start=0s
vukem-video edit --project prj_7k2m9x4q1b item.set_audio item_id=itm_s6t7v8w9x0 \
volume:=0.6 fade_in=1s fade_out=2sedit with the operations:
{ "op": "audio.add", "args": {
"track_id": "trk_m1n2p3q4r5", "asset_id": "ast_4h6j8k2m3n", "start": "0s"
} }
{ "op": "item.set_audio", "args": { "item_id": "itm_s6t7v8w9x0", "volume": 0.6, "fade_out": "2s" } }The default duration of an audio item is the rest of the asset from source_in. The two fades together cannot be longer than the item. A volume of 1, fades of 0s and audio_muted false clear the stored value.
Duck music under speech#
audio.duck lowers a music item while speech sounds. It writes volume keyframes on the music: the volume drops by gain_db (-12 by default, from -40 to -1) over attack (0.2s) before each stretch of speech and comes back over release (0.5s) after it. Two stretches of speech closer than the ramps are held low across the gap. speech_item_ids names the clips or audio items that carry the speech (1 to 20).
The speech is found by the analysis of those items, which the service reads for you; never send resolved. The music item must have no volume keyframes yet. To undo the ducking, clear them with keyframe.clear on volume.
vukem-video edit --project prj_7k2m9x4q1b audio.duck item_id=itm_s6t7v8w9x0 speech_item_ids:=[itm_m1n2p3q4r5] gain_db:=-14If the speech item has no analysis yet the edit fails with E_INVALID_STATE and the hint to wait until the asset is ready.
Mark the beats of a song#
audio.mark_beats writes a marker on a music item at each beat of its visible part, so you can place cuts and transitions on the music. every marks every nth beat (1 to 64, default 1), label names the markers (up to 60 characters) and replace (true by default) replaces the markers the item already has. The beat grid comes from the analysis of the asset. Markers change neither the picture nor the sound.
vukem-video edit --project prj_7k2m9x4q1b audio.mark_beats item_id=itm_s6t7v8w9x0 every:=2 label=beatAn asset without audio has no beat grid and the edit fails with E_INVALID_STATE. The same two operations are available to an MCP agent through edit. The editor has no section for ducking or beat markers yet.
Run vukem-video lint before you export. These rules concern sound: L_AUDIO_OVERLAP (audio items that overlap), L_AUDIO_CLIP (the mix reaches clipping) and L_SILENT_EXPORT (the export would have no sound).
Common mistakes#
- Adding audio to a visual track:
E_TYPE_MISMATCH. - Setting
audio_mutedon an audio item. It applies to clips; setvolumeto 0 for an audio item. - A volume above 4:
E_VALIDATION. - Ducking a music item that already has volume keyframes: the edit is refused. Clear them first.