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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
color.py: typed primary colour correction (--correct) (#23)
Shogo Kajiyamab51dc5e8c846
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdindex 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.mdindex 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.jsonindex 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.pyindex 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.pyindex 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 copypython3 color.py iphone_dv.mov --strip-dovi # drop Dolby Vision RPU, keep HLG base layerpython3 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 argparseimport osimport sysfrom 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_argsTONEMAPS = ["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 = Noneif 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 0diff --git a/tests/test_all.py b/tests/test_all.pyindex 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)