Motion Direction → the rules everything else obeys

Direction is the judgment layer above craft. It turns a brief into a short set of motion rules, so every shot reads as one hand. Most of the work is subtraction: deciding what does not move.

motion-principles gives the numbers. This decides which numbers the whole piece is allowed to use.

The one rule

Lock the motion language first, then animate to it. Pick one of each row below and reuse it. Consistency reads as confidence; variety reads as noise. When in doubt, repeat rather than invent.

The motion-language spec

Fill every row once, at the top of the job, and state it back to the user before you animate. The rows guide the timeline document; motion-graphics owns the tool calls.

Two easings maximum: one for entrances and landings, one for exits. A third has to justify itself.

Match depth to the brief

For a showcase, hero, launch, or "best" piece, plan each scene with a background bed, midground, foreground, and a grain or grade finish. Group each scene. Use path shapes, masks, repeaters, style tracks, animation links, and effects where they give the composition depth. Read the full document with get_timeline and use set_timeline_document for fields edit_timeline cannot write, including styleTracks and repeater.

Study prism.mjs, kite.mjs, voltra.mjs, and tidewater.mjs in scripts/example-timelines/, or their shipped .timeline.json bundles in packages/base-nodes/nodetool/examples/timelines/. In the app, install a copy from Examples → Timelines, then inspect it with get_timeline. get_example_workflow loads workflow graphs, not these timelines. Budget for a generated still or music bed in a showcase unless the user sets a cost limit.

Typography

Choose the family and weights in the motion-language spec before building text clips. NodeTool ships Inter, Space Grotesk, Bebas Neue, Playfair Display, Lora, and JetBrains Mono. Use one family across a piece and make the hero visibly heavier than support, such as Inter 800 against 400. Bebas Neue ships only at 400, so use size and spacing for contrast if you choose it.

On a 1920×1080 frame, start a hero title at 96–160 fontSizePx, support at 42–64, and a short kicker at 28–36. Keep large display tracking tight (letterSpacingPx −2 to 1); open an uppercase kicker to 2–5px. Check the actual words at the target frame size and adjust for fit and legibility.

For an existing text clip, edit_timeline can set the type as a set_clip_params patch:

{"timeline_id":"<id>","ops":[{"op":"set_clip_params","target":"Hero title","textStyle":{"fontFamily":"Inter","fontWeight":800,"letterSpacingPx":-1,"fontSizePx":128}}]}

motion-graphics owns the full tool contract. frame-composition handles placement and safe areas for each aspect ratio.

Tone and energy

Place the piece on two axes and commit. Mixing cells inside one piece is the usual cause of "inconsistent".

Motion personality

The named preset that fills the spec's easing, timing and intensity rows. Pick one per project and hand it to every later step by name.

Premium sits calm-soft, Corporate calm-sharp, Playful kinetic-soft, Energetic kinetic-sharp. Default to Corporate for product and Playful for lifestyle. easeOutElastic and easeOutBounce belong to Playful alone.

Motion hierarchy

Rank every element, animate down the list, and stop early.

These are the three layers motion-principles names Primary, Secondary and Ambient. If two elements compete for the eye in one frame, the direction failed: demote one before touching its keyframes.

Hierarchy is also a track decision. Lowest track index renders on top, so the hero belongs on a low index and the bed on a high one; a scrim sits between the picture it darkens and the text it carries. For a camera move, set clip transform.depthPx separately from track order. The sequence's camera2d can keyframe position and depth while focusDepthPx and aperturePx decide which plane softens. Keep one plane legible while the others move.

Use layout relations for elements whose spacing should survive a text or shape change: a row or stack holds ordered child IDs, a relative clip follows a target box, and fitText sizes a plate from live text. Use animationLinks when one clip should follow another's authored position, scale, rotation, or opacity. Linked followers share one motion decision; they do not chain through a second link.

Restraint

For every element ask whether the motion carries meaning. If not, hold it still.

• Do not animate the whole frame at once. Leave the eye an anchor.
• Do not stack a transition on a transition — a wipe cut under a spin in under a flash is three ideas competing for 500ms.
• Do not loop-animate text somebody is still reading.
• Do not give overshoot to serious content.
• One outsized moment per piece. A second cancels the first.
• A clip that both dissolves in and carries a fade in ramps twice and reads slower than either alone. Pick one.

Pacing

Map energy across the whole timeline before timing any single move: a low open, a build, one peak, a settled end. Vary it on purpose — tension, then release. Stillness is pacing, not a gap. beat-sync-editing turns this shape into cut points.

An animation's beat anchor follows the document tempo: one-based index, scope: "clip" or "sequence", and optional offsetMs. A measured audio curve from bake_audio_animation follows the audio source instead. Use the former for a rhythmic rule and the latter when a real onset or envelope must drive the picture. stagger_animations offsets existing animations across an ordered list of clip IDs while leaving media timing fixed.

Choose motion texture deliberately. repeater makes positioned, delayed copies of one clip; temporalEcho trails it with fading delayed copies; steppedTime quantizes its clock. Per-clip motionBlur controls its own shutter angle and minimum sample count. When layers request different counts, the scene uses the highest count up to 32 and samples each layer evenly across its own shutter. Give blur to the fast hero when it clarifies direction, then inspect the held frame for readability.

Direction notes, per shot

Write intent, not keyframes. One line per shot is enough for someone else — or a later turn — to animate it:

Shot 3, 4s. Hero: the price plate, pop in on the downbeat, Corporate. Support: the caption 80ms behind it, fade. Texture: bed holds kenBurns from shot 2. Nothing else moves.

For a repeated title or logo system, inspect list_compositions before building bare clips. title-slam, word-cards, and logo-sting are starting rigs when their timing matches the brief. motion-graphics owns the tool contract. set_clip_params does not accept the new camera, layout, link, repeat, echo, step, or per-clip blur fields; author those through the full document with set_timeline_document after reading it with get_timeline.

The consistency audit

Before calling a pass done, read the document back with get_timeline and check every clip against the spec. A miss is a direction defect, not a preference.

• Same easing family on comparable moves, and no stray linear outside loops.
• Every durationMs a multiple of the base unit.
• Only the chosen transition types on the cut.
• One text stagger rhythm, and one offset_ms order for cross-clip builds.
• Hold discipline respected: no two moves stacked with no rest between them.
• Exactly one hero animating at any instant.
• One font family, and it is a bundled one — Inter, Space Grotesk, Bebas Neue, Playfair Display, Lora, JetBrains Mono. Anything else reports font_not_portable and resolves differently per host.

Then look: preview_timeline_frame over the midpoints of the moves you just audited. An audit that only read the document has checked the spec, not the picture.