# audio.duck

> Lowers a music item while speech sounds, with a ramp down before and a ramp up after.

Source: https://alexgalhardo.github.io/vukem-video/docs/reference/commands/audio.duck

Writes volume keyframes on the music item: its volume drops by gain_db over attack before each stretch of speech and returns over release after it. Speech stretches closer than the ramps are held low across the gap. The speech comes from the analysis of the speech items and is supplied by the service in resolved; the command never starts a job. The item must have no volume keyframes yet; keyframe.clear on volume undoes the ducking.

## Arguments

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `attack` | `string` | no | A length, may be 0; the ramp down before speech. Default "0.2s". |
| `gain_db` | `number` | no | Change of volume while speech sounds, -40 to -1; default -12. min -40; max -1 |
| `item_id` | `string` | yes | The music: an audio item with no volume keyframes. |
| `release` | `string` | no | A length, may be 0; the ramp up after speech. Default "0.5s". |
| `resolved` | `object` | no | Filled by the service from the speech of the items; never sent by a caller. |
| `speech_item_ids` | array of `string` | yes | Clips or audio items that carry the speech. at least 1 items; at most 20 items |

## Example

As one operation of an `edit` batch (the `edit` tool of MCP, `vukem-video edit --ops`, or `POST /api/v1/projects/{id}/edit`):

```json
{
  "op": "audio.duck",
  "args": {
    "gain_db": -12,
    "item_id": "itm_s6t7v8w9x0",
    "speech_item_ids": [
      "itm_m1n2p3q4r5"
    ]
  }
}
```

## Errors

[`E_VALIDATION`](/docs/reference/error-codes#e_validation), [`E_INVALID_TIME`](/docs/reference/error-codes#e_invalid_time), [`E_NOT_FOUND`](/docs/reference/error-codes#e_not_found), [`E_TYPE_MISMATCH`](/docs/reference/error-codes#e_type_mismatch), [`E_INVALID_STATE`](/docs/reference/error-codes#e_invalid_state), [`E_LIMIT`](/docs/reference/error-codes#e_limit)

## Scope and phase

Scope `edit`, phase `beta`. Run `vukem-video command:help audio.duck` for the same description from the binary.
