Timeline fit: cover, contain, stretch or blur?

video[].fit on a Sume Timeline render has four values: cover (the default) fills the frame and crops the overflow, contain shows the whole clip and pads the rest with black, stretch scales to the frame and distorts the picture, and blur shows the whole clip over a blurred, enlarged copy of itself. It matters whenever a clip's aspect ratio differs from the output.

The value list is from the Sume docs page Timeline 1.0, read 2026-09-29. What each value does is stated in the render compiler source, packages/timeline-compiler/src/index.ts, as of that date; the docs page lists the names only.

What does each fit mode do?

The default output is 1080 by 1920, so a landscape clip is the usual case where you have to choose. Fit is set per clip, so one render can mix modes.

How does blur build the background?

The compiler splits the clip into two copies. One is scaled down by a factor of 8, cover-cropped, blurred with gblur at sigma 6 and scaled back up to the frame. The other is contained inside the frame, and the two are overlaid with the sharp copy centered. The comment in the source describes the point: a mismatched aspect ratio reads as depth instead of black bars.

Which mode should I pick?

Pick by what you can afford to lose. cover loses the edges of the picture, so a subject near an edge can be cut. contain and blur keep every pixel of the clip. stretch keeps everything but changes shapes, which shows on faces and circles. If the clip already matches the output shape, all four look the same.

Can I mix modes in one render?

Yes. fit sits on each entry of video[], so an intro that already matches the frame can use the default while a landscape interview clip in the same render uses blur. Stills are accepted in the same list and are held as static frames, so the same choice applies to a photo whose shape does not match the frame. Remember that the output size itself comes from output.width and output.height, which are even integers from 256 to 2160, and default to 1080 by 1920 when omitted.

What does a request with fit look like?

Add fit to the clip inside video[]. The rest of the request is unchanged from the Timeline docs example, and Idempotency-Key is required on the submit.

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: timeline-fit-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/wide.mp4",
        "start": 0,
        "duration": 8,
        "fit": "blur"
      }
    ]
  }'