---
name: "color_grading"
description: "Color grade video: correction-first workflow (normalize exposure/WB, then creative LUT, then secondaries), LUT selection and trimming, skin-tone protection via the vectorscope skin-tone line, shot matching to a hero still, and rescuing badly lit footage. Use when a video looks off, flat, inconsistent between shots, or needs a cinematic look — works in DaVinci Resolve, Premiere, or scripted via the bundled FFmpeg CLI."
metadata: { "includeInPrompt": true }
---

# Color Grading

## Purpose
Take footage from raw/flat/inconsistent to finished: correct first, grade second, match third. Ships a bundled `bin/grade-cli.py` that runs the same pipeline headlessly over FFmpeg for batch and agent use.

## Workflow
1. **Organize.** Lock the edit. Group shots by scene, lighting setup, and camera. Pick a **hero shot** per scene — everything else matches to it.
2. **Normalize (correction, not grade).** Per hero shot, with waveform + parade scopes up:
   - Fix exposure: lift shadows toward ~0.1 IRE with **gamma** (gamma < 1.0 lifts mids without fogging blacks; brightness shifts the whole floor — don't use it for shadow rescue).
   - Set white balance from a known-neutral patch (gray card, white wall). No neutral reference? Neutralize on the vectorscope until the gray blob centers.
   - Trim so blacks touch 0% and highlights stay under 100% without clipping.
3. **Creative LUT.** Apply a look LUT *after* normalization, at reduced intensity (Resolve: Key Output Gain; Premiere: Lumetri intensity slider; FFmpeg: chain order correction → `lut3d`). Technical (log→Rec.709) conversion LUTs belong in step 2's territory — they normalize, they don't look. After any creative LUT, re-trim saturation and mids contrast — LUTs are a starting point, never the finished grade. See `references/lut-guide.md`.
4. **Skin tones.** Skin on the vectorscope must sit on the **skin-tone line (~123°, the ~10:30 diagonal)** — same hue for all ethnicities; differences show on the waveform (light skin 50–70 IRE, dark skin 15–35 IRE). Isolate with an HSL/3D qualifier, protect with a dedicated node *before* the creative LUT so the grade can't push skin green or magenta. Full method: `references/skin-tones.md`.
5. **Shot match.** Match every shot to its hero: exposure/contrast first (waveform), then WB, then color bias, then saturation — matching hue before exposure fools the eye. Use gallery stills + split-screen compare. Level within-camera drift before cross-camera work.
6. **Rescue.** For bad lighting, run the playbooks in `references/rescue.md` (underexposure, clipped highlights, mixed lighting, WB casts).
7. **QC.** Review on a calibrated display; scopes must show no hard clipping, skin on the line, saturation inside the broadcast-safe targets.

Headless/batch: use `bin/grade-cli.py` (recipes in `assets/`).

## Output Contract
- A **finished clip**: normalized exposure/WB, coherent creative look, skin on the skin-tone line, no clipping.
- A **matched sequence**: every shot within tolerance of its hero still.
- From `grade-cli.py`: the output file at the requested path, plus the printed filter chain (reproducible recipe).

## Operating Rules
1. **Correction before grade, always.** Never apply a creative LUT to uncorrected footage and call it done.
2. One purpose per adjustment node/layer; name it.
3. Never clip channels on the parade to get contrast — crush the curve, not the channels.
4. Don't crush shadow detail to "fix" noise; denoise the lift, keep the detail.
5. No confident color claims without a scope check: "looks right" is opinion, scope-verified is fact.
6. Any recipe/LUT used must be named in the output so the grade is reproducible.