Motion Curves

Motion Curves → animation nobody had a preset for

An animate_clip input with {"preset":"custom"} carries exactly one of curves (keyframes you write) or code (a JS body baked into curves once, host-side). Add mask when a curve drives wipeProgress. A stored document animation can instead carry styleTracks or textAnimator without numeric custom curves.

motion-graphics carries the op contract and the preset catalog this file is the escape hatch from. motion-principles gives the duration and the shape a curve should hit before you write its keyframes.

For numeric custom curves, call edit_timeline with an animate_clip op or the in-product ui_timeline_animate_clip tool. Both accept the flat curves or code input shown below. For stored styleTracks, textAnimator, or beat, read get_timeline, edit the full clip animation in its document, then call set_timeline_document with every existing document field. The animate_clip input does not author those stored fields.

When to write one

Write curves as soon as a preset is close but not right. The catalog is seven entrance shapes and a handful of beats — where motion starts, not where it stops — and a piece whose every title arrives with pop reads like a template. A curve costs one field and a few numbers, and the recipes below are the shapes worth reaching for: an entrance that overshoots twice, a hold in the middle of a move, two channels on different schedules, a decay, an arc, a wiggle, a path draw-on.

Two shapes need no curve, and writing one anyway only makes the document harder to read: a single overshoot and a physical settle are already easing strings. cubic-bezier(0.16,1,0.3,1) and spring(180,12,1) on an ordinary preset do both. Everything past that is this file.

Curves by hand

{"op": "animate_clip", "target": "Title", "animations": [
  {"role": "in", "preset": "custom", "durationMs": 600,
   "curves": [
     {"property": "offsetY", "keyframes": [
       {"t": 0, "value": 80}, {"t": 0.7, "value": -12, "easing": "easeOut"},
       {"t": 1, "value": 0, "easing": "easeInOut"}]},
     {"property": "opacity", "keyframes": [
       {"t": 0, "value": 0}, {"t": 0.4, "value": 1}]}]}]}

t runs 0..1 over the animation's window, not the clip. easing on a keyframe eases the segment ending there. Keyframes are sorted, t is clamped to 0..1, and a curve that stops short of either end is extended by holding its end value — so sampling 0.05..0.95 does what it looks like.

Limits: 16 curves per animation, one per property, 4096 keyframes each.

durationMs defaults to the clip's own duration, so curves span the whole clip unless you say otherwise.

The channels, and how they combine

Several animations can drive one channel. How they fold decides whether the second adds to the first or throws it away.

The replace row is the trap. Two animations driving positionX over the same instants means one does nothing, reported as replace_curves_overlap. Move a clip with offsetX when it should compose with other motion, and with positionX only for an absolute placement nothing else touches.

Land the last keyframe on the identity value unless you mean the clip to stay where the curve stopped — and remember the role decides whether it stays: an in window holds its t: 0 values before it and contributes nothing after, an out window holds its t: 1 values after it, emphasis holds neither, and loop repeats its cycle, so a loop curve must end on the value it started on.

list_animation_presets reports this table from the engine. Read it there rather than from memory when a channel's range matters.

Style curves in a document

Use styleTracks on a stored animation when the target is a visual property rather than a numeric motion channel. The target names a clip style such as text.color, shape.cornerRadius, mask.featherPx, or clip.borderRadius; an effect target is effect.<effect-id>.<numeric-field> or a supported effect color such as effect.bg-field.colorB. A target needs the matching style, mask, or effect on the clip. Color values interpolate through the supported CSS color parser. shape.d and mask.d paths need matching commands and point counts. Glyph targets need a text stagger. validate_timeline reports an invalid target, incompatible path, or unsupported color.

This is one complete stored animation object to merge into an existing clip's animations array before the full-document write:

{"id":"round-in","role":"in","preset":"fade","durationMs":600,"styleTracks":[{"target":"clip.borderRadius","keyframes":[{"t":0,"value":0},{"t":1,"value":30,"easing":"easeOutExpo"}]}]}

styleTracks can accompany a preset, so a title can fade while its color changes. The id is required in the stored document; animate_clip creates one for its own inputs. Use motion-graphics for links, text animators, beat binding, and the document write boundary.