Composition format

View as Markdown

This is the reference for writing and editing data.json for the Blitframe engine: which Lottie (Bodymovin) features render, and how to write each one. New to data.json? Start with data.json basics.

Blitframe renders only what this page describes, whatever After Effects or other Lottie players support. Build anything else from supported primitives, or from prepared image or video files.

Agents can read this page over MCP with read_data_json_reference, one section at a time, or at /docs/blitframe/data-json-format.md.

How to read it:

  • problems, warnings and "refused" mean what What Blitframe checks says. A case marked problems makes the version not renderable. A case marked warnings renders, but not as written.
  • In property tables, Default is what the engine uses when you leave the property out. Required means you write it: without it the render fails, the item does not draw, or the result is not defined. None means the feature is off.
  • Each section ends with Edge cases: what the engine does with a value written another way.
  • Limits lists every numeric limit in one place.

The most important rule: layer ind sets the stacking order, and smaller numbers paint in front. Reordering the layers array restacks nothing.

Contents:

Supported features

Area Available Main limits
Layers Solids, images, shapes, text, video, nulls, precompositions, cameras, adjustment layers, native 3D models Audio comes from the version's soundtrack or the render's audio, not audio layers
Transforms Position, anchor, scale, opacity, 2D and 3D rotation, orientation, parenting, auto-orient Auto-orient needs a unified animated position track
Animation Linear, hold, temporal and spatial Bezier interpolation; compatible path morphs; time stretch on precomposition layers No roving keyframes. Other layers ignore time stretch.
Shapes Paths, rectangles, ellipses, stars and polygons, fills, strokes, static gradients, groups, single-path trims No nested groups, repeaters, merge paths, dashes or gradient animation. A group draws a limited number of paths and paints.
Text Font-backed copy, paragraph layout, inline fitting, range and expression selectors, text on a path Timed copy or font changes need separate text layers
Media File-backed images and video, reusable precompositions, time remapping No embedded images, media URLs or footage looping
Native models GLB meshes with PBR materials and textures, fixed studio lighting, animated layer transforms No lights or lighting settings; GLB animations, skins and morph targets are not played
Masks and mattes Any number of masks per layer, animated paths and opacity, static feather, alpha and luma mattes No mask expansion, lighten or darken masks, or matte chains
Effects The exact effects and parameters listed, plus color overlay, stroke, outer glow and drop shadow layer styles Only parameters marked animated animate; en: 0 does not turn an effect off
Expressions Transform expressions and text expression selectors No host APIs; no expressions on other properties

Choose a representation

Visual requirement Use
Flat color background or rectangle Solid ty:1 with sw, sh, sc. Never a one-color image.
Gradient background A full-canvas shape with gradient fill gf, or a Solid with ADBE Ramp or ADBE 4ColorGradient.
Headline, caption, price or other copy Text ty:5 with an available font. Never letters built from shapes or baked into an image.
Staggered character, word or line animation Text animators with range or expression selectors on one text layer, not one layer per glyph.
Logo or fixed artwork Image ty:2, ideally a transparent PNG sized for its largest display.
Artwork that bends, morphs or uses Trim Paths Shape ty:4, with path keyframes and the same vertex topology between poses.
Several shapes moving together One shape layer with sibling top-level gr groups.
Layers sharing only a transform A plain null ty:3 used as parent.
Several layers sharing a mask, matte, effect or fade A precomposition ty:0, with the treatment on its referring layer.
Complex motion that must be baked One MP4 or MOV on a video layer ty:9, not an image sequence.
Real 3D product rotation A native GLB model ty:16.

Keep the composition easy to edit later: descriptive layer and group names, real keyframes instead of per-frame samples, and editable text. Add no wrappers, duplicate layers or effects without a visual purpose.

Editing a composition through Blitframe

  1. Read the current file: MCP read_file with path: "data.json", or GET /v1/versions/{versionId}/files/data.json.
  2. Change only what was asked. Keep property wrappers and value types, unrelated motion, parenting, masks, mattes, expressions, assets, text and names. A layer's ks.a is its anchor, but a property's a is its animation flag. A text document's s is font size, but a keyframe's s is its start value.
  3. Don't infer array positions from layer names or ind: ind: 8 does not mean layers[8].
  4. When you remove or renumber layers, update parent, tp and index-based expressions in the same composition. Never create parent cycles, recursive precompositions, dangling refIds or duplicate inds.
  5. Use only files in the version and available fonts. Never invent a path, asset id or font, and never point at a URL.
  6. Send the whole new data.json, plus any new files, in an edit. Set expectedHeadVersionId to the head you read in step 1, so the edit cannot overwrite a change made since. On head_moved, read the new head and apply your change again, instead of replaying the old file.
  7. Read the new version's renderable, problems and warnings. warnings name what renders differently from what is written. Then render, with a short frame range as the cheapest preview, and check the output before you report success. A valid file does not prove it looks right.

Document and time

The root object holds the canvas, the timing and the lists. This one is a 1920 × 1080 canvas at 30 fps, five seconds long, with its layers still to add:

{"v":"5.12.2","nm":"Promo","w":1920,"h":1080,"fr":30,"ip":0,"op":150,"ddd":0,"assets":[],"fonts":{"list":[]},"layers":[]}
Property Type Default Notes
w, h whole number Required Canvas size in pixels, 1 to 16384 (16K), or less on your plan. MP4 and HLS renders need both even. Frame renders also accept odd sizes.
fr number Required Frame rate, 1 to 120. Fractional rates such as 29.97, 23.976 and 59.94 play at that rate.
ip number Required First frame, 0 or more
op number Required End frame, which is excluded. Greater than ip.
layers list None The layer objects. Without any, the render shows nothing (warnings).
assets list None Media, model and precomposition declarations. With none, write [] or null, or leave it out.
fonts.list list None A declaration for every font the text uses (fonts)
v, nm text None Bodymovin version string, such as "5.12.2", and composition name. Not read.
ddd whole number 0 Not read. Write 0 in ordinary 2D documents, and preserve authored 3D rigs.
  • The render's size and frame rate come from the document: a render request cannot change them.
  • At a fractional rate, a video holds one frame for each frame from ip to op. A frame render returns exactly the frames you ask for.
  • A composition is at most 3,600 seconds long.

Limits repeats these numbers next to your plan's.

File rules

The file is UTF-8 JSON, at most 50 MB: a larger file is refused when you add it. These are reported in problems:

  • more than 5,000,000 JSON tokens (each key and value counts once, each object or array twice)
  • lists and objects nested more than 255 levels deep
  • a lone UTF-16 surrogate in a key or string, which is not valid text
  • a number outside ±1.7976931348623157e308

Render limits

Only the root layers, and the precompositions they use at any depth, count. A precomposition asset no layer uses is not checked. A render that needs more than a limit fails.

Resource Per render What counts Reported in problems
Precomposition layers 180 not collapsed, and 10,000 copies in all, collapsed or not Each use inside another precomposition counts again Over either limit
Video layers (ty:9) 100 Hidden ones, ones outside their time, and every copy in a precomposition. An animated GIF or WebP on any layer plays as video and counts too. Over the limit. To show more clips, join clips that play one after another into one video file.
Textures 484, or 482 on a plan with the watermark Textures Image assets, 3D model textures and 3D lighting over 484. The other uses are not checked.
Meshes 199, shared by text and 3D models One per text layer and two per stroked text layer, counting hidden layers and every precomposition copy. One per 3D model asset a model layer uses, however many layers show it. Over the limit
Vector paths 2,000, across the composition and its precomposition instances Vector paths Over the limit

Textures

A composition takes one texture for each image asset in any format, used or not. Image assets with the same id share one. An asset the engine skips takes none: one with a data: p, or with w or h over 4096. A composition also takes:

  • one for each animated GIF or WebP a layer shows
  • one for each copy of a video layer, and of a precomposition that is not collapsed
  • one for each copy of an adjustment layer with masks, and of an image, solid, precomposition or video layer with static masks and no effects
  • for each 3D model asset a model layer uses, once however many layers show it: one for each texture its drawn materials read as color, and one for each they read as data. Base color and emissive are color, and metallic-roughness, normal and occlusion are data. A texture used both ways takes two. Only textures whose image is stored in the file, as PNG, JPEG or with no mimeType, count.
  • three for the lighting all models share, when a layer uses any model
  • two for each font the text uses

Effects, layer styles, gradient paints, stroked text and blend modes 17 to 26 can take more. Blitframe counts image assets once per id, leaving out GIF and WebP files and skipped assets. It also counts 3D model textures and the three for 3D lighting. It does not count the other uses or the watermark's, so stay well within the limit.

Vector paths

  • In a group that draws, every path up to the last one a fill or stroke follows takes one, in hidden layers too. A star or polygon the engine skips takes none.
  • An add, subtract, intersect or difference mask takes one when its layer has "hasMask": true, in hidden layers too. That holds on any layer that draws, not on a camera or a plain null. A text's path mask (t.p.m) takes none.
  • A shape group whose fill or gradient fill a trim cuts takes one more: a group with a tm that has exactly one path listed before it. It counts only on a shape layer that shows: not hidden, with an ip to op span that overlaps the time its composition plays.
  • Each use of a precomposition counts its paths again.
  • Other scene timings, fewer layers, or moving the same geometry into groups don't reduce the total.

Blitframe counts the paths of shape groups, masks and trimmed fills. Over the limit, remove redundant contours and duplicate artwork, or simplify geometry while keeping the required look and independent motion. Use a raster only where the artwork's editing and animation needs allow. Never flatten required animated parts, or substitute reference pixels, to meet a limit.

Time

  • Time fields and keyframe t are in frames. Time-remap values (tm) of video and precompositions, and expression time, are in seconds.
  • At fr: 30, ip: 0, op: 90 lasts three seconds. Frame 90 is excluded.
  • Changing fr alone changes the speed of frame-based animation. To keep the duration, multiply every frame-valued time by new fr / old fr, nested keyframe times and layer ranges included. Don't multiply tm values.
  • Layer ip and op set when the layer is visible in its composition. Every layer needs a numeric op.
  • st offsets a precomposition's child timeline, or a video layer's playback. Other layers ignore it (warnings). Ordinary transform keyframes stay on their containing composition's timeline.
  • sr stretches time on a precomposition layer without tm. Its contents play at 1/sr speed, counted from st, so sr: 2 plays them at half speed. Video inside still plays at normal speed (warnings, time remap).
  • Every other layer, and a precomposition with tm, ignores sr: keep it at 1 there and write timing out (warnings otherwise).
  • Preserve the overlap of parent, precomposition, matte and child visibility ranges.

Time remap

On a video layer (ty:9), tm:{"a":0,"k":1.5} holds the footage frame at source time 1.5 seconds for the layer's whole visible interval. It reuses source pixels without generating, tracing or uploading an image. Without tm, ordinary st playback applies.

  • An animated tm selects source time with second-valued s and e, at key times in frames of the containing composition. Use hold keys for deliberate freezes.
  • A curve that goes back in time plays the footage backwards. Played backwards, H.264 video can show the frame just before the one the curve asks for.
  • Position, scale, masks and opacity still animate over held footage.
  • Choose an inspected time inside the source duration.
  • Use source pixels only from production assets authorized for inclusion. A reference-only video or storyboard does not become footage because it can be held or cropped.

On a precomposition, tm drives its children's time, written as {"a":0,"k":seconds} or keyframes with "a": 1. A precomposition with tm ignores sr (warnings). Video inside a precomposition with tm or sr, at any depth, follows neither: it plays at normal speed on the render's timeline, offset only by each precomposition's st (warnings). Such a video decodes from its start. A frame render starting after its in point can then show it behind an MP4 of the same frames. To hold footage, set tm on the video layer instead. Changing st does not retime all ordinary layer properties.

Edge cases

  • A root w or h written with a decimal point or exponent, such as 1920.0, reads as 0: problems. Write whole numbers such as 1920.
  • A non-empty layers that is not a list: problems.
  • A layer without ip starts at frame 0. A layer without op ends at frame 0, so it never appears (warnings).
  • A layer ip, op or st that is not a number reads as an arbitrary frame (warnings).
  • On a precomposition without tm, sr: 0 plays its contents at normal speed (warnings). An sr that is not a number reads as an arbitrary stretch, which the warning gives.
  • A precomposition's tm written another way:
Precomposition tm written as Result
null, {}, false, 0, "" or [], or a k that is neither a number nor keyframes Holds the first frame (warnings)
A short bare decimal, such as 1.5 or 2.0 Holds the first frame (warnings)
A bare whole number other than 0, such as "tm": 5, and most other bare decimals Unreadable: problems

Layers, ordering, and relationships

Each entry of layers is one layer object. This solid fills a 640 × 360 canvas, behind every layer with a smaller ind:

{"ty":1,"ind":4,"nm":"Background","ip":0,"op":90,"st":0,"sr":1,"bm":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}

ty sets the kind of layer, and what else it needs:

ty Kind Needs
0 Precomposition refId naming a precomposition asset, and positive whole-number w and h. st, sr and tm are optional (precompositions).
1 Solid Positive whole-number sw and sh, and a text sc written "#rrggbb", such as "#17324d". Use ks.s for fractional displayed sizes.
2 Image refId to an image asset the engine loads (media)
3 Null or adjustment layer A plain null is an invisible parent. With ef and positive whole-number sw and sh, it is an adjustment layer.
4 Shape shapes, with geometry and paint (shapes)
5 Text A text document with copy and a declared font (text)
6 Audio Nothing: it is ignored (audio layers)
9 Video refId to a video, GIF or WebP the engine loads. A one-frame GIF or WebP shows as a still image. st is optional.
13 Camera A static nonzero zoom pe (cameras)
16 Native model refId to a GLB asset (native models)

A layer of any other type is skipped. Layers parented to it are placed as if their parent had no transform.

Fields every layer has

