grade-consistency-pass

Purpose

AI-generated scenes drift in color/contrast/saturation across cuts. This atom samples a reference clip, computes mean Y/U/V stats on every other clip, and applies an ffmpeg eq (+ optional curves) filter to each to bring its mean closer to the reference. The result is a graded set of clips with significantly reduced inter-clip variance.

Mirrors the manual color-grade logic in coca-cola/ad-runs/video-01-museum-painting/scripts/polish_v9.py but generalized and per-clip.

Inputs

• --clips-dir <path> — directory containing scene-*.mp4 (required)
• --output-dir <path> — destination (default: <clips-dir>/graded/)
• --reference <name|path> — clip used as the grade reference. Default: lexicographically first clip in <clips-dir>. Can be a scene filename (scene-03.mp4) or an absolute path.
• --match <y,u,v> — comma-separated channels to match (default y,u,v). Drop u,v to keep original tint per clip.
• --max-delta <0–1> — clamp the contrast/saturation/gamma adjustments so a single bad reference can't blow out everything (default 0.30)
• --archive <path> — if set, copy original clips here before overwriting (default: <clips-dir>/_archive/pre-grade-<ts>/)

Workflow