Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

color.py: typed primary colour correction (--correct) (#23)

Shogo Kajiyamab51dc5e8c846
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef5e877..24aa652 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,27 @@
# Changelog
+## 0.9.2 — typed primary colour correction
+
+- **color.py**: `--correct` (exposure / contrast / saturation / white balance), a fourth colour mode
+ alongside `--to-sdr` / `--lut` / `--retag` / `--strip-dovi`. Each flag is one option of one real,
+ always-available libavfilter filter — `--exposure` (`exposure` filter, -3..3 stops), `--contrast` /
+ `--saturation` (`eq` filter, 0..2, 1=unchanged), `--temperature` (`colortemperature`, 2000..12000 K,
+ 6500=unchanged) and `--tint` (green -1 .. +1 magenta, mapped to `colorbalance`'s three midtone
+ channels: `gm=-tint`, `rm=bm=tint/2`) — range-checked against this script's own safe subset of what
+ each filter documents (`ffmpeg -h filter=<name>`) before ffmpeg runs; no filter string, `filter_complex`
+ or raw argv is ever accepted from the caller. The four stages (exposure → white balance → contrast →
+ saturation) are always chained in that fixed order, each one always present at its filter's own
+ documented no-op default, so the pipeline is one stable four-filter chain regardless of which flags
+ were given. `--json`'s `measurements` field carries `analyze_levels()` (signalstats luma/saturation)
+ for the input and the output side by side — an OBSERVED technical measurement, never a "looks better"
+ judgement.
+- Contract: `color`'s optional capabilities gain `filter:exposure` / `filter:eq` / `filter:colorbalance` /
+ `filter:colortemperature` (declared `when: "--correct"`); `X264` now also lists `--correct` among its
+ callers. No change to any existing flag, contract field, MCP schema or tool semantics.
+- Tests: 4 real-media tests in `tests/test_all.py` (defaults are near-identity, positive exposure raises
+ measured luma, `--saturation 0` desaturates, temperature/tint run and preserve geometry, five
+ out-of-range parameters are each refused with no partial output).
+
## 0.9.1 — FFmpeg 8 capability detection; audio extraction, audio join, sample-accurate trims, typed dynamics
- **doctor / contract on FFmpeg 8.** `ffmpeg -filters` prints two flag characters on FFmpeg 8 (`T. acompressor A->A`) where 6 and 7 print three (`..C`); 0.9.0 anchored on three and reported every `filter:*` capability missing on FFmpeg 8 (macOS / Windows CI of consumers). Rows are now recognised by their `A->A` io-spec token, encoders by the `------` separator, so the flag width no longer matters. A listing that cannot be read yields a third state, `unknown`, distinct from `missing` (an installed filter is never reported absent) and from `available` (a failed detection is never a pass); `detection` and `errors` say which listing failed and why; exit 2 for "required but unknown". Existing keys unchanged. Fixtures for the 6.1 capture and the 7 / 8 layouts in `tests/fixtures/`, tests through a fake ffmpeg.
diff --git a/README.md b/README.md
index 119d4fe..0e8a119 100644
--- a/README.md
+++ b/README.md
@@ -154,7 +154,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; animated and word-by-word karaoke timed to the speech energy; optional local transcription |
| `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades |
| `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs drawn by FFmpeg from a brand kit |
-| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting |
+| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/white balance) |
**Delivery**
diff --git a/SKILL.md b/SKILL.md
index 448e270..b346cd3 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -103,6 +103,7 @@ Do not ask for things `probe.py` can tell you.
| "the colours look washed out / it's an iPhone HDR video" | `color.py input.mov --to-sdr` (probe shows `hdr: true`) |
| "apply this LUT", "convert the S-Log / V-Log footage" | `color.py input.mp4 --lut grade.cube [--lut-strength 0.7]` |
| "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (no re-encode) |
+| "brighten it a touch / punch up the contrast and saturation / fix the white balance" | `color.py input.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05` (typed, no filter string) |
| "clean up the audio", "remove the hiss / room noise" | `audio.py input.mp4 --voice` (speech) or `--denoise` |
| "add background music under the talking" | `audio.py input.mp4 --music bed.mp3 --duck --fade-out 3` |
| "convert the 5.1 to stereo" | `audio.py input.mov --downmix` |
diff --git a/package.json b/package.json
index d940bf8..b727b4e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.9.1",
+ "version": "0.9.2",
"description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 21 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
"keywords": [
"ffmpeg",
diff --git a/scripts/_contract.py b/scripts/_contract.py
index e7f0b33..c5b6f23 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -98,8 +98,10 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
required=FF + [X264, AAC, "filter:xfade", "filter:acrossfade"], optional=[HDR_X265] + AUDIO_OUT,
video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
"color": dict(role="execution", inputs=["video asset", ".cube LUT (--lut)"], outputs=["video artifact with converted colour"],
- required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
- {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"}],
+ required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut / --correct"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
+ {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"},
+ {"capability": "filter:exposure", "when": "--correct"}, {"capability": "filter:eq", "when": "--correct"},
+ {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"}],
video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
"export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "any preset except gif"},
diff --git a/scripts/color.py b/scripts/color.py
index 5e8de19..92b16af 100755
--- a/scripts/color.py
+++ b/scripts/color.py
@@ -1,7 +1,8 @@
#!/usr/bin/env python3
"""Colour management: convert HDR (HDR10/PQ, HLG, BT.2020) to SDR BT.709 with
-real tone mapping, apply a .cube LUT (Log footage, creative grades), or fix
-wrong colour tags without re-encoding.
+real tone mapping, apply a .cube LUT (Log footage, creative grades), fix wrong
+colour tags without re-encoding, or apply typed primary colour correction
+(exposure, contrast, saturation, white balance).
Examples:
python3 color.py iphone_hdr.mov --to-sdr # PQ/HLG -> BT.709 SDR, hable tonemap
@@ -11,16 +12,61 @@ Examples:
python3 color.py wrongly_tagged.mp4 --retag bt709 # metadata only, stream copy
python3 color.py iphone_dv.mov --strip-dovi # drop Dolby Vision RPU, keep HLG base layer
python3 color.py iphone_dv.mov --to-sdr # DV 8.4 = HLG base layer -> tone-mapped SDR
+ python3 color.py flat.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05
"""
import argparse
import os
import sys
from typing import List
-from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
+# Typed primary correction: each flag is one option of one real, always-available libavfilter filter
+# (never a caller-supplied filter string). Range is this script's own safe subset of what the filter
+# documents (`ffmpeg -h filter=<name>`), not the filter's full technical range. default is each filter's
+# own documented no-op value, so every stage below is always emitted and the chain never depends on
+# which flags were actually given.
+CORRECTION = {
+ # flag default lo hi unit
+ "exposure": (0.0, -3.0, 3.0, "stops"), # exposure filter's own full range (linear-domain stops)
+ "contrast": (1.0, 0.0, 2.0, "x"), # eq filter; 0=flat grey, 1=unchanged, 2=double contrast
+ "saturation": (1.0, 0.0, 2.0, "x"), # eq filter; 0=grayscale, 1=unchanged, 2=double saturation
+ "temperature": (6500.0, 2000.0, 12000.0, "K"), # colortemperature filter; 6500=unchanged (its own default)
+ "tint": (0.0, -1.0, 1.0, "x"), # mapped to colorbalance midtones, see correction_chain()
+}
+
+
+def _checked(args: argparse.Namespace, flag: str) -> float:
+ _, lo, hi, unit = CORRECTION[flag]
+ value = getattr(args, flag)
+ if not (lo <= value <= hi):
+ die(f"--{flag} {value:g} is outside {lo:g}..{hi:g} {unit} (the safe range this tool guarantees)")
+ return value
+
+
+def correction_chain(args: argparse.Namespace) -> str:
+ """Four always-present filter stages, in a fixed order chosen so each stage sees a picture already
+ corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint, so
+ contrast/saturation act on colour-balanced footage) -> contrast -> saturation (the most creative-
+ adjacent stage, applied last). `tint` (-1 green .. +1 magenta) is not a single ffmpeg option: it is
+ expressed as colorbalance's three midtone channels (gm=-tint, rm=bm=tint/2) so a positive tint shifts
+ midtones toward magenta and a negative one toward green without changing overall midtone lightness,
+ the same balanced-axis convention colour tools use for a one-dial tint control."""
+ exposure = _checked(args, "exposure")
+ contrast = _checked(args, "contrast")
+ saturation = _checked(args, "saturation")
+ temperature = _checked(args, "temperature")
+ tint = _checked(args, "tint")
+ gm, rm, bm = -tint, tint / 2.0, tint / 2.0
+ return ",".join([
+ f"exposure=exposure={exposure:g}",
+ f"colortemperature=temperature={temperature:g}",
+ f"colorbalance=rm={rm:g}:gm={gm:g}:bm={bm:g}",
+ f"eq=contrast={contrast:g}:saturation={saturation:g}",
+ ])
+
def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
v = meta["video"]
@@ -48,11 +94,17 @@ def main() -> int:
mode.add_argument("--lut", help=".cube LUT to apply (3D)")
mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
+ mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint")
ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
+ ap.add_argument("--exposure", type=float, default=CORRECTION["exposure"][0], help="--correct: exposure in stops, -3..3 (default 0)")
+ ap.add_argument("--contrast", type=float, default=CORRECTION["contrast"][0], help="--correct: contrast, 0..2, 1=unchanged (default 1)")
+ ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
+ ap.add_argument("--temperature", type=float, default=CORRECTION["temperature"][0], help="--correct: white-balance temperature in Kelvin, 2000..12000, 6500=unchanged (default 6500)")
+ ap.add_argument("--tint", type=float, default=CORRECTION["tint"][0], help="--correct: green(-1)/magenta(+1) tint, 0=unchanged (default 0)")
ap.add_argument("--crf", type=int, default=18)
ap.add_argument("--preset", default="medium")
add_common(ap)
@@ -106,12 +158,20 @@ def main() -> int:
emit(output)
return 0
+ measurements = None
if args.to_sdr:
if not v.get("hdr") and not args.force:
die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
output = args.output or default_output(args.input, "sdr")
tag = "sdr"
+ elif args.correct:
+ vf = correction_chain(args)
+ output = args.output or default_output(args.input, "correct")
+ tag = "correct"
+ # OBSERVED technical measurements (signalstats: luma / saturation distribution), never a
+ # "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
+ measurements = {"input": analyze_levels(args.input)}
else:
if not os.path.exists(args.lut):
die(f"LUT not found: {args.lut}")
@@ -130,7 +190,11 @@ def main() -> int:
r = probe(output)
info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
- emit(output)
+ if measurements is not None:
+ measurements["output"] = analyze_levels(output)
+ emit(output, measurements=measurements)
+ else:
+ emit(output)
return 0
diff --git a/tests/test_all.py b/tests/test_all.py
index f6d60a2..f225fc9 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -304,6 +304,42 @@ class FFmpegSkillTests(unittest.TestCase):
script("color.py", self.src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", out)
self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+ def test_color_correct_defaults_are_near_identity(self):
+ out = OUT / "correct_neutral.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)
+ m = data["measurements"]
+ self.assertIn("y_avg", m["input"])
+ self.assertAlmostEqual(m["input"]["y_avg"], m["output"]["y_avg"], delta=2.0)
+ self.assertAlmostEqual(m["input"]["saturation_avg"], m["output"]["saturation_avg"], delta=2.0)
+ v = probe(str(out))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+
+ def test_color_correct_exposure_and_saturation_change_measured_levels(self):
+ brighter = OUT / "correct_bright.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--exposure", "0.6", "--preset", "veryfast", "-o", brighter, "--json").stdout)
+ m = data["measurements"]
+ self.assertGreater(m["output"]["y_avg"], m["input"]["y_avg"], "positive exposure must raise measured luma")
+
+ gray = OUT / "correct_gray.mp4"
+ data2 = json.loads(script("color.py", self.src, "--correct", "--saturation", "0", "--preset", "veryfast", "-o", gray, "--json").stdout)
+ m2 = data2["measurements"]
+ self.assertLess(m2["output"]["saturation_avg"], m2["input"]["saturation_avg"], "saturation 0 must desaturate")
+ self.assertLess(m2["output"]["saturation_avg"], 5.0, "saturation 0 must be close to grayscale")
+
+ def test_color_correct_temperature_and_tint_run_and_preserve_geometry(self):
+ out = OUT / "correct_wb.mp4"
+ script("color.py", self.src, "--correct", "--temperature", "3200", "--tint", "-0.3", "--contrast", "1.1", "--preset", "veryfast", "-o", out)
+ v = probe(str(out))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+
+ def test_color_correct_rejects_out_of_safe_range_parameters(self):
+ for flag, bad in (("--exposure", "5"), ("--contrast", "3"), ("--saturation", "-1"), ("--temperature", "40000"), ("--tint", "2")):
+ out = OUT / "correct_reject.mp4"
+ proc = script("color.py", self.src, "--correct", flag, bad, "-o", out, expect_fail=True)
+ self.assertIn("outside", proc.stderr, f"{flag} {bad} should be refused as out of range")
+ self.assertFalse(out.exists(), f"{flag} {bad}: no partial output on refusal")
+
def test_export_warns_on_hdr(self):
out = OUT / "hdr_youtube.mp4"
proc = script("export.py", self.hdr, "--preset", "x", "-o", out)