Composition format
View as MarkdownThis 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,warningsand "refused" mean what What Blitframe checks says. A case markedproblemsmakes the version not renderable. A case markedwarningsrenders, 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:
- Start here: Supported features, Choose a representation, Editing a composition
- Structure: Document and time, Layers, Transforms, Static values and keyframes
- Content: Shapes and paints, Text and fonts, Media and precompositions, Native models
- Compositing: Masks and track mattes, Blend modes and effects, Layer styles, Expressions
- Copy and check: Starter and recipes, Examples, Check the result
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
- Read the current file: MCP
read_filewithpath: "data.json", orGET /v1/versions/{versionId}/files/data.json. - 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.ais its anchor, but a property'sais its animation flag. A text document'ssis font size, but a keyframe'ssis its start value. - Don't infer array positions from layer names or
ind:ind: 8does not meanlayers[8]. - When you remove or renumber layers, update
parent,tpand index-based expressions in the same composition. Never create parent cycles, recursive precompositions, danglingrefIds or duplicateinds. - Use only files in the version and available fonts. Never invent a path, asset id or font, and never point at a URL.
- Send the whole new
data.json, plus any new files, in an edit. SetexpectedHeadVersionIdto the head you read in step 1, so the edit cannot overwrite a change made since. Onhead_moved, read the new head and apply your change again, instead of replaying the old file. - Read the new version's
renderable,problemsandwarnings.warningsname 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
iptoop. 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
tmthat has exactly one path listed before it. It counts only on a shape layer that shows: not hidden, with aniptoopspan 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
tare in frames. Time-remap values (tm) of video and precompositions, and expressiontime, are in seconds. - At
fr: 30,ip: 0, op: 90lasts three seconds. Frame 90 is excluded. - Changing
fralone changes the speed of frame-based animation. To keep the duration, multiply every frame-valued time by newfr/ oldfr, nested keyframe times and layer ranges included. Don't multiplytmvalues. - Layer
ipandopset when the layer is visible in its composition. Every layer needs a numericop. stoffsets 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.srstretches time on a precomposition layer withouttm. Its contents play at 1/srspeed, counted fromst, sosr: 2plays them at half speed. Video inside still plays at normal speed (warnings, time remap).- Every other layer, and a precomposition with
tm, ignoressr: keep it at 1 there and write timing out (warningsotherwise). - 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
tmselects source time with second-valuedsande, 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
worhwritten with a decimal point or exponent, such as1920.0, reads as 0:problems. Write whole numbers such as1920. - A non-empty
layersthat is not a list:problems. - A layer without
ipstarts at frame 0. A layer withoutopends at frame 0, so it never appears (warnings). - A layer
ip,oporstthat is not a number reads as an arbitrary frame (warnings). - On a precomposition without
tm,sr: 0plays its contents at normal speed (warnings). Ansrthat is not a number reads as an arbitrary stretch, which the warning gives. - A precomposition's
tmwritten 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
indvalues paint in front. Array order is not paint order: moving an entry changes its pointer, not its pixels. To restack, change theindvalues and remap theparentandtpreferences that depend on them. - Each nested composition has its own index space.
refIdnames an assetid, 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 uniqueid, point only that layer'srefIdat it, then edit the duplicate. - Keep a precomposition layer's
wandhcoherent 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
worh. 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
parentor mattetp.
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.ais the point of interest, not a geometry anchor. - An authored 3D rig uses three-component position and scale, and
rx,ry,rzwithor. - The last camera layer in
layersis used for the whole render, hidden or not, whatever itsipandop. Keep one intended camera per composition: visibility cannot cut between cameras. - A camera moves every layer in its composition, 2D layers too, since
dddis 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
tywritten other than as an unsigned whole number, such as3.0or3e0, reads as the number its low 32 bits hold (warnings). That is usually0, a precomposition, and one without a textrefIdis inproblems. - A missing or repeated
indis inwarnings. A missingindreads as 0, which no layer can name asparentortp. - 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 thatindattach to the last. Their stacking is undefined, and a mattetpuses 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
opis at or before itsipis accepted but never appears. - A nonzero
parentnaming no layer in the composition, or naming an audio layer:problems. - Only the boolean
truehides a layer:hd: 1reads asfalse. - An entry of
layersthat is not an object:problems. - The engine skips the first character of a solid's
scand 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-textsc:problems. - An image, video or 3D model layer whose
refIdnames no asset of its kind that the engine loads:problems. So is a precomposition layer whoserefIdis not text or names no asset. - A camera without
pehas a zoom of 0 (warnings). Apethe engine cannot read, such as a bare whole number:problems. - Effects on a
ty:3withoutswdon't render, and the layer is a plain null (warnings). - An adjustment layer whose
efholds 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
pto 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
rxandr,ris ignored (warnings). - An
orwithout three numbers, such as[]:problems. - A
poffthe engine cannot read, such as[]ornull:problems. On a layer whose transform has no"a": 1value or expression, even[1,2]can be. - Only
s: trueseparates a position:s: 1does not. The engine then reads the position'sk, which a separated position lacks, so the layer stays at 0,0 (warnings). - A separated position ignores
z(warnings). - A separated position with an
xgives the layer an animator, so its keyframes animate on any layer. Withoutx, keyframes inyareproblemson 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'spandstake 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
aout, or usenullorfalse, so{"k":100}is valid. A stroke widthwis the exception: it needsa(strokes). - Never mark a static value
trueor 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
sstarts its segment, and the next key'ssends it: edit that one to change where a segment ends.eis ignored, except that a last key withoutstakes the previous key'se. - Preserve terminal keys.
- Scalar keys usually use one-element lists, such as
s:[100], though a static scalar isk:100. Where only the first key is read (rectangle roundness, star radii and rotation, mask opacity), the one-element list is required. h:1holds instead of interpolating.h:0holds too, so leavehout for an interpolating segment.oandiare temporal Bezier easing handles, withxandyas numbers or component lists.toandtiare spatial tangent offsets. Don't confuse them with a path'soandivertex 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": 1over a single value. - A list where a plain number belongs is misread: rectangle roundness, star radii and rotation, and rectangle, ellipse and star
pands. A list stroke width drops the stroke. "a": 1with a missing or emptyk:- is dropped on layer transform values, fill and stroke values, group transforms and trims
- cannot be read (
problems) on a mask'spt,oorf, a path'sks, rectangle, ellipse or star geometry, and a gradient'ss,eoro
- Under
"a": trueor"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'ss,eandoand a star'spt, only"a": 1counts as animated. Undertrueor2, 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). Anethat differs from the next key'ssis listed inwarnings. - 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-levelgrgroups ending in atrtransform. Loose top-level items work too, and every top-level group renders. - Every item, in
shapesor a group'sitlist, is an object with a textty. 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
warningswith 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
grgroups 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
grpaints 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 agrto 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 (
florgf) 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]]}}}
vholds local vertices.iandoare incoming and outgoing offsets relative to each vertex, not absolute control points. Supply lists of equal length. Zero offsets make straight segments.ccloses the path when it istrueor 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.kholds four numbers per color stop (position, R, G, B), then optional opacity stops as position/alpha pairs with their own positions. Keepg.pequal 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
ois 0–100. To recolor, change only the RGB entries. - Gradients are static:
s,e,oand the stops are read once, for the whole render. They come from the first frame, or the first keyframe'sswhenais 1. To change one over time, fade between two layers with different static gradients using layer opacity. - Group opacity
odoes not fade gradients. - Radial gradients are always centered: highlight length
hand angleaare ignored. - The
ADBE Rampeffect is separate (effects).
Trim paths
sandeare 0–100 percent of the path's length, andois an offset in degrees. All three can animate.- A trim is skipped when more than one path (
sh,rc,elorsr) is listed before it in its group (warnings). Som(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 roundnessrother than a static 0. Setrto{"a":0,"k":0}, or draw it as a pathsh.
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'snmdoes 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.aholds the text animators. Write[]without any. With animators, writet.mtoo.- The render stops (
problems) unlesst.d.k[0].sis an object holding copytwith a visible character, and fontf. The font must be declared infonts.list, and be in the version or the font library.
Fonts
- Find the available fonts before you choose the typography:
GET /v1/fonts, or MCPlist_fonts. Each library font has a readydeclarationforfonts.list. Don't assume the example's font exists. For another typeface, add its file to the version (Fonts). fmatchesfonts.list[].fNameexactly, including case and whitespace.- Declare every font you use with its actual
fName,fFamilyandfStyle. KeepfPathabsent 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:
psis in the layer's own coordinates, like its anchorks.a. Witha:[0,0,0], the box's top-left corner sitspsfrom the positionp. To center a W × H box onp, usea:[0,0,0]andps:[-W/2,-H/2].- Text is top-aligned, and
jaligns lines within the box width. There is no vertical alignment: to center a block vertically, size the box to the text or moveps. - 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
lhfits 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: falsefits the width only, from the widest line before wrapping. The size can have a fraction, and the text keeps its placement.wrap: truepicks 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 byj: left (0), right (1) or center (2). Preservejunless 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 (
minSizewhen 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 widthswand blurbl.warningsname 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 (
j3 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.aa 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
bsets 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.listentry without a textfName, used or not, fails the render (problems). If a name is declared more than once, the last declaration decides its font. - A missing
s,trorjreads as 0, and a missinglhas 1.2 times the size (warnings). So do values that are not finite numbers, and ajwith a decimal point. \r\nis two breaks, with an empty line between. A break at the very end adds no line. A NUL character ends the text.fcorsc(withswabove 0.01) that is not a list, or is empty, fails the render (problems). So doszorpsthat is not a list, andszwithoutps.- A missing
t.areads as[]. - Text whose drawn lines hold no glyph stops the render (
problems, or onlywarningson 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:
jaligns lines about the box's left edge, and the first baseline sits at its top. A negative side is listed inwarnings. wrapother than the booleantruedoes not wrap. Ashrinkthat is not text does not shrink. Aregion.refthat is not text turns the fit off.- These fits leave the text at its own size (
warnings): one past the fifteenth, one with anothersource, and one whoserefnames no layer. So does arefwhose first match is the text itself, or any text, null or camera layer. - An adjustment layer is a region only when it has an
eflist and positiveswandsh. 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.athat is not a list of objects fails the render (problems). So does an animator whoseais not an object. - A property or selector value written bare, instead of
{"a":0,"k":value}or keyframes, fails the render (problems). t.m.goutside 1 to 4 is clamped. With animators, at.mthat is not an object, or at.m.athat is not an object with aklist, fails the render (problems).- A selector that is not an object, or a list of selectors with a
tother than 0 or 1, fails the render (problems). mreads every value as additive.shof 0 or outside 1 to 6 reads as square.- An expression selector
xthat is not a string cannot run, so the selector is skipped (warnings). After Effects exports a selector withoutxwhen 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,poraturns the option on.trueand1.0read as 0. A missing option reads as 0. - Text on a path: an
mthat 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
mreadsmasksPropertieswhateverhasMasksays. The render fails (problems) when that is not a list of mask objects, or when the named mask'sptis not an object. So it does when an optionf,l,r,porais 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
wandhrenders 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 onty: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 + pexactly, 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
worh(native models). Audio comes from the version's soundtrack or the render'saudio(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
stlater thanip, the video does not wait: it plays from its beginning atip, as ifstequalledip. - 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,wandhand its references together. Every referenced file must exist in the version. - New pixels may need a new anchor, scale and crop:
wandhalone don't place the subject. - For an unrotated
iw × ihimage filling abw × bhbox, contain scale is100 * min(bw/iw,bh/ih)and cover scale is100 * 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
nmon the asset itself: the referring layer's name does not replace it. Include real child layers for visible output. - The referring
ty:0layer needsrefId:"scene_1", positive whole-numberwandh, transforms and timing, and optionallystandsr. - 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
wandhset 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 itsw×h. - A layer does not collapse when it has masks (
hasMask: true), effects, layer styles (sy) or a matte role (ttortd). 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
worhis over 4096, or whosepis adata:URI (warnings). It does so even if the upload was accepted. An image or video layer that shows it:problems. - A layer whose
refIdnames no asset, a precomposition, an audio file, a file of the other kind, or a skipped asset:problems. - An asset
worhwritten1920.0reads as1920. - A video asset without
wandh:warnings. - A precomposition asset without a text
nmfails the render (problems). So does a precomposition that contains itself. - A precomposition layer whose
refIdmatches no assetid, or whosetmthe engine cannot read, such as a bare whole number:problems. - A precomposition layer's
worhwritten with a decimal point reads as the number its low 32 bits hold, usually 0 (warnings). cpcollapses when it istrueor 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.aat[0,0,0], it lands on the layer's position. A nonzero anchor, in those pixels, is the pivotks.pplaces. 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,rzandor. 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
indlike 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 positivebyteLength - 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
modeabove 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
targetNamesor defaultweightswhose 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 whoserefIdnames no asset, an asset without a filep(such as a precomposition), an asset whosepis adata:URI, or an asset that is not a.glbor.gltffile 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:0ora:1, and complete path and opacity objects. - To animate a mask path, replace
ptwith 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
ttlayer a whole-numbertp, or removett. Don't rely on adjacency, chain receivers and casters, or leave a danglingtp. - 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 itsipandop, entirely off screen, or a null or camera. Then, or whentpnames no layer, an alpha or luma matte hides the receiver. An inverted matte draws it unmatted. - Any
td, whatever its value (td: 0too), makes its layer draw only as a matte. Atdlayer no receiver points at is never drawn (warnings). - Don't use a precomposition collapsed with
cpas a matte: giving ittdstops the collapse. - To clear or move a matte role, remove the obsolete
tt,tpandtd: 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. invother than the booleantruereads asfalse.- A missing
ptdraws an empty mask, so an add mask hides the layer (warnings). - A fixed
owritten as a list is misread (warnings). - A feather of one number reads its second from beyond the list (
warnings). - A
pt,oorfthe engine cannot read, such as a bare whole number:problems. So is a feather that isnullor has nok. - A
masksPropertiesthat is not a list of mask objects whilehasMaskistrue:problems. ttwritten1.0reads 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. warningsname 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
bmas 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
mnselects the effect. The display namenmmay be an exported custom name. - The nested
eflists parameters, matched by exact Englishnm, not position, translated name orix. Transform and Color Balance (HLS) match each by its ownmn, such asADBE 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.
enis not read: an effect withen: 0still 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
gfandgsendpoints 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×His 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
bmthat 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 as1.0or a non-number. So is an"a": 1whosekholds 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 keyframedGlow Based Onkeeps 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 DimensionsorGlow Dimensionsoutside 1 to 3 runs no blur, and leaves undefined pixels.Color Loopingoutside 1 to 4 draws as 4, triangle B>A>B.- Fast Box Blur
Iterationsover 50 renders as 50 (warnings). - A negative Gaussian
Blurrinessreads as 0. - Transform
Uniform Scalefrom 0.01 to 0.49 reads as off. - Hue/Saturation
Channel Controlother than 1 is inwarnings. - CC Light Sweep
ShapeorLight Receptionabove 3 is inwarnings.
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
efthat is not a list of effect objects, such as"ef":5,"ef":[5]or a single effect object - an
mnor parameternmthat is not text - a parameter list
efthat is not a list of objects - a parameter
vthat is not a{"a":…,"k":…}object of the right kind, such as"v":5, or a static point or color whosekis a number or empty list - keyframes on Glow's
Glow Based Onwhosesvalues 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
tyvalues render. Inner shadow, inner glow, bevel, satin and gradient overlay are skipped. - Colors, opacity, size, spread, angle, distance and range can be keyframed.
bmandtcare 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":1or"c":5written bare. So is ansythat is not a list of style objects, such as"sy":[5]or a single style object. - A few
bmvalues far outside the list, such as0.1or-5000000, cannot render at all:problems. - A
bmwithoutk, orbm: nullor[], reads as 0 and blends normal, not the drop shadow's multiply or the glow's screen (warnings). - A
tythat 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,kand other metadata: they give its static or keyframed base and its fallback. Don't switch a static property toa:1because its expression changes over time. - An expression can override the base, so changing only
kmay 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, usevarfor 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:truebecomes 1,falseandnullbecome 0, and a string that reads as a number becomes that number. Other strings, objects andundefinedbecome NaN. That includesundefinedfrom a script ending in avardeclaration or anifwithout 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.
timeis in seconds.valueis 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,constorclassfails 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.warningsflag each expression with a top-levellet,constorclass. Declarations inside a function or block are fine. - Top-level
varand 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 asease,linear,clamp,smooth,wiggle,key,loopOutorthisComp. It would replace it for every other expression. - Top-level
varvalues 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
xon an effect parameter'svor 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.jsonfor editable copy. - Preserve exported
$bm_sum,$bm_sub,$bm_mul,$bm_div,$bm_modand$bm_neghelpers. - 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
selectorValueafter a range selector squares partial selections. - Selectors can use composition size and duration,
thisComp.frameDuration, math and interpolation helpers. They cannot usethisLayer,thisComp.layer,numKeys, keyframe sampling, or loop helpers that need a property track. wigglegives every element of a selector the same amount: usetextIndexfor per-element variation.- Return one amount, not separate X, Y and Z amounts.
Edge cases
- An
xthat 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: aminormaxgiven as a list of two or more numbers is ignored, and that side is left unbounded. The other bound still applies.linearoreasewith four arguments reads them as(t,v1,v2)and ignores the fourth. AtMaxbelowtMinswaps the two.- An unknown loop type means
cycle. A track with one key gives NaN. loopOutDurationwith 0 or no duration loops from the layer's in point to the last key.loopInDurationwith 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
- The version's
problemsmust be empty: every asset path and font resolves, and the document fields are in range. - 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. - Check text, clipping, mattes, effects, image sharpness and occlusion. A layer or effect in the JSON does not prove it renders as intended.
- 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.