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:

  1. Where the film lives. One folder under version control. Everything the agent writes goes in; generated video does not.
  2. What is on the required path. Five tools. No GPU, no paid editor.
  3. 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

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.

  1. Install the five tools and run each check. Paste the five outputs into setup-check.txt.
  2. 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.

  3. 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.mp4
    
    ffmpeg -f lavfi -i "smptebars=size=1280x720:rate=24" -t 6 -c:v libx264 -pix_fmt yuv420p cuts/clips/B.mp4
    

    B has no sound on purpose; generated clips often arrive silent and the conform must cope.

  4. 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
    
  5. Have the agent run the conform and report in the Chapter 0 format:

    python3 tools/build_cut.py cuts/shots.csv cut01
    

    Our run of this table printed OK …/cut01/cut01.mp4 240 frames 10.000 s; verification.json read expected 240, actual 240.

  6. 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.

  7. Performance task: the seeded mismatch. Below is a verification.json from an imaginary cut02. 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."}
    
  8. Ledger three rows (kind read): the frame count and duration from verification.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.

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.