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
fix(check): read the matrix tag in the colour row (#329)
Shogo Kajiyamae56ba469d4ba
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 918bc75..303e542 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,9 @@## Unreleased-(nothing yet)+### Fixed++- **`check.py`'s colour row reads the matrix tag.** It decided "untagged" from the primaries and transfer alone, so a file whose only colour tag is a BT.601 matrix (`smpte170m`/`bt470bg`, as some renderers write) passed as `untagged (players assume bt709)` although a player that honours the tag decodes it as BT.601. A non-BT.709 matrix is now a tag: the row is WARN, and so is a BT.709 primaries/transfer file with a BT.601 matrix. For a BT.601 matrix the fix no longer offers `color.py --retag bt709`, which only relabels the pixels (as every SDR re-encode here does); it says to re-export from the master as BT.709. A file tagged only with a BT.709 matrix still passes, worded `bt709 matrix, primaries/transfer untagged (players assume bt709)` instead of "untagged" (#325).## 2.8.6diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex deea470..a7f1ce0 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -115,6 +115,12 @@ exists. When a decision changes, edit the entry in the same PR.is a deliverable, keep the HDR (10-bit HEVC) path. Test: `test_grid_composites_cols_rows_with_labels`.- **`look.py -o` is used verbatim only for a single `--at` with an image extension**; several frames,or `-o` given as a stem, produce `<stem>_<t>s.png` names. Test: `test_hdr_source_stays_hdr_through_reencodes`.+- **`check.py`'s colour row WARNs on a BT.601 matrix without naming a command.** The matrix is a+ tag (#325): a file tagged only `smpte170m`/`bt470bg` is BT.601, not "untagged". No tool here+ converts the matrix -- `color.py --retag bt709`, and every SDR re-encode (`bt709_tag_args`), only+ relabels it, which shifts the colours of BT.601 pixels -- so the fix says to re-export from the+ master as BT.709. Untagged 8-bit video, or a BT.709 matrix alone, still passes: players assume+ BT.709. Code: `check.py`, the colour row. Test: `test_check_colour_row_reads_the_matrix_tag`.- **`--correct` converts through bt601 on both legs** (not bt709), because on every testedFFmpeg the 709 round trip through 8-bit 4:2:0 loses ~5 dB more than 601. Code:`color.py _rgb_stage()`. Test: `test_color_correct_identity_holds_on_a_bt709_tagged_source`.diff --git a/scripts/check.py b/scripts/check.pyindex 3d2dd07..4f95c96 100755--- a/scripts/check.py+++ b/scripts/check.py@@ -163,13 +163,25 @@ def main() -> int:else:tags = (v.get("color_primaries"), v.get("color_transfer"))untagged = not tags[0] and not tags[1]- if v.get("bt2020_or_hdr") or tags == ("bt709", "bt709") or args.platform in ("podcast", "custom"):+ # The matrix (color_space) is a tag too (#325): a player that honours it decodes with it,+ # so a file whose only tag is a BT.601 matrix is BT.601, not "untagged".+ matrix = v.get("color_space")+ matrix_709 = matrix in (None, "bt709")+ shown = (f"{matrix} matrix, primaries/transfer untagged" if untagged and matrix else+ f"{tags[0]}/{tags[1]}" + ("" if matrix in (None, tags[0]) else f", {matrix} matrix"))+ if v.get("bt2020_or_hdr") or (tags == ("bt709", "bt709") and matrix_709) or args.platform in ("podcast", "custom"):row("colour", "PASS", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("bt2020_or_hdr") else ""), "bt709/bt709 tagged (or HDR)")- elif untagged and (v.get("bit_depth") or 8) == 8:+ elif untagged and matrix_709 and (v.get("bit_depth") or 8) == 8:# untagged 8-bit video is treated as BT.709 by every player and platform; nothing to fix- row("colour", "PASS", "untagged (players assume bt709)", "bt709/bt709 tagged (or HDR)")+ row("colour", "PASS", shown + " (players assume bt709)" if matrix else "untagged (players assume bt709)", "bt709/bt709 tagged (or HDR)")+ elif matrix in ("smpte170m", "bt470bg"):+ # The pixels are BT.601-encoded. Nothing here converts the matrix: --retag bt709 and+ # every SDR re-encode (bt709_tag_args) only relabel it, which shifts the colours.+ row("colour", "WARN", shown, "bt709/bt709 tagged (or HDR)",+ "re-export from the master as BT.709; color.py --retag bt709 (like any re-encode here) only relabels the matrix: right only if the pixels really are BT.709",+ reason="a player that honours the BT.601 tag and one that ignores it on HD video (decoding it as BT.709) show different colours")else:- row("colour", "WARN", f"{tags[0]}/{tags[1]}", "bt709/bt709 tagged (or HDR)", "color.py --retag bt709 when the picture really is 709; color.py --to-sdr when it is HDR")+ row("colour", "WARN", shown, "bt709/bt709 tagged (or HDR)", "color.py --retag bt709 when the picture really is 709; color.py --to-sdr when it is HDR")elif args.platform not in ("podcast", "custom"):row("video", "FAIL", "none", "video stream", "")diff --git a/tests/test_analysis.py b/tests/test_analysis.pyindex 6c52e92..4311ce7 100644--- a/tests/test_analysis.py+++ b/tests/test_analysis.py@@ -286,6 +286,37 @@ class AnalysisTests(MediaFixtures):r = self._rows(mixed, "--content")self.assertEqual((r["black"]["status"], r["silence"]["status"]), ("WARN", "WARN"), r)+ def test_check_colour_row_reads_the_matrix_tag(self):+ """#325: the colour row decided "untagged" from primaries and transfer only, so a file whose+ only tag is a BT.601 matrix passed as "untagged (players assume bt709)" while a tag-honouring+ player decodes it as BT.601. The tags are x264 VUI parameters (a label, no conversion)."""+ cases = { # name: (x264 VUI params, status, value)+ "matrix-only-601": ("colormatrix=smpte170m", "WARN", "smpte170m matrix, primaries/transfer untagged"),+ "matrix-only-bt470bg": ("colormatrix=bt470bg", "WARN", "bt470bg matrix, primaries/transfer untagged"),+ "full-601": ("colorprim=smpte170m:transfer=smpte170m:colormatrix=smpte170m", "WARN", "smpte170m/smpte170m"),+ "709-601-matrix": ("colorprim=bt709:transfer=bt709:colormatrix=smpte170m", "WARN", "bt709/bt709, smpte170m matrix"),+ "matrix-only-709": ("colormatrix=bt709", "PASS", "bt709 matrix, primaries/transfer untagged (players assume bt709)"),+ "full-709": ("colorprim=bt709:transfer=bt709:colormatrix=bt709", "PASS", "bt709/bt709"),+ "untagged": ("scenecut=0", "PASS", "untagged (players assume bt709)"),+ }+ for name, (params, status, value) in cases.items():+ with self.subTest(name):+ path = OUT / f"colour_{name}.mp4"+ if not path.exists():+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=10",+ "-f", "lavfi", "-i", "sine=sample_rate=48000", "-t", "1", "-pix_fmt", "yuv420p",+ "-c:v", "libx264", "-x264-params", params, "-c:a", "aac", "-shortest", path)+ # the later --platform wins over _rows' custom, which passes any colour+ row = self._rows(path, "--no-loudness", "--platform", "reels")["colour"]+ self.assertEqual((row["status"], row["value"]), (status, value), row)+ if status == "PASS":+ self.assertEqual((row["fix"], row["reason"]), ("", ""), row)+ else:+ # every WARN here is a BT.601 matrix: nothing converts it, so --retag bt709 is not the fix+ self.assertTrue(row["fix"].startswith("re-export from the master as BT.709"), row)+ self.assertIn("only relabels", row["fix"])+ self.assertIn("BT.601", row["reason"])+def test_check_default_rows_unchanged_without_content(self):clip = self._content_clip("content_black.mp4", "color=black:size=160x90:rate=10","sine=frequency=440:sample_rate=48000")