# Compiler project 1.0

Project `1.0` describes one logical animation and an ordered set of codec
encodings. The compiler creates one AVAL wire-1.0 file for each encoding; it
never combines codec families in one file.

```json
{
  "projectVersion": "1.0",
  "alpha": "auto",
  "canvas": {
    "width": 1920,
    "height": 1080,
    "fit": "contain",
    "pixelAspect": [1, 1],
    "colorSpace": "srgb"
  },
  "frameRate": { "numerator": 30, "denominator": 1 },
  "sources": [
    {
      "id": "render",
      "type": "video",
      "path": "render.mov",
      "timing": { "mode": "exact" }
    }
  ],
  "encodings": [
    {
      "codec": "av1",
      "bitDepth": 10,
      "cpuUsed": 0,
      "tiles": { "columns": 4, "rows": 2 },
      "rowMt": true,
      "threads": 32,
      "renditions": [
        { "id": "video.1x", "width": 1920, "height": "auto", "crf": 15 }
      ]
    },
    {
      "codec": "vp9",
      "deadline": "best",
      "cpuUsed": 0,
      "threads": 8,
      "renditions": [
        { "id": "video.1x", "width": 1920, "height": "auto", "crf": 40 }
      ]
    },
    {
      "codec": "h265",
      "preset": "veryslow",
      "threads": 8,
      "renditions": [
        { "id": "video.1x", "width": 1920, "height": "auto", "crf": 32 }
      ]
    },
    {
      "codec": "h264",
      "preset": "veryslow",
      "renditions": [
        { "id": "video.1x", "width": 1920, "height": "auto", "crf": 20 }
      ]
    }
  ],
  "units": [
    {
      "id": "idle.body",
      "kind": "body",
      "source": "render",
      "range": [0, 120],
      "playback": "loop",
      "ports": []
    }
  ],
  "initialState": "idle",
  "states": [{ "id": "idle", "bodyUnit": "idle.body" }],
  "edges": [],
  "bindings": []
}
```

The schema is exact: unknown fields and older project versions are rejected.
Encoding order is also the recommended browser `<source>` order. Codec names
must be unique, and every encoding owns an authored-quality rendition ladder.
One rendition dimension may be `"auto"`; the compiler resolves the matching
even dimension while preserving the canvas aspect ratio.

## Alpha and precision

`alpha` is `"auto"`, `"opaque"`, or `"packed"`. Auto inspects the canonical
source pixels once. Packed alpha places color and alpha in one decoded video
surface for every codec. The shared working spool is 16-bit RGBA. Eight-bit
inputs expand exactly; AV1 `bitDepth: 10` downconverts only when producing the
10-bit YUV surface, while all 8-bit encodings downconvert at their output
boundary.

## Compression controls

Rendition `crf` accepts `0..51` for H.264/H.265 and `0..63` for VP9/AV1.
H.264/H.265 `preset` accepts the encoder presets from `ultrafast` through
`placebo`. VP9 accepts `deadline: best|good|realtime`, `cpuUsed: -8..8`, and
`threads: 1..64`. AV1 accepts `bitDepth: 8|10`, `cpuUsed: 0..8`, power-of-two
tile columns/rows with a product at most 64, `rowMt`, and `threads: 1..64`.

These are closed structured controls, not arbitrary FFmpeg arguments. The
compiler owns scaling, elementary-stream output, pixel formats, color
metadata, unit boundaries, and audio/subtitle/data removal. VP9 and AV1 CRF
automatically add `-b:v 0`. MP4/WebM settings such as `hvc1`/`av01` tags,
`faststart`, and `strict experimental` do not apply to AVAL elementary chunks.

Slow settings have no default wall-clock cutoff. Use
`--media-timeout-ms <positive-integer>` only when the build environment needs
an explicit limit.

## Graph and timing

Ranges are half-open authored frame ranges. Every body, bridge, reversible,
and one-shot unit is independently decodable. Encoded chunks are stored in
decoder submission order; their presentation timestamps, displayed-frame
counts, and random-access status are stored separately. This permits B-frames,
lookahead, hidden references, and multi-output chunks without changing the
authored presentation timeline or creating dependencies across unit
boundaries.