JsonCutDocs

Motion, keyframes and transitions

Animate editable properties with fractional keyframes and connect scenes with the transition catalog.

Keyframes animate one layer while it exists. Transitions connect an outgoing clip to an incoming clip. Entrance and exit presets in Studio write ordinary keyframe tracks, so their result stays editable through API and MCP.

In Studio, the Motion section of a layer has four tabs: Entrance and Exit for ready-made moves, Keyframes to step through the keyframes, change their values and shape the curve to the next one, and Behaviors for moves that run without keys (Float, Pulse, Spin, Swing, Count up, Draw on, Follow path, Wiggle). A behavior is a motion-program segment with the id behavior-<name>, so the API and the AI Director can add the same ones. Once a layer moves, Pivot sets the point it scales and turns around: one of nine points, or any position in percent of the box (also outside it); in Animate a crosshair on the canvas shows it and can be dragged, snapping to the edges and the middle. Turning a layer on the canvas keeps its pivot. The curve list offers Smooth, Snappy, Soft end, Soft start, Cinematic, Overshoot, Anticipate, Spring, Bounce, Bounce both, Elastic, Linear and Hold; drag the curve's handles for a custom one.

Rendered output

API request journey

Position, scale, opacity and blur tracks move through a multi-scene technical story.

Video1920 × 108014 secondsEditable V2 source

Property tracks

data-jc-animation contains JSON encoded for an HTML attribute:

{
  "transformOrigin": "center center",
  "tracks": [
    {
      "id": "card-position",
      "property": "position",
      "keyframes": [
        { "id": "p0", "time": 0, "value": { "x": -80, "y": 0 }, "easing": "ease-out" },
        { "id": "p1", "time": 0.7, "value": { "x": 0, "y": 0 }, "easing": "ease-in-out" }
      ]
    },
    {
      "id": "card-opacity",
      "property": "opacity",
      "keyframes": [
        { "id": "o0", "time": 0, "value": 0, "easing": "linear" },
        { "id": "o1", "time": 0.45, "value": 1, "easing": "ease-out" }
      ]
    }
  ]
}

Times are fractional seconds relative to the owning layer. Supported properties include position, scale, 2D/3D rotation, opacity, size, blur, color, background, clip path and audio volume.

The MCP/Agent patch_clip action replaces each submitted property track in full while preserving other property tracks. For example, adding rotation does not discard position. Use animation: null to clear all tracks; keyframe arrays are not partial append operations. An authoring call (jsoncut_author_project) accepts at most 160 actions, separately from the limit of 256 keys per submitted track.

Named curves are linear, ease-in, ease-out, ease-in-out, back-out, bounce-out and bounce-in-out; see Easing for steps, spring, elastic and custom. Custom cubic-bezier(x1,y1,x2,y2) curves are accepted throughout authoring and rendering: X controls must be between 0 and 1; all controls must be finite. The easing on the destination key controls the incoming segment. For example, use cubic-bezier(0.22,1,0.36,1) for a fast arrival with a soft finish.

Motion programs: one timeline, independent properties

For composed motion, use a motion program through patch_clip with animation.program. It uses the same preview and export contract. Discover the complete schema through jsoncut_get_primitive_catalog with kind: "motion" (Studio Agent: list_motion_presets). No separate chart engine or runtime package is needed.

ControlWhat it does
x, y, width, heightAnimate pixel geometry
scale, rotation, opacityScale multiplier, additive degrees, absolute opacity
drawStart, drawEndIndependently trim a native vector stroke from 0 to 1
pathProgress + followMove a separate layer along the actual curve, independently of its reveal
numberAnimate native text with decimals, prefix and suffix
inputAnimate a declared numeric custom-block input, read inside jsoncut.onFrame

Each segment has an ID, property, from, to, start at and duration. Times are local seconds. at can instead be { "cue": "arrival", "offset": 0.15 } with cues: { "arrival": 1 }; reuse cue names and increment offsets to stagger related layers. Cues are stored per layer, not as global project variables. repeat counts extra iterations; gap holds the endpoint between them; yoyo reverses alternate iterations. Final values hold. No fade-out is inserted.

