Motion paths, motion blur and text on a path

Bend a clip's travel into a curve, turn it along the way, blur fast moves with a shutter angle, and set titles along lines, arcs, circles and drawn paths, on the monitor or by an agent with setMotionPath and setTextPath.

Motion paths. When keyframes.x and keyframes.y both have a key at the same time, that is a position key. Give position keys curve handles and the clip travels along a bezier path between them instead of a straight line. The handles are pin (arriving) and pout (leaving) on the x and y keys, in px relative to the key's position, in the clip's x/y space:

"keyframes": {
  "x": [ { "t": 0, "v": -450, "pout": 250 }, { "t": 2, "v": 0, "pin": -250, "pout": 250 }, { "t": 4, "v": 450, "pin": -250 } ],
  "y": [ { "t": 0, "v": 150, "pout": -300 }, { "t": 2, "v": 0 },                        { "t": 4, "v": 150, "pin": -300 } ]
}

Between two position keys the clip moves along the curve at the pace of the arriving key's ease, measured along the curve, so a linear key gives an even speed around a bend. A segment with an extra x or y key inside it, or with no handles, runs the channels as before. autoOrient: true turns the clip to face its direction of travel, and its rotation adds on top. A parent on a curved path carries its children along it.

Motion blur. motionBlur is a shutter angle: the clip is drawn at motionBlurSamples moments across motionBlur / 360 of a frame, centred on the frame, and the samples are averaged. 180 is the film look; 360 smears a whole frame. It blurs whatever changes: position, scale, rotation, a parent's motion, keyed shapes and trims. A clip that does not move draws once. During playback the preview uses as many samples as fit in the frame time (all of them on a fast machine); a paused frame and export always use them all. It works on video, image, svg, text and shape clips.

Text on a path. textPath on a text clip is one shape item (path, line, ellipse, rect, polygon or star, with the same geometry keys and keys as in Shapes, nulls and parenting, but no paint or trim) whose outline is the baseline, in the title's own px. The first line of text runs along it, each letter turned with the path; each further line (\n) runs on a parallel curve one line-height below, so its letters space by that curve's own length. pathOffset (% of the path's length, keyframable) is where the text sits, and pathAlign says which end of each line sits there. On a closed path the text wraps around; keying pathOffset 0 → 100 sends it once around a circle. Every text animation plays along the path. Font, size, colour, gradient, stroke, glow, shadow, lineHeight and letterSpacing all apply; text boxes and align do not (pathAlign takes their place).

{ "kind": "text", "props": { "text": "AROUND AND AROUND • ", "font": "Anton", "fontSize": 40, "letterSpacing": 4,
  "textPath": { "type": "ellipse", "w": 300, "h": 300 }, "pathAlign": "start" },
  "keyframes": { "pathOffset": [ { "t": 0, "v": 0 }, { "t": 6, "v": 100, "ease": "linear" } ] } }

In the editor: when the selected clip has two or more position keys, its path shows on the monitor: the curve, a dot per frame (their spacing is the speed), a square per key and the keys' handles. Drag a key to move it, drag a handle to bend the path (Alt breaks the pair), Alt-drag a key to pull new handles, and double-click a key to make it a corner again. Moving the clip on the monitor or typing X / Y keys both channels together. The Inspector's Motion section has Smooth (handles through every position key), Straight, Auto-orient, Motion blur and Blur samples. A title's Text path section sets it on a Line, Arc, Circle, Wave or a Pen path (click points, drag to curve, Enter to finish, click the first point to close it). Edit path shows the path's points on the monitor, and Offset and Align place the text along it.

Agents:

Recipes: fly-in on a curve - two position keys, setMotionPath smooth, autoOrient:true, motionBlur:180; orbiting label - circle textPath, pathOffset keyed 0 → 100 linear; stamp along a road - an open path textPath that follows the shape in the footage, pathAlign:"center", textAnim:"letter-pop"; whip without the transition - a fast x move over 4–6 frames with motionBlur:360.

Edit this in CLAUDE.md The whole manual as Markdown