color-corrector

Files (15)

• SKILL.md
• looks.toml
• camera_match_plan.py · scripts/
• color_apply_plan.py · scripts/
• color_benchmark.py · scripts/
• color_review_package.py · scripts/
• generate_shaper_luts.py · scripts/
• look_region_plan.py · scripts/
• look_region_review_package.py · scripts/
• rendered_contact_sheet.py · scripts/
• arri_logc3_to_rec709_g24.csp · shapers/
• arri_logc4_to_rec709_g24.csp · shapers/
• bmd_film_gen5_to_rec709_g24.csp · shapers/
• slog3_sgamut3_to_rec709_g24.csp · shapers/
• vlog_vgamut_to_rec709_g24.csp · shapers/

SKILL.md (first lines)

# Color corrector

Use this when the user asks to fix exposure, contrast, saturation,
white balance, camera matching, or LUT/look application. This is a
graph-native finishing pass: color intent must land as `Set Color
Correction` or `Apply LUT` EDL ops, never as a detached FFmpeg command
that bypasses the edit graph.

## Workflow

### 1. Inspect color signals

Start from the edit graph and the color index:

```
view_timeline
read_index(channel="color", asset_id=<asset>)
```

Start from `summary.policy` and, when present, `scenes[].policy`. The
policy is the routing layer:

- `recommended_action: no_op` means leave the graph untouched.
- `recommended_action: auto_correct` means a graph-native correction can
  be proposed from `recommended_correction`, then rendered and verified.
- `recommended_action: review_only` means inspect frames/contact sheets
  before applying anything.

Use `policy.edit_types` to decide the pass: `lighting_correction`,
`white_balance`, or `contrast_correction`. Then use
`summary.recommended_correction` and, when present,
`scenes[].recommended_correction` as the parameter source. Check
`issue_tags`, `confidence`, and `auto_correct_safe` before applying
anything. If the index marks a clip or scene as `unsafe_to_auto_correct`,
show the issue and inspect frames instead of blindly applying the value.

For multi-camera podcasts/interviews, compare each camera's brightness
percentiles, contrast range, RGB means, estimated color cast, clipping
fractions, and scene-level recommendations. Camera matching in v1 is
recommendation-driven: compute the per-camera deltas and emit normal
`Set Color Correction` ops on each clip.

Use the policy-to-EDL helper when a color index should be converted into
an edit proposal:

```bash
python3 <skill-root>/scripts/color_apply_plan.py \
  --color-index /path/to/color-index.json \
  --clip-uuid <clip_uuid>
```

Use the camera matching helper when multiple cameras need to be brought
into the same baseline:

```bash
python3 <skill-root>/scripts/camera_match_plan.py \
  --color-index cam-a.json \
  --color-index cam-b.json \
  --camera-label A \
  --camera-label B
```

For offline benchmark runs or dataset checks, use the bundled helper:

```bash
python3 <skill-root>/scripts/color_benchmark.py \
  --color-index /path/to/color-index.json \
  --dataset-dir /optional/external/dataset/cache
```

Datasets are only benchmark inputs. Do not make them runtime
dependencies and do not treat the benchmark as an alternate editor.

### 1.5. Plan look regions and generated LUTs

When the user asks for an end-to-end look pass, per-timeframe LUTs, or
agent-generated looks, produce a look-region plan before applying edits.
Prefer the first-class execution tool when the user wants the pass run:

```json
start_look_region_pass({"style":"cinematic"})
```

This tool runs the plan -> `apply_edl` -> `start_render(scope="timeline")`
sequence and returns the render `job_id`, render path, plan paths, and
the exact `review_look_regions` call to use after `poll_render` reports
`state: done`.

Use the planning-only tool when drafting or when the user wants to review
the EDL before applying it:

```json
plan_look_regions({"style":"cinematic"})
```

Both tools auto-discover color-analysis sidecars under
`index/color-analysis/`, writes `renders/look-plan.edl`,
`renders/look-plan.json`, `renders/look-plan.md`, and generated `.cube`
files under `luts/generated/`.

When running the helper directly for debugging, use:

```bash
python3 <skill-root>/scripts/look_region_plan.py \
  --project /path/to/project \
  --color-index /path/to/index/color-analysis/raw/source.mp4.json \
  --style cinematic \
  --output-edl /path/to/project/renders/look-plan.edl \
  --output-json /path/to/project/renders/look-plan.json \
  --report-md /path/to/project/renders/look-plan.md
```

Use multiple `--color-index` arguments, or the tool's `color_indexes`
array, when the timeline uses multiple assets and auto-discovery is not
enough. The planner reads `project.otio.json`, intersects timeline clips
with color-analysis scenes, records look-region consistency groups,
writes generated `.cube` files under `luts/generated/`, and emits
graph-native EDL using `Split Clip`, `Set Color Correction`, and
`Apply LUT`. The emitted EDL is still a proposal: apply it through

From explicit09/montage, Apache-2.0.

More from explicit09/montage