Choose easing or spring: { mass, stiffness, damping, velocity } on each segment. Springs work on any numeric channel and are normalized to finish at the requested endpoint over that duration. This is a timed spring response, not a collision/rigid-body simulation. Progress and opacity remain clamped to 0–1; geometry dimensions remain positive.

This patch makes an existing layer follow a previously created native path:

{
  "animation": {
    "tracks": [],
    "program": {
      "version": 1,
      "segments": [{
        "id": "signal", "property": "pathProgress",
        "from": 0, "to": 1, "at": 0.5, "duration": 1,
        "repeat": 2, "gap": 0.2, "easing": "linear"
      }],
      "follow": {
        "pathId": "your-existing-path-id",
        "anchorX": 0.5, "anchorY": 0.5,
        "orient": true, "rotationOffset": 0
      }
    }
  }
}

The layer must last at least 3.9 seconds. Create targets first and use their real IDs. Imported SVG image contents are not native paths.

To connect nodes, put connector on a native vector layer:

{
  "from": { "clipId": "source-node", "x": 1, "y": 0.5 },
  "to": { "clipId": "destination-node", "x": 0, "y": 0.5 },
  "bend": 0.55
}

Anchor coordinates are fractions of the target layer's bounds. Moving or resizing either node updates the connection. bend runs from 0 to 1: 0 gives a straight line; larger values produce horizontal-tangent curves. Edit a native vector directly for other curve shapes. Followers work on either kind of path.

Ownership and editing

  • One owner per property: do not combine a program channel with the same property track or measured audio binding. Clear conflicts explicitly.
  • Spatial bindings support 2D layer and parent transforms. Cycles, missing targets and 3D bindings are rejected; invisible references hide their dependents.
  • Programs cannot share a layer with legacy procedural or motion descriptors. Existing projects keep their old behavior without migration.
  • animation.program: null removes only the program; animation: null removes the complete animation. Submitted programs replace the whole program; omitted programs and unrelated property tracks are retained by Agent/MCP patches.
  • At most 64 segments, 32 cues and 1000 extra iterations. Segments on the same channel may be sequential, not overlapping; all timing must fit the layer.
  • Group duplication remaps internal references. Delete a complete group or detach external bindings before deleting their targets. Splitting program layers is explicitly blocked; duplicate and retime them instead. Ungrouping a group with its own program is also blocked until that program is removed; this prevents silently discarding group motion. Cross-project paste must include referenced targets, not just the follower.

Native starting compositions

Search the shared Library for component.native-flow, component.native-chart, component.native-logo or component.native-process. Every node, line, moving signal, column, value and label is an ordinary editable layer. These are starting compositions, not a hidden data engine: edit their layers and motion segments to change the design. Existing hybrid recipes remain available when an intentionally code-controlled inner graphic is preferable.

Rendered output

Native connected flow

Six independently timed signals follow anchor-connected curves. Nodes, labels, paths and signals remain separate Studio layers. Exported at 60 source fps.

Video800 × 4505 secondsEditable V2 source

Legacy parametric motion

For a physical spring, apply Library item motion.physical-spring to a selected visual layer. An older spring offset shows in Studio's Behaviors tab as a card with mass, stiffness, damping, initial velocity, distance and seconds; for new work use the spring() curve or the Pulse and Swing behaviors. Its horizontal offset adds to existing keyframes. The analytic spring is evaluated from local layer time on every seek; it does not depend on playback history or create hundreds of keys. Durations from 0.05 to 3600 seconds are supported.

In Studio, Count up (text) and Draw on (vector paths) in the Behaviors tab cover the same ground. Counter typography remains native and editable; its from, to, prefix, suffix, precision and easing control the displayed number. A path's reveal and oriented marker use its actual curve, including resized anchors. Use Library items motion.native-counter and motion.native-path, or a validated procedural layer patch, from MCP. These are native controls, distinct from the optional code-edited hybrid artwork recipes.

Only one parametric motion system is active per layer. Use separate layers for independent effects. Image compositions do not support animation. Public rendering still samples source frames; experimental temporal-sampling research is not a public render option.

