Make a voice louder than the music: gain_db and duck_db ranges

Put the voice on the Timeline 1.0 audio spine and the music on soundtrack, then use two numbers: audio.gain_db (−60 to 12) to lift or cut the voice, and soundtrack.duck_db (0 to 20) to push the music down by that many decibels. Ducking needs a real spine, so a silent render refuses it.

OpusClip's September 10 changelog added noise reduction and voice enhancement sliders. Timeline has no enhancement filter in its documented fields; it is a numeric mixer, described in https://docs.sume.com/models/timeline and read 2026-10-01.

Which numbers control the mix?

Four fields matter for balance. They come from the Timeline program table.

Should I raise the voice or lower the music?

Either works, and they are different fields. Raising audio.gain_db changes the spine for the whole render, up to 12 dB. duck_db acts on the bed. Which one you want depends on whether the music is too loud everywhere or only under speech. The docs give ranges, not target loudness values, so listen to a short render before committing a long one; the unbilled /plan call checks structure but cannot judge the mix.

{
  "audio": { "url": "https://media.sume.com/artifacts/artf_demo/voice.wav", "duration_seconds": 30, "gain_db": 3 },
  "soundtrack": {
    "url": "https://media.sume.com/artifacts/artf_demo/bed.wav",
    "duck_db": 12,
    "loop": true,
    "fade_out_seconds": 2
  },
  "video": [{ "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 0, "duration": 30 }]
}

What errors will a bad mix request return?

duck_requires_audio_spine means you set soundtrack.duck_db with audio.mode: "silence". silent_audio_takes_gain means a gain_db on a silent spine. soundtrack_fade_exceeds_output means the fade is longer than the spine. For a plain how-to without the field ranges, see mix voice with background music.