project.yaml

The top of the project. It holds project-level meta, the ordered scenes: list (which is the play order), and an optional thumbnail.

# yaml-language-server: $schema=../../schemas/project.schema.json
meta:
  title: My Video
  resolution: [1920, 1080]
  fps: 30
  target: { platform: youtube, max_duration: 120, encode: youtube-1080p }
  budget: { max_usd: 5.0, require_approval_above: 0.5 }
scenes: [intro, demo, outro]        # order = play order; each id names a scenes/<id>.yaml
thumbnail: { source: hero_img, title_text: My Video }

meta

Project-wide settings that every scene inherits.

Field	Meaning
title	The video title (used in metadata, thumbnail, chapters).
resolution	[width, height] of the output canvas, e.g. [1920, 1080].
fps	Frames per second.
target	Delivery target — platform, max_duration (seconds), and an encode profile.
budget	Cost guardrail — max_usd caps the run; require_approval_above gates paid work above a threshold.

meta also carries optional brand, avatar, voice, music, captions, and defaults (e.g. defaults.video_speed) — a per-scene value always overrides the project default.

scenes

The ordered list of scene ids. The list is the play order, and each id must name a file in scenes/ (intro → scenes/intro.yaml):

scenes: [intro, demo, outro]

Reorder the video by reordering this list. Deleting an id removes that scene from the cut (the scene file can stay on disk).

thumbnail

Optional. Points at an image source and overlays title text:

thumbnail: { source: hero_img, title_text: My Video }

Validate before you render

decodx plan my-video

decodx plan validates the whole file set, expands defaults, and prints the estimate table — no cost, no render. Errors name the exact authored file and field.

Next: sources.yaml — the recipe map your scenes reference.