Motion composer
Motion is a reading aid. Every entrance, transition and stagger either helps the viewer parse the frame faster or gets in the way. This skill is about choosing which.
The timing model you are working inside
PulseFrame does not render scenes back to back with gaps. Each scene has a render window
that begins leadIn frames before its declared startFrame and ends outFrames after its
declared end. Windows overlap exactly across a transition, and the incoming scene is painted
beneath the outgoing one so a slide or wipe reveals rather than flashes.
Consequences you must design around:
- There is never a blank frame between scenes. If you want black, that is
dip-to-color, chosen deliberately. outFramesis derived from the transition type and the style'sexitDurationFrames, clamped to one third of the scene's duration. A 40-frame scene cannot have a 30-frame transition out of it.- Because windows overlap, the outgoing scene's text is still visible for
outFramesafter its declared end. Do not put a hardcuton the next scene and expect the old text to vanish instantly — it will not, unless the transition iscutwith zero duration.
Pacing
creative.pacing ∈ calm | measured | brisk | rapid. It is the single dial that
expresses intent; the style pack's motion block supplies the actual numbers.
| Pacing | Entry frames | Stagger | Scene floor | Reads as |
|---|---|---|---|---|
calm | 18–24 | 6–8 | 90 frames | Considered, documentary |
measured | 12–16 | 4 | 60 frames | Default, most explainers |
brisk | 8–12 | 2–3 | 45 frames | Social-native |
rapid | 6–8 | 1–2 | 36 frames | Montage, high density |
Mismatch is the most common motion defect: a calm pacing with rapid entry durations
produces scenes that snap in and then sit still, which reads as broken rather than as calm.
Transitions
Pick from the style pack's motion.transitionVocabulary. If the transition you want is not
in the list, either change the pack or pick a different transition — do not add to the
vocabulary to solve one scene.
| Transition | Cost | Use for |
|---|---|---|
cut | 0 frames | Default. Continuation, no time change. |
fade | ~14 frames | Change of time, place or register. |
slide | ~16 frames | Extension; the next scene continues this one. |
wipe | ~18 frames | Adjacent comparison; A gives way to B. |
dip-to-color | ~24 frames | Chapter break. Once per video, maximum. |
zoom | ~14 frames | Emphasis into a detail. |
Rules:
- Two consecutive non-
cuttransitions is the ceiling. slidein the same direction twice in a row reads as a stuck carousel.dip-to-colortwice in a 30-second video is a slideshow, not a chapter structure.- Never use a transition to cover a bad cut. If two scenes do not flow, the storyboard is wrong; a wipe will not fix it.
Element motion
MOTION_PRESETS and what each is actually for:
fade— the safe default. Works on every background.slide-up— content arriving from below; implies continuation or addition.slide-left— content moving through; implies sequence.scale-in— emphasis; the element claims the frame. Use on one element per scene.reveal— a clip-path wipe. Good for a rule or an accent bar, wrong for a paragraph.stagger— the container spreads its children byelementStaggerFrames. Only meaningful on a group.none— deliberately present from frame 0. Correct for a persistent background or a scene where motion would distract from the voice.
delayFrames sequences elements. A working pattern: headline at 0, subheadline at
elementStaggerFrames, accent rule at 2 × stagger, body at 3 × stagger. Total entry
completes inside entryDurationFrames + 3 × stagger, which must be under ~25% of the scene
duration or the viewer is watching an animation rather than reading.
Readability arithmetic
Before finalising a scene, check it can actually be read:
readable_frames ≈ 0.6 × characters_in_primary_text
available_frames = durationFrames − entryDurationFrames − stagger_total
If available_frames < readable_frames, either shorten the text or lengthen the scene. At
30fps a 60-character headline needs ~36 frames of hold. This is the calculation that
separates a scene that feels rushed from one that feels right, and it is cheap to run.
Subtitles interact with motion
If creative.burnedInSubtitles is true, the renderer reserves vertical space for the caption
track and shrinks the content box to match. That means:
- Content placed in the bottom 20% of the frame is not where you put it — it is above the caption reserve.
- A
lower-thirdscene and a two-line caption stack. Check the result at a real frame; do not assume the layout holds. - Long captions with
subtitles.maxLines: 3reserve more space thanmaxLines: 2, and a three-line reserve can push a tall image out of frame.
Verifying motion without watching the video
Render stills at the frames that matter and look at them:
pulseframe render <project> --still --frame 0 -o out/f00.png
pulseframe render <project> --still --frame 60 -o out/f60.png
pulseframe render <project> --still --frame 140 -o out/f140.png
Choose frames at: a scene's first frame, the midpoint of a transition, and the last frame before a transition starts. A transition that looks fine in the middle can still leave the outgoing text half-visible on the incoming scene's background — that only shows at the boundary frames.
What not to do
- Do not animate everything. Motion on every element at every scene change is noise; the eye stops tracking entrances and the video becomes exhausting.
- Do not use
scale-inon more than one element per scene. - Do not set
delayFramesbeyond a scene's entry budget; the element will appear mid-scene with no context. - Do not tune motion in the plan to compensate for a style pack you have not looked at. Read
motionin the pack first.