video-color-grade

Video Color Grade (assess → correct → looks → choose → LUT + apply)

Write the grade from scratch as code, generate several distinct named looks on the real footage, select one through explicit human choice or delegated agent judgment, then bake a portable .cube LUT and apply it to the full clip. No preset packs.

Core idea — correct, then style. Every look is corrective base + creative layer:

• corrective base makes the footage honest — for flat LOG/HLG it's the log→Rec.709 conversion; for already-Rec.709 footage it's WB neutralize + exposure + mild contrast. Every look shares this base, so "neutral" stays meaningful and looks differ by intent.
• creative layer is the look stacked on top (warm / cool / teal-orange / punchy / faded…).

Skin is the quality bar. On people — especially darker skin — teal_orange and cool_desat routinely throw a green/grey cast. Judge every look on faces first; keep midtone warmth, push the tint into shadows/highlights/background, prefer vibrance over raw saturation. Don't push the white balance all the way to neutral or skin goes lifeless.

Requirements: ffmpeg/ffprobe on PATH, Python with numpy + Pillow.

Contract

• Every look = base + creative layer; the base is shared by all looks.
• All looks render on the same representative frame (a fair, controlled comparison), labeled, at full resolution.
• The full apply uses -c:a copy (audio never re-encoded → A/V sync identical) and keeps source duration, fps, dimensions.
• Complete look selection before delivery. Use human mode when the user asked to choose; use agent mode without pausing when the user delegated the choice or requested an autonomous run. In both modes, preserve the rationale in the durable plan.

Project protocol workflow

Store the durable decision in work/color-grade/grade-plan.json:

{
  "schema_version": 1,
  "target": "base-video",
  "base": "eq=contrast=1.05",
  "looks": [{"name": "clean", "chain": "null"}],
  "selected_look": "clean",
  "selection_mode": "agent",
  "selection_rationale": "Neutral correction preserves natural skin and source lighting.",
  "selected_lut": "../../final/selected-color-look.cube",
  "evidence_refs": ["media:source"]
}