# `sources.yaml`

> The sources.yaml reference — the recipe map of raw assets your scenes reference by id.

# `sources.yaml`

The **recipe map**: *how* each raw asset is made, keyed by id. Scenes reference these ids; the ids
point at files under `inputs/`. Paths are relative to the project directory.

```yaml
# yaml-language-server: $schema=../../schemas/sources.schema.json
install_demo:   { kind: cli,   tape: inputs/recordings/install.tape }          # terminal recording (vhs)
dashboard_demo: { kind: web,   spec: inputs/recordings/dashboard.scenes.yaml } # browser recording (Playwright)
hero_img:       { kind: image, file: inputs/media/hero.png }                   # a provided image
```

Each entry is `id: { kind: …, <recipe fields> }`. A scene then refers to the asset by its id, e.g.
`background: { kind: web, source: dashboard_demo }`.

## Source kinds

| `kind` | What it produces | Key field |
|--------|------------------|-----------|
| `cli` | A terminal recording rendered from a [vhs](https://github.com/charmbracelet/vhs) `.tape` script | `tape:` |
| `web` | A browser capture driven by a Playwright `.scenes.yaml` recipe | `spec:` |
| `image` | A provided still image used directly | `file:` |
| `video` | A pre-recorded clip you already have (screencast, captured demo) | `file:` |
| `avatar` | A talking-head clip generated from narration | — |

## `sources.yaml` is optional

A project whose scenes are all `slide` or `avatar` needs no `sources.yaml` at all — those scenes
generate their own visuals from templates and narration.

## Where files live

Point recipe fields into `inputs/`:

```
inputs/
├── media/            # image files for `image` / `video` sources (file:)
│   └── hero.png
└── recordings/       # recipe sources: .tape (vhs), .scenes.yaml (Playwright), frozen .har
    ├── install.tape
    └── dashboard.scenes.yaml
```

At `decodx plan`, a `file:`-backed source whose pixel dimensions differ from `meta.resolution`
prints an advisory (below the canvas → upscaled and soft; far above → downscaling can blur fine
screen text).

Next: [`scenes/<id>.yaml`](./scenes) — where you assemble backgrounds, avatars, and narration.