---
name: color-grade
description: Colour grade videos and images with a .cube 3D LUT or ten built-in looks (teal-orange, warm-film, cool-night, bleach-bypass, vintage-fade, mono, punchy, golden-hour, matte-pastel, noir) plus exposure, contrast, saturation, warmth and tint, at any intensity. Renders a looks sheet to choose from, before / after split frames, and exports the grade as a .cube for Premiere, Resolve or CapCut. Use when the user wants a cinematic look, a consistent grade across Kenerate clips from different models, a LUT applied, or footage warmed / cooled / matched.
compatibility: Python 3.9+ with Pillow and ffmpeg (lut3d filter). The Kenerate MCP server only for making the footage.
metadata:
  author: kenerate
  version: "1.1"
  kenerate-tools: "generate_video generate_image restyle_video apply_filter wait_for_generation"
---

# Colour grade (LUTs and looks)

`scripts/grade.py` bakes the whole grade (look or LUT at an intensity + adjustments) into one 33-point `.cube`, then
applies it with ffmpeg `lut3d` (video) or Pillow (stills), so both match exactly. Free, local. Rules:
[references/KENERATE.md](references/KENERATE.md) (models and voices: [references/MODELS.md](references/MODELS.md), or the free `pick_model` / `pick_voice` tools).

## When to use / not to use
- Use: "make it cinematic", "teal and orange", "match these clips", "apply my LUT", "warmer", "black and white".
- Not for: changing the style of the content (anime, clay, painting): that is `restyle_video` / `apply_filter` on Kenerate.

## 1. Let the user pick (free preview)
```
python <skill-dir>/scripts/grade.py --input "<clip or image url>" --looks-sheet [--intensity 0.8]
```
Show `looks_sheet.jpg` (the original plus all ten looks on one frame) and ask which look and how strong.
A brand LUT: `--lut brand.cube` (3D .cube only).

## 2. Grade
```
python <skill-dir>/scripts/grade.py --input "<clip1>" "<clip2>" "<still>" \
  --look teal-orange --intensity 0.7 --contrast 1.05 --warmth 8 \
  --export-cube kenerate-out/color-grade/brand_look.cube
```
- Several clips from different models: grade them all with the same settings so the edit feels like one shoot; fix
  one odd clip with `--exposure` / `--warmth` on its own run.
- Each input gets `<name>_graded.*` and a `_compare.jpg` (left before, right after); `grade_preview.jpg` collects them. Show it.
- Audio is copied untouched. Grade before `video-editing` (cleaner) or after (one pass on the final) - both work.

## Progress and output
Steps: build the .cube → fetch → grade (percent per video) → preview. `RESULT_JSON.outputs[]` lists each file and its
compare image; `cube` is the exported LUT.

## If something fails
"Not a valid 3D .cube LUT" → the file is a 1D LUT or broken; ask for the 3D version. ffmpeg errors → re-run with a
local copy of the clip and check it plays.

## Limits
8-bit, display-referred (Rec.709 in, Rec.709 out). Log-to-Rec.709 conversion LUTs work only on log footage.