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