Holiday spot with a music bed: timeline soundtrack, duck_db, fade-out

A holiday music bed goes in the optional soundtrack block of a Sume Timeline 1.0 request: a hosted url, a gain_db, loop, a fade_out_seconds of up to 10, and duck_db from 0 to 20 to lower the music under the voice. Ducking needs a real audio spine, not silence, or the job refuses with duck_requires_audio_spine. The render is $0.10 per ceil(output minute), so a 30 second spot with a bed is $0.10.

The voiceover is the spine; the bed is a second layer on top of it.

The soundtrack fields

These come straight from the timeline docs, and each has a refusal if you break it.

A 30 second spot

Set audio.url to your hosted voiceover and audio.duration_seconds to its length. Then add a soundtrack with a bed URL, loop: true if the bed is shorter than 30 seconds, duck_db around 10 to start, and a fade_out_seconds of 2 so the music ends softly. A fade longer than the spine is refused, so keep it short.

curl -X POST https://api.sume.com/v1/timeline-1.0/plan \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio": {"url": "https://media.sume.com/artifacts/a/vo.wav", "duration_seconds": 30},
    "video": [{"source_url": "https://media.sume.com/artifacts/a/clip.mp4", "start": 0, "duration": 30}],
    "soundtrack": {"url": "https://media.sume.com/artifacts/a/bed.mp3", "loop": true, "duck_db": 10, "fade_out_seconds": 2}
  }'

Tuning the duck

Start with duck_db near 10 and listen. If the music still covers a price or a name, raise it toward 20; if the bed disappears whenever the voice speaks, lower it. Change one value at a time and re-render, which at $0.10 per minute of output costs about as little as a test can. Plan the check on a phone speaker, because that is where most shoppers will hear it.

Mind the licensing of your music. The API places whatever hosted file you give it, and the right to use a track in an ad is yours to confirm.

If you need a bed generated for you, Sume also lists music models in its docs; a separate post covers that, and here the bed is any hosted file. Keep the clean voiceover so you can re-render a market with a different bed.

• Voiceover = spine, music = soundtrack.
• duck_db 0 to 20, needs a real spine.
• Fade-out up to 10 s, never longer than the spot.

Pitfalls in sale week

The first is a bed that is longer or shorter than the spot. If it is shorter, set loop: true and listen for the seam, because a hard loop point can click. If it is longer, the render uses the spot's length, so trim your bed before upload if the best part comes late.

The second is the fade. A fade_out_seconds longer than the spine is refused with soundtrack_fade_exceeds_output, and edge fades on the picture have a similar check. Keep both short and compare the combined result.

The third is skipping the plan step. The unbilled POST /v1/timeline-1.0/plan compiles your program and catches the refusals, so use it on every new template before you submit the real render. Once the template passes, you change only the URLs per market, and you can run twelve language versions with the same bed and the same settings, 12 x $0.10 = $1.20 for 30 second spots.