# Composition format

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

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

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

How to read it:

- `problems`, `warnings` and "refused" mean what [What Blitframe checks](/docs/blitframe/data-json#what-blitframe-checks) says. A case marked `problems` makes the version not renderable. A case marked `warnings` renders, but not as written.
- In property tables, **Default** is what the engine uses when you leave the property out. Required means you write it: without it the render fails, the item does not draw, or the result is not defined. None means the feature is off.
- Each section ends with **Edge cases**: what the engine does with a value written another way.
- [Limits](/docs/blitframe/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](#supported-features), [Choose a representation](#choose-a-representation), [Editing a composition](#editing-a-composition-through-blitframe)
- Structure: [Document and time](#document-and-time), [Layers](#layers-ordering-and-relationships), [Transforms](#transforms-and-coordinates), [Static values and keyframes](#static-values-and-keyframes)
- Content: [Shapes and paints](#shapes-and-paints), [Text and fonts](#text-and-fonts), [Media and precompositions](#media-and-precompositions), [Native models](#native-models)
- Compositing: [Masks and track mattes](#masks-and-track-mattes), [Blend modes and effects](#blend-modes-and-effects), [Layer styles](#layer-styles), [Expressions](#expressions)
- Copy and check: [Starter and recipes](#complete-starter-and-edit-recipes), [Examples](#example-shared-movement-and-a-line-reveal), [Check the result](#check-the-result-and-recover)

## Supported features

| Area | Available | Main limits |
| --- | --- | --- |
| [Layers](#layers-ordering-and-relationships) | 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](#transforms-and-coordinates) | Position, anchor, scale, opacity, 2D and 3D rotation, orientation, parenting, auto-orient | Auto-orient needs a unified animated position track |
| [Animation](#static-values-and-keyframes) | Linear, hold, temporal and spatial Bezier interpolation; compatible path morphs; time stretch on precomposition layers | No roving keyframes. Other layers ignore time stretch. |
| [Shapes](#shapes-and-paints) | 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](#shape-structure) of paths and paints. |
| [Text](#text-and-fonts) | 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](#media-and-precompositions) | File-backed images and video, reusable precompositions, time remapping | No embedded images, media URLs or footage looping |
| [Native models](#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](#masks-and-track-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](#blend-modes-and-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](#expressions) | Transform expressions and text expression selectors | No host APIs; no expressions on other properties |

## Choose a representation

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

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

## Editing a composition through Blitframe

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

## Document and time

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

```json
{"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](/docs/blitframe/renders#plan-limits). 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](#fonts)) |
| `v`, `nm` | text | None | Bodymovin version string, such as `"5.12.2"`, and composition name. Not read. |
| `ddd` | whole number | 0 | Not read. Write `0` in ordinary 2D documents, and preserve authored 3D rigs. |

- The render's size and frame rate come from the document: a render request cannot change them.
- At a fractional rate, a video holds one frame for each frame from `ip` to `op`. A frame render returns exactly the frames you ask for.
- A composition is at most 3,600 seconds long.

[Limits](/docs/blitframe/limits#compositions) 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](#precompositions), 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](#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](#vector-paths) | Over the limit |

### Textures

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

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

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

### Vector paths

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

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

### Time

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

### Time remap

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

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

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

### Edge cases

- A root `w` or `h` written with a decimal point or exponent, such as `1920.0`, reads as 0: `problems`. Write whole numbers such as `1920`.
- A non-empty `layers` that is not a list: `problems`.
- A layer without `ip` starts at frame 0. A layer without `op` ends at frame 0, so it never appears (`warnings`).
- A layer `ip`, `op` or `st` that is not a number reads as an arbitrary frame (`warnings`).
- On a precomposition without `tm`, `sr: 0` plays its contents at normal speed (`warnings`). An `sr` that is not a number reads as an arbitrary stretch, which the warning gives.
- A precomposition's `tm` written another way:

| Precomposition `tm` written as | Result |
| --- | --- |
| `null`, `{}`, `false`, `0`, `""` or `[]`, or a `k` that is neither a number nor keyframes | Holds the first frame (`warnings`) |
| A short bare decimal, such as `1.5` or `2.0` | Holds the first frame (`warnings`) |
| A bare whole number other than `0`, such as `"tm": 5`, and most other bare decimals | Unreadable: `problems` |

## Layers, ordering, and relationships

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

```json
{"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](#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](#media-and-precompositions)) |
| `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](#adjustment-layers-and-cameras). |
| `4` | Shape | `shapes`, with geometry and paint ([shapes](#shapes-and-paints)) |
| `5` | Text | A text document with copy and a declared font ([text](#text-and-fonts)) |
| `6` | Audio | Nothing: it is ignored ([audio layers](#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](#adjustment-layers-and-cameras)) |
| `16` | Native model | `refId` to a GLB asset ([native models](#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](#stacking-and-references). |
| `nm` | text | Required | A stable, non-empty name. An audio layer needs none. |
| `ks` | object | Required | The [transform](#transforms-and-coordinates) |
| `ip`, `op` | number | 0 | Visibility in frames, from `ip` up to but not including `op` ([time](#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](#time)) |
| `sr` | number | 1 | Read only on precomposition layers without `tm` ([time](#time)) |
| `ao` | whole number | 0 | Auto-orient ([transforms](#transforms-and-coordinates)) |
| `bm` | whole number | 0, normal | [Blend mode](#blend-modes-and-effects) |
| `ddd` | whole number | 0 | Not read. Preserve it when present. |

### Stacking and references

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

### Audio layers

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

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

### Adjustment layers and cameras

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

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

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

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

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

### Edge cases

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

## Transforms and coordinates

A complete ordinary 2D transform:

```json
{"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](#separated-position) | `[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](#expressions)). Layer `ddd` is not read: 3D comes from `rx`, `ry`, `rz` and three-component `p`, `s` and `a`. Timing is in [time](#time).

### Where a layer sits

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

### Separated position

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

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

### Edge cases

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

## Static values and keyframes

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

A raw number or list cannot replace the property object.

### Value shapes

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

### The animation marker `a`

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

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

### Which layers can animate

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

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

### Keyframes

```json
{"a":1,"k":[
  {"t":0,"s":[100,180,0],"e":[300,180,0],"o":{"x":0.33,"y":0},"i":{"x":0.67,"y":1}},
  {"t":30,"s":[300,180,0],"h":1}
]}
```

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

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

### Path morphs

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

### Edge cases

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

Keyframes under other markers:

| Property | Keyframes under `1` | Under `true`, another nonzero whole number, `null` or no `a` | Under `0`, `false` or `1.0` |
| --- | --- | --- | --- |
| Layer transform values, separated position components, a video's `tm` | Animate | Animate on a layer that already has an [animator](#which-layers-can-animate); `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](#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:

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

### Shape structure

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

### Paint order

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

### Shape items

| Item | Property | Type | Default | Notes |
| --- | --- | --- | --- | --- |
| `rc` rectangle | `p`, `s` | property: `[x,y]` | Required | Center and `[width,height]`. Animatable. |
| | `r` | property: number | Required | Corner radius, which needs no rounded-corner modifier. Animatable. |
| | `d` | whole number | 1 | Direction ([codes](#plain-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](#plain-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](#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](#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](#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](#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`:

```json
{"ty":"sh","nm":"Triangle","ks":{"a":0,"k":{"c":true,"v":[[0,-50],[50,50],[-50,50]],"i":[[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0]]}}}
```

- `v` holds local vertices. `i` and `o` are incoming and outgoing offsets relative to each vertex, not absolute control points. Supply lists of equal length. Zero offsets make straight segments.
- `c` closes the path when it is `true` or a nonzero whole number.
- For compound holes, keep the winding and fill rule across the paths that share a fill.

### Gradients

```json
{"ty":"gf","nm":"Blue gradient","t":1,"r":1,"s":{"a":0,"k":[-140,0]},"e":{"a":0,"k":[140,0]},"o":{"a":0,"k":100},"g":{"p":2,"k":{"a":0,"k":[0,0.1,0.3,0.8,1,0.5,0.8,1,0,1,1,1]}}}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `t` | whole number | Linear | `2` radial, any other value linear |
| `s`, `e` | property: `[x,y]` | Required | Start and end in local pixels: a fixed list of two numbers, or a first keyframe `s` holding one |
| `o` | property: number | 0, transparent (`warnings`) | Paint opacity, 0–100: a plain number such as `k:100`, or when animated a one-element first keyframe `s:[100]` |
| `g` | object | White (`warnings`) | `p` is the color stop count, at most 16. `k` is a property object holding four numbers per color stop, then at most 16 opacity stops of two. |
| `r` | whole number | Nonzero | `gf` only: the fill rule |

- `g.k` holds four numbers per color stop (position, R, G, B), then optional opacity stops as position/alpha pairs with their own positions. Keep `g.p` equal to the number of color stops.
- Keep stops ordered from 0 to 1. The engine holds the first stop's color before its position and the last one's after, and blends the first pair around each point.
- Geometry is in local pixels. Color, stop position and stop alpha are 0–1, and paint `o` is 0–100. To recolor, change only the RGB entries.
- Gradients are static: `s`, `e`, `o` and the stops are read once, for the whole render. They come from the first frame, or the first keyframe's `s` when `a` is 1. To change one over time, fade between two layers with different static gradients using layer opacity.
- Group opacity `o` does not fade gradients.
- Radial gradients are always centered: highlight length `h` and angle `a` are ignored.
- The `ADBE Ramp` effect is separate ([effects](#effects)).

### Trim paths

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

### Shape features that do not render

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

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

### Edge cases

| Written as | Result |
| --- | --- |
| An item `5` or without `ty`; `"it":5`; `"c":5`; `"w":4`; a rectangle without `s` | Unreadable, and the render fails (`problems`) |
| A marker that does not match the value ([static values and keyframes](#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"}`:

```json
{"d":{"k":[{"t":0,"s":{"t":"Summer sale","f":"Montserrat-Bold","s":48,"lh":56,"ls":0,"tr":0,"j":2,"fc":[1,1,1]}}]},"a":[]}
```

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

### Fonts

- Find the available fonts before you choose the typography: `GET /v1/fonts`, or MCP `list_fonts`. Each library font has a ready `declaration` for `fonts.list`. Don't assume the example's font exists. For another typeface, add its file to the version ([Fonts](/docs/blitframe/fonts)).
- `f` matches `fonts.list[].fName` exactly, including case and whitespace.
- Declare every font you use with its actual `fName`, `fFamily` and `fStyle`. Keep `fPath` absent or empty, and never write machine paths.
- An unused declaration needs no font file, but every entry, used or not, needs a text `fName`.
- Use text layers and fonts for all copy. Don't convert glyphs to shapes or images to get around font discovery. Animate text with [text animators](#text-animators), or an [expression selector](#per-character-expression-selectors) 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](#point-and-paragraph-text)) |
| `ps` | list of 2 numbers | Required with `sz` | The box's top-left corner `[x,y]` |
| `ca` | whole number | None | Not applied: All Caps and Small Caps (`ca` 1 and 2) render text as `t` is written. Write `"WOMEN\rSHOES"`, not `"women\rshoes"` with `ca: 2`. |

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

### Point and paragraph text

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

Paragraph text sits in a box:

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

### Scripts and type styles

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

### Fit text to a layer

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

```json
{"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](/docs/blitframe/text-fitting). An applied rule there replaces an inline one on the same layer. |
| `region.ref` | text | Required | The name of a shape, solid, image, video, 3D model, precomposition or adjustment layer in the same composition. The first layer in `layers` with that name counts, skipping audio layers. |
| `region.margin` | number | 0 | The margin inside the region |

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

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

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

### Text animators

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

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

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

| Property | Type | Notes |
| --- | --- | --- |
| `p` | property: 3 numbers | Position offset in text-local pixels, such as `[0,24,0]` |
| `a` | property: 3 numbers | Anchor point offset in text-local pixels. It moves the point each element scales, rotates and skews about, from where `t.m` puts it. Without scale, rotation or skew, it shifts the elements by minus its value. |
| `s` | property: 3 numbers | Scale in percent: `[100,100,100]` is unchanged |
| `r` | property: number | In-plane rotation in degrees |
| `rx`, `ry` | property: number | X and Y rotation in degrees, as a flat projection without perspective: elements narrow or flatten about their anchor, they do not recede |
| `o` | property: number | Target opacity in percent: 0 makes fully selected elements transparent. It fades the fill and the stroke together. |
| `fc` | property: RGB, 0–1 | Fill color. The stroke keeps its own color. |
| `sc` | property: RGB, 0–1 | Stroke color |
| `t` | property: number | Added tracking in text-local pixels, a different unit from the document's `tr` |
| `ls` | property: 2 numbers | Line-spacing offset `[x,y]` in pixels, not the document's baseline shift `ls` |
| `sk`, `sa` | property: number | Skew, limited to ±70°, and skew axis, in degrees |

- These belong in animators, not the text document, and an animator cannot replace the text.
- Fill or stroke hue, saturation, brightness and opacity (`fh`, `fs`, `fb`, `sh`, `ss`, `sb`, `fo`, `so`) are not supported. Nor are stroke width `sw` and blur `bl`. `warnings` name each.
- Animated tracking keeps each line's left edge in place on left-aligned text, its right edge on right-aligned text and its middle on centered text. On justified paragraphs (`j` 3 to 6), it keeps the left edge while the lines are centered.
- An animator with no selector, or whose only selector is an expression that fails to compile, applies to the whole text.
- Use a separate animator for properties that need a different selector.

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

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

### Selectors

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

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

An expression selector has `t: 1`, `b` and a script string `x`, and needs no range fields ([per-character expression selectors](#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:

```json
{"m":0,"f":{"a":0,"k":0},"l":{"a":0,"k":0},"r":{"a":0,"k":0},"p":{"a":0,"k":1},"a":{"a":0,"k":0}}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `m` | whole number | None | The index of one of the layer's masks |
| `f`, `l` | property: number | 0 | First and last margins. They may animate. |
| `r` | property: whole number | 0 | Static. `1` reverses the direction. |
| `p` | property: whole number | 0 | Static. `1` makes glyphs perpendicular to the path. Without it, glyphs stand upright. |
| `a` | property: whole number | 0 | Static. `1` forces alignment. |

- The engine uses the mask path's first keyframe: path morphs don't move the text. Use a static path.
- The path's mask is not also a coverage mask.
- Path text takes precedence over the paragraph box.

### Edge cases

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

## Media and precompositions

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

```json
{"id":"image_1","w":1200,"h":800,"u":"images/","p":"hero.png"}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | text | Required | Non-empty, and unique across the document. A layer's `refId` names it. |
| `u` | text | `""` | The file's directory, from the version's root, where `data.json` lives. Leave it out or empty when `p` includes the directory. |
| `p` | text | Required | The file. `u + p` is its path: `u:"images/", p:"hero.png"` or `u:"", p:"images/hero.png"`. `..` is not allowed. Keep directories, case and names exactly as in the version. |
| `w`, `h` | whole number | The file's size | The size the file renders at, before layer transforms. A video needs them. |

- Declare the file's own size when it is at most 4096 pixels on each side. A file of another size is stretched to the declared one. For a larger file, declare its size scaled to fit 4096, and the file is scaled down to that.
- An image without `w` and `h` renders at its file's size, scaled to fit 4096 if larger.
- The declared size is not the size on the canvas: scale the layer for that.
- An image layer (`ty:2`) needs an image, and a video layer (`ty:9`) a video: all video belongs on `ty:9`. A GIF or WebP may sit on either. An animated one plays as video, and a one-frame one shows as a still.
- Don't embed base64 images or point to a URL.
- When no file matches `u + p` exactly, Blitframe takes one that differs only in letter case. Failing that, it takes the only file in the version with that name ([asset paths](/docs/blitframe/data-json#asset-paths)).
- Model assets need no `w` or `h` ([native models](#native-models)). Audio comes from the version's soundtrack or the render's `audio` ([audio layers](#audio-layers)).

### File formats

Images and video can be in any format [Projects](/docs/blitframe/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:

```json
{"ty":9,"ind":2,"nm":"Clip","refId":"video_1","ip":30,"op":150,"st":30,"sr":1,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}}}
```

- With `st: 0`, it would show the clip from its 1-second mark, as if it had played unseen since frame 0.
- With `st` later than `ip`, the video does not wait: it plays from its beginning at `ip`, as if `st` equalled `ip`.
- A video layer plays forward once, with no looping or time stretch. After its last frame, that frame stays on screen until the layer's `op`.
- To hold a frame or play backwards, use [time remap](#time-remap) on the video layer.

### Replace or place media

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

### Precompositions

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

```json
{"id":"scene_1","nm":"Scene 1","layers":[]}
```

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

### Edge cases

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

## Native models

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

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

```json
{
  "v":"5.12.2","nm":"Product rotation","w":1080,"h":1080,"fr":30,"ip":0,"op":90,"ddd":0,
  "assets":[{"id":"product","u":"models/","p":"product.glb"}],
  "layers":[{
    "ty":16,"ind":1,"nm":"Product","refId":"product","ip":0,"op":90,"st":0,"sr":1,"bm":0,
    "ks":{
      "p":{"a":0,"k":[540,540,0]},"a":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},
      "o":{"a":0,"k":100},"or":{"a":0,"k":[0,0,0]},
      "rx":{"a":0,"k":0},"ry":{"a":1,"k":[{"t":0,"s":[0]},{"t":90,"s":[360]}]},"rz":{"a":0,"k":0}
    }
  }]
}
```

- One glTF unit (one metre) is 512 composition pixels, times the layer's scale.
- The GLB's origin is the layer's own (0,0,0). With anchor `ks.a` at `[0,0,0]`, it lands on the layer's position. A nonzero anchor, in those pixels, is the pivot `ks.p` places. The engine does not recenter the model.
- glTF's up (+Y) points up the composition.
- Lighting is fixed: a built-in studio environment lights every model the same way. There are no lights, exposure or environment settings, and lights or cameras in the GLB are not used.
- The layer's 3D transforms move and turn the model, animated or static: three-component position, anchor and scale, `rx`, `ry`, `rz` and `or`. So does the composition camera. Without a camera layer, the default perspective camera shows the model, not an orthographic view.
- Each model layer draws in its own pass. Model layers don't hide each other, or 2D layers, by depth: they stack by `ind` like other layers. Put parts that must pass through each other in one GLB.
- A model layer takes its layer opacity, blend mode and track matte. It draws no effects or layer styles (`warnings`).
- Masks on a model layer may not apply. To clip a model, use a [track matte](#track-mattes), and render a frame to check.
- Each model asset loads once, however many layers show it, and takes one [mesh](#render-limits). Two asset ids naming one file load it twice. Its textures count toward the [texture limit](#textures).

### What the engine draws

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

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

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

### Models Blitframe refuses

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

- not a valid GLB container of glTF version 2 or later, a truncated GLB, or empty JSON
- a key repeated in one JSON object
- a buffer whose URI is not a base64 `data:` URI holding its size, or without a positive `byteLength`
- a buffer view outside its buffer, or a first buffer larger than the binary chunk
- an image linked by URI to another file, or by a `data:` URI that is not valid base64
- accessors outside their buffer view, or that break glTF's accessor type and sparse storage rules
- index values outside their primitive's vertices (or their sparse accessor's elements)
- index data that is interleaved, or not unsigned byte, short or int scalars
- a primitive `mode` above 6
- references to missing elements
- no meshes or nodes, or a mesh without primitives
- vertex attributes of one primitive with different counts
- primitives of one mesh with different morph target counts
- a morph target whose vertex count differs from its primitive's
- `targetNames` or default `weights` whose count differs from the morph target count
- an animation sampler whose output count does not match its input
- an animation sampler or channel missing its input, output, sampler or target, or a weights animation on a node without a mesh
- a node that contains itself or has two parents, or a scene root node that has a parent
- a required extension other than `KHR_materials_emissive_strength`
- no triangles to draw
- more than these limits:

| Resource | Limit |
| --- | --- |
| One GLB | 100 MB, with its JSON at most 8 MB and nested at most 64 deep (Blitframe's limits) |
| One `.gltf` | 8 MB |
| Drawn geometry | 22,369,621 vertices and 268,435,455 indices across the drawn scene, and 67,108,863 vertices in one primitive (the engine's limits). A node counts every time the scene reaches it, up to one draw per node and primitive in the file. A mesh without normals counts one vertex per index. |

### Edge cases

- A model layer without a text `refId`: `problems`. So is one whose `refId` names no asset, an asset without a file `p` (such as a precomposition), an asset whose `p` is a `data:` URI, or an asset that is not a `.glb` or `.gltf` file in the version (such as an image).
- A model the engine cannot load stops the render ([models Blitframe refuses](#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:

```json
{"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](#paths). 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](#vector-paths).
- A layer whose masks are all skipped draws unmasked.
- Write an explicit numeric `a:0` or `a:1`, and complete path and opacity objects.
- To animate a mask path, replace `pt` with path keyframes that keep the vertex topology. Masks don't run expressions.
- An image, solid, video or precomposition layer is masked before its effects run ([effects](#effects)).

### Track mattes

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

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

### Edge cases

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

## Blend modes and effects

A layer's `bm` sets its blend mode:

| `bm` | Mode | `bm` | Mode | `bm` | Mode |
| --- | --- | --- | --- | --- | --- |
| 0 | normal | 9 | soft light | 18 | linear burn |
| 1 | multiply | 10 | difference | 19 | darker color: renders as normal |
| 2 | screen | 11 | exclusion | 20 | linear dodge |
| 3 | overlay | 12 | hue | 21 | lighter color: renders as normal |
| 4 | darken | 13 | saturation | 22 | vivid light |
| 5 | lighten | 14 | color | 23 | linear light |
| 6 | color dodge | 15 | luminosity | 24 | pin light |
| 7 | color burn | 16 | add | 25 | subtract |
| 8 | hard light | 17 | hard mix | 26 | divide: renders as normal |

- Write `bm` as a whole number from 0 to 26, without a decimal point.
- Don't choose 19, 21 or 26: they render as normal, and Blitframe warns.
- A blend mode changes how the layer mixes with the content below. It does not replace a transparent asset or a matte.
- Layer styles number their blend modes differently ([style blend modes](#style-blend-modes)).

### Effects

Effects are entries in a layer's `ef` list:

```json
{"ty":21,"mn":"ADBE Fill","nm":"Fill","ef":[{"ty":2,"nm":"Color","v":{"a":0,"k":[0.1,0.3,0.8,1]}},{"ty":0,"nm":"Opacity","v":{"a":0,"k":1}}]}
```

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

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

| Effect `mn` | Display `nm` | Parameters and animation |
| --- | --- | --- |
| `ADBE Fill` | `Fill` | Animated `Color` RGB and `Opacity` 0–1 |
| `ADBE Gaussian Blur`, `ADBE Gaussian Blur 2` | `Gaussian Blur` | Animated `Blurriness` (it stops growing at about 344); static `Blur Dimensions`, `Repeat Edge Pixels` |
| `ADBE Box Blur2` | `Fast Box Blur` | Static `Blur Radius` (at most 500 pixels), whole-number `Iterations` 1 to 50, `Blur Dimensions`, `Repeat Edge Pixels` |
| `ADBE Drop Shadow` | `Drop Shadow` | Static `Shadow Color` RGB and whole-number `Shadow Only`: 0 draws the layer over its shadow, 1 the shadow alone. Animated `Opacity` 0–255 (255 opaque, 128 about half), `Direction` in degrees, `Distance` in pixels, `Softness`. |
| `ADBE Ramp` | `Gradient Ramp` | Static `Start of Ramp` and `End of Ramp` XY, `Start Color` and `End Color` RGB, `Ramp Shape`, `Ramp Scatter` (a noise amount, clamped to 0–1), `Blend With Original` |
| `ADBE Linear Wipe` | `Linear Wipe` | Animated `Transition Completion` 0–100, `Wipe Angle` in degrees, `Feather` in pixels |
| `ADBE Corner Pin` | `Corner Pin` | Animated XY `Upper Left`, `Upper Right`, `Lower Left`, `Lower Right` ([corner pins](#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](#layer-styles). 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).

### Effect canvas size

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

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

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

### Effect coordinates

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

| Layer receiving the effect | Point coordinates |
| --- | --- |
| Image, solid, video or precomposition layer | Local source pixels, before the layer's transform: a solid's `sw` × `sh` canvas, a precomposition layer's `w` × `h` |
| Text, shape or adjustment layer | Pixels of the composition containing the layer, after layer and parent transforms: inside a precomposition, its canvas, not the root's |

- On text and shape layers, Corner Pin, CC Power Pin, Mirror, CC Cylinder and Transform act on the whole containing composition, not only the content.
- Venetian Blinds bands are anchored at the layer's center on image, solid, video and precomposition layers. On text and shape layers, they are anchored at the composition's center.
- Shape-paint `gf` and `gs` endpoints stay local to their shape group: they are not effect parameters.

### Corner pins

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

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

### Effect dropdown values

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

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

### Edge cases

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

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

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

## Layer styles

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

```json
{"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](#style-blend-modes) |
| `ty:0` stroke | `c` | property: RGB | `[1,0,0]`, red | Opacity is full, blend is normal, and the stroke sits outside the layer. |
| | `s` | property: number | 3 | Size in pixels |
| `ty:3` outer glow | `c` | property: RGB | `[1,1,0.75]` | |
| | `o` | property: number | 75 | Opacity 0–100 |
| | `s` | property: number | 5 | Size in pixels |
| | `ch` | property: number | 0 | Spread 0–100, a percentage of size |
| | `r` | property: number | 50 | Range 0–100 |
| | `bm` | `{"k":whole number}` | 11, screen | |
| | `tc` | `{"k":whole number}` | 1, softer | Technique: 1 softer, 2 precise |
| | `no`, `j` | | None | Noise and jitter are ignored (`warnings` when set) |
| `ty:1` drop shadow | `c` | property: RGB | `[0,0,0]`, black | |
| | `o` | property: number | 75 | Opacity 0–100 |
| | `a` | property: number | 120 | Angle in degrees |
| | `d`, `s` | property: number | 5, 5 | Distance and size in pixels |
| | `ch` | property: number | 0 | Spread 0–100 |
| | `bm` | `{"k":whole number}` | 5, multiply | |
| | `lc` | `{"k":whole number}` | 1 | Layer knocks out drop shadow. Changes nothing. |
| | `ga` | `{"k":whole number}` | 0 | Use Global Light is not applied: the shadow always uses its own `a`. Turn it off. Blitframe warns when `ga` is 1. |

- A field you leave out takes the value in the Default column, which is After Effects' own dialog default. Use Global Light is the exception: the shadow always uses its own `a`. Write every field you rely on.
- Only these `ty` values render. Inner shadow, inner glow, bevel, satin and gradient overlay are skipped.
- Colors, opacity, size, spread, angle, distance and range can be keyframed. `bm` and `tc` are static whole numbers.
- Write every field as an object with `k`.
- Image, solid, video, precomposition, text and shape layers can carry styles. A 3D model layer draws neither effects nor styles, and an adjustment layer draws no styles, with a warning for both.
- Styles composite after the layer's effects and transform, in pixels of the containing composition. Scaling a layer does not scale its style's size, spread or distance.

### Style blend modes

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

| `bm.k` | Mode | `bm.k` | Mode | `bm.k` | Mode |
| --- | --- | --- | --- | --- | --- |
| 1 | normal | 13 | linear dodge | 22 | hard mix |
| 4 | darken | 14 | lighter color | 24 | difference |
| 5 | multiply | 16 | overlay | 25 | exclusion |
| 6 | color burn | 17 | soft light | 26 | subtract |
| 7 | linear burn | 18 | hard light | 27 | divide |
| 8 | darker color | 19 | vivid light | 29 | hue |
| 10 | lighten | 20 | linear light | 30 | saturation |
| 11 | screen | 21 | pin light | 31 | color |
| 12 | color dodge | | | 32 | luminosity |

- Color overlay renders every mode in the table. On drop shadow and outer glow, 8, 14 and 27 render as normal.
- Any other value, such as 2 (dissolve), renders as normal. Blitframe warns about a style blend mode that renders as normal.

### Edge cases

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

| `ty` written as | Read as |
| --- | --- |
| Missing, `null`, `true`, `false`, `""`, `[]`, and many decimals such as `7.0` or `7.5` | 0: a stroke |
| A one-item list | 1: a drop shadow |
| A negative number, most strings, and decimals such as `0.1` | Skipped |

## Expressions

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

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

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

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

```json
{"a":0,"k":[944,204,0],"x":"[value[0], value[1] + 30 * Math.sin(2 * Math.PI * time / 2), value[2]];"}
```

- Preserve the property's `a`, `k` and other metadata: they give its static or keyframed base and its fallback. Don't switch a static property to `a:1` because its expression changes over time.
- An expression can override the base, so changing only `k` may change nothing.

### How to write a script

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

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

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

- A top-level `let`, `const` or `class` fails from the second run, and the expression falls back to the property's value. Another expression declaring the same top-level name fails from its first run. `warnings` flag each expression with a top-level `let`, `const` or `class`. Declarations inside a function or block are fine.
- Top-level `var` and function names are shared too, and the helpers are ordinary globals. Never name a top-level variable or function after a helper or global such as `ease`, `linear`, `clamp`, `smooth`, `wiggle`, `key`, `loopOut` or `thisComp`. It would replace it for every other expression.
- Top-level `var` values persist from frame to frame. Don't rely on them: compute each frame's value from its inputs.
- All scripts together get 64 MB of memory and a 256 KB stack. A script that exceeds either throws and falls back.

| Intent | Property | Script |
| --- | --- | --- |
| Gentle rotation around the authored angle | `ks.r` | `value + 8 * Math.sin(2 * Math.PI * time / 2);` |
| Pulse X and Y scale by 5%, keep Z | `ks.s` | `var factor = 1 + 0.05 * Math.sin(2 * Math.PI * time / 2); [value[0] * factor, value[1] * factor, value[2]];` |
| Position wiggle around existing motion | `ks.p` | `wiggle(2, 15);` |
| Repeat a keyframed track after its last key | A supported keyframed property | `loopOut("cycle");` |
| Ping-pong a keyframed track | A supported keyframed property | `loopOut("pingpong");` |
| Offset separated X by 40 pixels | `ks.p.x` | `value + 40;` |

### What does not run

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

### Expression functions and values

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

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

- Don't use expressions to recover authored layer names, indices or visibility bounds. Keep names and relationships from the inspected document, and read `data.json` for editable copy.
- Preserve exported `$bm_sum`, `$bm_sub`, `$bm_mul`, `$bm_div`, `$bm_mod` and `$bm_neg` helpers.
- Expression selectors do per-text selection, not transform placement ([per-character expression selectors](#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:

```javascript
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:

```json
{"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:

```json
{"a":{"p":{"a":0,"k":[0,24,0]}},"s":{"t":1,"b":1,"x":"100 * Math.sin(2 * Math.PI * time / 1.5 - (textIndex - 1) * 0.5);"}}
```

- Append it to the existing animator list to keep other animation, and inspect several frames for readability and clipping.
- A selector weights every property in its animator. Use separate animators for different selections.
- It multiplies the selection of the selectors before it, as After Effects' Intersect does, and starts from full selection when it comes first. So returning `selectorValue` after a range selector squares partial selections.
- Selectors can use composition size and duration, `thisComp.frameDuration`, math and interpolation helpers. They cannot use `thisLayer`, `thisComp.layer`, `numKeys`, keyframe sampling, or loop helpers that need a property track.
- `wiggle` gives every element of a selector the same amount: use `textIndex` for per-element variation.
- Return one amount, not separate X, Y and Z amounts.

### Edge cases

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

## Complete starter and edit recipes

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

```json
{"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](#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.

```json
{"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.

```json
{"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`.

```json
{"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.

```json
{"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.

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

## Check the result and recover

1. The version's `problems` must be empty: every asset path and font resolves, and the document fields are in range.
2. Render the exact version. For a quick look, render a few frames with `format: "frames"` at the moments that matter. Pick the opening, during and after transitions, motion extremes, and the last visible frame.
3. Check text, clipping, mattes, effects, image sharpness and occlusion. A layer or effect in the JSON does not prove it renders as intended.
4. If something is wrong, fix its cause in another edit, and check the affected moments again.

| Symptom | What to inspect |
| --- | --- |
| A shape or part of a logo is missing | Missing paint, paths after paints, unsupported modifiers. Nested groups and per-group path and paint limits are in `warnings`. |
| A shape reveal does not animate | Several paths before one trim, missing keyframes on the trim's `s`, `e` or `o`, or animation on a static-only property |
| An effect has no visible result | Exact `mn`, parameter `nm`, units, supported animation, effect order |
| Text is wrong, clipped or does not change | Font resolution, the first text document, baseline, paragraph or fitting region, visibility intervals. Timed copy changes need separate layers. |
| Content is clipped or misplaced | Anchor, parent and group transforms, precomposition size, transparent padding, mask space, effect coordinates |
| A matte reveals the wrong object | Which layer has `td` and which `tt` and `tp`, its `ind`, same-composition references, overlapping visibility |
| Movement snaps, or an edit seems ignored | Every key's `s` and `e`, easing, spatial tangents, separated axes, overriding expressions |
| An empty opening or tail | Root and nested `ip` and `op`, precomposition and video `st`, time remap, media duration |
| An expression appears static | Supported property slot, return shape, enough keys for loops, fallback to the authored value |
| A render is refused, or an image or video is missing | MP4 and HLS need an even width and height, or `422 version_not_renderable`. An asset declared too large is skipped ([asset fields](#media-and-precompositions)). |
| Many vector shapes don't render as designed | The [vector path](#vector-paths) limit |

See also: [data.json basics](/docs/blitframe/data-json), [Fonts](/docs/blitframe/fonts), [Renders](/docs/blitframe/renders).