Property Type Default Notes
ty whole number Required The layer type
ind whole number 0 Unique and positive within its composition. It sets stacking.
nm text Required A stable, non-empty name. An audio layer needs none.
ks object Required The transform
ip, op number 0 Visibility in frames, from ip up to but not including op (time)
parent whole number None The ind of a layer in the same composition. 0 means no parent.
hd boolean false true hides the layer
st number 0 Read only on precomposition and video layers (time)
sr number 1 Read only on precomposition layers without tm (time)
ao whole number 0 Auto-orient (transforms)
bm whole number 0, normal Blend mode
ddd whole number 0 Not read. Preserve it when present.

Stacking and references

  • Smaller ind values paint in front. Array order is not paint order: moving an entry changes its pointer, not its pixels. To restack, change the ind values and remap the parent and tp references that depend on them.
  • Each nested composition has its own index space.
  • refId names an asset id, not a layer name.
  • Several precomposition layers can share one asset, and editing /assets/{index}/layers/... changes them all. To change one instance, duplicate the asset with a new unique id, point only that layer's refId at it, then edit the duplicate.
  • Keep a precomposition layer's w and h coherent with its children's local coordinates. Changing only the outer canvas does not resize the content.

Audio layers

Audio layers (ty:6) are ignored and give no output audio. A render plays the version's soundtrack, which an edit sets with its soundtrack field (Projects). A render request can name another file in audio, which overrides it (Renders).

  • Audio asset declarations use a supported audio file path and need no w or h. They cannot serve as image or video layer assets.
  • The engine never opens an audio file, or any asset that is not an image, video or model. Such a file may be left out of the version (warnings).
  • An audio layer cannot be another layer's parent or matte tp.

Adjustment layers and cameras

An adjustment layer is ty:3 with positive sw and sh, transforms, timing, and a non-empty ef list of supported effects. It applies them to what is painted behind its rectangle, and only inside it.

  • Its effects run on the rectangle's bounding box on screen, clipped to the composition. A rotation changes only what the rectangle covers: the effects stay aligned to the screen.
  • Effects that spread, such as a blur, glow or shadow, get no extra room and stop at the rectangle's edges.
  • It reads only the layers behind it in its own composition.
  • Place it in front of the layers it affects, using ind, and size and place the rectangle deliberately.

A plain null has no paint and only groups transforms: leave out ef, sw and sh, and never add an empty ef. Parenting gives no group masking, clipping or composited effects.

A camera is ty:13 with a zoom pe, timing and camera transforms.

  • pe:{"a":0,"k":zoom} is a static nonzero zoom: one number, never animated, sign ignored.
  • A one-node camera has no ks.a. On a two-node camera, ks.a is the point of interest, not a geometry anchor.
  • An authored 3D rig uses three-component position and scale, and rx, ry, rz with or.
  • The last camera layer in layers is used for the whole render, hidden or not, whatever its ip and op. Keep one intended camera per composition: visibility cannot cut between cameras.
  • A camera moves every layer in its composition, 2D layers too, since ddd is not read. To keep a background or title fixed, put the camera and the layers it moves in a precomposition that does not collapse transformations. Keep the fixed layers outside it.
  • Camera support does not imply lights, material shading, depth of field, motion blur or continuous rasterization.

Edge cases

  • A ty written other than as an unsigned whole number, such as 3.0 or 3e0, reads as the number its low 32 bits hold (warnings). That is usually 0, a precomposition, and one without a text refId is in problems.
  • A missing or repeated ind is in warnings. A missing ind reads as 0, which no layer can name as parent or tp.
  • Of layers sharing an ind, the engine keeps only the last in its layer tree. The others are not placed by their transforms, and children of that ind attach to the last. Their stacking is undefined, and a matte tp uses whichever draws first.
  • A layer without a text nm, other than an audio layer: problems.
  • A ks, or a value in it, that is not an object: problems.
  • A layer whose op is at or before its ip is accepted but never appears.
  • A nonzero parent naming no layer in the composition, or naming an audio layer: problems.
  • Only the boolean true hides a layer: hd: 1 reads as false.
  • An entry of layers that is not an object: problems.
  • The engine skips the first character of a solid's sc and reads the next six as hex. So "17324d" without #, or a short "#fff", gives another color. Characters after the six digits, such as alpha, are ignored. A missing or non-text sc: problems.
  • An image, video or 3D model layer whose refId names no asset of its kind that the engine loads: problems. So is a precomposition layer whose refId is not text or names no asset.
  • A camera without pe has a zoom of 0 (warnings). A pe the engine cannot read, such as a bare whole number: problems.
  • Effects on a ty:3 without sw don't render, and the layer is a plain null (warnings).
  • An adjustment layer whose ef holds no supported effect, or is empty, draws as an opaque white rectangle (warnings).

Transforms and coordinates

A complete ordinary 2D transform:

{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[320,180,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}}
Property Type Default Notes
ks.a property: 2 or 3 numbers [0,0,0] Anchor, in the layer's local pixels
ks.p property: 2 or 3 numbers, or separated [0,0,0] Position of the anchor, in parent coordinates
ks.s property: 2 or 3 numbers [100,100,100] Scale in percent: [100,100,100] is unchanged
ks.r property: number 0 2D rotation in degrees. Ignored when rx is present.
ks.o property: number Required Opacity, 0–100
ks.rx, ks.ry, ks.rz property: number 0 3D rotations in degrees. Supply all three when you preserve a 3D rig.
ks.or property: 3 numbers [0,0,0] Orientation in degrees. Keyframes may hold two or three numbers.
ks.poff list of 2 numbers None A static [x,y] offset. Preserve it and never keyframe it. To move a layer, change p.
ao whole number 0 A nonzero value turns the layer to the tangent of a unified animated position track. Separated x and y cannot drive it.

Expressions run on p, a, s, r and o only (expressions). Layer ddd is not read: 3D comes from rx, ry, rz and three-component p, s and a. Timing is in time.

Where a layer sits

  • Position places the anchor. It does not center the visible content.
  • Solids and images have their origin at the upper-left corner. A full-canvas solid with anchor [0,0,0] needs position [0,0,0]. Or anchor it at half its width and height, and position that at the canvas center.
  • Image anchors usually sit at half the image's size. Shape geometry is often centered on the origin: a rectangle with its own p: [0,0] is centered there. Text position is tied to a baseline, not to the center of the visible text.
  • A child uses its parent's coordinates. Don't apply the canvas-center offset again to each child.
  • With no rotation or parent, a local point lands at position + (point - anchor) * scale / 100. Parenting, group and precomposition transforms compose on top.
  • Convert a measured canvas distance to parent coordinates before you change a position. Setting a nested layer's p to the root canvas center does not center its subject.
  • 2D and 3D vectors are not interchangeable with scalar wrappers: keep each value's dimensions.
  • Moving an anchor changes the picture, unless position compensates through scale and rotation at every affected time. For a move, offset the position and keep the anchor.

Separated position

{"s":true,"x":{"a":0,"k":320},"y":{"a":0,"k":180}}

Here s is a separation flag, not scale. Edit /ks/p/x and /ks/p/y as scalar properties, and add no vector k. A separated position has X and Y only, so a 3D layer uses a unified three-component position. It gives auto-orient no tangent.

Edge cases

  • With both rx and r, r is ignored (warnings).
  • An or without three numbers, such as []: problems.
  • A poff the engine cannot read, such as [] or null: problems. On a layer whose transform has no "a": 1 value or expression, even [1,2] can be.
  • Only s: true separates a position: s: 1 does not. The engine then reads the position's k, which a separated position lacks, so the layer stays at 0,0 (warnings).
  • A separated position ignores z (warnings).
  • A separated position with an x gives the layer an animator, so its keyframes animate on any layer. Without x, keyframes in y are problems on a layer with no other animation.

Static values and keyframes

Form Example
Static number {"a":0,"k":100}
Static vector {"a":0,"k":[100,100,100]}
Animated {"a":1,"k":[ keyframes ]}

A raw number or list cannot replace the property object.

Value shapes

  • Scalars on layer transforms, solid fills and strokes, group transforms and trims also accept nested lists, such as k:[[100]]. The first item at each level counts.
  • Rectangle roundness r, star radii and rotation, and a rectangle's, ellipse's or star's p and s take plain numbers: write [280,100], not [[280],[100]]. A stroke width is one plain number (strokes).
  • Position, anchor and scale take two or more numeric components, which can use the same scalar wrappers. The first three are used, and a third must be a number.
  • Rotation and opacity use the first number of a list.
  • Keep the original dimensions when you edit.

The animation marker a

Write "a": 0 with a fixed value, and "a": 1, the whole number, with keyframes.

  • A static value may also leave a out, or use null or false, so {"k":100} is valid. A stroke width w is the exception: it needs a (strokes).
  • Never mark a static value true or another nonzero number.

Which layers can animate

Keyframes whose values change run on the layer's animator. A shape layer always has one. Any other layer has one when a property directly in ks has "a": 1 or an expression, or when its position is separated with an x. A text layer also has one with text animators (t.a) or animated path margins, and a video layer when its tm has "a": 1. Effects and layer styles give the layer one for its transform values other than opacity. Animated masks don't.

So write every keyframed value with "a": 1. Keyframes that all hold the same value read as that value.

Keyframes

{"a":1,"k":[
  {"t":0,"s":[100,180,0],"e":[300,180,0],"o":{"x":0.33,"y":0},"i":{"x":0.67,"y":1}},
  {"t":30,"s":[300,180,0],"h":1}
]}
  • Order keys by increasing t. Equal times are allowed.
  • A key's s starts its segment, and the next key's s ends it: edit that one to change where a segment ends. e is ignored, except that a last key without s takes the previous key's e.
  • Preserve terminal keys.
  • Scalar keys usually use one-element lists, such as s:[100], though a static scalar is k:100. Where only the first key is read (rectangle roundness, star radii and rotation, mask opacity), the one-element list is required.
  • h:1 holds instead of interpolating. h:0 holds too, so leave h out for an interpolating segment.
  • o and i are temporal Bezier easing handles, with x and y as numbers or component lists. to and ti are spatial tangent offsets. Don't confuse them with a path's o and i vertex tangents.
  • Preserve easing and dimensions unless the change is to the motion itself.

To move an animation 40 pixels right, add 40 to every authored position s[0] (or separated X value). Add it to any e[0] too, so it keeps matching the next s. Leave t, easing and relative spatial tangents unchanged. When you scale a motion path, scale its tangent offsets too. Don't edit only the last key to move the whole animation. Replace a whole track only when the new one holds every key to keep, or the user wants static motion.

Path morphs

A morphing path uses s:[pathObject] on every key. Keep vertex count, vertex order, closure and tangent topology the same, and don't interpolate between unrelated structures.

Edge cases

  • On a layer transform, a mask or a time remap, a value the engine cannot read is reported in problems, which name it. That covers a bare whole number, keyframes that are not objects, and "a": 1 over a single value.
  • A list where a plain number belongs is misread: rectangle roundness, star radii and rotation, and rectangle, ellipse and star p and s. A list stroke width drops the stroke.
  • "a": 1 with a missing or empty k:
    • is dropped on layer transform values, fill and stroke values, group transforms and trims
    • cannot be read (problems) on a mask's pt, o or f, a path's ks, rectangle, ellipse or star geometry, and a gradient's s, e or o
  • Under "a": true or "a": 2, a fixed value fails (problems) on layer transforms, fill and stroke values, group transforms, trims, and rectangle, ellipse or star geometry.
  • On a path's ks, a gradient's s, e and o and a star's pt, only "a": 1 counts as animated. Under true or 2, the fixed value is used.
  • Keyframes that change, in a value the layer has no animator for: problems.
  • A track whose times go backwards is dropped (warnings). An e that differs from the next key's s is listed in warnings.
  • If a morph's keys differ in vertex count or closure, the engine drops the whole morph and draws the first key throughout (warnings). That holds for shape and mask paths alike. The engine compares only the encoded length. A closed path of n vertices and an open one of n + 1 still morph, with the first key's closure.

Keyframes under other markers:

Property Keyframes under 1 Under true, another nonzero whole number, null or no a Under 0, false or 1.0
Layer transform values, separated position components, a video's tm Animate Animate on a layer that already has an animator; problems otherwise, and always on a video's tm Dropped
A mask's pt, o or f; a precomposition's tm Animate, except a mask's feather f, which keeps its first keyframe's value Read as one fixed value; true reads as 0 Read as one fixed value
A path's ks Animate The path draws empty; true reads as 0 The path draws empty
Rectangle, ellipse and star geometry; fill and stroke values; group transforms; trims Animate, except a stroke width w, which then draws at no width Animate, except a stroke width w, which draws at no width Dropped
Camera zoom pe, and other values the engine reads as fixed numbers Marker ignored Marker ignored Marker ignored
Gradients Never animate (gradients) Never animate Never animate

Where keyframes read as one fixed value, a mask path draws empty, so an add mask hides the layer. Mask opacity and feather then read as arbitrary numbers, and a precomposition holds its first frame. Where shape keyframes are dropped, geometry is misread from the keyframe list. The other values keep their defaults: white, fully opaque, no transform, untrimmed. warnings name the cases the engine drops or misreads.

Shapes and paints

Shape layers (ty:4) hold their items in shapes. A group lists its paths, then the paints that draw them, then its transform. This group draws a rounded blue plate:

