duck_requires_audio_spine: no music ducking under silence mode

duck_requires_audio_spine is the Timeline 1.0 refusal for soundtrack.duck_db combined with audio.mode: "silence". Ducking lowers the music while a voice plays, and silence mode has no voice file. Remove duck_db and set the bed level with soundtrack.gain_db, or give the timeline a real spine (audio.url or audio.parts[]) and keep the duck.

Which silence-mode fields are refused?

The Timeline 1.0 page defines audio.mode: "silence" as a declared length with no spine file. In that mode url, parts, gain_db and source_in on the audio are illegal, and each one has its own code. duck_db on the soundtrack is the one people hit after switching an existing request to silence.

audio.duration_seconds is still required, from 1 to 1800 seconds, because it sets the output length.

How is this different from sidechain ducking in FFmpeg?

In an FFmpeg graph you wire the voice into a compressor yourself, and nothing stops you from wiring silence into it. Sume's duck_db (0 to 20 dB) is a field on the soundtrack that always refers to the audio spine, so the API checks that a spine exists.

With a silent video and a music bed, what you want is a level, not a duck. Use soundtrack.gain_db (-60 to 12), loop: true for a bed shorter than the video, and fade_out_seconds up to 10.

A request that passes

The sketch below builds both bodies and asserts the rule that separates them. It runs as written, using placeholder artifact URLs in the documented shape.

Send the corrected body to POST /v1/timeline-1.0/plan first. It is unbilled and returns the same refusal, with no job created. Then render with an Idempotency-Key and poll as in Jobs and results.

base = {"video": [{"source_url": "https://media.sume.com/artifacts/artf_demo/b.mp4",
                   "start": 0, "duration": 12}]}
bad = {**base, "audio": {"mode": "silence", "duration_seconds": 12},
       "soundtrack": {"url": "https://media.sume.com/artifacts/artf_demo/bed.mp3",
                      "duck_db": 12}}
good = {**base, "audio": {"mode": "silence", "duration_seconds": 12},
        "soundtrack": {"url": "https://media.sume.com/artifacts/artf_demo/bed.mp3",
                       "gain_db": -6, "loop": True, "fade_out_seconds": 2}}

def refusal(body):
    if body["audio"].get("mode") == "silence" and body.get("soundtrack", {}).get("duck_db", 0) > 0:
        return "duck_requires_audio_spine"

print(refusal(bad))   # duck_requires_audio_spine
print(refusal(good))  # None

Which mode should a silent product loop use?

Silence mode with a soundtrack bed. Declare the length with audio.duration_seconds, give the video slots starts that add up to it, and let the soundtrack loop under the picture with a gain that sits well below full scale. The bed's fade_out_seconds gives a clean ending without any voice track.

If a voiceover is added later, switch the audio to a real spine, keep the same video slots, and then duck_db becomes legal. Because only the audio block changes, the move from silent to narrated is a small edit to the same document.

What are the soundtrack ranges?

On the Timeline 1.0 page the soundtrack fields are gain_db from -60 to 12, duck_db from 0 to 20, fade_out_seconds up to 10, and loop. Out-of-range values are refused at submit, so a quick range check in your builder saves a round trip.

A sensible starting point for a silent product loop is a negative gain, a loop and a short fade-out, then adjust by ear after the first render. Because the plan call is unbilled, you can iterate on the structure for free and only pay for the renders you listen to.