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):
{
"op": "audio.duck",
"args": {
"gain_db": -12,
"item_id": "itm_s6t7v8w9x0",
"speech_item_ids": [
"itm_m1n2p3q4r5"
]
}
}Errors#
E_VALIDATION, E_INVALID_TIME, E_NOT_FOUND, E_TYPE_MISMATCH, E_INVALID_STATE, E_LIMIT
Scope and phase#
Scope edit, phase beta. Run vukem-video command:help audio.duck for the same description from the binary.