{"ty":"gr","nm":"Plate","it":[
  {"ty":"rc","nm":"Plate path","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[280,100]},"r":{"a":0,"k":16}},
  {"ty":"fl","nm":"Plate fill","c":{"a":0,"k":[0.1,0.3,0.8,1]},"o":{"a":0,"k":100},"r":1},
  {"ty":"tr","p":{"a":0,"k":[0,0]},"a":{"a":0,"k":[0,0]},"s":{"a":0,"k":[100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100},"sk":{"a":0,"k":0},"sa":{"a":0,"k":0}}
]}

Shape structure

  • Supported items: sh, rc, el, sr, fl, st, gf, gs, tm, and top-level gr groups ending in a tr transform. Loose top-level items work too, and every top-level group renders.
  • Every item, in shapes or a group's it list, is an object with a text ty. Every animatable value is a property object, such as "c":{"a":0,"k":[1,0,0]}.
  • A fill or stroke paints the paths before it in its own group only. A paint before every path is ignored, and paths after every paint are dropped.
  • A shape layer needs a path followed by a fill or stroke that draws, or the engine stops and the render fails (problems). A stroke the engine drops (strokes) does not count.
  • A group draws at most 10 paths and 8 paints. The rest are skipped, each in warnings with its layer and group. The limits apply to each sibling group, and to the loose items, separately: spread more filled shapes that share motion over sibling groups.
  • Nested gr groups don't render: flatten them.
  • Group transforms animate independently in one layer. Split shapes into layers only when masks, effects, matte roles, visibility or compositing need it.

Paint order

  • Top-level groups are stored front to back: an earlier gr paints over a later one, so put foreground details first.
  • Loose top-level items form one more untransformed group in front of every gr, wherever they sit. Wrap them in a gr to place them in the stack.
  • Each paint applies to all the paths before it in its group. Paints draw in reverse order, so an earlier fill can cover a later fill's details.
  • Give independently colored elements their own sibling groups, each with geometry then paints, such as a colored symbol before its white panel. Share a group only to share paint on purpose.
  • A fill (fl or gf) paints all the paths before it together, holes included. Keep a compound contour's winding and shared fill in one group: splitting the outer contour from its holes changes the result.

Shape items

Item Property Type Default Notes
rc rectangle p, s property: [x,y] Required Center and [width,height]. Animatable.
r property: number Required Corner radius, which needs no rounded-corner modifier. Animatable.
d whole number 1 Direction (codes)
el ellipse p, s property: [x,y] Required Center and size. Animatable.
d whole number 1 Direction, which sets the winding
sr star or polygon sy whole number Polygon Star or polygon (codes)
pt property: whole number Required Point count, 3 to 300. Static.
p property: [x,y] Required Center. Animatable.
r property: number 0 Rotation in degrees. Animatable.
or, ir property: number 0 Outer and inner radius. A polygon ignores ir. Animatable.
sh path ks property: path {c,i,o,v} Required The vertices (paths). Animatable.
fl fill c property: RGB, 0–1 White A fourth component is ignored: use o for transparency. Animatable.
o property: number 100 Opacity, 0–100. Animatable.
r whole number 1 Fill rule
st stroke c, o as fl White, 100 Color and opacity. Animatable.
w property: number Required Width, never animated (strokes)
lc, lj whole number 1, 1 Cap and join
ml number 4 Miter limit
gf gradient fill, gs gradient stroke t, s, e, o, g Gradients. gf also has a fill rule r, and gs the w, lc, lj and ml of st.
tm trim s, e, o property: number Required Start, end and offset (trim paths). Animatable.
tr group transform p, a, s, r, o, sk, sa property No transform Position, anchor, scale, rotation, opacity, skew and skew axis. Animatable. Group opacity fades solid fills and strokes, not gradients.

Stroke width, star point count and gradients are static: a:1 does not make every property animatable. Star roundness is and os is ignored, so edges are straight.

Plain codes

Plain codes are whole numbers, not property objects:

Code Values Default
d direction 1 normal; any other value reverses the path Normal
sy star type 1 star; any other value polygon Polygon
r fill rule 1 nonzero, 2 even-odd Nonzero
t gradient type 2 radial; any other value linear Linear
lc cap 1 butt, 2 round, 3 square Butt
lj join 1 miter, 2 round, 3 bevel Miter

Strokes

Solid and gradient stroke widths are a fixed positive number with an explicit static marker "a": 0 (or false or null), such as "w":{"a":0,"k":5}. A width of 0 or less draws nothing.

Paths

Bezier paths live in the sh item's ks.k, never beside ty:

{"ty":"sh","nm":"Triangle","ks":{"a":0,"k":{"c":true,"v":[[0,-50],[50,50],[-50,50]],"i":[[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0]]}}}
  • v holds local vertices. i and o are incoming and outgoing offsets relative to each vertex, not absolute control points. Supply lists of equal length. Zero offsets make straight segments.
  • c closes the path when it is true or a nonzero whole number.
  • For compound holes, keep the winding and fill rule across the paths that share a fill.

Gradients

{"ty":"gf","nm":"Blue gradient","t":1,"r":1,"s":{"a":0,"k":[-140,0]},"e":{"a":0,"k":[140,0]},"o":{"a":0,"k":100},"g":{"p":2,"k":{"a":0,"k":[0,0.1,0.3,0.8,1,0.5,0.8,1,0,1,1,1]}}}
Property Type Default Notes
t whole number Linear 2 radial, any other value linear
s, e property: [x,y] Required Start and end in local pixels: a fixed list of two numbers, or a first keyframe s holding one
o property: number 0, transparent (warnings) Paint opacity, 0–100: a plain number such as k:100, or when animated a one-element first keyframe s:[100]
g object White (warnings) p is the color stop count, at most 16. k is a property object holding four numbers per color stop, then at most 16 opacity stops of two.
r whole number Nonzero gf only: the fill rule
  • g.k holds four numbers per color stop (position, R, G, B), then optional opacity stops as position/alpha pairs with their own positions. Keep g.p equal to the number of color stops.
  • Keep stops ordered from 0 to 1. The engine holds the first stop's color before its position and the last one's after, and blends the first pair around each point.
  • Geometry is in local pixels. Color, stop position and stop alpha are 0–1, and paint o is 0–100. To recolor, change only the RGB entries.
  • Gradients are static: s, e, o and the stops are read once, for the whole render. They come from the first frame, or the first keyframe's s when a is 1. To change one over time, fade between two layers with different static gradients using layer opacity.
  • Group opacity o does not fade gradients.
  • Radial gradients are always centered: highlight length h and angle a are ignored.
  • The ADBE Ramp effect is separate (effects).

Trim paths

  • s and e are 0–100 percent of the path's length, and o is an offset in degrees. All three can animate.
  • A trim is skipped when more than one path (sh, rc, el or sr) is listed before it in its group (warnings). So m (trim multiple shapes) has no effect.
  • Put the trim right after its single path in the same group. For several Trim Paths reveals, give each trimmed path its own sibling group, with its paint and tm. A single loose top-level path, paint and trim needs no group.
  • A stroke trim draws the span from start to end. A fill trim rebuilds the contour.
  • A fill trim on a rectangle with rounded corners fills the whole path and ignores the trim (warnings). The engine cannot measure any roundness r other than a static 0. Set r to {"a":0,"k":0}, or draw it as a path sh.

Shape features that do not render

Feature What the engine does
Repeater rp, merge paths mm, rounded corners rd, offset paths op, pucker and bloat pb, zig zag zz, twist tw, any other unsupported item Draws the shape as if it were not there
Stroke dashes (d on st or gs) Draws a solid line
A fill's or stroke's blend mode bm Paints it normally
hd on a shape item Ignores it: a hidden item still draws, and a hidden trim still trims

Each is listed in warnings. Express the required geometry as supported paths, using sibling groups where transforms or paints differ. Preserve unsupported source data during unrelated edits, rather than silently deleting it.

Edge cases

Written as Result
An item 5 or without ty; "it":5; "c":5; "w":4; a rectangle without s Unreadable, and the render fails (problems)
A marker that does not match the value (static values and keyframes) The render fails (problems)
No a, with a k that is neither the value nor keyframes, such as "c":{"k":"#ff0000"} or "c":{"k":[1]} The render fails (problems)
An it of {}, 0, false or "" An empty group (warnings)
An animatable value written 0, true, false, or a number such as 4.0 Missing: the default is used, and named in warnings
A nested gr Skipped with everything in it (warnings)
A plain code with a decimal point or exponent, such as 2.0 Reads as 0 (warnings): a reversed path, a polygon, nonzero winding or a linear gradient. A join reads as no corner joins. A cap reads as the cap of another stroke on the same paths, or butt when there is none.
A cap or join above 255 The engine reads its lowest 8 bits, so 257 is 1. A cap or join it does not read as 1, 2 or 3 is in warnings.
A miter limit ml that is not a number An unpredictable limit (warnings)
A star point count with a fraction, such as 5.7 The fraction is dropped: 5 points
A star point count that is animated or outside 3 to 300 The star or polygon is skipped (warnings)
Nonzero star roundness is or os Straight edges (warnings)
A path c of 1.0 or a text Reads as false: the path draws open (warnings)
A group whose paths all reach past 1,000,000 units in its own coordinates, before its transform, where misread geometry usually lands Not drawn. On a layer with effects or layer styles, it still draws.
A fill trim whose span reaches past three lengths of its path (s and e far outside 0–100) Fills the whole path and ignores the trim. Keep s and e within 0–100.

A stroke width w:

w written as Result
{"a":0,"k":5} Draws at that width
Animated, or without a Draws at no width (warnings)
Missing, or a static w that is not a single number The stroke is dropped (warnings)
A value that reads as empty, such as 0, 4.0, true or false Draws at no width (warnings)
A bare number, such as "w": 4 The render fails: problems

A gradient:

Written as Result
s or e missing The render fails (problems)
o as a list, such as k:[100] Misread
g.p as 2.0 0 color stops, so white (warnings)
Non-numeric stops Unpredictable colors or positions (warnings)
Over 16 color or opacity stops, or fewer than four numbers per color stop in g.k ("p":2 with 7 numbers, or a negative p) The render fails (problems)
Stops out of order A different ramp (warnings)
Animated The first frame's values for the whole render (warnings)
A group opacity o that would fade it The gradient does not fade (warnings)
A nonzero radial highlight Ignored (warnings)

Text and fonts

A text layer (ty:5) shows the copy of its first text document. This is a layer's t, with fonts.list holding {"fName":"Montserrat-Bold","fFamily":"Montserrat","fStyle":"Bold"}:

{"d":{"k":[{"t":0,"s":{"t":"Summer sale","f":"Montserrat-Bold","s":48,"lh":56,"ls":0,"tr":0,"j":2,"fc":[1,1,1]}}]},"a":[]}
  • The copy is at /layers/{arrayIndex}/t/d/k/0/s/t, or the same pointer in a precomposition. The layer's nm does not change it.
  • Text document properties are plain values, not {a,k} property objects.
  • Only the first document, t.d.k[0], is read: later document keyframes change neither the text nor the font. Font, size and paragraph settings belong there. For changing captions, use separate text layers with distinct visibility intervals, not document keyframes.
  • t.a holds the text animators. Write [] without any. With animators, write t.m too.
  • The render stops (problems) unless t.d.k[0].s is an object holding copy t with a visible character, and font f. The font must be declared in fonts.list, and be in the version or the font library.

Fonts

  • Find the available fonts before you choose the typography: GET /v1/fonts, or MCP list_fonts. Each library font has a ready declaration for fonts.list. Don't assume the example's font exists. For another typeface, add its file to the version (Fonts).
  • f matches fonts.list[].fName exactly, including case and whitespace.
  • Declare every font you use with its actual fName, fFamily and fStyle. Keep fPath absent or empty, and never write machine paths.
  • An unused declaration needs no font file, but every entry, used or not, needs a text fName.
  • Use text layers and fonts for all copy. Don't convert glyphs to shapes or images to get around font discovery. Animate text with text animators, or an expression selector when the animation needs expressions.

Text document fields

Property Type Default Notes
t text Required The copy. \r, \n and ETX (\u0003) each break the line: write one per line break. At most 64 lines and the first 16,383 characters draw.
f text Required Font name, matching a fonts.list[].fName
s number 0 Font size in pixels
lh number 1.2 × s Line height in pixels. 0 or less also means 1.2 × s.
ls number 0 Baseline shift in pixels
tr number 0 Tracking in thousandths of an em: at size 40, tracking 100 adds 4 pixels per glyph. Preserve it for copy-only edits.
j whole number 0, left 0 left, 1 right, 2 center. Any other value, such as After Effects' justified paragraphs (3 to 6), renders centered.
dir whole number The first character with a strong direction decides 1 lays the text out right to left, any other value left to right
fc list of 3 numbers None RGB fill, 0–1. Without it, a stroked text draws only its outline, and unstroked text fills white.
sc list of 3 numbers None RGB stroke, 0–1. A stroke needs sc and sw.
sw number None Stroke width in pixels. 0.01 or less draws no stroke. Text strokes always have round caps and joins.
of boolean false true draws the stroke over the fill, otherwise it draws behind
sz list of 2 numbers None Paragraph box size [width,height] (point and paragraph text)
ps list of 2 numbers Required with sz The box's top-left corner [x,y]
ca whole number None Not applied: All Caps and Small Caps (ca 1 and 2) render text as t is written. Write "WOMEN\rSHOES", not "women\rshoes" with ca: 2.

Write s, lh, tr and j explicitly: a missing one is listed in warnings.

Point and paragraph text

Point text has no sz or ps. j: 2 centers it horizontally only: it still sits on a baseline, not centered vertically. Measure the rendered glyph bounds when you align text to a plate or logo.

Paragraph text sits in a box:

  • ps is in the layer's own coordinates, like its anchor ks.a. With a:[0,0,0], the box's top-left corner sits ps from the position p. To center a W × H box on p, use a:[0,0,0] and ps:[-W/2,-H/2].
  • Text is top-aligned, and j aligns lines within the box width. There is no vertical alignment: to center a block vertically, size the box to the text or move ps.
  • Lines wrap at the box width after a space, - or /. A word wider than the box breaks where it overflows.
  • A letter wider than the box ends the text there: nothing from it on is laid out.
  • A line draws while at least half its lh fits in the box, so the last can reach half a line below it. The first line always draws.

Scripts and type styles

  • Text supports Unicode, mixed right-to-left and left-to-right layout, and the font's metric kerning by default.
  • Use the real bold or italic font face, not faux styles.
  • Don't rely on document-level text scaling, custom kerning, ligature switches, inter-character blending or emoji.
  • Scale glyphs with an animator's scale, or the whole block with the layer transform.
  • Check multilingual and mixed-direction copy visually with the exact font: glyph coverage alone does not prove correct shaping or layout.
  • For a decorative symbol the font can't show, use an image, and keep the copy around it as text.

Fit text to a layer

Add t.textFit to fit the text to a layer in the same composition:

{"wrap":true,"shrink":"toFit","grow":"none","region":{"source":"layer","ref":"Plate","margin":10},"minSize":12,"maxSize":48}
Property Type Default Notes
wrap boolean false true wraps the text into the region. false fits one width.
shrink text None Any text but "none" shrinks, such as "toFit"
grow text None Only "toFill" grows
minSize number 1 The smallest size when shrinking
maxSize number None The largest size when growing. Without it, growth stops at the region height with wrap: true, and has no ceiling with wrap: false.
region.source text Required "layer". Inline fitting has no box, rect or originalBounds sources: those belong in a version's text_fitting.json. An applied rule there replaces an inline one on the same layer.
region.ref text Required The name of a shape, solid, image, video, 3D model, precomposition or adjustment layer in the same composition. The first layer in layers with that name counts, skipping audio layers.
region.margin number 0 The margin inside the region

The engine reads no other fields. Set wrap, shrinking, growth and limits explicitly.

  • wrap: false fits the width only, from the widest line before wrapping. The size can have a fraction, and the text keeps its placement.
  • wrap: true picks a whole-pixel size, rounded down. With shrinking or growth, it is the largest size whose wrapped lines fit the region within the limits. Otherwise it is the text's own size.
  • With wrap: true, lines break after a space, - or /, and at each line break, which stays single. A size that cuts a word does not fit.
  • With wrap: true, the block is centered vertically in the region and aligned by j: left (0), right (1) or center (2). Preserve j unless the design needs another. Moving only the layer's anchor or position is compensated.
  • With wrap: true, the engine writes its line breaks into the text. So a "lines" selector and line grouping follow the fitted lines. Text past the line limit, or past a letter wider than the region, is dropped.
  • Text that does not fit at the smallest size the fit allows (minSize when it shrinks, otherwise its own size) overflows, and a word wider than the region is broken.
  • The fit runs once, when the composition loads. It uses the two layers' position, anchor and scale as written, not their animation, rotation or parenting. It fits the current text, not replacement copy.
  • At most 15 fit directives apply per composition, in layer order.
  • Preserve referenced layer names, make sure the layer exists, and check the rendered placement, including parent transforms and depth.

On paragraph text the box still applies: wrapping at its width, alignment in it, and clipping at its height. With wrap: true, the box's top-left corner moves to where the engine would anchor centered point text. That is the region's left edge, center or right edge by alignment, at the first line's baseline. So the block sits lower than centered, and further right for center or right alignment: fit point text. If a fit could leave paragraph text nothing to draw in its box, Blitframe leaves the fit out (warnings). It does the same when it cannot tell the fitted size.

Text animators

Text animators go in t.a, a list of objects. Each has a, its properties, and s, a selector object or list. This animator makes the selected first half of the text transparent. Animate the selector boundaries for a reveal:

{"a":{"o":{"a":0,"k":0}},"s":{"t":0,"r":1,"b":1,"m":1,"sh":1,"s":{"a":0,"k":0},"e":{"a":0,"k":50},"o":{"a":0,"k":0},"a":{"a":0,"k":100},"ne":{"a":0,"k":0},"xe":{"a":0,"k":0},"sm":{"a":0,"k":100}}}

With animators, also supply t.m:{"g":1,"a":{"a":0,"k":[0,0]}}. Properties can be static or keyframed, and the selector sets how strongly they affect each element. A property left out leaves that aspect unchanged:

Property Type Notes
p property: 3 numbers Position offset in text-local pixels, such as [0,24,0]
a property: 3 numbers Anchor point offset in text-local pixels. It moves the point each element scales, rotates and skews about, from where t.m puts it. Without scale, rotation or skew, it shifts the elements by minus its value.
s property: 3 numbers Scale in percent: [100,100,100] is unchanged
r property: number In-plane rotation in degrees
rx, ry property: number X and Y rotation in degrees, as a flat projection without perspective: elements narrow or flatten about their anchor, they do not recede
o property: number Target opacity in percent: 0 makes fully selected elements transparent. It fades the fill and the stroke together.
fc property: RGB, 0–1 Fill color. The stroke keeps its own color.
sc property: RGB, 0–1 Stroke color
t property: number Added tracking in text-local pixels, a different unit from the document's tr
ls property: 2 numbers Line-spacing offset [x,y] in pixels, not the document's baseline shift ls
sk, sa property: number Skew, limited to ±70°, and skew axis, in degrees
  • These belong in animators, not the text document, and an animator cannot replace the text.
  • Fill or stroke hue, saturation, brightness and opacity (fh, fs, fb, sh, ss, sb, fo, so) are not supported. Nor are stroke width sw and blur bl. warnings name each.
  • Animated tracking keeps each line's left edge in place on left-aligned text, its right edge on right-aligned text and its middle on centered text. On justified paragraphs (j 3 to 6), it keeps the left edge while the lines are centered.
  • An animator with no selector, or whose only selector is an expression that fails to compile, applies to the whole text.
  • Use a separate animator for properties that need a different selector.

t.m groups the text: g is 1 character, 2 word, 3 line or 4 all. Without t.m, animators group by character.

  • Keep its alignment t.m.a a static {"a":0,"k":[x,y]}, two numbers in percent of the group's bounds.
  • For word and line grouping, [0,0] is the horizontal center on each word's or line's baseline. For all grouping, it is on the last line's baseline.
  • Character grouping ignores t.m.a: each character turns and scales about its own center on the baseline.
  • Grouping sets the pivot scope, and the selector's b sets which elements animate.

Selectors

Each selector is an object whose t is 0 (range) or 1 (expression). A range selector's fields:

Property Type Default Notes
t whole number Required 0 range, 1 expression
r whole number 1 Units: 1 percent, 2 index
b whole number 1 Based On: 1 characters, 2 characters without spaces, 3 words, 4 lines
m whole number 1 Mode: every value adds
sh whole number 1 Shape: 1 square, 2 ramp up, 3 ramp down, 4 triangle, 5 round, 6 smooth
s property: number 0 Start, in the selected units. Animatable.
e property: number 100 End. Animatable.
o property: number 0 Offset. Animatable.
a property: number 100 Amount, in percent from −100 to 100. Animatable.
ne, xe property: number 0 Low and high easing, in percent from −100 to 100. Animatable.
sm property: number 100 Smoothness, 0–100, for the square shape (sh: 1) only. Animatable.

An expression selector has t: 1, b and a script string x, and needs no range fields (per-character expression selectors).

In a list of selectors, order matters. Range selectors add influence, clamped to −100–100%. An expression selector multiplies the influence before it by its returned percentage. So a range followed by {"t":1,"b":1,"x":"50;"} halves that range's influence, and leaves unselected characters alone. An expression selector placed first starts from full influence. This avoids separate text layers where it expresses the selection.

Text on a path

t.p.m is a zero-based index into the same layer's masksProperties. Supply the path and all its options:

{"m":0,"f":{"a":0,"k":0},"l":{"a":0,"k":0},"r":{"a":0,"k":0},"p":{"a":0,"k":1},"a":{"a":0,"k":0}}
Property Type Default Notes
m whole number None The index of one of the layer's masks
f, l property: number 0 First and last margins. They may animate.
r property: whole number 0 Static. 1 reverses the direction.
p property: whole number 0 Static. 1 makes glyphs perpendicular to the path. Without it, glyphs stand upright.
a property: whole number 0 Static. 1 forces alignment.
  • The engine uses the mask path's first keyframe: path morphs don't move the text. Use a static path.
  • The path's mask is not also a coverage mask.
  • Path text takes precedence over the paragraph box.

Edge cases

  • On a layer that never draws, text without a visible character is only in warnings.
  • A fonts.list entry without a text fName, used or not, fails the render (problems). If a name is declared more than once, the last declaration decides its font.
  • A missing s, tr or j reads as 0, and a missing lh as 1.2 times the size (warnings). So do values that are not finite numbers, and a j with a decimal point.
  • \r\n is two breaks, with an empty line between. A break at the very end adds no line. A NUL character ends the text.
  • fc or sc (with sw above 0.01) that is not a list, or is empty, fails the render (problems). So do sz or ps that is not a list, and sz without ps.
  • A missing t.a reads as [].
  • Text whose drawn lines hold no glyph stops the render (problems, or only warnings on a layer that never draws).
  • A paragraph box side of 0 or less clips no lines. The text wraps at the box width when that is positive. Otherwise it is laid out like point text: j aligns lines about the box's left edge, and the first baseline sits at its top. A negative side is listed in warnings.
  • wrap other than the boolean true does not wrap. A shrink that is not text does not shrink. A region.ref that is not text turns the fit off.
  • These fits leave the text at its own size (warnings): one past the fifteenth, one with another source, and one whose ref names no layer. So does a ref whose first match is the text itself, or any text, null or camera layer.
  • An adjustment layer is a region only when it has an ef list and positive sw and sh. Otherwise it is a plain null, and the text keeps its size.
  • The text also keeps its size when a margin leaves no room, or when the text layer's scale is 0 on X or Y. So it does with a shape region whose bounds are empty, and a size or widest line of 0.
  • A t.a that is not a list of objects fails the render (problems). So does an animator whose a is not an object.
  • A property or selector value written bare, instead of {"a":0,"k":value} or keyframes, fails the render (problems).
  • t.m.g outside 1 to 4 is clamped. With animators, a t.m that is not an object, or a t.m.a that is not an object with a k list, fails the render (problems).
  • A selector that is not an object, or a list of selectors with a t other than 0 or 1, fails the render (problems).
  • m reads every value as additive. sh of 0 or outside 1 to 6 reads as square.
  • An expression selector x that is not a string cannot run, so the selector is skipped (warnings). After Effects exports a selector without x when it reduces the expression to a constant. That one is skipped too, so the animator applies through its other selectors, or to the whole text when it has none (warnings).
  • Text on a path: any nonzero whole number in r, p or a turns the option on. true and 1.0 read as 0. A missing option reads as 0.
  • Text on a path: an m that is not a whole-number index of one of the layer's masks lays the text out without the path. So does a mask path with no length, such as one whose points and tangents all meet in one spot.
  • A whole-number m reads masksProperties whatever hasMask says. The render fails (problems) when that is not a list of mask objects, or when the named mask's pt is not an object. So it does when an option f, l, r, p or a is present but not an object.
  • An empty t.p:{} does not turn on text on a path.

Media and precompositions

An image or video asset, which a layer shows with refId:"image_1":

{"id":"image_1","w":1200,"h":800,"u":"images/","p":"hero.png"}
Property Type Default Notes
id text Required Non-empty, and unique across the document. A layer's refId names it.
u text "" The file's directory, from the version's root, where data.json lives. Leave it out or empty when p includes the directory.
p text Required The file. u + p is its path: u:"images/", p:"hero.png" or u:"", p:"images/hero.png". .. is not allowed. Keep directories, case and names exactly as in the version.
w, h whole number The file's size The size the file renders at, before layer transforms. A video needs them.
  • Declare the file's own size when it is at most 4096 pixels on each side. A file of another size is stretched to the declared one. For a larger file, declare its size scaled to fit 4096, and the file is scaled down to that.
  • An image without w and h renders at its file's size, scaled to fit 4096 if larger.
  • The declared size is not the size on the canvas: scale the layer for that.
  • An image layer (ty:2) needs an image, and a video layer (ty:9) a video: all video belongs on ty:9. A GIF or WebP may sit on either. An animated one plays as video, and a one-frame one shows as a still.
  • Don't embed base64 images or point to a URL.
  • When no file matches u + p exactly, Blitframe takes one that differs only in letter case. Failing that, it takes the only file in the version with that name (asset paths).
  • Model assets need no w or h (native models). Audio comes from the version's soundtrack or the render's audio (audio layers).

File formats

Images and video can be in any format Projects lists:

File How it renders
Upright, limited-range, 8-bit 4:2:0 H.264 or HEVC in MP4, at most 4096 pixels a side, not tagged BT.2020 Fastest, as it is
Other formats, and larger videos Converted on first use to H.264. Video with alpha, or with an odd width or height, becomes PNG in MOV, which decodes without hardware acceleration.
Video over 4096 pixels Scaled down to fit
Video with a rotation flag (portrait phone footage) Turned upright
Video with several video streams Plays the first stream that is not a cover image
Full-range or BT.2020 video Re-encoded with the BT.709 matrix in limited range. Colors are not converted from the BT.2020 gamut, so export BT.709.
HDR footage Not tone-mapped: export SDR.
Animated GIF or WebP on an image layer Plays as video: its frames play once from the layer's st (its in point when st is missing), then the last frame holds. It draws at the declared w × h, or its own frame size without one.
PSD Its merged composite image
16-bit or interlaced PNG, PNG with gray+alpha or tRNS transparency, TGA Converted to an 8-bit RGBA PNG first
JPEG that is not 8-bit baseline, extended or progressive (such as lossless, arithmetic-coded or 12-bit) Converted to an 8-bit PNG
JPEG, PNG or TGA with EXIF orientation Orientation not applied: export these upright.
Other stills with EXIF orientation, such as WebP, AVIF, HEIC, TIFF, BMP and PSD Turned upright
Video with alpha in ProRes 4444, Apple RLE (QuickTime Animation) or PNG, in a MOV or MP4 at most 4096 pixels a side Keeps its alpha
Other video with alpha, such as VP8 or VP9 WebM, or a larger file Converted to PNG in MOV, keeping its alpha

Export video with alpha as Premultiplied (Matted) alpha against black, whatever its container. data.json has no switch for straight alpha, which composites incorrectly. WebM alpha is the exception: it is straight by definition, and its conversion premultiplies it.

Video timing

A video that appears part way through plays from its first frame when the layer's st equals its ip. This layer appears at 1 second (frame 30 at 30 fps) and starts the clip there:

{"ty":9,"ind":2,"nm":"Clip","refId":"video_1","ip":30,"op":150,"st":30,"sr":1,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}}}
  • With st: 0, it would show the clip from its 1-second mark, as if it had played unseen since frame 0.
  • With st later than ip, the video does not wait: it plays from its beginning at ip, as if st equalled ip.
  • A video layer plays forward once, with no looping or time stretch. After its last frame, that frame stays on screen until the layer's op.
  • To hold a frame or play backwards, use time remap on the video layer.

