Timeline Edit Ops

Timeline edit ops → the edit_timeline reference

This is the op-by-op contract for changing a timeline document that already exists. motion-graphics owns the build loop and picks the surface: a new cut goes through the @nodetool-ai/sandbox-timeline pack, which handles tracks, groups, layout and most of what follows here for you. Reach for this skill once that document exists and needs a few changes.

Ops are the right tool when the timeline has no authoring code (code.get answers code: null), or for a deliberate hand tweak on one that does. On a code-backed timeline, an op inside a scene the code tracks marks that scene "edited": the next code.set/code.edit/code.rebake (api-timelines) keeps your edit and reports it in conflicts rather than overwriting it, unless force says otherwise.

Read before you edit

Call get_timeline first. You need the sequence's fps, width, height, the track list with each track's index and type, and every clip's startMs, durationMs, mediaType and existing animations. Edit nothing until you have clip ids from the document — never a guessed one.

Snapshot with create_timeline_version before your first edit. Motion work is iterative and a wrong mode: "replace" wipes animations somebody wrote.

edit_timeline takes a timeline ID and an ops array, run in order, up to 60 per call. Inspect each op's ok and the batch's failed result before a dependent edit. In an in-product agent, use the matching ui_timeline_* tool for an individual op:

{"timeline_id":"<id>","ops":[{"op":"animate_clip","target":"Title","animations":[{"role":"in","preset":"fade","durationMs":400}]}]}

The animate_clip input accepts catalog presets or custom curves and code, plus stagger and a typewriter caret. It does not author styleTracks, textAnimator, or beat. set_clip_params does not author layout, repeater, motionBlur, steppedTime, temporalEcho, animationLinks, or transform.depthPx. Adding those keys to an op does not write those features. For those fields, read get_timeline's timeline object, change the needed clip or sequence fields, and call set_timeline_document with a complete document assembled from it. Preserve tracks, clips, markers, tempo, setup, templateId, mediaTracks, transcript, scriptEnabled, and camera2d when present. Include timeline.updatedAt as expected_updated_at so a concurrent edit is refused. A whole-document write validates the result and snapshots the prior version. Omitted document fields are removed, so never send only the changed clip. The JSON objects in the document sections below are fields to merge into that complete document, not edit_timeline ops. The editor may lack controls for them even though they render and survive a save.

Track layering

Lowest index renders on top. Track 0 covers track 1, which covers track 2 — Premiere, Resolve and FCP order, and the opposite of a paint stack. The compositor turns the index into z = 1000 - index; preview_timeline_frame reports that z_index per layer and lists layers top of the stack first.

Four track types, and the type is a role, not a restriction on what draws:

Rules that follow from the ordering:

• A scrim goes on a higher index than the text it sits behind, and a lower index than the picture it darkens — so picture, then scrim, then text, in descending index order.
• Give each motion element its own overlay track when their timings overlap. Two animated clips on one track that overlap in time trigger an automatic crossfade you did not ask for (see Transitions).
• Captions are the exception you do not control: word-level captions from a voiceover clip composite above every real track regardless of which track that clip sits on. Do not build a title that expects to cover them.
• An audio clip never contributes a layer. A frame that looks empty because everything is on audio tracks is a track-type mistake.
• At most 8 video layers composite at once, resolved top track first. Text, shape and image clips are not counted, so a stack of titles is unaffected — but nine overlapping video clips means the bottom one silently does not draw. A preview frame is how you find that out.

Build the elements

The clips you animate are made with the same edit_timeline op list.

[
  {"op":"add_text_clip","text":"Maya Chen","trackId":"<overlay>","startMs":4000,"durationMs":3000,"fontSizePx":64},
  {"op":"add_shape_clip","shape":{"kind":"rect","x":0,"y":0.72,"width":1,"height":0.18,"fill":"#000000"},"startMs":4000,"durationMs":3000,"opacity":0.55}
]

