Chapter 1 — Setup
Status: DRAFT 2 (2026-09-21), rewritten to DESIGN v6 §5. Draft 1's tool inventory and media.sh command table moved to Appendix B; the build-script walkthrough moved to Chapter 11. Commands and outputs quoted were run on the production machine on 2026-09-21.
1.0 Objective
Given a shot table and two clips, you can conform a 10-second cut, read its verification file, and diagnose a seeded one-frame mismatch.
1.1 What you are deciding
Three things, all free:
- Where the film lives. One folder under version control. Everything the agent writes goes in; generated video does not.
- What is on the required path. Five tools. No GPU, no paid editor.
- How you know the setup works. A 10-second conform from a shot table, fully decoded, frame count matching the plan. This proves the setup and nothing else.
One rule arrives with this chapter and stays for the whole book: never delete or overwrite. Every cut, every retake, every audio version gets its own file or folder. A "fix" that overwrites the approved version destroys the thing the Director approved. We ended at CUT33 and all thirty-three assemblies still exist.
1.2 How we did it
One laptop, no GPU on the required path. Every read (trims, contact sheets, strips, loudness, transcripts) went through one shell script wrapping ffmpeg, ffprobe and whisper, built on the rule in its own header: "this tool must fail loudly. A gate that silently reports 'fine' on an unreadable file is worse than no gate at all." A bare call only reports; it never claims a pass.
Every assembly was one Python script per cut: shot table in code, each shot rendered to a segment of an exact whole number of frames, joined, decoded once end to end, and two files written: manifest.json (what was planned) and verification.json (what was measured). The last one, for the director's cut:
"expected_frames": 4520,
"actual_frames": "4520",
"duration": "188.333333",
"status": "Technical decode only; NOT final quality approval"
That fourth line is the habit to copy. A decode pass is not a viewing.
What the conform tool does not do: choose an in-point, overlap sound across a cut, or decide anything. It can hold a still and lay one recorded line on one shot at an offset (Chapters 10 and 11); sound that runs across a cut is the mix, Chapter 14. This chapter's tool joins picture at planned lengths, which is all a setup test needs.
1.3 Case 1-A — the GPU that died on day one
- What I saw: before paying for hosted generation we ran the whole film on a home server with two RTX 3090 cards. On 2026-09-08 one card logged NVIDIA Xid 154 ("GPU Reset Required") three times under load, then stopped enumerating at boot (docs/artifacts/BRAIN-GPU0-FAULT-REPORT-2026-09-08.md). The pass finished on one card: 59 takes, about 41 GPU-hours, 0 of 38 cards passing the strict gate (docs/artifacts/BRAIN-PASS-2026-09-08.md).
- Why I think so: hardware fault; the identical second card under the same load stayed at 42–57 °C and healthy.
- What I changed: production moved to a hosted platform; the only later use of the box was the AI score, which Appendix B gives a hosted fallback for.
- Would this happen on your tool? The fault is ours. The lesson is general: nothing on this book's required path needs a GPU you own. If a step seems to, check Appendix B before buying anything.
1.4 Do it with your tools
| You need | Any of these | Check |
|---|---|---|
| Video toolkit | ffmpeg 6 or later | ffmpeg -version prints a version |
| Speech to text, offline | whisper.cpp, faster-whisper, openai-whisper | a 5 s voice memo comes back as words |
| Scripting | Python 3.9 or later with Pillow and numpy | python3 -c "import PIL, numpy" is silent |
| Version control | git and a private remote | git status in the film folder |
| Agent | any coding agent that runs shell commands and appends to files | it runs ffprobe on a file and quotes the output |
Install lines. macOS with Homebrew:
brew install ffmpeg whisper-cpp git python
pip3 install --user Pillow numpy
Ubuntu or Debian:
sudo apt install ffmpeg git python3 python3-pip && pip3 install --user Pillow numpy faster-whisper
Windows: install ffmpeg and git from their sites, Python from python.org, then pip install Pillow numpy faster-whisper in a terminal.
Whisper needs a model file, downloaded once. media.sh transcribe calls whisper-cli (whisper.cpp) and expects ~/.cache/whisper/ggml-large-v3-turbo.bin (1.62 GB, from the whisper.cpp model repository) or the path in WHISPER_MODEL; on this laptop it transcribed a 10 s clip in 1.8 s. If you installed faster-whisper instead, media.sh transcribe will stop with "missing dependency: whisper-cli"; transcribe directly with faster-whisper --language zh --model large-v3-turbo <file> (or whisper <file> --language zh for openai-whisper), which downloads the model on first use, and paste the text into the ledger the same way. If a transcript comes back empty: check the clip has an audio stream (ffprobe lists it), then that you passed the right language code, then try a smaller model. An empty transcript is a fail, never a pass.
If you cut in an editor instead of a script, the rules do not change: the shot table is a file, each export is a new file in its own folder, and the frame count of the export is checked against the table.
1.5 Your turn
Time cap: two hours. Spend: none.
- Install the five tools and run each check. Paste the five outputs into
setup-check.txt. -
Create the film folder and put it under version control:
my-film/ AGREEMENT.md ← Chapter 0 ledger.csv ← Chapter 0 fences/ story/ ← Chapters 3–5 assets/ ← Chapter 9 (ignored by git) shots/ ← generated takes (ignored by git) audio/ ← Chapter 7 cuts/ ← one folder per cut, never reused tools/build_cut.py ← copy of docs/curriculum/templates/build_cut.py (the conform tool) tools/media.sh ← copy of docs/curriculum/templates/media.sh (probe, frames, sheet, strips, loudness, transcribe) tools/stress_pack.py← copy of docs/curriculum/templates/stress_pack.py (Chapter 9).gitignore:*.mp4,*.mov,*.wav,assets/,shots/. Git is not your media backup; the platform project and your disk are. -
Make two test clips without generating anything. Film ten seconds of anything on your phone, twice, or let ffmpeg draw them:
ffmpeg -f lavfi -i "testsrc2=size=1280x720:rate=24" -f lavfi -i "sine=frequency=440:sample_rate=48000" -t 6 -c:v libx264 -pix_fmt yuv420p -c:a aac cuts/clips/A.mp4ffmpeg -f lavfi -i "smptebars=size=1280x720:rate=24" -t 6 -c:v libx264 -pix_fmt yuv420p cuts/clips/B.mp4B has no sound on purpose; generated clips often arrive silent and the conform must cope.
-
Write the shot table
cuts/shots.csv:name,source,start,duration A-tone,clips/A.mp4,0,4 B-silent,clips/B.mp4,1,3.5 A-again,clips/A.mp4,3,2.5 -
Have the agent run the conform and report in the Chapter 0 format:
python3 tools/build_cut.py cuts/shots.csv cut01Our run of this table printed
OK …/cut01/cut01.mp4 240 frames 10.000 s;verification.jsonread expected 240, actual 240. -
Run it again, unchanged. It must refuse:
cut01.mp4 exists. A cut is never overwritten; pick a new cut name.If your build rewrites the file, fix that before anything else in this book. -
Performance task: the seeded mismatch. Below is a
verification.jsonfrom an imaginarycut02. Write three lines: what is wrong, what most likely caused it, what you do next. Answer at the end of the chapter.{"full_decode": "exit0", "expected_frames": 240, "actual_frames": 239, "duration": "9.958333", "status": "Technical decode only. Not a quality approval."} -
Ledger three rows (kind
read): the frame count and duration fromverification.json; the refusal on the second run; your three-line answer to step 7. Commit.
1.6 Gate
Each line needs valid evidence per DESIGN §5; outcomes are pass / fail / unverified, and unverified blocks.
- Five tool checks pass (evidence:
setup-check.txt, outputs pasted, not retyped). - The film folder is under version control with media ignored (evidence:
git statusshows no.mp4tracked). cut01exists withmanifest.jsonandverification.json; expected frames equal actual frames (evidence: the two files).- The second run refused to overwrite (evidence: the quoted refusal in the ledger).
- Performance task: your three lines on the seeded mismatch match the answer on cause and next step (evidence: the ledger row).
- The agent's report on the conform used the three-line format and contained only measurements (evidence: the report; the judgment "only measurements" is yours, by name).
- You played
cut01.mp4start to end, sound on (evidence: self-attested in the ledger; a decode is not a viewing).
Pass example from HALFWAY: CUT33 verification.json above, 4520 of 4520, status refusing to be read as approval. Fail example: the seeded cut02 file in step 7; no real HALFWAY cut failed its frame assertion, because the assertion ran on every one.
What this gate does not show: that your generation tool holds a face, that a line can be synced, that a score can be made without a GPU. DESIGN §7 describes a test of that whole path on a clean laptop; the Director decided on 2026-09-22 not to run it, so Chapters 9–15 are verified on one tool, and you are the first run on yours.
Answer for step 7
One frame short of the plan and the duration says the same thing (239 ÷ 24 = 9.958 s). The decode passed, so the file is whole; the join lost or a segment under-rendered one frame, most often a source shorter than start + duration so the last shot came up one frame short. Next: read each segment's frame count against the manifest to find the short one; do not touch cut02; fix the table and build cut03. The ledger row records the mismatch, the segment found, and the new cut name.