Replace or place media

  • To replace media by hand, add the new file and update the asset's u, p, w and h and its references together. Every referenced file must exist in the version.
  • New pixels may need a new anchor, scale and crop: w and h alone don't place the subject.
  • For an unrotated iw × ih image filling a bw × bh box, contain scale is 100 * min(bw/iw,bh/ih) and cover scale is 100 * max(bw/iw,bh/ih). Use contain for a whole logo or hero silhouette, and cover for a full-bleed background when asked.
  • Cover does not crop by itself. Transparent padding changes the visible bounds, and parent transforms change these numbers: work from the visible subject, in its own coordinate space.

Precompositions

A precomposition asset needs id, a text nm and a layers list:

{"id":"scene_1","nm":"Scene 1","layers":[]}
  • Put nm on the asset itself: the referring layer's name does not replace it. Include real child layers for visible output.
  • The referring ty:0 layer needs refId:"scene_1", positive whole-number w and h, transforms and timing, and optionally st and sr.
  • Keep asset ids unique across the document, and references non-recursive.
  • Use a precomposition only for a shared treatment or clipping (choose a representation). Children keep their local coordinates and their own animation.
  • The layer's w and h set the clipping frame. Scaling the layer scales the frame and its content, not the child canvas.
  • A precomposition layer wider or taller than 4096 pixels draws through a 4096 by 4096 work area, so the part beyond it is undefined (warnings).
  • Each reuse shares the contents but places a separate instance. Each instance that is not collapsed counts toward the precomposition limit.
  • Collapse transformations (cp: true) draws the layers straight into the parent with only the layer's transform. The layer's opacity and blend mode are not applied, and its content is not clipped to its w × h.
  • A layer does not collapse when it has masks (hasMask: true), effects, layer styles (sy) or a matte role (tt or td). Blitframe warns about a collapse in both cases.
  • Timing: time and time remap. One instance of a shared asset: stacking and references.

