Timeline transition_not_frame_aligned: why a 0.01 s fade fails

What does transition_not_frame_aligned mean?

A Timeline fade has to be a whole number of frames. Sume rounds seconds x fps to the nearest frame. If that gives less than one frame, there is nothing to round to except a hard cut, so the request is refused with transition_not_frame_aligned at the path video[i].transition.duration. Snapping a tiny fade to zero would quietly delete a transition you asked for, which the compiler's own comment names as the reason for failing instead.

Which durations fail?

The check is round(seconds x fps) below 1, so anything under half a frame fails.

What if I leave output.fps out?

When output.fps is omitted, a render takes its rate from the probed sources, but checks that run before the sources are known hold at the slowest allowed rate, 24 fps. So a fade of 0.03 seconds or more passes at plan time on every allowed rate; one near 0.02 seconds is risky. Pick fades of at least 0.1 second for anything a viewer should see.

The allowed rates are 24, 25, 30 and 60. The unbilled plan call runs the same compile, so check a spec there first.

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/artf_demo/voice.wav","duration_seconds":10},
       "output":{"width":720,"height":1280,"fps":25},
       "video":[
         {"source_url":"https://media.sume.com/artifacts/artf_demo/a.mp4","start":0,"duration":5},
         {"source_url":"https://media.sume.com/artifacts/artf_demo/b.mp4","start":5,"duration":5,
          "transition":{"type":"fade","duration":0.01}}]}'
# 0.01 s x 25 fps = 0.25 frames -> transition_not_frame_aligned

What is the fix?

Raise the duration to at least one frame, or remove the transition and take the hard cut. The first slot cannot carry a transition at all; see no transition on the first slot. Fades up to 1 second are allowed, and no more than half of the shorter neighbor.