craft-libs/crates/lottie/README.md

# craft-lottie

Lottie (Bodymovin) JSON: the document as the file has it, and the encodings its values use. Bytes
in, a neutral model out, and back. Which layer, shape, effect and text feature becomes what in an
application's document is the application's work.

No file access: callers pass bytes, so the crate builds for wasm32.

## The document model

`Animation::read(bytes)` gives the document; `to_json` and `to_vec` write it. The model is the
lottie-spec 1.0 object model, one struct per object and one field per key:

- `Animation`: version, frame rate, frame range, size, `assets`, `layers`, `markers`, `fonts`,
  `chars`, `meta`.
- `Asset`: an image (`dir`, `path`, `embedded`) or a precomposition (`layers`).
- `Layer`: the keys every layer has (name, `index`, `parent`, timing, blend mode, `transform`,
  `masks`, `effects`, matte keys) and `content`, by `ty`: `Precomp`, `Solid`, `Image`, `Null`,
  `Shape`, `Text`, or `Other` for a type the model has no struct for.
- `Shape`: the keys every shape item has and `kind`, by `ty`: group, rectangle, ellipse, polystar,
  path, fill, stroke, gradient fill and stroke, transform, trim, round corners, repeater, merge,
  pucker and bloat, twist, zig-zag, offset path, or `Other`.
- `Transform`, `Mask`, `Effect` (an effect and its values), `Marker`, `Fonts`, `Font`, `Char`.
- `TextData`: the documents over time (`TextDocument`), range animators (`TextRange`,
  `TextSelector`, `TextStyle`), alignment and path options.

Every field is an `Option`: files leave keys out, and a writer sets what it needs. An animatable
property is an `Animated`, the property's JSON; `Animated::read` gives its value or keyframes (see
below). What a value means depends on the property, so the model does not decode values.

Nothing a file holds is dropped because the model does not know it. A key the struct does not
name, and a key whose value has another type than the struct expects, stay in the struct's `extra`
and are written back. A layer or shape of an unknown `ty` keeps its `ty` and its keys. So a
document read and written back is the same JSON, with three exceptions: an entry of a list that is
not an object where objects are expected is left out, a whole number written `30.0` comes back
`30`, and a flag written `1` or `0` where the schema has a boolean comes back `true` or `false`.

`Limits` bounds what is read: bytes of JSON (256 MiB), nesting (128 levels, which is also where
`serde_json` stops), layers of the document and its precompositions together (100,000), assets
(20,000) and shape items (2,000,000). Passing one is `LottieError::TooLarge`. No reader panics on
any input.

## The encodings

These work on `serde_json` values, for the values the model leaves as JSON.

| Part | Read | Write |
|---|---|---|
| Document JSON and header (`w`, `h`, `fr`, `ip`, `op`, `nm`) | `parse_document`, `Header::read` | the application builds the JSON |
| Animatable property (`{a, k, x}`) and keyframes | `read_prop` | `write_prop`, `write_keys` |
| Ease of a segment (`o`, `i`) and speed / influence | `Tangents::read`, `to_speed` | `Tangents::from_speed` |
| Bezier path (`{c, v, i, o}`) | `Bezier::from_json` | `Bezier::to_json` |
| Gradient stop list (`g.k`) | `Gradient::from_flat` | `Gradient::to_flat` |
| Numbers, colours, `#rrggbb` | `nums`, `color`, `hex_color` | `round6`, `to_hex` |
| Embedded images (`data:` URIs, RFC 4648 base64) | `base64::data_uri` | `base64::to_data_uri`, `image_mime` |

Not here: dotLottie (`.lottie`), which is a ZIP archive around the same JSON, and layer styles
(`sy`), which lottie-spec 1.0 does not define (they stay in a layer's `extra`).

## What the readers accept

Files in the wild come from many Bodymovin versions and other exporters, so the readers are
tolerant where players are:

- a property that is a bare value (`"o": 100`), a property without `a` whose `k` is a key list,
  and a key value wrapped once more (`[[x, y]]`);
- keys before 5.0: a segment ends with `e` and the last key has no `s`; the value of a key is
  then the `e` of the key before;
- ease tangents whose `x` and `y` are a number or a list, per dimension; a missing `x` is a
  third of the way and a missing `y` is linear;
- a path without `c`: Bodymovin 3.x and early 4.x keep the flag outside the path (`cl` on a
  mask, `closed` on an `sh` item), so the caller passes it; tangent lists shorter or longer than
  the vertex list;
- colours written 0..=255 instead of 0..=1;
- a gradient list without alpha pairs, and a colour count larger than the list.

Nothing is indexed by a number from the file, and no reader panics.

## Ease

A Lottie keyframe holds the start value of a segment and the segment's normalised cubic Bezier
ease: `o` (out of this key) and `i` (into the next), each with `x` (time fraction) and `y` (value
progress fraction), per dimension. After Effects' temporal ease is speed (units per second) and
influence (fraction of the segment). For a segment of duration `d` and value change `Δv`:

```text
o.x = influence_out          o.y = speed_out · influence_out · d / Δv
i.x = 1 − influence_in       i.y = 1 − speed_in · influence_in · d / Δv
```

`Tangents::from_speed` and `Tangents::to_speed` are this formula and its inverse. A spatial
property eases along its motion path: one dimension, with `Δv` the arc length, which the caller
computes.

## Sources and clean room

Implemented from the public Lottie format description (the lottie-spec 1.0 schema and the
LottieFiles format documentation); no player or exporter source was used. The encodings come from
EffectCraft's `effectcraft-lottie` crate; the document model is written here from the same
description. The four fixtures in `tests/fixtures` are hand-written
JSON (original work), not exported from any product.