Fade in and out on a Timeline render: output fade seconds 0 to 5

Set output.fade_in_seconds and output.fade_out_seconds in a Timeline render to fade the whole output up from black and down to black, each from 0 to 5 seconds, with the sum no longer than the output length. A separate soundtrack.fade_out_seconds, up to 10 seconds, fades only the music bed. If either is longer than the render, you get a refusal: edge_fades_exceed_output for the output fades and soundtrack_fade_exceeds_output for the bed.

These are two different controls and you will often use both: the output fade shapes the picture and the soundtrack fade shapes the music.

Which field does what

The Timeline docs list output.fade_in_seconds / fade_out_seconds as 0 to 5 seconds, with the sum required to be at most the output length. For a 6-second render, a 3-second fade in plus a 3-second fade out is the limit; 4 plus 3 is refused.

The bed is a separate field on soundtrack: fade_out_seconds up to 10, with loop, gain_db and duck_db. A fade-out on the bed does not fade the picture, and a fade on the output does not by itself change how the music ends, so set each on purpose.

A short example

The request below renders 8 seconds with a half-second fade in and a one-second fade out of the output, and a looped bed that fades over 2 seconds. The fades add 1.5 seconds, well below the 8-second limit. An 8-second render is one billable minute at $0.10.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fade-001" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
      "duration_seconds": 8
    },
    "video": [
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4",
        "start": 0,
        "duration": 8
      }
    ],
    "output": { "fade_in_seconds": 0.5, "fade_out_seconds": 1 },
    "soundtrack": {
      "url": "https://media.sume.com/artifacts/artf_demo/bed.mp3",
      "loop": true,
      "fade_out_seconds": 2
    }
  }'

When to skip the fade

Do not fade a clip that will loop. A black frame at the start and end of every loop is easy to see, and many short-form feeds replay clips automatically. For a loopable ending, leave the output fade at zero and use a hard cut back to the opening, or shape the end of the music with the bed fade only.

A fade to black is also a poor way to hide a clip that ran out. The docs say coverage can stop at most 0.5 seconds before the end of the spine, and a short source is padded or looped with a soft warning, so extend the slot or add another clip rather than fading over the gap.

Checking the result

Pull a still from the first and the last half-second of the output with video frames and check that they are near black. Then compare the render length with audio.duration_seconds: fades do not change it. The result's duration_seconds and billable_minutes show what was billed.

Arithmetic for the limits

The output fades must satisfy fade_in + fade_out <= output length. For a 10-second render, 5 plus 5 is the exact limit and is allowed; 5 plus 5.5 is refused. For the bed, the limit is the spine length, so a 10-second fade on a 6-second render is refused as well.

If you render the same program at several lengths, compute the fades from the length instead of hard-coding them, for instance a fade-out of min(2, length / 4) seconds. That keeps every variant inside the rules without a retry.

Fades and transitions together

The output fades and the per-slot transitions are separate controls and do not replace one another. A fade in on the output darkens the first frames of slot one, while a transition blends two slots in the middle of the program. If the first slot is only 1 second long, a 1-second fade in covers all of it, so check the opening still before you accept the render.

Pick fades by what the viewer needs: a half-second fade in is enough to avoid a hard first frame, and a one-second fade out marks the end of an ad. Longer fades near the 5-second limit suit a trailer or an intro, not a six-second clip.