# Audio editing

> Add music and sound, set volume and fades, mute a clip and keep the mix out of clipping.

Source: https://alexgalhardo.github.io/vukem-video/docs/guide/audio/

## 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](/docs/guide/keyframes) 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

**CLI**

```bash
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=2s
```

**MCP**

`edit` with the operations:

```json
{ "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](/docs/guide/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`.

```bash
vukem-video edit --project prj_7k2m9x4q1b audio.duck item_id=itm_s6t7v8w9x0   speech_item_ids:=[itm_m1n2p3q4r5] gain_db:=-14
```

If 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.

```bash
vukem-video edit --project prj_7k2m9x4q1b audio.mark_beats item_id=itm_s6t7v8w9x0 every:=2 label=beat
```

An 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_muted` on an audio item. It applies to clips; set `volume` to 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.

## Next steps

- [Remove silence](/docs/guide/silence-removal)
- [Animate with keyframes](/docs/guide/keyframes)
