## 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` |