Edge cases

  • With a repeated id, the engine uses the first declaration (warnings).
  • An image, video or model file asset without a text id: problems. So is any asset without one ahead of the asset a precomposition layer uses.
  • The engine skips an image or video asset whose w or h is over 4096, or whose p is a data: URI (warnings). It does so even if the upload was accepted. An image or video layer that shows it: problems.
  • A layer whose refId names no asset, a precomposition, an audio file, a file of the other kind, or a skipped asset: problems.
  • An asset w or h written 1920.0 reads as 1920.
  • A video asset without w and h: warnings.
  • A precomposition asset without a text nm fails the render (problems). So does a precomposition that contains itself.
  • A precomposition layer whose refId matches no asset id, or whose tm the engine cannot read, such as a bare whole number: problems.
  • A precomposition layer's w or h written with a decimal point reads as the number its low 32 bits hold, usually 0 (warnings).
  • cp collapses when it is true or a nonzero number.

Native models

Add a .glb file, or a self-contained .gltf file, to the version. Declare it as an asset with id, u and p, like an image, but with no w, h or t. A ty:16 layer whose refId names the asset draws the model. A .gltf has its buffers embedded as base64 data: URIs and its images in buffer views.

This example assumes you uploaded models/product.glb, a model about one unit across:

{
  "v":"5.12.2","nm":"Product rotation","w":1080,"h":1080,"fr":30,"ip":0,"op":90,"ddd":0,
  "assets":[{"id":"product","u":"models/","p":"product.glb"}],
  "layers":[{
    "ty":16,"ind":1,"nm":"Product","refId":"product","ip":0,"op":90,"st":0,"sr":1,"bm":0,
    "ks":{
      "p":{"a":0,"k":[540,540,0]},"a":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},
      "o":{"a":0,"k":100},"or":{"a":0,"k":[0,0,0]},
      "rx":{"a":0,"k":0},"ry":{"a":1,"k":[{"t":0,"s":[0]},{"t":90,"s":[360]}]},"rz":{"a":0,"k":0}
    }
  }]
}
  • One glTF unit (one metre) is 512 composition pixels, times the layer's scale.
  • The GLB's origin is the layer's own (0,0,0). With anchor ks.a at [0,0,0], it lands on the layer's position. A nonzero anchor, in those pixels, is the pivot ks.p places. The engine does not recenter the model.
  • glTF's up (+Y) points up the composition.
  • Lighting is fixed: a built-in studio environment lights every model the same way. There are no lights, exposure or environment settings, and lights or cameras in the GLB are not used.
  • The layer's 3D transforms move and turn the model, animated or static: three-component position, anchor and scale, rx, ry, rz and or. So does the composition camera. Without a camera layer, the default perspective camera shows the model, not an orthographic view.
  • Each model layer draws in its own pass. Model layers don't hide each other, or 2D layers, by depth: they stack by ind like other layers. Put parts that must pass through each other in one GLB.
  • A model layer takes its layer opacity, blend mode and track matte. It draws no effects or layer styles (warnings).
  • Masks on a model layer may not apply. To clip a model, use a track matte, and render a frame to check.
  • Each model asset loads once, however many layers show it, and takes one mesh. Two asset ids naming one file load it twice. Its textures count toward the texture limit.

What the engine draws

Part of the GLB Drawn
Meshes The triangle meshes of the default scene, with their node hierarchy. Without a default, the first scene draws, and a file with no scenes draws every root node. A node that repeats a mesh draws it again. Only triangle lists draw: points, lines, strips and fans are skipped.
Materials Metallic-roughness: base color, metallic and roughness factors and textures, normal maps, occlusion, emissive color and texture (with KHR_materials_emissive_strength), OPAQUE, MASK and BLEND alpha, and double-sided materials
Transparency MASK discards texels below the cutoff but keeps the alpha of the rest, so they draw partly transparent, not opaque. BLEND surfaces are not sorted back to front, so overlapping transparent parts can hide what is behind them.
Textures Embedded PNG or JPEG images, read with TEXCOORD_0, linear filtering and mipmaps. The sampler's horizontal wrap applies in both directions: clamp-to-edge clamps, and any other wrap, or no sampler, repeats.
Texture coordinates A texture that names another coordinate set still draws, with TEXCOORD_0. A primitive without TEXCOORD_0 shows one texel of each texture.
Normals, tangents From the file. A mesh without normals gets flat ones. Tangents come from the file only together with its normals, and are generated otherwise.
Animations, skins, morph targets Not played: the model renders in the pose the file stores, without its default morph weights
Vertex colors, other texture coordinate sets, texture transforms, other optional extensions Ignored

The engine reads an image stored in a buffer view, in the GLB's binary chunk or in an embedded base64 buffer. The image's mimeType must be image/png, image/jpeg or absent. The engine decodes PNG, JPEG, BMP, TGA, PSD, PNM, Softimage PIC and Radiance HDR content.

A texture the engine cannot read is left out, and the model still renders. That covers an image with another mimeType or that is not valid, and an image given as a data: URI. It also covers an image the decoder cannot hold: over about 41.9 megapixels (such as 8192 × 8192), or about 21 for a 16-bit PNG. Nothing reports these, so check the textures before you add a GLB, and keep each at most 4096 pixels a side.

Models Blitframe refuses

Blitframe checks a model when you add it, and refuses a GLB the engine cannot load:

  • not a valid GLB container of glTF version 2 or later, a truncated GLB, or empty JSON
  • a key repeated in one JSON object
  • a buffer whose URI is not a base64 data: URI holding its size, or without a positive byteLength
  • a buffer view outside its buffer, or a first buffer larger than the binary chunk
  • an image linked by URI to another file, or by a data: URI that is not valid base64
  • accessors outside their buffer view, or that break glTF's accessor type and sparse storage rules
  • index values outside their primitive's vertices (or their sparse accessor's elements)
  • index data that is interleaved, or not unsigned byte, short or int scalars
  • a primitive mode above 6
  • references to missing elements
  • no meshes or nodes, or a mesh without primitives
  • vertex attributes of one primitive with different counts
  • primitives of one mesh with different morph target counts
  • a morph target whose vertex count differs from its primitive's
  • targetNames or default weights whose count differs from the morph target count
  • an animation sampler whose output count does not match its input
  • an animation sampler or channel missing its input, output, sampler or target, or a weights animation on a node without a mesh
  • a node that contains itself or has two parents, or a scene root node that has a parent
  • a required extension other than KHR_materials_emissive_strength
  • no triangles to draw
  • more than these limits:
