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