Motion Principles

Motion Principles → the numbers before the call

timeline-edit-ops is how to write an animation onto a clip with edit_timeline. This is how to decide what to write. Every number here is in the units animate_clip takes: milliseconds, a normalized 0..1 distance, an easing string.

The same numbers, written as code

Building with @nodetool-ai/sandbox-timeline instead (motion-graphics picks the surface)? Every number below still applies — only the unit changes. durationMs becomes dur in seconds (divide by 1000: 400ms is dur: 0.4). A normalized 0..1 distance becomes actual px, against the frame's own width/height (0.3 on a 1920-wide frame is offsetX: 576 in from). Easing strings are identical — ease: "outExpo" or a raw curve — and every role still means the same thing: el.enter() is in, el.exit() is out, el.animate() covers emphasis and general keyframing, el.loop() is loop. el.count(), el.draw(), el.scramble(), el.typewriter(), el.expr() and el.morph() have no ops equivalent below; they are shortcuts for a ticker, a trimEnd draw-on, a scramble reveal, a whole-clip typewriter entrance, a hand-written keyframe function, and a path outline morph.

Settle three things before picking a number

A number chosen before the intent is a number you will change twice.

Three layers, or the frame reads flat

Plan three levels of attention. Track index controls their z-order, while timing decides which one the eye follows:

• Primary — the one move the eye follows. The clip the shot is about.
• Secondary — supporting motion reacting to the primary: a scrim settling late, a label arriving 80ms after the plate.
• Ambient — background life that never asks for attention. A loop preset at low amplitude on the bed.

motion-direction ranks the same three as Hero / Support / Texture and decides which elements earn each. Two clips carrying primary motion at once is the most common cause of a busy frame.

Easing is the biggest lever

linear reads as robotic. Keep it for motion that never lands: the loop presets float, rotate and hueShift, and the shake emphasis, whose zig-zag is linear by default. Everything the eye reads as an event decelerates into rest.

The role defaults already do the right thing: in gets easeOut, out gets easeIn. Leave easing unset unless you want something the default is not. A string the parser cannot read eases linearly and reports unknown_easing — easeOut, never ease-out.

Overshoot reads as toy-like. Keep easeOutBack, easeOutElastic and easeOutBounce off anything financial, medical or corporate.

Duration carries weight

Distance and area scale it. A caption travelling distance: 0.05 and a full-bleed plate travelling 0.5 must not share 400ms — the plate looks weightless. Add roughly 30–50% when the travel or the area doubles.

Two limits the engine enforces rather than warns about in prose:

• in + out must fit the clip with hold left over. A 3000ms title with 500ms each way holds 2000ms. Under about 1000ms of hold the element never settles and reads as a glitch. Over-long windows report animation_exceeds_clip.
• A loop cycle longer than the clip shows a fragment. kenBurns at its 3000ms default on a 2000ms clip is a drift that stops halfway.

Stagger is rhythm, and it is clamped

Never reveal a group in one event. On a text clip, stagger splits the animation per word, grapheme or wrapped line. Which unit counts what, and how the count changes with the frame, is in motion-graphics.

The span is durationMs + offsetMs × (units − 1), halved for from: "center". Work it out and compare it against the clip's durationMs minus delayMs. A span that does not fit is compressed silently: the engine shrinks the offset, never the per-unit duration, so the line lands flatter than written and only validate_timeline says so, as stagger_compressed.

For a group of separate clips — three lower-third parts, five icons — stagger by giving each clip's in animation a delayMs 60–80ms apart, and cap the whole reveal near 700ms. Past that the tail drags.

The 1/3 rule, in both forms

• Distance. Nothing travels more than about a third of the frame in one unbroken move. slide with distance above 0.35 reads as "the template moved". Break it with a scale or opacity change on the same window, or shorten the travel.
• Simultaneity. With three or more elements, keep at most a third in active motion at any instant. The rest hold, or run ambient loops.