add_text_clip needs only text; the style fields (fontSizePx, color, background, stroke) are read from the op itself or from a style bag, and with no trackId it lands on an overlay track. add_shape_clip takes its geometry in shape (or shapeStyle, or the op's own keys) with x, y, width and height as 0..1 fractions of the frame — no geometry at all is a full-frame rect, which is the scrim you usually want.

Tracks are the z-order, so how they are made matters:

[
  {"op":"add_track","type":"overlay","name":"Titles"},
  {"op":"move_track","target":"Picture","toIndex":2}
]

add_track takes type (video, audio, overlay, subtitle) and an optional name, and appends to the bottom — the highest index, which draws last. A picture track added after the overlays therefore covers them. Add the overlays last, or move the picture down afterwards: move_track takes a target and one of toIndex (0 is the top), before or after.

Animating a clip

edit_timeline with {"op": "animate_clip", "target": <clip id or name>, "animations": [...]}. Each animation is {role, preset, durationMs?, delayMs?, easing?, params?}. mode is "replace" (default) or "add".

Four roles. A clip may carry several, one of each kind or more:

• in — entrance. delayMs offsets from the clip's start.
• out — exit. delayMs offsets backwards from the clip's end, so 0 means it finishes exactly as the clip ends. This is the one people get wrong.
• emphasis — a beat mid-clip. delayMs from the clip's start.
• loop — runs continuously; durationMs is one cycle, not the total.

The presets

in / out — fade (500ms), slide (500ms; direction left/right/up/down, distance 0–1 of the frame, default 0.3), pop (500ms, easeOut; overshoot 1–1.5, default 1.08), spin (500ms; turns 0–2, default 0.25), wipe (500ms; direction, softness 0–0.5, default 0.05), blur (500ms; amount 0–40, default 12), colorFade (600ms, grayscale blooming into color).

in on text only — typewriter reveals whole characters in reading order. Set durationMs to the time for the entire text to appear. Without it, the characters type 65ms apart and finish within the clip. To set a fixed speed, use durationMs: 1 with stagger: {unit: "character", offsetMs: 40}. animate_clip stores every typewriter in that form. A document you write by hand must use it too: a stored plain durationMs with no stagger shows the whole text at once, with no caret.

emphasis — pulse (600ms; intensity 0–0.5, default 0.06), flash (400ms; intensity 0–1, default 0.6), shake (600ms; seeded noise on both axes: intensity 0–0.2 default 0.02, frequency Hz default 8, seed default 1, fadeInMs/fadeOutMs default 0; the same seed repeats the same motion), bounce (600ms; height 0–0.3, default 0.05), squash (500ms, easeOutBack; amount 0–0.5, default 0.12), followPath (also loop; d an SVG path in 0..1 space plus pathX/pathY/pathWidth/pathHeight, orient turns the clip along the tangent, startT/endT pick a stretch of the path; writes positionX/positionY, so it replaces the clip's position).

loop — kenBurns (3000ms; zoom 0–1 default 0.12, direction in/out, driftX/driftY −0.2–0.2), float (3000ms; amplitude 0–0.2, frequency cycles per period default 1, seed 0 = pure sine, else drift), breathe (3000ms; intensity 0–0.3), rotate (3000ms; direction cw/ccw), hueShift (3000ms; direction forward/reverse), orbit (3000ms; degrees default 360, direction cw/ccw) — which sweeps a 3D clip's camera and does nothing on any other clip.

Named easing includes linear, easeIn, easeOut, easeInOut, easeOutBack, easeOutElastic, easeOutBounce, exponential, quintic, and circular variants (easeOutExpo, easeInOutQuint, easeOutCirc), and hold for a segment that keeps its prior keyframe value until the segment ends. Unset means the preset's own default, and failing that the role's — in gets easeOut, out gets easeIn. That default is almost always right: an entrance decelerates into place, an exit accelerates away. Reach for easeOutBack or easeOutElastic only when the piece is playful; they read as cheap on anything corporate.

{"op": "list_animation_presets"} reports the exact param list when this summary is not enough — the catalog is the authority. It is an edit_timeline op like every other call here, not a tool of its own.

Keyframes and the easing grammar

easing takes more than the seven named ids. cubic-bezier(x1,y1,x2,y2) is the CSS curve: cubic-bezier(0.16,1,0.3,1) is the deceleration most entrances want. spring(stiffness,damping,mass) solves a real spring, so spring(180,12,1) settles with one small overshoot and spring(180,26,1) does not overshoot at all. All three constants must be positive. Anything the parser cannot read eases linearly and reports unknown_easing.

The presets are where motion starts, not where it stops. A custom animation is one extra field and it reaches shapes no preset has: an entrance that overshoots twice, a hold in the middle of a move, two channels on different schedules, a decay, an arc, a path draw-on. Reach for one as soon as a preset is close but not right — bending durationMs and easing around a preset that was never the shape you wanted takes longer and lands flatter. motion-curves carries the channel table and the worked recipes. Then {"role": "in", "preset": "custom", ...} carrying exactly one of

• curves — [{property, keyframes: [{t, value, easing?}]}], with t running 0..1 across the animation's window. The list_animation_presets op reports the animatable properties.
• code — a JavaScript body baked into curves once, host-side, at author time. Nothing evaluates at render.

Add mask when a curve drives wipeProgress; without it the wipe has no edge to run against.

Motion that has to follow a piece of audio is a different call: bake_audio_animation measures an audio clip and writes the curve onto a target clip through the set_baked_animation op, either following the loudness (mode: "envelope") or pulsing on each onset (mode: "beats"). Its keyframes sit in the target clip's own media, so trimming or splitting that clip re-slices the motion, and the animation carries bakedFrom — running it again with different settings replaces that curve instead of stacking a second one, and never touches a curve you keyframed by hand. set_markers_from_beats is the other tool: markers to cut against, rather than motion to animate with.

How several animations on one channel combine decides whether the second one adds to the first or throws it away:

The replace row is the trap. Two animations driving positionX over the same instants means one of them does nothing, and validate_timeline reports replace_curves_overlap. Move a clip with offsetX when you want it to compose with other motion, and with positionX only when you mean an absolute placement nothing else touches.

Durations the contract constrains

motion-principles holds the numbers — how long an entrance runs, how long a title holds. What this contract adds is what the document refuses:

• in + out together must fit inside the clip. A window that does not fit after its delayMs is clamped or never runs, and validate_timeline says so as animation_exceeds_clip.
• A loop on a clip shorter than one cycle shows a fragment of the motion. kenBurns at its 3000ms default on a 2000ms clip is a slow drift that stops halfway, not a Ken Burns move.

Choosing motion that matches the cut

Pick the entrance from the edit, not from variety. A title over a locked-off shot can slide; a title over a whip pan or a moving camera should fade or blur, because sliding text plus moving picture reads as two unrelated motions. Match the direction to the picture: text sliding against the camera move fights it.

One motion idea per moment. A clip with pop in, shake emphasis and spin out is not three times as expressive.

Animating typography

Text clips take every preset above, and one thing media clips do not: per-word stagger. Add stagger to an animation on a text clip:

{"op": "animate_clip", "target": "Title", "animations": [
  {"role": "in", "preset": "pop", "durationMs": 400,
   "stagger": {"unit": "word", "offsetMs": 80, "from": "start"}}
]}

Each unit runs the full animation for durationMs, offset offsetMs from the previous. from picks which unit leads: start (default), end, or center. A stagger needs at least two units — below that it compiles as an ordinary block animation.

unit is one of three, and the count is what the span math is built on:

The span is durationMs + offsetMs × (units − 1), halved for from: "center" (the middle unit leads and both edges run last, so the largest delay is half the span). Six words at offsetMs: 200 with a 500ms preset span 1500ms. The same line at unit: "character" is roughly thirty units, so the same offset spans six seconds — character staggers want offsets an order of magnitude smaller than word staggers, and a line stagger changes count when the frame does.

A span that does not fit the clip is silently compressed, not cut off. The engine shrinks the per-step offset — never the per-word duration — so the last word still completes inside the clip. Ask for 200ms of offset on a clip with room for 60ms and you get 60ms: every word still animates, the motion is simply tighter and more simultaneous than you wrote. validate_timeline reports stagger_compressed. This is the most common reason staggered type "doesn't look staggered". Work out the span, compare it against durationMs minus any delayMs, and if it does not fit, lengthen the clip or lower the offset yourself rather than letting the clamp choose for you.

loop staggers are the exception: the offset is a phase shift, so it is neither stretched nor clamped.

Which offset reads as texture and which reads as one word at a time is in motion-principles, with the line-length limit that goes with it.

For several separate clips, stagger_animations shifts existing animation delays in the order of clip_ids without moving the clips. Give at least two distinct clip IDs, each already animated, and a non-negative offset_ms. The in-product tool is ui_timeline_stagger_animations with the same fields.

{"op":"stagger_animations","clip_ids":["logo-id","title-id","tagline-id"],"offset_ms":80}

Stagger applies only to text clips and only to transform and opacity motion. wipe, blur and colorFade stay block-level even with a stagger set — the mask and effect curves are per-layer, not per-word. A stagger on a media clip is ignored, not an error, so a "why isn't it staggering" bug is usually a clip that is not mediaType: "text".

Type sizes are authored against the sequence resolution: fontSizePx on a 1920×1080 sequence means the same thing at any preview width.

Document motion fields

The fields below belong to clips in the complete timeline document. Merge them into the clip read by get_timeline, retaining its other fields and animations, then write the full document with set_timeline_document. edit_timeline and ui_timeline_animate_clip do not accept them as animation inputs.

styleTracks animate visual properties in the same animation window as a preset. Each stored animation needs id, role, preset, and durationMs. Targets include text.color, shape.fill, shape.cornerRadius, clip.borderRadius, mask.featherPx, effect.<effect-id>.<numeric-field>, supported effect colors such as effect.bg-field.colorB, gradient stops, and compatible shape.d or mask.d paths. The clip must already have the targeted style, mask, or effect. A per-glyph target such as glyph.color also needs text stagger.

{"animations":[{"id":"title-color","role":"in","preset":"fade","durationMs":600,"styleTracks":[{"target":"text.color","keyframes":[{"t":0,"value":"#8bd5ff"},{"t":1,"value":"#ffffff","easing":"easeOutExpo"}]}]}]}

textAnimator changes text content over its animation window. ticker supports from, to, decimals, padTo, prefix, and suffix. Set groupSeparator to "," for grouped thousands such as 2,847; without it the output stays ungrouped. scramble supports charset and deterministic seed. It needs a text clip. An animation's beat binds its start to a one-based beat index at the live sequence tempo; scope is clip or sequence, and offsetMs moves it around that beat. delayMs still applies on top.

{"id":"count-up","role":"emphasis","preset":"custom","durationMs":900,"beat":{"index":3,"scope":"sequence","offsetMs":-20},"textAnimator":{"kind":"ticker","from":1,"to":7,"padTo":2}}

animationLinks copy a source clip's authored positionX, positionY, scale, rotation, or opacity channel, with optional time offset, loop, scale, and offset. A wiggle link supplies seeded motion without a render-time script. Links do not follow the source's own links. Resolve each sourceClipId against the document's clip IDs before writing it. An opacity link replaces the target clip's own opacity while its group and transition coverage still multiply the result.

{"animationLinks":[{"target":"positionX","sourceClipId":"leader-id","source":"positionX","scale":0.35},{"target":"rotation","kind":"wiggle","amplitude":0.025,"frequencyHz":1.4,"seed":8}]}

layout turns a group clip into a flex container for its real children (their parentId names the group): flexDirection: "row" | "column", gap, justifyContent, alignItems, padding. A child's own sizing is flexItem (grow, width, position: "absolute" + inset to fill the container). repeater.count includes the original clip and is capped at 128. timeStepMs offsets each copy in time. These are fields on a clip, not new clip records to add by hand.

Do not scroll a still plate by tiling it with a repeater. Each copy meets the next at a seam, and the seam shows when the image differs at its edges. A generated rain plate is denser at the top, so it always does. To make rain fall, move one plate to a random offset on hold keyframes every two frames. This reads as falling rain and has no seam.

{"layout":{"display":"flex","flexDirection":"row","gap":24},"repeater":{"count":3,"positionStep":{"x":180,"y":0},"timeStepMs":67}}

(logo-id/wordmark-id are separate clips with parentId naming this group.)

camera2d is a sequence document field. It needs position, depthPx, and positive focalLengthPx. Keyframes use absolute timeMs and include position and depth. Add depthPx to a clip's existing transform for perspective; focusDepthPx and aperturePx add depth-of-field blur. camera2d: null clears the camera.

For a tilted wall of cards, use a parent group's rotation, rotationX, and perspective for the shared tilt, each card's depthPx and scroll animation for the separate planes, and camera2d for the push and depth blur. Keep a shape's normalized geometry inside the frame-sized source raster. Move the clip or group with transform.position or custom offsetX/offsetY curves to scroll or fly it across the frame; geometry outside that raster is clipped before the transform places it.

{"camera2d":{"position":{"x":0,"y":0},"depthPx":0,"focalLengthPx":1400,"keyframes":[{"timeMs":0,"position":{"x":0,"y":0},"depthPx":0},{"timeMs":1200,"position":{"x":90,"y":-20},"depthPx":120}]}}

motionBlur is per clip: samplesPerFrame is 1–32 and shutterAngle is 0–360 degrees. One sample disables blur for that clip. A higher count sets a minimum; the scene renders at its highest requested count, with evenly weighted samples across each layer's own shutter window. steppedTime.fps quantizes a clip's source and animation clock. temporalEcho adds delayed copies through copies, intervalMs, and opacityDecay.

{"motionBlur":{"samplesPerFrame":8,"shutterAngle":180},"steppedTime":{"fps":12},"temporalEcho":{"copies":3,"intervalMs":80,"opacityDecay":0.5}}

Groups

{"op":"add_group","name":"Lower third","startMs":4000,"durationMs":4000,"children":["name-id","role-id"]} makes a clip with no media whose transform, opacity and window every clip naming it inherits. {"op": "set_parent", "target": "Name plate", "parentId": "<group id>"} adopts a clip that already exists; "parentId": null releases it, and a cycle is refused.

Rig a lower third this way: scrim, name, role, each on its own overlay track, all three parented to one group. Then animate the group. One slide in and one fade out on the group moves the assembly together and keeps the parts locked to each other, where animating them separately is three chances to drift.

Children keep their own tracks, so grouping does not change what covers what. A plain group's opacity multiplies into each child. A group with an effect, non-normal blend mode, or transition precomposes its children into one surface first. The effect or transition then runs once on the assembled picture. Put a glow on the group for the whole look, on a child for that child alone.

parent_missing, parent_not_group and parent_cycle all mean the child renders unparented, losing the group's transform, opacity and window.

Transitions

A transition is between clips, not on one clip. It is authored on the incoming clip and resolved for both: the compositor finds the clip beneath it on the same track and gives that one the complementary half of the cut. The incoming clip may be a group: set_transition on the group transitions its whole precomposed assembly, with children still parented on their own tracks. Its outgoing partner is the previous overlapping sibling on the group's track under the same parent.

Two clips on the same track whose times overlap dissolve across the overlap with no tool call at all. The corollary: an accidental overlap is an accidental dissolve. When two clips look soft where you wanted a hard cut, check their startMs and durationMs before looking anywhere else.

set_transition picks a cut instead of taking the default: {"op": "set_transition", "target": "Shot 2", "transition": {"type": "wipe", "durationMs": 500, "direction": "left", "softness": 0.1}}. Pass "transition": null to clear it. The cut plays over the target's head, so overlap the two clips by at least durationMs or there is nothing beneath for it to play against — a transition with nothing under it reads as a fade from black.

direction on wipe, push, slide, whip, and gradientWipe names the incoming edge. gradientWipe also takes map: "linear" | "radial" | "noise", scale, seed, and softness. iris takes softness; lightLeak takes color, scale, and seed. easing takes a named id, cubic-bezier(...), or spring(...).

fadeInMs and fadeOutMs on set_clip_params are audio fades. The compositor does not read them, so they will not fade a picture — for that, animate the clip with a fade in or out.

A transition's opacity multiplies with animation opacity rather than replacing it, so a clip that both dissolves in and carries a fade in ramps twice and reads slower and softer than either alone. Pick one.

validate_timeline reports transition_exceeds_duration when the cut is longer than the clip carrying it, and unknown_transition for a type or direction this build cannot draw — which falls back to a cross-fade running left rather than failing the render.