Project Setup and State

Layout

my-reel/
├── project.md     # session memory — read first, update after every gate
├── state.json     # pipeline state (gates, config) — managed by pipeline.py
├── raw/           # user's original clips (never modified) — may be a symlink
├── music/         # one audio track (mp3/m4a/wav)
├── work/          # mezzanine files, sheets/, extracts/, cards/, beats.json, clips.json
├── plan/          # cut_plan.json (the human-editable artifact), reel.fcpxml
├── preview/       # low-res draft renders
└── exports/       # final platform deliverables

The four intake answers

Step 1 settles format, aspect, resolution, and captions before any media is touched. All four land in state.json and route the rest of the pipeline.

• Aspect — 9:16 reel/short (default), 16:9 landscape YouTube, 1:1 feed. A 16:9 master exports a single youtube.mp4; export_variants.py reads the master's dimensions and skips the vertical targets, because a landscape cut posted as a Short would be letterboxed into a vertical frame.
• Resolution — 1080 (default) or 4k. Worth it for an archival master or a YouTube-primary upload; platforms downscale on delivery either way. 4K normalize and render are markedly slower.
• Cropping across aspect upscales. A landscape source cut to 9:16 keeps only height * 9/16 of width (~1215px from UHD); a portrait source cut to 16:9 keeps only its own width. normalize_clips.py names each affected clip on stderr — bigger, not sharper.
• Captions — burning in is a render-time flag, but transcription has to happen before Gate 2, so the answer changes the plan. Talking-head reels are watched muted; recommend yes.

init flags

python3 scripts/pipeline.py init --target-duration 30 --mode music-video --resolution 1080

• --mode {music-video,talking-head} — answer Step 1 before running init. pipeline.py mode talking-head switches an existing project.
• --resolution {1080,4k} — added to the normalize and render commands pipeline.py emits, so a 4K project cannot silently fall back to 1080.
• --target-duration — 30 suits a montage; talking-head runs 60–90.

Both settings live in state.json and route every later status / next. Records written before these flags existed read as music-video / 1080.

Footage on another disk

Never copy gigabytes into raw/ — symlink it:

rmdir raw && ln -s /Volumes/Drive/shoot-folder raw

Every script follows symlinks. Tell the user the drive must stay mounted for any re-probe or re-normalize; the mezzanines in work/ keep renders working if it is not.

state.json vs project.md

state.json tracks where the pipeline is — stage completion read from artifacts on disk, staleness chained through file mtimes (edit the cut plan and preview/master/exports flip to stale), and gate decisions.

project.md records why — the human's settled decisions. pipeline.py init copies assets/project_template.md into place; update it after each gate with approved hook, trims, and grade tweaks so later sessions and batch reels never re-ask a settled question. Copy the "carry-forward learnings" section into each new project.

Gate bookkeeping

python3 scripts/pipeline.py gate 1|2 presented|approved|nle-wait|reopen

Record every human decision the moment it happens. The command refuses an approval when the preview or master has gone stale, and enforces the NLE pause.