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(check): read the matrix tag in the colour row (#329)

Shogo Kajiyamae56ba469d4ba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.6
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 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 tested
FFmpeg 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.py
index 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.py
index 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")