Resource Limit
One GLB 100 MB, with its JSON at most 8 MB and nested at most 64 deep (Blitframe's limits)
One .gltf 8 MB
Drawn geometry 22,369,621 vertices and 268,435,455 indices across the drawn scene, and 67,108,863 vertices in one primitive (the engine's limits). A node counts every time the scene reaches it, up to one draw per node and primitive in the file. A mesh without normals counts one vertex per index.

Edge cases

  • A model layer without a text refId: problems. So is one whose refId names no asset, an asset without a file p (such as a precomposition), an asset whose p is a data: URI, or an asset that is not a .glb or .gltf file in the version (such as an image).
  • A model the engine cannot load stops the render (models Blitframe refuses).
  • With a repeated model id, the first declaration is used.

Masks and track mattes

hasMask: true turns on a layer's masks: with any other value, the layer draws without them. Each masksProperties entry is one mask:

{"nm":"Window","mode":"a","inv":false,"pt":{"a":0,"k":{"c":true,"v":[[0,0],[200,0],[200,100],[0,100]],"i":[[0,0],[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0],[0,0]]}},"o":{"a":0,"k":100},"f":{"a":0,"k":[0,0]}}
Property Type Default Notes
mode text Required a add, s subtract, i intersect, f difference. n (none), lighten l, darken d and other values are skipped.
inv boolean false true inverts the mask
pt property: path Empty The path, with the same tangent and topology rules as a shape path. It may animate.
o property: number 0, transparent Opacity, 0–100. Fixed, a plain number: {"a":0,"k":100}. Animated, a list such as [100] in each key's s.
f property: [x,y] Required Feather in pixels, drawn as a static blur. When animated, it keeps its first value.
x property None Expansion. Ignored (warnings).
  • Mask coordinates are local to the masked layer.
  • Keep one entry per mask, in authored order. A layer can have any number of masks: use the fewest that express the region, since each add, subtract, intersect or difference mask counts toward the path limit.
  • A layer whose masks are all skipped draws unmasked.
  • Write an explicit numeric a:0 or a:1, and complete path and opacity objects.
  • To animate a mask path, replace pt with path keyframes that keep the vertex topology. Masks don't run expressions.
  • An image, solid, video or precomposition layer is masked before its effects run (effects).

Track mattes

A track matte uses two layers in the same composition. The receiver, the content, has tt and a tp equal to the caster's ind. The caster has td: 1. tt is 1 alpha, 2 inverted alpha, 3 luma or 4 inverted luma.

  • For video inside a shape, the shape is the caster and the video is the receiver.
  • Always give a tt layer a whole-number tp, or remove tt. Don't rely on adjacency, chain receivers and casters, or leave a dangling tp.
  • Mattes don't chain: a caster's own blend mode and track matte are ignored.
  • The receiver is matted only while its caster draws. The caster does not draw when it is hidden (hd: true), outside its ip and op, entirely off screen, or a null or camera. Then, or when tp names no layer, an alpha or luma matte hides the receiver. An inverted matte draws it unmatted.
  • Any td, whatever its value (td: 0 too), makes its layer draw only as a matte. A td layer no receiver points at is never drawn (warnings).
  • Don't use a precomposition collapsed with cp as a matte: giving it td stops the collapse.
  • To clear or move a matte role, remove the obsolete tt, tp and td: zero is not the same as removing them. Change both sides together.
  • Keep the caster's geometry, transforms and opacity aligned with the content throughout the animation.

Edge cases

  • A missing mode, or one that is not text: problems.
  • inv other than the boolean true reads as false.
  • A missing pt draws an empty mask, so an add mask hides the layer (warnings).
  • A fixed o written as a list is misread (warnings).
  • A feather of one number reads its second from beyond the list (warnings).
  • A pt, o or f the engine cannot read, such as a bare whole number: problems. So is a feather that is null or has no k.
  • A masksProperties that is not a list of mask objects while hasMask is true: problems.
  • tt written 1.0 reads as 0, no matte. The receiver is still hidden whenever its caster does not draw.
  • A caster that does not draw for part of the receiver's visible span: warnings.
  • warnings name the other cases the engine drops or misreads.

Blend modes and effects

A layer's bm sets its blend mode:

bm Mode bm Mode bm Mode
0 normal 9 soft light 18 linear burn
1 multiply 10 difference 19 darker color: renders as normal
2 screen 11 exclusion 20 linear dodge
3 overlay 12 hue 21 lighter color: renders as normal
4 darken 13 saturation 22 vivid light
5 lighten 14 color 23 linear light
6 color dodge 15 luminosity 24 pin light
7 color burn 16 add 25 subtract
8 hard light 17 hard mix 26 divide: renders as normal
  • Write bm as a whole number from 0 to 26, without a decimal point.
  • Don't choose 19, 21 or 26: they render as normal, and Blitframe warns.
  • A blend mode changes how the layer mixes with the content below. It does not replace a transparent asset or a matte.
  • Layer styles number their blend modes differently (style blend modes).

Effects

Effects are entries in a layer's ef list:

{"ty":21,"mn":"ADBE Fill","nm":"Fill","ef":[{"ty":2,"nm":"Color","v":{"a":0,"k":[0.1,0.3,0.8,1]}},{"ty":0,"nm":"Opacity","v":{"a":0,"k":1}}]}
  • The exact match name mn selects the effect. The display name nm may be an exported custom name.
  • The nested ef lists parameters, matched by exact English nm, not position, translated name or ix. Transform and Color Balance (HLS) match each by its own mn, such as ADBE Geometry2-0007. Never rename parameter nodes.
  • Each value is v:{"a":0,"k":...} or a supported animated property object. Preserve exported metadata and effect order. Arbitrary added color controls don't recolor pixels.
  • Colors are RGB with finite components 0–1; a fourth is ignored. Opacity units vary: Fill 0–1, Drop Shadow 0–255, layer opacity 0–100.
  • en is not read: an effect with en: 0 still renders, with a warning. Remove an effect to turn it off.
  • Masks cut the layer before its effects run, so a blur spreads past the mask edge. Layer styles come after all effects.

The engine reads every parameter in this table, and ignores any other:

Effect mn Display nm Parameters and animation
ADBE Fill Fill Animated Color RGB and Opacity 0–1
ADBE Gaussian Blur, ADBE Gaussian Blur 2 Gaussian Blur Animated Blurriness (it stops growing at about 344); static Blur Dimensions, Repeat Edge Pixels
ADBE Box Blur2 Fast Box Blur Static Blur Radius (at most 500 pixels), whole-number Iterations 1 to 50, Blur Dimensions, Repeat Edge Pixels
ADBE Drop Shadow Drop Shadow Static Shadow Color RGB and whole-number Shadow Only: 0 draws the layer over its shadow, 1 the shadow alone. Animated Opacity 0–255 (255 opaque, 128 about half), Direction in degrees, Distance in pixels, Softness.
ADBE Ramp Gradient Ramp Static Start of Ramp and End of Ramp XY, Start Color and End Color RGB, Ramp Shape, Ramp Scatter (a noise amount, clamped to 0–1), Blend With Original
ADBE Linear Wipe Linear Wipe Animated Transition Completion 0–100, Wipe Angle in degrees, Feather in pixels
ADBE Corner Pin Corner Pin Animated XY Upper Left, Upper Right, Lower Left, Lower Right (corner pins). Include all four.
ADBE HUE SATURATION Hue/Saturation Animated Master Hue and Colorize Hue in degrees, Master Saturation and Master Lightness −100–100, Colorize Saturation 0–100, Colorize Lightness −100–100; static whole-number Colorize 0 or 1. Master channel only: Channel Control is ignored.
ADBE Venetian Blinds Venetian Blinds Animated Transition Completion 0–100, Direction, Width, Feather
ADBE Glo2 Glow Animated Glow Threshold 0–255 (153 is After Effects' 60%), Glow Radius, Glow Intensity, Color Loops, Color Phase, A & B Midpoint 0–1, Color A and Color B RGB; static Glow Based On, Composite Original, Glow Operation, Glow Colors, Color Looping, Glow Dimensions
CC Power Pin CC Power Pin Animated XY Top Left, Top Right, Bottom Left, Bottom Right, number Perspective, and edge expansion Top, Left, Right, Bottom in percent; static Unstretch. Include all four corners.
CC Cylinder CC Cylinder Animated Radius (%), Position X/Y/Z, Rotation X/Y/Z, Light Intensity, Light Color RGB, Light Height, Light Direction, Ambient, Diffuse, Specular, Roughness, Metal; static Rotation Order, Render
ADBE Mirror Mirror Animated XY Reflection Center, Reflection Angle
ADBE 4ColorGradient 4-Color Gradient Animated Point 1 to Point 4 XY, Color 1 to Color 4 RGB, Blend as After Effects' number, Jitter in percent, Opacity 0–100; static Blending Mode
ADBE Tint Tint Animated Map Black To and Map White To RGB, Amount to Tint 0–100
ADBE Simple Choker Simple Choker Animated Choke Matte in signed pixels: positive contracts the matte, negative expands it. View does not change the output.
CC Light Sweep CC Light Sweep Animated Center XY, Direction in degrees, Width in pixels, Sweep Intensity and Edge Intensity in percent, Edge Thickness for edge-detection scale, Light Color RGB. Static whole-number Shape, Light Reception. The band reaches twice Width on each side of its line.
CC Radial Blur CC Radial Blur Animated Amount, Quality, Center XY; static whole-number Type. The match name is CC Radial Blur, not ADBE Radial Blur.
CC Light Rays CC Light Rays Animated Intensity, Center XY, Radius, Warp Softness, Direction in degrees, Color from Source and Allow Brightening 0 or 1, Color RGB; static whole-number Shape, Transfer Mode
ADBE Geometry2 Transform Matched by mn, all animated: ADBE Geometry2-0001 Anchor Point XY, -0002 Position XY, -0011 Uniform Scale, and -0003 Scale Height and -0004 Scale Width in percent. Also -0005 Skew in degrees (limited to ±85), -0006 Skew Axis and -0007 Rotation in degrees, and -0008 Opacity 0–100. Uniform Scale is on at 0.5 or more, and when omitted: -0003 Scale Height then scales both axes. Shutter angle and sampling settings are ignored.
ADBE Color Balance (HLS) Color Balance (HLS) Matched by mn, all animated: ADBE Color Balance (HLS)-0001 Hue in degrees, -0002 Lightness −100–100, -0003 Saturation −100–100

Author new effects from this table. Outer glow is also a layer style. Unsupported effects in existing files, and effects without mn, are skipped at render time, each with a warning, and the rest renders. A skipped effect can change the look: render a frame to check. For an essential look no supported effect gives, use supported shapes, a prepared raster or video, not an invented effect node.

Effect values

A parameter marked animated is fixed with "a": 0. It animates with keyframes under "a": 1, true, another nonzero whole number, null or no a. A static parameter is read once, as a fixed value: write a point or color as a fixed list of numbers.

A parameter you leave out takes the engine's default, which can differ from After Effects:

Effect Defaults
Gaussian Blur, Fast Box Blur Repeat Edge Pixels on (After Effects: off). Fast Box Blur: Iterations 3, Blur Radius 0.
Drop Shadow Opacity 255, opaque (After Effects: 50%), Direction 135, Distance 5, Softness 0, Shadow Only 0
Glow Glow Threshold 153, Glow Radius 10, Glow Intensity 1, A & B Midpoint 0.5, Glow Based On 2 (color channels), Composite Original 2 (behind), Glow Operation add, Glow Colors 1 (original), Color Looping 3 (triangle A>B>A)
Fill Color white, Opacity 1
Transform Anchor Point and Position [0,0], scale 100, Uniform Scale on, Opacity 100
CC Power Pin Perspective 1
Corner Pin, CC Power Pin A missing corner stays within a pixel of the top left (warnings)

A keyframed parameter, or a mask whose path, opacity or feather has "a": 1, makes the layer's whole effect stack render again every frame. The stacks of precomposition and video layers always do. Other stacks render once, which decides how they are cropped.

Effect canvas size

On image, solid, video and precomposition layers, effects run on a working canvas of at most 8192 pixels a side. That is the layer plus the room its effects add around it. Glow and Drop Shadow add room, and so do Gaussian Blur and Fast Box Blur with Repeat Edge Pixels off. Corner Pin, CC Power Pin and Transform grow the canvas to the box around the layer and the corners they move it to. They stop at 8192 and crop what lies past it, so they alone never go over: a blur, glow or shadow after them can. CC Light Rays adds no room on these layers. When the canvas would be larger:

  • A layer not drawn axis-aligned on screen draws without any effects. That means a rotation that is not a multiple of 180 degrees. It can come from the layer, a parent, a collapsed precomposition that shows it, or a rotated or two-node camera.
  • An axis-aligned layer has its effects cropped to the part that can reach the screen. Precomposition and video layers, and layers whose effect parameters or masks animate, are cropped again every frame.
  • Other layers are cropped once, at the first frame they draw, so a layer that moves later can show edges without effects.
  • When even the cropped part is over the limit, the layer draws without effects.

A masked layer whose source is over 4096 pixels a side always renders without effects. Blitframe warns in each case.

Effect coordinates

Effect points are pixel coordinates, with the origin at the top left and Y down. They are the Gradient Ramp endpoints, 4-Color Gradient points, Corner Pin and CC Power Pin corners, the Transform anchor and position, Mirror's Reflection Center, and Light Sweep, Radial Blur and Light Rays centers.

Layer receiving the effect Point coordinates
Image, solid, video or precomposition layer Local source pixels, before the layer's transform: a solid's sw × sh canvas, a precomposition layer's w × h
Text, shape or adjustment layer Pixels of the composition containing the layer, after layer and parent transforms: inside a precomposition, its canvas, not the root's
  • On text and shape layers, Corner Pin, CC Power Pin, Mirror, CC Cylinder and Transform act on the whole containing composition, not only the content.
  • Venetian Blinds bands are anchored at the layer's center on image, solid, video and precomposition layers. On text and shape layers, they are anchored at the composition's center.
  • Shape-paint gf and gs endpoints stay local to their shape group: they are not effect parameters.

Corner pins

Corner Pin maps the whole source canvas onto its four corners. For a W × H source, the unchanged Upper Left, Upper Right, Lower Left and Lower Right are [0,0], [W,0], [0,H] and [W,H].

  • On text and shape layers, W × H is the containing composition, even when the content fills a small part of it. Corners set to the content's bounds would shrink the whole canvas into them. Move the full-canvas corners to make the warp, and don't add a precomposition just to get identity corners.
  • On an adjustment layer, the source is its rectangle on screen, so the unchanged corners are that rectangle's corners, in composition pixels.

Effect dropdown values

Dropdown values are not layer blend modes. Preserve other existing dropdown codes unless you have a matching supported example.

Effect Parameter Values
Gaussian Blur, Fast Box Blur Blur Dimensions 1 horizontal and vertical, 2 horizontal, 3 vertical. Use one of these.
Gaussian Blur, Fast Box Blur Repeat Edge Pixels Whole number 0 or 1
Gradient Ramp Ramp Shape 1 linear. Any other value, such as 2, is radial.
Gradient Ramp Blend With Original 0–1: 0 uses the gradient, 1 keeps the original image
4-Color Gradient Blending Mode 1 none (the gradient replaces the layer's colors), 2 and 3 normal, 4 add, 5 multiply, 6 screen, 7 overlay, 8 soft light, 9 hard light, 10 color dodge, 11 color burn, 12 darken, 13 lighten, 14 difference, 15 exclusion, 16 hue, 17 saturation, 18 color, 19 luminosity. Others blend as normal.
Glow Glow Based On 1 alpha channel, 2 color channels
Glow Composite Original 1 on top, 2 behind, 3 or any other value none (the glow alone)
Glow Glow Colors 1 original colors, 2 A & B colors. 3 (arbitrary map) renders as A & B, with a warning.
Glow Color Looping 1 sawtooth A>B, 2 sawtooth B>A, 3 triangle A>B>A, 4 triangle B>A>B
Glow Glow Dimensions The Blur Dimensions values 1 to 3
Glow Glow Operation Only when Composite Original is 2 (behind): 1 and 2 normal, 3 add, 4 multiply, 5 screen, 6 overlay, 7 soft light, 8 hard light, 9 linear dodge, 10 and 11 color dodge, 12 linear burn, 13 and 14 color burn, 15 darken, 16 lighten, 17 and 18 difference, 19 exclusion, 20 hue, 21 saturation, 22 color, 23 luminosity. Others add.
CC Light Sweep Shape 1 linear, 2 smooth, 3 sharp; others linear
CC Light Sweep Light Reception 1 add, 2 composite, 3 cutout; others add
CC Light Sweep Direction Turns the band's normal (across its width), not the visible stripe: 0 gives a vertical stripe, 90 a horizontal one. Choose the angle, and animate Center in the layer's effect coordinates, for the highlight you want.
CC Light Rays Shape 1 round, 2 square
CC Light Rays Transfer Mode 1 none, 2 add, 3 lighten, 4 screen
CC Radial Blur Type 1 straight zoom, 2 fading zoom, 3 centered zoom, 5 rotate, 6 scratch, 7 rotate fading. 4 renders as 1, and values outside 1–7 are clamped.
CC Radial Blur Amount, Quality Amount sets pixel displacement. Quality sets sampling density together with the amount, not an exact sample count.

Edge cases

  • A bm that is not a whole number from 0 to 26 is misread, usually as normal (warnings).
  • Keyframes on a parameter marked animated are dropped under 0, false, a decimal such as 1.0 or a non-number. So is an "a": 1 whose k holds no keyframes. Each has a warning.
  • A static parameter that is keyframed, or a whole-number setting written with a decimal point such as 1.0, is misread. Each has a warning. A keyframed Glow Based On keeps its first key.
  • A point or color that is keyframed, has too few numbers or is not a list is misread, not always with a warning.
  • A parameter that appears twice is applied each time, so the last fixed value wins.
  • Blur Dimensions or Glow Dimensions outside 1 to 3 runs no blur, and leaves undefined pixels.
  • Color Looping outside 1 to 4 draws as 4, triangle B>A>B.
  • Fast Box Blur Iterations over 50 renders as 50 (warnings).
  • A negative Gaussian Blurriness reads as 0.
  • Transform Uniform Scale from 0.01 to 0.49 reads as off.
  • Hue/Saturation Channel Control other than 1 is in warnings.
  • CC Light Sweep Shape or Light Reception above 3 is in warnings.

Effects the engine cannot read at all are reported in problems, which name the layer, effect and field. Only the precompositions a layer uses are checked:

  • an ef that is not a list of effect objects, such as "ef":5, "ef":[5] or a single effect object
  • an mn or parameter nm that is not text
  • a parameter list ef that is not a list of objects
  • a parameter v that is not a {"a":…,"k":…} object of the right kind, such as "v":5, or a static point or color whose k is a number or empty list
  • keyframes on Glow's Glow Based On whose s values are bare numbers

Layer styles

Layer styles are a layer's sy list, not ef entries. Each style is an object with a whole-number ty and properties such as {"a":0,"k":5}:

{"ty":7,"c":{"a":0,"k":[1,0.2,0.1]},"so":{"a":0,"k":60},"bm":{"a":0,"k":1}}
Style Property Type Default Notes
ty:7 color overlay c property: RGB, 0–1 [1,0,0], red
so property: number 100 Opacity 0–100 (not o)
bm {"k":whole number} 1, normal Style blend mode
ty:0 stroke c property: RGB [1,0,0], red Opacity is full, blend is normal, and the stroke sits outside the layer.
s property: number 3 Size in pixels
ty:3 outer glow c property: RGB [1,1,0.75]
o property: number 75 Opacity 0–100
s property: number 5 Size in pixels
ch property: number 0 Spread 0–100, a percentage of size
r property: number 50 Range 0–100
bm {"k":whole number} 11, screen
tc {"k":whole number} 1, softer Technique: 1 softer, 2 precise
no, j None Noise and jitter are ignored (warnings when set)
ty:1 drop shadow c property: RGB [0,0,0], black
o property: number 75 Opacity 0–100
a property: number 120 Angle in degrees
d, s property: number 5, 5 Distance and size in pixels
ch property: number 0 Spread 0–100
bm {"k":whole number} 5, multiply
lc {"k":whole number} 1 Layer knocks out drop shadow. Changes nothing.
ga {"k":whole number} 0 Use Global Light is not applied: the shadow always uses its own a. Turn it off. Blitframe warns when ga is 1.
  • A field you leave out takes the value in the Default column, which is After Effects' own dialog default. Use Global Light is the exception: the shadow always uses its own a. Write every field you rely on.
  • Only these ty values render. Inner shadow, inner glow, bevel, satin and gradient overlay are skipped.
  • Colors, opacity, size, spread, angle, distance and range can be keyframed. bm and tc are static whole numbers.
  • Write every field as an object with k.
  • Image, solid, video, precomposition, text and shape layers can carry styles. A 3D model layer draws neither effects nor styles, and an adjustment layer draws no styles, with a warning for both.
  • Styles composite after the layer's effects and transform, in pixels of the containing composition. Scaling a layer does not scale its style's size, spread or distance.

Style blend modes

A style's bm.k uses its own numbers. Don't copy a layer's bm into a style: multiply is 1 on a layer and 5 on a style.

bm.k Mode bm.k Mode bm.k Mode
1 normal 13 linear dodge 22 hard mix
4 darken 14 lighter color 24 difference
5 multiply 16 overlay 25 exclusion
6 color burn 17 soft light 26 subtract
7 linear burn 18 hard light 27 divide
8 darker color 19 vivid light 29 hue
10 lighten 20 linear light 30 saturation
11 screen 21 pin light 31 color
12 color dodge 32 luminosity
  • Color overlay renders every mode in the table. On drop shadow and outer glow, 8, 14 and 27 render as normal.
  • Any other value, such as 2 (dissolve), renders as normal. Blitframe warns about a style blend mode that renders as normal.

Edge cases

  • A style the engine cannot read is reported in problems, such as "tc":2, "bm":11, "lc":1 or "c":5 written bare. So is an sy that is not a list of style objects, such as "sy":[5] or a single style object.
  • A few bm values far outside the list, such as 0.1 or -5000000, cannot render at all: problems.
  • A bm without k, or bm: null or [], reads as 0 and blends normal, not the drop shadow's multiply or the glow's screen (warnings).
  • A ty that is not a whole number is read through its bytes (warnings):
ty written as Read as
Missing, null, true, false, "", [], and many decimals such as 7.0 or 7.5 0: a stroke
A one-item list 1: a drop shadow
A negative number, most strings, and decimals such as 0.1 Skipped

Expressions

Write an expression when the caller asks for one, or when procedural motion such as oscillation, wiggle, looping or a layer dependency fits the result. It is a script string x inside one of these transform properties:

Property Notes
ks.p Position
ks.p.x, ks.p.y Separated position: each axis is a property object, and its own x member holds the script
ks.a, ks.s Anchor, scale
ks.r Rotation. Not run on a layer with rx.
ks.o Opacity. Not run on a null, a camera or a collapsed precomposition.

Expressions don't run on rx, ry, rz or or. On a layer with rx, no rotation expression runs, r included.

This adds a 30-pixel vertical oscillation with a two-second period to a position, and keeps its base:

{"a":0,"k":[944,204,0],"x":"[value[0], value[1] + 30 * Math.sin(2 * Math.PI * time / 2), value[2]];"}
  • Preserve the property's a, k and other metadata: they give its static or keyframed base and its fallback. Don't switch a static property to a:1 because its expression changes over time.
  • An expression can override the base, so changing only k may change nothing.

How to write a script

Expressions follow an After Effects-style model: JavaScript computes the value from inputs such as time and value. Only what this section describes is supported. Don't assume full After Effects compatibility.

  • End with the expression whose value is assigned. Don't use a top-level return. In longer scripts, use var for temporaries and finish with a number or list.
  • The final value must be a number or a list. Anything else is converted the way JavaScript's Number() converts it, not replaced by the authored value: true becomes 1, false and null become 0, and a string that reads as a number becomes that number. Other strings, objects and undefined become NaN. That includes undefined from a script ending in a var declaration or an if without a value.
  • Return a number for rotation, opacity or a separated axis, and an explicit three-component list for position, anchor or scale. Keep results finite.
  • time is in seconds. value is the authored property at the current time, before this expression: add offsets to it to keep existing animation.
  • Units: position and anchor in pixels, rotation in degrees, scale and opacity in percent (100 is full). Preserve Z when you change only X and Y.
  • Use component-wise arithmetic. Expressions are supported as Bodymovin exports them: hand-written +, - or * directly on arrays is outside the supported path.

All expressions share one script context and run again every frame. They run on every layer of an active composition, hidden layers and layers outside their ip and op included. Expression selectors run once for each character, word or line their b counts.

  • A top-level let, const or class fails from the second run, and the expression falls back to the property's value. Another expression declaring the same top-level name fails from its first run. warnings flag each expression with a top-level let, const or class. Declarations inside a function or block are fine.
  • Top-level var and function names are shared too, and the helpers are ordinary globals. Never name a top-level variable or function after a helper or global such as ease, linear, clamp, smooth, wiggle, key, loopOut or thisComp. It would replace it for every other expression.
  • Top-level var values persist from frame to frame. Don't rely on them: compute each frame's value from its inputs.
  • All scripts together get 64 MB of memory and a 256 KB stack. A script that exceeds either throws and falls back.
Intent Property Script
Gentle rotation around the authored angle ks.r value + 8 * Math.sin(2 * Math.PI * time / 2);
Pulse X and Y scale by 5%, keep Z ks.s var factor = 1 + 0.05 * Math.sin(2 * Math.PI * time / 2); [value[0] * factor, value[1] * factor, value[2]];
Position wiggle around existing motion ks.p wiggle(2, 15);
Repeat a keyframed track after its last key A supported keyframed property loopOut("cycle");
Ping-pong a keyframed track A supported keyframed property loopOut("pingpong");
Offset separated X by 40 pixels ks.p.x value + 40;

What does not run

  • Expressions on other shape, effect or text-document properties don't run. An x on an effect parameter's v or a layer-style property is ignored: the value renders without it, with a warning.
  • This is not the whole After Effects host API: no file system, network or host access.
  • An expression that throws, or names a missing layer, falls back to the authored value. A successful save or render does not prove it ran.
  • A script that runs too long on one frame, such as an endless loop, is stopped and not run for the rest of the render. The property keeps its own value, and a selector returns 100%. Every property and selector with exactly the same script text stops with it.
  • The time limit applies to each run: once per frame for a property, and once per element for a selector.
  • A failed expression selector returns 100%. As the first selector of its animator, it selects everything. After other selectors, it keeps their selection.
  • An expression selector that does not compile is dropped. If it was the animator's only selector, the animator applies to the whole text. Otherwise its other selectors still apply.
  • Render and inspect several frames where the result should differ from the base. For oscillation, check opposing phases, not only whole periods where the offset is zero.
  • Fix a failing expression. Don't silently replace a requested expression with keyframes.

Expression functions and values

Expression API Meaning and usage
time, value Current time in seconds, and the property's value without this expression
thisComp.width, .height, .duration, .numLayers, .frameDuration The containing composition's size, duration in seconds, layer count, and seconds per frame. Use thisComp.frameDuration, not an assumed bare global. In the main composition, .duration is (op − ip) / fr. In a precomposition, it is the precomposition layer's own op − ip in its parent, in seconds, not the precomposition's length. A frame render keeps the composition's timing, so .duration matches a video render. .numLayers counts every layer except audio layers. A plan's watermark changes none of these.
numKeys, key(n), nearestKey(t) The property's key count, and keys with index, time and value. Keys count from 1. Check numKeys first, call key() and nearestKey() only on a keyframed property, and keep n from 1 to numKeys. Keyframes that all hold one value count as none here.
thisComp.layer(nameOrInd), thisLayer A layer's position, anchorPoint, scale, rotation or opacity, directly or under .transform. Only the same composition. A number is the layer's ind, not its array place. A text is always a name, so "3" is not ind 3. Of layers sharing a name, the first in layers counts. A null's or camera's opacity reads 100. A layer also has index (its ind), inPoint and outPoint in seconds, and name, always an empty string. The globals inPoint and outPoint are the current layer's.
valueAtTime(t), velocityAtTime(t) The property's base animation at a time in seconds, and its velocity in units per second. Functions of the current property, not methods on other layers' values.
wiggle(frequency, amplitude, octaves) Repeatable noise around value: frequency in cycles per second, amplitude in property units, optional octaves clamped to 1–4. A fourth or fifth argument is ignored. The noise follows the layer's name: renaming a layer changes its wiggle, and layers with the same name wiggle alike on the same property.
linear(t,tMin,tMax,v1,v2), ease(...), easeIn(...), easeOut(...) Interpolate between number or matching vector endpoints, clamped to the interval. The forms (t,v1,v2) use the interval 0–1.
clamp(value,min,max) Bound a number, or each component, between two numbers. A one-item list such as [5] reads as its number.
smooth(width,samples) Average the base animation across a window in seconds. Defaults: 0.4 and 5.
loopOut(type,count), loopIn(type,count) Extend a keyed track after its last key or before its first. Use at least two keys at different times. count: 0 uses the whole keyed segment; a positive count limits the keyframe intervals.
loopOutDuration(type,seconds), loopInDuration(type,seconds) Pick the loop segment by duration. Use a positive, explicit duration.
Math, ordinary JavaScript Arithmetic, lists, conditions, bounded loops, functions and standard math. Return the final value, and don't rely on state from a previous frame.

Loop types are cycle (repeat), pingpong (alternate direction), offset (repeat with accumulated displacement) and continue (extend the end velocity). Loop helpers need an authored keyframed track: preserve its keys. A loop extends values, not the layer's ip and op.

  • Don't use expressions to recover authored layer names, indices or visibility bounds. Keep names and relationships from the inspected document, and read data.json for editable copy.
  • Preserve exported $bm_sum, $bm_sub, $bm_mul, $bm_div, $bm_mod and $bm_neg helpers.
  • Expression selectors do per-text selection, not transform placement (per-character expression selectors).

Layer relationships and loops

Read the document before choosing layer names or indices. thisComp.layer("Leader").transform.position reads a layer in the same composition, by name or ind. Its transform values are values, not After Effects property objects. Positions are local to their parents, so a direct offset fits only layers sharing a coordinate space. A follower's position script there could be:

var leaderPosition = thisComp.layer("Leader").transform.position;
[leaderPosition[0] + 120, leaderPosition[1], leaderPosition[2]];
  • Use the actual inspected name instead of inventing Leader. Keep these references through renames and restacks.
  • Keep dependencies one-way, never circular.
  • A referenced layer's expression runs before its value is returned. The two scripts share one scope, so give their top-level variables different names.
  • There are no world-space conversion functions and no cross-composition lookup.

This complete property repeats a rotation between −12 and 12 degrees every second at 30 fps, playing the authored segment forward and backward:

{"a":1,"k":[{"t":0,"s":[-12],"e":[12],"o":{"x":0.333,"y":0.333},"i":{"x":0.667,"y":0.667}},{"t":30,"s":[12]}],"x":"loopOut(\"pingpong\");"}

Key times are frames. The loop is a function of time: it shows while the layer is visible, and it does not extend the layer's ip or op. A looping parent keeps moving its children while it is hidden or outside its own ip and op. On an existing track, add the loop without replacing its keys, unless the caller asks for a new track.

Per-character expression selectors

Use an expression selector in a text animator, not on the text document. It returns a percentage from −100 to 100 that weights the animator's properties:

Value Meaning
textIndex The element's position in the selected domain, from 1
textTotal The number of elements in the domain
selectorValue The incoming selection percentage
value The base Amount, 100, not the character position
time Seconds, to animate the selection

This complete t.a entry sends a vertical wave across the characters, 24 pixels high with a 1.5-second period. Keep the layer's t.m grouping on characters:

{"a":{"p":{"a":0,"k":[0,24,0]}},"s":{"t":1,"b":1,"x":"100 * Math.sin(2 * Math.PI * time / 1.5 - (textIndex - 1) * 0.5);"}}
  • Append it to the existing animator list to keep other animation, and inspect several frames for readability and clipping.
  • A selector weights every property in its animator. Use separate animators for different selections.
  • It multiplies the selection of the selectors before it, as After Effects' Intersect does, and starts from full selection when it comes first. So returning selectorValue after a range selector squares partial selections.
  • Selectors can use composition size and duration, thisComp.frameDuration, math and interpolation helpers. They cannot use thisLayer, thisComp.layer, numKeys, keyframe sampling, or loop helpers that need a property track.
  • wiggle gives every element of a selector the same amount: use textIndex for per-element variation.
  • Return one amount, not separate X, Y and Z amounts.

Edge cases

  • An x that is not a string cannot run, and the property animates without it (warnings).
  • A single number on position, anchor or scale sets all three axes to it. A two-item list keeps the base Z. Items past the third are dropped, and an empty list reads as 0 on every axis.
  • clamp: a min or max given as a list of two or more numbers is ignored, and that side is left unbounded. The other bound still applies.
  • linear or ease with four arguments reads them as (t,v1,v2) and ignores the fourth. A tMax below tMin swaps the two.
  • An unknown loop type means cycle. A track with one key gives NaN.
  • loopOutDuration with 0 or no duration loops from the layer's in point to the last key. loopInDuration with 0 or no duration loops from the first key to the out point.

Complete starter and edit recipes

This self-contained document needs no media or fonts and shows one rounded plate for two seconds. A background layer you add needs a larger ind than the plate: array position does not decide stacking.

{"v":"5.12.2","nm":"Plate example","w":640,"h":360,"fr":30,"ip":0,"op":60,"ddd":0,"assets":[],"layers":[{"ty":4,"ind":1,"nm":"Plate","ddd":0,"sr":1,"ip":0,"op":60,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[320,180,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"shapes":[{"ty":"gr","nm":"Plate geometry","it":[{"ty":"rc","nm":"Rectangle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[280,100]},"r":{"a":0,"k":16}},{"ty":"fl","nm":"Blue","r":1,"c":{"a":0,"k":[0.1,0.3,0.8,1]},"o":{"a":0,"k":100}},{"ty":"tr","p":{"a":0,"k":[0,0]},"a":{"a":0,"k":[0,0]},"s":{"a":0,"k":[100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100},"sk":{"a":0,"k":0},"sa":{"a":0,"k":0}}]}]}]}

To move the plate 40 pixels right and make it red, change layers[0].ks.p.k to [360,180,0] and the fill's c.k to [0.8,0.2,0.1,1]. Send the whole edited data.json in an edit, with the head you read as expectedHeadVersionId.

Edit How
Copy Replace the first text document's t. Keep nm, font, transform, timing and animators. Check that the new glyphs fit the existing region.
Color Replace a solid's sc, a text document's fc or sc, a paint's c, gradient RGB entries, or a supported effect's color parameter. Keep each in its own representation, and keep alpha and stop positions.
Animated movement Add the same local-space distance to every authored position endpoint, keeping all times and easing. Handle separated dimensions and expressions explicitly.
Restack Change the ind values (array order does not stack), then update parent, tp and index-based expressions in that composition.
Extend a scene Adjust the root and layer op values, the relevant nested intervals and final holds, without changing time-remap data in seconds. Extending only the root op can leave a blank tail.
Resize Update the canvas size, and deliberately recompose content, precomposition extents, masks, crop and text fitting. Changing only w and h is not a layout adaptation. Effect points on text and shape layers are composition pixels (effect coordinates). Move or scale such a layer together with its effect points, or its colors shift. That covers Gradient Ramp, 4-Color Gradient, Corner Pin, Light Sweep, Radial Blur and Light Rays.
Add a shape Add complete geometry, paint, transform, a unique identity and timing. A lone appended path does not render.
Replace an asset Add the new file, then account for its real size and visible bounds, keeping the requested motion.

Example: shared movement and a line reveal

Three seconds and four layers, with no precomposition, media or fonts. They are a solid background, a gradient-filled shape plate, an animated null parent, and a stroked path with an animated trim. The plate and line share movement through parent: 3, so their own positions stay at zero. The line reveals from frame 15 to 45, while the shared movement ends at frame 30. Change timings and geometry to suit your design.

{"v":"5.12.2","nm":"Shared movement and line reveal","w":640,"h":360,"fr":30,"ip":0,"op":90,"ddd":0,"assets":[],"layers":[{"ty":4,"ind":1,"nm":"Line reveal","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"parent":3,"shapes":[{"ty":"sh","nm":"Line path","ks":{"a":0,"k":{"c":false,"v":[[-160,35],[-85,-35],[0,35],[85,-35],[160,35]],"i":[[0,0],[0,0],[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0],[0,0],[0,0]]}}},{"ty":"st","nm":"Line stroke","c":{"a":0,"k":[1,1,1]},"o":{"a":0,"k":100},"w":{"a":0,"k":8},"lc":2,"lj":2,"ml":4},{"ty":"tm","nm":"Line reveal","s":{"a":0,"k":0},"e":{"a":1,"k":[{"t":15,"s":[0],"e":[100],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":45,"s":[100]}]},"o":{"a":0,"k":0},"m":1}]},{"ty":4,"ind":2,"nm":"Gradient plate","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"parent":3,"shapes":[{"ty":"rc","nm":"Rectangle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[420,220]},"r":{"a":0,"k":24}},{"ty":"gf","nm":"Gradient","t":1,"r":1,"s":{"a":0,"k":[-210.0,-110.0]},"e":{"a":0,"k":[210.0,110.0]},"o":{"a":0,"k":100},"g":{"p":2,"k":{"a":0,"k":[0,0.12,0.24,0.6,1,0.12,0.78,0.72]}}}]},{"ty":3,"ind":3,"nm":"Shared movement","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":1,"k":[{"t":0,"s":[320,240,0],"e":[320,180,0],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":30,"s":[320,180,0]}]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}}},{"ty":1,"ind":4,"nm":"Background","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}]}

Example: animated alpha matte

Three seconds, three layers, no precomposition, media or fonts. An animated rectangular alpha matte reveals a gradient card. The caster has td: 1 and ind: 1, and the card has tt: 1 and tp: 1. The caster controls visibility and does not paint white over the card, and both stay directly editable shape layers. A mask also suits when it describes the clipping more simply.

{"v":"5.12.2","nm":"Animated alpha matte","w":640,"h":360,"fr":30,"ip":0,"op":90,"ddd":0,"assets":[],"layers":[{"ty":4,"ind":1,"nm":"Reveal matte","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":1,"k":[{"t":0,"s":[-320,180,0],"e":[320,180,0],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":45,"s":[320,180,0]}]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"td":1,"shapes":[{"ty":"rc","nm":"Rectangle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[640,360]},"r":{"a":0,"k":0}},{"ty":"fl","nm":"Matte fill","r":1,"c":{"a":0,"k":[1,1,1]},"o":{"a":0,"k":100}}]},{"ty":4,"ind":2,"nm":"Gradient card","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[320,180,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"tt":1,"tp":1,"shapes":[{"ty":"rc","nm":"Rectangle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[420,220]},"r":{"a":0,"k":24}},{"ty":"gf","nm":"Gradient","t":1,"r":1,"s":{"a":0,"k":[-210.0,-110.0]},"e":{"a":0,"k":[210.0,110.0]},"o":{"a":0,"k":100},"g":{"p":2,"k":{"a":0,"k":[0,0.12,0.24,0.6,1,0.12,0.78,0.72]}}}]},{"ty":1,"ind":3,"nm":"Background","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}]}

Example: editable text with a range reveal

Three seconds, a text layer and a solid background. One range selector controls opacity and vertical position to reveal and settle editable characters. Its start moves from 0 to 100 percent over frames 0 to 45. Fully selected characters start transparent and displaced, then return to their authored look.

The font is an explicit dependency. Like the rest of these docs, the example uses Montserrat Bold (slug montserrat-bold). Check GET /v1/fonts?q=montserrat (MCP: list_fonts) first. If it is not listed, copy the declaration of a font that is into fonts.list, and use its fName as the text document's f.

{"v":"5.12.2","nm":"Range selector reveal","w":640,"h":360,"fr":30,"ip":0,"op":90,"ddd":0,"assets":[],"layers":[{"ty":5,"ind":1,"nm":"Editable copy","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[320,200,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"t":{"d":{"k":[{"t":0,"s":{"t":"MOTION","f":"Montserrat-Bold","s":64,"lh":76,"ls":0,"tr":0,"j":2,"fc":[1,1,1]}}]},"a":[{"a":{"p":{"a":0,"k":[0,30,0]},"o":{"a":0,"k":0}},"s":{"t":0,"r":1,"b":1,"m":1,"sh":1,"s":{"a":1,"k":[{"t":0,"s":[0],"e":[100],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":45,"s":[100]}]},"e":{"a":0,"k":100},"o":{"a":0,"k":0},"a":{"a":0,"k":100},"ne":{"a":0,"k":0},"xe":{"a":0,"k":0},"sm":{"a":0,"k":100}}}],"m":{"g":1,"a":{"a":0,"k":[0,0]}}}},{"ty":1,"ind":2,"nm":"Background","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}],"fonts":{"list":[{"fName":"Montserrat-Bold","fFamily":"Montserrat","fStyle":"Bold"}]}}

Example: editable text with an expression selector

Three seconds, with a per-character expression on one editable text layer. The selector weights a 24-pixel vertical offset with a 1.5-second traveling wave, and does not replace the text or its font. It uses the same font as the previous example: substitute an available one the same way. Use this motion only where the design calls for procedural character movement, and check readability over the whole sequence.

{"v":"5.12.2","nm":"Expression selector motion","w":640,"h":360,"fr":30,"ip":0,"op":90,"ddd":0,"assets":[],"layers":[{"ty":5,"ind":1,"nm":"Editable copy","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[320,200,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"t":{"d":{"k":[{"t":0,"s":{"t":"MOTION","f":"Montserrat-Bold","s":64,"lh":76,"ls":0,"tr":0,"j":2,"fc":[1,1,1]}}]},"a":[{"a":{"p":{"a":0,"k":[0,24,0]}},"s":{"t":1,"b":1,"x":"100 * Math.sin(2 * Math.PI * time / 1.5 - (textIndex - 1) * 0.5);"}}],"m":{"g":1,"a":{"a":0,"k":[0,0]}}}},{"ty":1,"ind":2,"nm":"Background","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}],"fonts":{"list":[{"fName":"Montserrat-Bold","fFamily":"Montserrat","fStyle":"Bold"}]}}

Example: sibling groups and a purposeful precomposition

Three seconds: two root layers, two child layers, one precomposition, no nested shape groups, media or fonts. One shape layer holds two sibling square groups, one with an extra group-scale animation. A circle moves independently above it, leaving the frame on purpose. One precomposition applies a shared rectangular mask and an entrance fade to their combined output. That is what makes it useful: a common treatment on content with independent animations. hasMask: true turns the mask on: storing masksProperties alone does not. For simpler content without a shared treatment, place layers directly in the parent composition.

{"v":"5.12.2","nm":"Shared mask with independently animated children","w":640,"h":360,"fr":30,"ip":0,"op":90,"ddd":0,"assets":[{"id":"moving_content","nm":"Moving content","layers":[{"ty":4,"ind":1,"nm":"Independent circle movement","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":1,"k":[{"t":0,"s":[-30,90,0],"e":[350,90,0],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":45,"s":[350,90,0]}]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"shapes":[{"ty":"el","nm":"Circle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[52,52]}},{"ty":"fl","nm":"Fill","r":1,"c":{"a":0,"k":[1,0.52,0.14]},"o":{"a":0,"k":100}}]},{"ty":4,"ind":2,"nm":"Independent plate movement","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[160,90,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":1,"k":[{"t":0,"s":[-12],"e":[12],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":45,"s":[12]}]},"o":{"a":0,"k":100}},"shapes":[{"ty":"gr","nm":"Left square","it":[{"ty":"rc","nm":"Rectangle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[110,110]},"r":{"a":0,"k":12}},{"ty":"fl","nm":"Fill","r":1,"c":{"a":0,"k":[0.12,0.24,0.6]},"o":{"a":0,"k":100}},{"ty":"tr","p":{"a":0,"k":[-65,0]},"a":{"a":0,"k":[0,0]},"s":{"a":0,"k":[100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100},"sk":{"a":0,"k":0},"sa":{"a":0,"k":0}}]},{"ty":"gr","nm":"Right square","it":[{"ty":"rc","nm":"Rectangle","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[110,110]},"r":{"a":0,"k":12}},{"ty":"fl","nm":"Fill","r":1,"c":{"a":0,"k":[0.12,0.78,0.72]},"o":{"a":0,"k":100}},{"ty":"tr","p":{"a":0,"k":[65,0]},"a":{"a":0,"k":[0,0]},"s":{"a":1,"k":[{"t":0,"s":[50,50],"e":[100,100],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":45,"s":[100,100]}]},"r":{"a":0,"k":0},"o":{"a":0,"k":100},"sk":{"a":0,"k":0},"sa":{"a":0,"k":0}}]}]}]}],"layers":[{"ty":0,"ind":1,"nm":"Shared clipping and fade","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[160,90,0]},"p":{"a":0,"k":[320,180,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":1,"k":[{"t":0,"s":[0],"e":[100],"o":{"x":0.25,"y":0},"i":{"x":0.75,"y":1}},{"t":15,"s":[100]}]}},"refId":"moving_content","w":320,"h":180,"masksProperties":[{"nm":"Shared frame","mode":"a","inv":false,"pt":{"a":0,"k":{"c":true,"v":[[20,20],[300,20],[300,160],[20,160]],"i":[[0,0],[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0],[0,0]]}},"o":{"a":0,"k":100},"f":{"a":0,"k":[0,0]}}],"hasMask":true},{"ty":1,"ind":2,"nm":"Background","ddd":0,"sr":1,"ip":0,"op":90,"st":0,"bm":0,"ao":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}]}