For example, patch an existing text layer with this descriptor. Use the normal authoring endpoint/tool and its current project version; position, typography and other motion tracks remain unchanged.

{
  "procedural": {
    "type": "counter",
    "from": 0,
    "to": 2400,
    "decimals": 0,
    "prefix": "",
    "suffix": "+",
    "seconds": 2,
    "easing": "cubic-bezier(0.22,0,0.36,1)"
  }
}

Set procedural to null to remove the system. A counter replaces the visible text while active, so do not combine it with a character-based entrance on the same layer.

Source and output FPS

For smooth 60 fps animation, set the project to 60 fps before authoring and export at 60 fps. Exporting a 30 fps source at 60 fps does not create new motion states; preflight warns about that upconversion. Temporal motion blur is not currently a public output option.

Scene transition

<section id="scene-result" data-jc-clip data-jc-kind="scene"
  data-jc-start="4.1" data-jc-duration="4.5" data-jc-track="0"
  data-jc-transition="mask-bars-vertical"
  data-jc-transition-duration="0.62"
  data-jc-transition-easing="ease-in-out"
  data-jc-transition-from="scene-request"
  data-jc-transition-to="scene-result">
</section>

Use keyframes to move an object from A to B. Use a transition when the edit itself changes from one scene or clip to another.

Smart Animate

smart-animate on the second of two scenes moves layers instead of cutting: every layer with the same data-jc-name in the scene before and in this one travels from its old position, size, rotation, colour and corner radius to the new ones, and two vector shapes morph their outline. Text with the same words scales with its box; different words cross-fade inside it. Layers without a partner fade out or in. In Studio, Duplicate for Smart Animate in the scene menu copies a scene right after itself with the transition set, so you only move and restyle the copy. The check SMART_ANIMATE_NO_MATCH warns when no names match.

Animatable properties

FamilyProperties
Transformposition, scale, rotation, rotationX, rotationY, skewX, skewY
Visibility and geometryopacity, width, height, clipPath, borderRadius
Image treatmentblur, brightness, saturation, hue
Designcolor, background (gradients too), boxShadow, strokeWidth, strokeColor
TextletterSpacing, lineHeight, textShadow
Shapepath (morph)
Audiovolume

Position values use {x,y} with optional z. Colours, backgrounds, shadows, stroke colour and clip path use CSS strings; two keys built alike (the same gradient with other colours or angle, a shadow with another blur) are interpolated number by number and colour by colour, others switch halfway. A glow is a shadow without offset. Skew is in degrees, corner radius, letter spacing and stroke width in pixels, line height as a factor of the font size. Stroke means a vector shape's stroke or a text's outline. Through the authoring contract a layer may have up to 16 tracks (one MCP patch sends at most 12), one per property, and every keyframe time must fall between zero and that layer's duration.

Morphing shapes

A path keyframe holds a whole outline, { "points": [...], "closed": true }, in the same point format as vectorPoints. Between two keys the outline morphs: point counts may differ (the shorter one is subdivided) and a closed target starts where it lies nearest the source, so it does not twist. In Studio, Morph in the inspector of a shape turns it into a library shape or another shape of the project from the playhead on; rectangles, circles, pills and polygon masks become vector paths first with the same look. Moving the points of a shape in Animate keys its outline too. On a shape that already morphs, the path editor shows the outline at the playhead and every change keys it there. The path tool (P) works on rectangles, circles, pills and polygon masks too: the first change turns the shape into a path with the same look (a border becomes its stroke). In Animate a bar above the canvas shows the shape keys, steps between them and keeps the current outline with Key shape here, so a later change morphs from that moment; the outlines of the neighbouring keys appear as dashed guides. Smart Animate morphs from the outline on screen in the scene before to the one the new shape draws, its shape keys included.

Easing

