# YAML Overview

> How a Decodx video is described in YAML — the three-file spec model and how it composes.

# YAML Overview

In Decodx, a video is **not** a timeline you drag clips onto — it's a small set of committed YAML
files that you author like source code. Decodx reads those files, composes them into one canonical
spec object, and renders it. The build is a pure function of the inputs, so the **same YAML always
produces the same MP4**.

## The three-file model

A project is a directory. You author three kinds of YAML file:

```
my-video/
├── project.yaml          # project meta + the ordered scene list
├── sources.yaml          # the recipe map: how each raw asset is made
└── scenes/               # one file per scene (the filename is the scene id)
    ├── intro.yaml
    ├── demo.yaml
    └── outro.yaml
```

| File | Role |
|------|------|
| [`project.yaml`](./project) | Project-level `meta` (title, resolution, fps, budget…) and the ordered `scenes:` list — the play order. |
| [`sources.yaml`](./sources) | The recipe map: *how* each raw asset (terminal recording, browser capture, image, clip) is produced, keyed by id. Optional. |
| [`scenes/<id>.yaml`](./scenes) | One scene each — a background, an optional avatar overlay, and narration. |

## How they compose

The three files are **not** independent. They compose into one object that drives the whole render:

```
project.yaml  ──┐
sources.yaml  ──┼──►  one canonical spec  ──►  render (pure function)  ──►  final.mp4
scenes/*.yaml ──┘
```

- `project.yaml`'s `scenes: [intro, demo, outro]` list names files in `scenes/` **and** fixes the
  play order.
- Each `scenes/<id>.yaml` references asset ids that are defined in `sources.yaml`.
- `sources.yaml` points at the actual files under `inputs/`.

Because the render is deterministic, you can re-render freely: expensive assets are cached by content
hash, so only what you changed is redone.

## Why YAML

- **Diff-able & reviewable** — a video change is a line change in a pull request, not an opaque binary.
- **Composable** — reuse a source across many scenes; reorder scenes by reordering a list.
- **Automatable** — an agent or CI job edits the YAML and calls `decodx run`; no GUI in the loop.

## Editor autocomplete

Every Decodx YAML file starts with a schema comment so your editor gives you inline validation and
autocomplete:

```yaml
# yaml-language-server: $schema=../../schemas/project.schema.json
```

The schemas live in `schemas/` and regenerate with `decodx schema`. Run `decodx plan <project-dir>`
to validate the whole file set before spending anything on a render — errors name the exact file and
field.

Next: the [YAML syntax primer](./syntax), then the per-file references for
[`project.yaml`](./project), [`sources.yaml`](./sources), and [`scenes/<id>.yaml`](./scenes).