Check the result and recover

  1. The version's problems must be empty: every asset path and font resolves, and the document fields are in range.
  2. Render the exact version. For a quick look, render a few frames with format: "frames" at the moments that matter. Pick the opening, during and after transitions, motion extremes, and the last visible frame.
  3. Check text, clipping, mattes, effects, image sharpness and occlusion. A layer or effect in the JSON does not prove it renders as intended.
  4. If something is wrong, fix its cause in another edit, and check the affected moments again.
Symptom What to inspect
A shape or part of a logo is missing Missing paint, paths after paints, unsupported modifiers. Nested groups and per-group path and paint limits are in warnings.
A shape reveal does not animate Several paths before one trim, missing keyframes on the trim's s, e or o, or animation on a static-only property
An effect has no visible result Exact mn, parameter nm, units, supported animation, effect order
Text is wrong, clipped or does not change Font resolution, the first text document, baseline, paragraph or fitting region, visibility intervals. Timed copy changes need separate layers.
Content is clipped or misplaced Anchor, parent and group transforms, precomposition size, transparent padding, mask space, effect coordinates
A matte reveals the wrong object Which layer has td and which tt and tp, its ind, same-composition references, overlapping visibility
Movement snaps, or an edit seems ignored Every key's s and e, easing, spatial tangents, separated axes, overriding expressions
An empty opening or tail Root and nested ip and op, precomposition and video st, time remap, media duration
An expression appears static Supported property slot, return shape, enough keys for loops, fallback to the authored value
A render is refused, or an image or video is missing MP4 and HLS need an even width and height, or 422 version_not_renderable. An asset declared too large is skipped (asset fields).
Many vector shapes don't render as designed The vector path limit

See also: data.json basics, Fonts, Renders.