Stitch cleanup and grading!

README.md

@@ -126,6 +126,53 @@ gnommo -p myproject pre
 
 **When to use:** After recording narration that needs background removal, sound normalization or other processing.
 
+#### Green screen keying (`gnommokey`)
+
+The `talkinghead` preset in `project.json` chains a `gnommokey` keyer (a
+Keylight-style color-difference keyer) with a `color_grade` step. Key fields:
+
+| Field | What it does |
+|-------|--------------|
+| `screen_color` | RGB of your green screen (sampled from the footage). |
+| `screen_gain` | Key extraction strength. Higher = more aggressive matte. |
+| `screen_balance` | Mixes luminance into the key (helps darker/lighter greens). |
+| `clip_black` / `clip_white` | Compress the matte range (crush transparent / opaque). |
+| `despill_bias` | RGB the keyed *edges* shift toward. A light neutral/skin tone reads better than cool blue. |
+| `despill_strength` | How hard the edge/dominant-green despill pulls toward `despill_bias`. |
+| `spill_suppress` | **Interior green-limiter — see below.** |
+| `edge_erode` | Shrinks the alpha edge by N passes to kill green fringe (0–5). |
+
+**`spill_suppress` — the bald-head knob.** The regular despill only acts where
+green is the *dominant* channel (`g > max(r,b)`). On skin — especially a bald
+head catching green bounce — red stays dominant, so that despill never touches
+the interior and a green cast survives. `spill_suppress` caps green across the
+**whole frame** at a reference extrapolated through the other two channels:
+
+```
+0.0  → cap at max(r, b)   (only strong spill; effectively off)
+1.0  → cap at avg(r, b)   (removes visible cast)
+2.0  → cap at min(r, b)   (green can never exceed the smallest channel — nuclear)
+```
+
+Green is only ever *reduced*, never boosted, so clean pixels are untouched.
+Start around `0.6`; go past `1.0` for heavy close-up spill. If skin tips
+magenta/pink, ease back down. Range is `0.0`–`2.0`.
+
+#### Grade preview (`grade`)
+
+Iterate on keying/grading without running a full preprocess. It seeks a few
+seconds into a raw clip, runs it through the `talkinghead` filter chain, and
+writes `grade_preview.mov` (ProRes 4444 with alpha) to the project root.
+
+```bash
+gnommo -p myproject grade                      # first raw_mov clip, 3s from 5s in
+gnommo -p myproject grade --ss 12 --dur 4      # seek 12s in, make a 4s preview
+gnommo -p myproject grade --file media/narration/raw_mov/clipA.mov
+```
+
+Tweak the `gnommokey` / `color_grade` values in `project.json`, re-run `grade`,
+re-open the `.mov`, repeat until it looks right.
+
 ---
 
 ### Stage 4: stitch
@@ -267,6 +314,7 @@ gnommo -p myproject render
 
 ```bash
 gnommo -p myproject validate      # Check for errors without rendering
+gnommo -p myproject grade         # Preview the keyer/grade on a few seconds of raw footage
 gnommo -p myproject description   # Generate YouTube description with chapters
 gnommo -p myproject transcribe --final  # Transcribe final.mp4 for subtitles
 ```