<!-- kernel -->
> Creatomate AI reference — topic page "Duration & timing rules"; the index of all pages is https://creatomate.com/llms.txt
<!-- /kernel -->

### Duration & timing rules

The number-one source of broken renders. The engine resolves every element's start and length like this:

**`duration` values:** `null` (or `"auto"`) = auto-fill; a number = seconds; `"media"` = the file's length ÷ speed (video/audio only); `"x %"` = share of the parent composition; `"x fr"` = fractional share of the track (transition overlaps accounted). Defaults: video/audio → `"media"`; everything else → `null`.

**`time` values:** a number = seconds from the composition start; `"x %"`; `"end"` = stick to the composition's end; `null` = auto (sequence after the previous element on the same track).

1. A composition takes its length from its children with resolvable durations (`"media"`, fixed numbers). Children with `null` duration then stretch to that length. This cascades through nesting, root included.
2. A fixed `duration` on a composition wins: `null`-duration children stretch to it and `fr` children divide it. It does **NOT** clip children with explicit durations (a number or `"media"`) — audio in particular plays on past the composition's end. Bind music to its scene with `duration: null` (+ `"loop": true` in case the scene outgrows the file); keep `"media"` only when the audio should drive the scene's length.
3. An element followed by another on the same track is capped at the follower's start.
4. **If nothing is resolvable, the composition falls back to 5 seconds.** "My video is 5 seconds for no reason" = no duration driver anywhere. Give one element a real duration: a voiceover (`"media"`), a fixed composition duration, or a fixed element duration.
5. **Loop or freeze:** a non-looping video/audio never plays past its file length. A `null`-duration background video must have `"loop": true`. Note: trimming is ignored while looping — use `loop` or `trim_*`, not both.
6. **Same composition = linkage; visual alignment across tracks is NOT linkage.** Parallel tracks sequence independently and drift apart, especially with dynamic media of varying lengths. Elements that must start and end together belong in ONE composition; compositions sequence on track 1. Editor paths: select elements → right-click → **Group**; right-click an element → **Auto Arrange** → Start: Auto / Duration: Auto / Duration: Media / Duration: Loop. Timeline bars label their duration mode ("Media"/"Auto") on the right edge.
7. Voiceover-driven scenes: the voiceover keeps `duration: "media"`, visuals get `duration: null` and stretch to match. Music beds: `duration: null` + `"loop": true` on a root-level track follows the whole video (loop covers files shorter than the video).

**More timing facts:**

- `"track": null` gives an element its own new track after the numbered ones, so it plays in parallel from its `time`; it never sequences.
- `"x fr"` divides the composition's **whole** duration among the fr elements on that track; fixed-duration siblings on the same track are not subtracted, so a fixed open plus fr features plus a fixed close overflow by exactly open + close — keep a track either fr or fixed. An fr duration needs a composition whose length is known without it. On a composition that takes its length from a `duration: null` media child, an fr element cannot resolve and the whole composition falls back to 5 s (render-checked: a 3 s clip with a `1 fr` element beside it, shape or composition, at the root or nested, renders 5 s; the same with the clip's `duration` set to 3 renders 3 s). Give the media a `duration` of `"media"` (its own length, so a clip that varies per render still drives the video) or a number, or give the composition a fixed `duration`, and fr resolves against it.
- An element timed outside the output duration is silently never shown, and validation does not flag it. `snapshot_time` must lie inside the duration; elements with no duration driver end at the 5 s fallback, so a later snapshot renders blank.
- A transition's overlap is subtracted from the track (a crossfaded sequence runs one overlap shorter per transition); hard cuts do not shorten it.
