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.

fix(color): --correct no longer desaturates bt709-tagged sources (#167)

Shogo Kajiyama55490aa0d3b3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0ddabea..6cdc3f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
## Unreleased
-(nothing yet)
+- `color.py --correct` no longer desaturates bt709-tagged sources: the RGB stages are wrapped in explicit, matching YUV<->RGB conversions instead of libavfilter's auto-inserted pair, which used bt709 one way and bt601 the other (#159).
## 1.4.1
diff --git a/scripts/color.py b/scripts/color.py
index 71d6b54..8d6b0b6 100755
--- a/scripts/color.py
+++ b/scripts/color.py
@@ -112,26 +112,46 @@ def correction_chain(args: argparse.Namespace) -> str:
die(f"--levels-out-black {out_black} must be less than --levels-out-white {out_white}")
gm, rm, bm = -tint, tint / 2.0, tint / 2.0
- terms = [
+ rgb = [
f"exposure=exposure={exposure:g}",
f"colortemperature=temperature={temperature:g}",
f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}",
- f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}",
]
+ terms = [_rgb_stage(rgb), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
+ rgb2 = []
if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
rimin, rimax = in_black / 255.0, in_white / 255.0
romin, romax = out_black / 255.0, out_white / 255.0
- terms.append(
+ rgb2.append(
f"colorlevels=rimin={rimin:g}:gimin={rimin:g}:bimin={rimin:g}:"
f"rimax={rimax:g}:gimax={rimax:g}:bimax={rimax:g}:"
f"romin={romin:g}:gomin={romin:g}:bomin={romin:g}:"
f"romax={romax:g}:gomax={romax:g}:bomax={romax:g}"
)
if args.curves:
- terms.append(f"curves=preset={args.curves}")
+ rgb2.append(f"curves=preset={args.curves}")
+ if rgb2:
+ terms.append(_rgb_stage(rgb2))
return ",".join(terms)
+def _rgb_stage(filters: list) -> str:
+ """Wrap a run of RGB-only filters in explicit, matching YUV<->RGB conversions.
+
+ exposure/colortemperature/colorbalance/colorlevels/curves take RGB, so libavfilter inserts a
+ swscale conversion on each side. Left to itself, the way in honours the frame's colour tag
+ (bt709 on any camera or export.py file) while the way back uses swscale's default matrix
+ (bt601): on a bt709-tagged source an all-defaults --correct came out 26 dB PSNR from its
+ input and ~8 % less saturated (#159). Untagged sources never showed it because both legs
+ then fall back to bt601 and cancel. Pinning both legs to the same matrix restores the
+ identity on every source (39 dB, the same as an untagged one always got); bt601 on both
+ sides measured better than bt709 on both (34 dB) because swscale's 601 path round-trips
+ 8-bit 4:2:0 more exactly. The matrix here is only the working space of the conversion pair,
+ never a tag: the output carries the encoder's BT.709 tags as before."""
+ return ("scale=in_color_matrix=bt601,format=gbrpf32le," + ",".join(filters)
+ + ",scale=out_color_matrix=bt601,format=yuv420p")
+
+
def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
v = meta["video"]
trc = v.get("color_transfer") or "smpte2084"
diff --git a/tests/test_all.py b/tests/test_all.py
index eea12bb..21cd0b6 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -1426,6 +1426,31 @@ class FFmpegSkillTests(unittest.TestCase):
script("color.py", self.src, "--lut", lut, "--lut-strength", "2.5", "-o", OUT / "lut_oob.mp4", expect_fail=True)
script("color.py", self.src, "--lut", lut, "--lut-strength", "-1", "-o", OUT / "lut_oob2.mp4", expect_fail=True)
+ def test_color_correct_identity_holds_on_a_bt709_tagged_source(self):
+ """#159: the identity test below only ever ran on the untagged synthetic source. On a
+ source *tagged* bt709 (any camera file, anything export.py wrote) an all-defaults
+ --correct came back 26 dB PSNR and ~8 % less saturated, because libavfilter's auto-
+ inserted swscale legs around the RGB filters disagreed: yuv->rgb honoured the frame's
+ bt709 tag, rgb->yuv used the default bt601. Both legs are now pinned to one matrix, so
+ the result is the same on a tagged and an untagged copy of the same pixels, on FFmpeg
+ 5.1 through 8.1 (measured 39.5 dB on all four)."""
+ tagged = OUT / "correct_src709.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.src), "-t", "3",
+ "-vf", "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv",
+ "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-an", str(tagged))
+ self.assertEqual(probe(str(tagged))["video"]["color_space"], "bt709")
+ untagged = OUT / "correct_srcU.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.src), "-t", "3", "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-an", str(untagged))
+ results = {}
+ for name, src in (("tagged", tagged), ("untagged", untagged)):
+ out = OUT / f"correct_identity_{name}.mp4"
+ data = json.loads(script("color.py", src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)
+ m = data["measurements"]
+ self.assertAlmostEqual(m["input"]["saturation_avg"], m["output"]["saturation_avg"], delta=2.5, msg=name)
+ results[name] = self._psnr(src, out)
+ self.assertGreater(results[name], 36, f"{name}: an all-defaults --correct must be near-identity, got {results[name]:.1f} dB")
+ self.assertAlmostEqual(results["tagged"], results["untagged"], delta=1.0, msg="the colour tag must not change what --correct does to the pixels")
+
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)