color_grading v1.0.0

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.

1. 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.
2. 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.
3. 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.
4. Rescue. For bad lighting, run the playbooks in references/rescue.md (underexposure, clipped highlights, mixed lighting, WB casts).
5. 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.