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-level meta (title, resolution, fps, budget…) and the ordered scenes: list — the play order.
sources.yaml	The recipe map: how each raw asset (terminal recording, browser capture, image, clip) is produced, keyed by id. Optional.
scenes/<id>.yaml	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-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, then the per-file references for project.yaml, sources.yaml, and scenes/<id>.yaml.