Frame Composition

Frame Composition → staging on the timeline

Where things sit, how deep the frame is, and how the camera moves through it. motion-graphics is the build loop; timeline-edit-ops carries the op contract. This decides the coordinates you pass either.

Four coordinate spaces, and mixing them is the usual bug

Read width, height and fps off get_timeline before you compute anything. A layout authored against 1920×1080 and saved onto a 1080×1920 sequence is off by more than a crop.

Text is placed by containers

Building with @nodetool-ai/sandbox-timeline (see motion-graphics for when code is the right surface)? A container decides where its children sit — you almost never write x/y for text. s.stack(children, o) and s.row(children, o) build a real Yoga flex container and reparent children onto it as its real children — nest freely, a row of stacks or a stack holding a nested row both resolve correctly. A text child reflows to whatever width Yoga offers it, not a guessed line length.

The container's own placement in the frame is o.at ({x, y}, default the frame centre) plus o.anchor (default "center"): anchor names the point of the container's own computed box that lands at at — the name "left" puts that box's left edge at at.x, no measuring a sibling's width required. Named anchors: "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right", or pass {x, y} fractions directly. o.align (cross axis, default "start") and o.justify (main axis, unset) are the Yoga alignItems/justifyContent. A child's own flex sizing is o.flexItem on that child's own call (grow, width, alignSelf, …); absolute: true on a rect/ellipse (or any clip) takes it out of flow and resizes it to fill its flex parent's box exactly — how a plate sits behind a card's text with no pixel math.

Reach for explicit x/y only for decoration (a stray mark, a background shape) or a deliberate free placement that has nothing to do with reading order. Anything a viewer reads — a title, a kicker, a caption, a row of stats — goes in a container.

Title block — kicker, title, sub, stacked with a shared rhythm:

// fragment
const kicker = s.kicker("LAUNCHING TODAY");
const title = s.text("Round-ups", { size: 120, weight: 700 });
const sub = s.text("on every card", { size: 40 });
s.stack([kicker, title, sub], { gap: 20 });

Lockup — a mark beside its wordmark, one row:

// fragment
const mark = s.image(logoAssetId);
const wordmark = s.text("Northwind", { size: 64, weight: 700 });
s.row([mark, wordmark], { gap: 16, align: "center" });

Card — a padded column over an absolute plate:

// fragment
const plate = s.rect(1, 1, "#0c2a21", { r: 24, absolute: true });
const heading = s.text("Plan Pro", { size: 48, weight: 700 });
const price = s.text("$12/mo", { size: 32 });
s.stack([plate, heading, price], { gap: 8, padding: 24 });

List / grid — a row that wraps into a grid when it runs out of width:

// fragment
const chips = ["Round-ups", "Instant transfers", "No fees"].map((t) => s.pill(t));
s.row(chips, { gap: 12, wrap: true });

Grid

Twelve columns for landscape, six for vertical. For a 1920-wide frame with a 100px outer margin and a 24px gutter:

content = 1920 − 2×100 = 1720
column  = (1720 − 11×24) / 12 = 121.3px

Space everything in multiples of 8. fontSizePx for body copy sits near 2.5–4% of frame height; below 2.5% validate_timeline reports text_illegible. Choose the family, weights, and title scale from motion-direction § Typography before placing text on this grid.

One focal point

Place the subject on a thirds power point, not dead centre, unless the piece uses symmetry deliberately. The intersections:

Rank the eye's path by size, then contrast, then colour, then position. One primary per frame; everything else supports. Leave negative space around it — a frame filled edge to edge reads as cheap and gives the motion nowhere to go.

Depth: planes and track order

Split the picture into background, midground and foreground. Track index controls order between tracks: lowest index draws on top. Within one track, clips sort by transform.depthPx: farther values draw first and nearer, positive values draw later, in front. The same depth controls perspective under the sequence's camera2d. Moving a clip to another track changes its overlap order but not its camera distance.

For flat parallax, run three speeds over one window. One kenBurns per layer with zoom: 0 and a different drift is a fullClip preset, so all three cover the same span:

{"role": "loop", "preset": "kenBurns",
 "params": {"zoom": 0, "driftX": -0.02, "driftY": 0}}

Background −0.02, midground −0.06, foreground −0.12. One layer at one speed is not parallax, it is the template moving.

For a shared 2.5D move, give the layers distinct transform.depthPx values and keyframe the sequence's camera2d. Its absolute timeMs keyframes interpolate camera position and depth linearly. focusDepthPx and aperturePx control depth of field. Use one camera move to connect the planes, then inspect a middle frame for unwanted scale or blur. Set track indexes for overlap between tracks and clip depth for order within a track.

For a tilted card wall, parent the cards to a group with the wall's 2D rotation, rotationX, and perspective. Give each card its own depthPx and scroll curve, then use camera2d for the shared push and depth blur. This is a flat card projection: preview the wall at several frames to check that spacing, overlap, and blur read as one assembly.

For a move with a shape of its own, write a custom curve instead and mind the role: an in window holds its t=0 values before it and contributes nothing after, an out window holds its t=1 values after it, and a loop repeats its cycle — so a one-way travel that must stay where it landed is an out, and a loop curve has to return to the value it started on or it jumps every cycle.

Parent the assembly to a group when the layers must hold their relationship through a move: add_group, then animate the group. Children keep their own tracks, so grouping never changes what covers what. For a transition on the assembled picture, set transitionIn on the group. The children stay parented on their own tracks while the transition acts once on their precomposed surface.

Shape geometry is rasterized inside a frame-sized source surface before the clip is placed. Keep normalized shapeStyle geometry inside that surface, then move the clip or parent group with transform.position or custom offsetX/offsetY curves for scrolling walls and flying cards. Geometry authored outside the source surface clips before placement.