Timeline & Timing

Shot length is computed automatically. See Core Concepts → The Timeline Model for the full mental model; this page is the practical cheat sheet.

The rules in one table

You write	Resulting frame_end
actions only (idle/say/walk)	the longest actor's length
+ shot.clip(s), s < natural	capped to s
+ shot.clip(s), s > natural	unchanged (clip is a ceiling)
set_frame(n) then an action	that action starts at frame n

with bare_scene as shot:
    a.actor.perform("idle")     # natural length
    a.set_frame(150)            # jump the cursor
    a.actor.perform("waving")   # starts at 150
    shot.clip(8.0)              # hard cap at 8 s

Verified behaviour

These rules were checked directly (calibrating the native idle length, then deriving expected frame counts):

Natural end = longest actor          ✅
clip() caps below natural            ✅
clip() above natural is a no-op      ✅
set_frame sequencing                 ✅

duration is ignored for in-place actions

perform("idle", duration=20) does not produce a 20-frame clip — the strip plays its full native length. Use shot.clip() to bound a shot. (Known issue — see Known Issues.)