Built-in values are linear, ease-in, ease-out, ease-in-out, back-out, bounce-out (lands and bounces like a ball) and bounce-in-out. A CSS-compatible cubic-bezier(x1,y1,x2,y2) is also accepted when both X control points stay between zero and one. steps(n) (1–60) holds each value and jumps, spring(bounce) (0–0.9) moves like a spring that swings past the target and settles by the keyframe, and elastic(amplitude,period) (1–3, 0.1–1) overshoots and rings out like a rubber band.

custom(x,y,inX,inY,outX,outY;…) is a curve through 2–8 points, from 0,0 to 1,1, each with an incoming and outgoing handle (like a multi-point CustomEase): x must increase from point to point and each handle stay inside its segment; y may leave 0–1 for anticipation and overshoot. In Studio choose Multi-point curve in any curve menu, double-click the curve to add a point, drag points and handles, and press Delete to remove a point. Volume keys take only the curves the audio export plays: the named ones up to back-out, cubic-bezier, steps and spring.

The easing on a keyframe controls interpolation from the previous keyframe into that keyframe.

Presets remain editable

Studio entrance and exit presets generate ordinary property tracks. Families include fades, slides, wipes, geometric reveals, slices, dynamics, depth and focus effects. After applying a preset, inspect and adjust its tracks like any other motion.

Text layers additionally support independent entrance and exit effects with all, word, character or line staggering. Replacement and shimmer effects have bounded text-specific controls; they do not introduce executable code. Scramble lets each letter cycle through random characters until it settles (scrambleCharset: upper, letters, digits, symbols, binary or up to 64 characters of your own); the layout keeps the final text throughout.

With several layers selected, the next entrance or exit goes on all of them one after another: set the delay between layers and the order (reading order, reverse, from the middle, from the edges, random, or a grid ripple from a corner or the centre). From MCP or the API use apply_motion with clipIds and stagger: { each, order, from, seed }. The Drop and bounce and Elastic pop presets use the bounce and elastic curves.

Wiggle in the Behaviors tab shakes a layer like a handheld camera, with nerves or with energy: seeded noise on position, rotation and size that adds to everything else (keyframes included), with strength, frequency and a variation. In a motion program it is a segment with wiggle: { amount, frequency, seed } on x, y, rotation or scale (frequency 0.1 to 30 Hz, an integer seed, from and to 0, and no easing, spring or repeat).

The Animate view of the timeline shows behaviors, text effects and Smart Animate as bars in a Motion row under a layer's keyframe rows.

New text layers start with no entrance or exit effect. In Studio, choose None / Off above either text-effect library to disable that phase. Text exit was previously labelled “Keep visible”. An entrance does not automatically add an exit. Animated library presets can deliberately include effects.

For apply_text_motion, use effect: "none" and exitEffect: "none" to disable both text phases. Omitting exitEffect preserves an existing exit. These controls do not remove separate layer or parent keyframes, transitions, or the clip's end time; inspect those if the layer still disappears.

Transition constraints

The transition is stored on the destination clip. Its duration must be positive and fit inside that destination (without data-jc-transition-duration it is 0.5 seconds). When fromClipId (data-jc-transition-from) is supplied, the source must exist and be adjacent to or overlap the destination at the edit point. Keep toClipId (data-jc-transition-to) equal to the owning destination ID.

Transition families

The public catalog includes dissolves and color dips; directional pushes, slides and wipes; diagonal, circle and iris reveals; blur, zoom and exposure changes; light leak, film burn and flash effects; glitch, RGB split and pixelation; bar, blind and checker masks; 3D flips, cubes and page turns; plus luma, ripple, warp, split and shutter transitions, and smart-animate between two scenes. Use the live Studio catalog for visual selection and the source schema for the stable transition ID.

Each does what its name says: pixelate breaks the picture into blocks, rgb-split and glitch shift colors and bands, ripple and warp bend it, radial-blur streaks it from the center, venetian-blinds and checker-reveal open slats and squares, page-turn turns the old picture over its left edge, cube-left/cube-right show both faces, light-leak sweeps warm light across and film-burn burns holes with glowing edges. Pushes, slides and zooms blur with their speed. Layers can also carry pixel effects (effects, or an effect preset), motionBlur while they move by keyframes, and an effect layer (adjustment: true) applies its effects and grade to everything below.