ffmpeg-skill 2.10.0 → 2.10.2

package/README.md

@@ -248,7 +248,7 @@ These are the rules the skill file gives the agent and the code enforces.
 
 | Tool | What it does |
 |---|---|
-| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `tiktok`, `shorts`, `linkedin`, `facebook`, `x`, `youtube-hdr` (HEVC Main10, source HDR tags kept), `youtube-av1`, `prores`, `h265`, `gif`, `copy`, all tagged BT.709 unless they carry HDR; `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) |
+| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `tiktok`, `shorts`, `linkedin`, `facebook`, `x`, `youtube-hdr` (HEVC Main10, source HDR tags kept), `youtube-av1`, `prores`, `h265`, `gif`, `copy`, all tagged BT.709 unless they carry HDR (a BT.601-matrix or RGB source is converted to BT.709, not relabelled); `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) |
 | `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--quality` (default 30), `--fps`, `--no-audio`; not a delivery preset |
 | `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row |
 | `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run; `--pack` renders a social pack table |

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.10.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.2`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.10.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.2", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -217,6 +217,15 @@ BT.709 for SDR; av1 is SVT-AV1 with libaom as the fallback; prores is 422 HQ and
 its default is the tool's own (18, `proxy.py` 30). 1.x also accepted `--crf` as an alias; 2.0
 removed it (`export.py` keeps its own `--crf`). Without `--codec` the encoder is what it always was (x264 for SDR, x265
 Main10 for HDR), so the flags add no behaviour to a caller that does not pass them.
+Every SDR line except prores is tagged BT.709; a source whose matrix is BT.601 (`smpte170m`,
+`bt470bg`, or `fcc`/`smpte240m`) is converted to it in the filter graph (`colorspace`, matrix
+only; `_common.bt709_matrix_filter()`), so the label and the pixels agree. An untagged or BT.709
+source adds no filter, and the tags themselves never convert (`bt709_tag_args()`). An RGB picture
+(a PNG or JPEG still, a PNG sequence, a qtrle clip, an `overlay --image` logo, an emoji PNG,
+`waveform --image`) is converted to BT.709 YUV explicitly (`scale=out_color_matrix=bt709`; a JPEG is
+a `bt470bg` source); `grid.py` converts each cell by its own tags. Where a converted picture meets an
+untagged one in a mixing filter, the untagged one is labelled BT.709 (`setparams`, tags only), so
+FFmpeg 7.1+'s colourspace negotiation converts neither.
 `cut.py --keep-hevc` (opt-in) re-encodes an SDR HEVC source as x265 8-bit BT.709 instead of x264; an HDR or
 BT.2020 source keeps the Main10 line with its own colour tags, with or without the flag. The
 encoder each value needs is listed under the tool's optional capabilities (`--codec hevc` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.10.0",
+  "version": "2.10.2",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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",

package/references/gotchas.md

@@ -8,7 +8,13 @@ detail, not an aside.
 ## Colour, HDR and Log
 
 ### HDR and colour
-SDR outputs are H.264 tagged BT.709 `yuv420p`. When `probe.py` reports
+SDR outputs are H.264 tagged BT.709 `yuv420p`. A source tagged with a BT.601 matrix
+(`smpte170m`, `bt470bg`; also `fcc`, `smpte240m`) has its pixels converted to that BT.709 matrix
+by every re-encode (through 2.10.0 only the label changed); `color.py --retag bt709` is a
+stream copy and still only relabels. Untagged sources are taken as BT.709 and left alone. An RGB
+picture (PNG/JPEG still, logo, emoji PNG, PNG sequence, qtrle clip) is converted to BT.709 YUV
+explicitly (through 2.10.1 FFmpeg's BT.601 default did it), and `grid.py` converts each cell by its
+own tags. When `probe.py` reports
 `bt2020_or_hdr: true` (HDR10/PQ, HLG, Dolby Vision, or BT.2020 SDR), every editing script keeps
 the output on the 10-bit path (HEVC Main10, source colour tags) so nothing is silently
 flattened. Decide with the user: keep HDR (fine for YouTube/phones) or run

package/references/scripts.md

@@ -1615,7 +1615,7 @@ export.py INPUT --preset youtube|youtube4k|reels|tiktok|shorts|linkedin|facebook
                 [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [--normalize] [-o OUT]
 export.py --list
 ```
-Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
+Scales into the preset frame (pad by default), tags BT.709 (a BT.601-matrix or RGB source is converted to it, as by every re-encode), sets `+faststart`,
 trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`. It
 does not touch levels: for youtube / youtube4k / reels / x the written file is
 measured and the result's `loudness` (and a `notes` line) says when it is

package/scripts/_common/__init__.py

@@ -83,7 +83,7 @@ from _common.decision import (
     _onset_strength, _pick_onsets, _autocorrelation_peak, _grid_score,
     brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
     fmt_secs, fmt_smpte_time, fmt_srt_time, frame_size, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
-    signed_time_arg, source_codec_video_args, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
+    signed_time_arg, source_codec_video_args, label_chain, matrix_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
 )
 from _common.asr import (
     ASR_ENGINES, ASR_INSTALL_HINT, _asr_run, die_no_engine, parse_srt, transcribe, _transcribe_in,
@@ -91,7 +91,8 @@ from _common.asr import (
     whisper_word_timings, write_srt
 )
 from _common.color import (
-    bt709_tag_args, color_hex, _COLOR_TOKEN_RE, _sdr_bt709, validate_color
+    bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, color_hex, _COLOR_TOKEN_RE, fold_bt709_matrix,
+    is_rgb, NON_BT709_MATRICES, rgb_to_bt709_filter, _sdr_bt709, validate_color
 )
 from _common.text import (
     ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align,
@@ -178,7 +179,7 @@ __all__ = [
     "platform", "re", "shutil", "subprocess", "sys", "unicodedata",
     "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "apply_common", "detect_scenes", "detect_silences", "SCORE_RE", "SIL_RE", "_aspect_string",
     "audio_codec_for", "AUDIO_CODECS", "BIDI_SCRIPTS", "_bit_depth", "brand_caption_style", "BRAND_DEFAULTS",
-    "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_tag_args", "cfr_args", "_char_em",
+    "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_matrix_args", "bt709_matrix_filter", "bt709_tag_args", "cfr_args", "_char_em",
     "char_script", "_check_existing_output", "refuse_existing_outputs", "_check_no_overwrite_input", "_check_output_path", "child_args",
     "child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
     "concat_list_line", "Context", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",
@@ -196,12 +197,12 @@ __all__ = [
     "_EMOJI_TAIL", "encoder_args", "_ENCODERS", "_env_timeout", "ERROR_CODE", "ERROR_RETRYABLE", "escape_drawtext",
     "escape_filter_path", "EVEN_SCALE", "_execute", "_fail", "_family_rank", "FC_LANG", "_fc_list_fonts",
     "FC_UNKNOWN", "ffmpeg_base", "ffmpeg_encoders", "ffmpeg_exe", "_FFMPEG_VERSION", "ffmpeg_version", "fingerprint",
-    "flush_drawtext_textfiles", "fmt_secs", "fmt_smpte_time", "fmt_srt_time", "font_covers_script",
+    "flush_drawtext_textfiles", "fold_bt709_matrix", "fmt_secs", "fmt_smpte_time", "fmt_srt_time", "font_covers_script",
     "font_family_for_script", "font_family_of_file", "FONT_FLAG_HINT", "font_for_script", "FONT_INSTALL_HINT",
     "fonts_dir_covers_script", "_fraction", "has_emoji", "info", "INSTALL_HINTS", "install_signal_handlers",
     "is_audio_output", "_is_emoji_base", "_is_emoji_char", "_is_ffmpeg", "_is_mark", "_KEYCAP", "_KEYCAP_BASES",
     "keyframes_near", "classify_frame_timing", "measure_frame_timing", "LANGUAGE_NAMES", "LATIN_EM", "LEADING_VOWELS", "_libass_color_probe", "_limit_for",
-    "load_brand", "measured_level_dbfs", "AUDIO_MEDIA_EXT", "MEDIA_EXT", "MissingFpsError", "needs_shaping", "NO_SPACE_SCRIPTS",
+    "load_brand", "measured_level_dbfs", "AUDIO_MEDIA_EXT", "MEDIA_EXT", "MissingFpsError", "needs_shaping", "NO_SPACE_SCRIPTS", "NON_BT709_MATRICES",
     "_odd_dimension_retry", "_on_signal", "_output_failed", "_OutputLock", "pad_filters", "parse_time", "_pid_dead",
     "place_output", "_plan_at_exit", "_plan_inputs", "_PLAN_STRIP", "PLAN_VERSION", "PREFERRED_FAMILIES",
     "print_json", "probe", "PROBE_TIMEOUT", "_progress_line", "read_text_or_die", "refuse_output_is_input",
@@ -212,7 +213,7 @@ __all__ = [
     "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote", "sibling_temp",
     "_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
     "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "validate_color", "verify_output",
-    "source_codec_video_args", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
+    "source_codec_video_args", "label_chain", "matrix_chain", "rgb_chain_to_bt709", "bt709_label_filter", "rgb_to_bt709_filter", "is_rgb", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
     "_x264_raw", "_ZWJ",
     "ASR_ENGINES", "ASR_INSTALL_HINT", "_asr_run", "die_no_engine", "parse_srt", "transcribe",
     "_transcribe_in", "transcribe_words", "_words_from_openai_whisper_json",

package/scripts/_common/color.py

@@ -4,7 +4,7 @@ validation for the tools that take a `--color`.
 from __future__ import annotations
 
 import re
-from typing import List, Tuple
+from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die
 from _common.runner import ffmpeg_version
 
@@ -18,9 +18,13 @@ def bt709_tag_args(encoder: str = "libx264") -> List[str]:
     screen recordings, many cameras) the CLI now auto-inserts a *real* matrix conversion (its
     guess for "unknown" is bt601) into every SDR re-encode: a --lut-strength 0 no-op grade
     came back ~24 dB PSNR from its source on 7.1. From 7.1 on, the tags therefore go through
-    the encoder's own VUI parameters instead, which libavfilter never sees; a source that is
-    genuinely tagged bt601/bt2020 is left alone either way (it keeps its own tags on the old
-    path, and the encoder VUI is a label, not a conversion, on the new one).
+    the encoder's own VUI parameters instead, which libavfilter never sees.
+
+    These tags are a label on every FFmpeg version: they never convert the pixels. A source
+    whose matrix is not BT.709 (a BT.601 `smpte170m`/`bt470bg` file) gets its pixels converted
+    separately, by bt709_matrix_filter() in the filter graph; through 2.10.0 nothing did, and
+    such a source came out labelled BT.709 over BT.601 pixels (measured on 6.1: 48.5 dB YUV
+    PSNR against the source, i.e. untouched, tagged bt709/bt709/bt709).
     """
     if ffmpeg_version() < (7, 1):
         return ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
@@ -42,6 +46,149 @@ def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
     return "colorprim=bt709:transfer=bt709:colormatrix=bt709", []
 
 
+# The SDR matrices (ffprobe's names) whose pixels an output tagged BT.709 has to convert:
+# BT.601 (`smpte170m` 525-line, `bt470bg` 625-line: the same coefficients) and the two rare
+# pre-BT.709 ones the colorspace filter also reads. bt2020nc/c sources take the HDR/BT.2020 path.
+NON_BT709_MATRICES = ("smpte170m", "bt470bg", "fcc", "smpte240m")
+
+# RGB pictures (ffprobe's pix_fmt names: PNG rgb24/rgba/pal8/rgb48be, qtrle, gbrp...). Their
+# conversion to YUV is wherever the graph first needs YUV, and FFmpeg's default for it is BT.601
+# (5.1, 6.1, 7.0; 7.1+ follows the link's tag, unspecified = BT.601). Gray has no matrix.
+_RGB_PIX_FMT_RE = re.compile(r"^(?:rgb|bgr|argb|abgr|0rgb|0bgr|gbr|x2rgb|x2bgr|pal8)")
+
+
+def rgb_to_bt709_filter(pix_fmt: str = "yuv444p") -> str:
+    """An RGB picture converted to BT.709 limited-range YUV right here, in `pix_fmt`, so no later
+    conversion (an auto-inserted one, with FFmpeg's BT.601 default) decides the matrix. 4:4:4 by
+    default: the tool's own scaling and the encoder's 4:2:0 come after, as they did on the RGB."""
+    return f"scale=out_color_matrix=bt709:out_range=tv,format={pix_fmt}"
+
+
+def is_rgb(meta: Optional[Dict[str, Any]]) -> bool:
+    """True when the probed picture is RGB (a PNG/still, a qtrle/png-in-mov clip, an image sequence)."""
+    return bool(_RGB_PIX_FMT_RE.match(str(((meta or {}).get("video") or {}).get("pix_fmt") or "")))
+
+
+_MATRIX_FILTER_RE = re.compile(r"^(?:colorspace=ispace=(?:%s):iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709|(?:format=rgb24,)?%s)$"
+                               % ("|".join(NON_BT709_MATRICES), re.escape(rgb_to_bt709_filter())))
+_INPUT_VIDEO_REF = re.compile(r"\[(\d+):v(?::0)?\]")
+
+
+def bt709_matrix_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
+    """The filter that turns the probed source's pixels into BT.709 ones before an output is
+    tagged BT.709, or None when nothing needs converting: an SDR source tagged with a non-BT.709
+    matrix (NON_BT709_MATRICES) only. An untagged or BT.709 source, an HDR/BT.2020 one (it keeps
+    its own tags, or color.py --to-sdr converts it) and a missing probe get None, so their
+    commands are what they were.
+
+    The matrix is converted and nothing else: primaries and transfer are passed through
+    (iprimaries/itrc = the output's), so the picture a player that decodes with the source's
+    matrix showed is the picture the BT.709 output shows. The `colorspace` filter is in every
+    FFmpeg build (no zscale needed) and takes explicit input properties, so the conversion does
+    not depend on how a build reads or negotiates the frames' own tags. The range is left as it is.
+
+    An RGB source (is_rgb: a PNG/still, an image sequence, a qtrle clip) has no matrix of its own
+    but gets one where the graph first needs YUV, and FFmpeg's default there is BT.601: through
+    2.10.1 such a source came out labelled BT.709 over BT.601-encoded pixels (pure red decoded as
+    (255,24,0), pure green as (0,216,0), on 5.1.1 to 8.1). It is converted to BT.709 YUV here
+    (rgb_to_bt709_filter). A JPEG (yuvj, tagged bt470bg) is a BT.601 source like any other."""
+    v = (meta or {}).get("video") or {}
+    matrix = v.get("color_space")
+    if v.get("bt2020_or_hdr"):
+        return None
+    if is_rgb(meta):
+        # a palette is turned into YUV with fixed BT.601 coefficients whatever out_color_matrix
+        # says (5.1.1, 6.1): expand it to RGB first
+        return ("format=rgb24," if v.get("pix_fmt") == "pal8" else "") + rgb_to_bt709_filter()
+    if matrix not in NON_BT709_MATRICES:
+        return None
+    return f"colorspace=ispace={matrix}:iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709"
+
+
+def bt709_label_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
+    """For an UNTAGGED SDR YUV picture that meets a converted (BT.709-tagged) one in a filter that
+    mixes pictures (overlay, xstack): its BT.709 label, tags only (setparams), or None for any
+    other picture (tagged, RGB, HDR, no probe).
+
+    FFmpeg 7.1+ negotiates one colourspace for all of a mixing filter's inputs and converts the
+    others to it, taking "unknown" as BT.601: the untagged main under a converted logo, or an
+    untagged grid cell beside a converted one, was shifted (7.08 mean / 25 max RGB on 7.1.1 and
+    8.1.3), or the converted picture converted back. Labelled as what the output says it is, the
+    inputs agree and nothing is converted; on 5.1-7.0 the label changes nothing. The pixels are not
+    touched, as for the untagged source of a one-input re-encode (bt709_tag_args)."""
+    v = (meta or {}).get("video") or {}
+    if (not v.get("pix_fmt") or v.get("bt2020_or_hdr") or is_rgb(meta)
+            or (v.get("color_space") or "unknown") not in ("unknown", "unspecified")):
+        return None
+    return "setparams=colorspace=bt709" + ("" if v.get("color_range") == "pc" else ":range=tv")
+
+
+def bt709_matrix_args(meta: Optional[Dict[str, Any]]) -> List[str]:
+    """["-vf", bt709_matrix_filter(meta)] for an encoder line that tags its output BT.709, or [].
+
+    It rides on the encoder line (decision.video_args() and friends) so every tool that
+    re-encodes through that line converts without building it into its own graph. That -vf is
+    valid as it stands for a command with no other filter; run() folds it into the tool's own
+    -vf or -filter_complex (fold_bt709_matrix()) before the command is recorded or run."""
+    f = bt709_matrix_filter(meta)
+    return ["-vf", f] if f else []
+
+
+def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
+    """`cmd` with the conversion bt709_matrix_args() appended to its encoder line moved into the
+    tool's own filter graph, where it runs first, on the decoded source:
+
+    - no other filter: unchanged (the -vf is the graph);
+    - a -vf: the conversion is prepended to that chain;
+    - a -filter_complex: every `[N:v]` / `[N:v:0]` reference to an input that reads the same file
+      as input 0 (the file the encoder line was built for; cut.py's segment join opens it once
+      per segment) reads that input through the conversion instead. Other inputs are untouched.
+
+    A -filter_complex with no such reference is refused rather than run with two graphs (ffmpeg
+    would refuse it anyway, less clearly). Every other command is returned as it is."""
+    out: List[str] = []
+    conv, at = None, -1
+    i = 0
+    while i < len(cmd):
+        if cmd[i] == "-vf" and i + 1 < len(cmd) and _MATRIX_FILTER_RE.match(str(cmd[i + 1])):
+            conv, at = conv or str(cmd[i + 1]), (at if at >= 0 else len(out))
+            i += 2
+            continue
+        out.append(cmd[i])
+        i += 1
+    if conv is None:
+        return list(cmd)
+    graph_at = next((k for k, a in enumerate(out[:-1]) if a in ("-filter_complex", "-lavfi")), None)
+    if graph_at is not None:
+        inputs = [out[k + 1] for k in range(len(out) - 1) if out[k] == "-i"]
+        source = {n for n, p in enumerate(inputs) if p == inputs[0]} if inputs else set()
+        refs: Dict[int, List[str]] = {}  # input index -> [its first reference, the labels standing in for it]
+
+        def through(m: "re.Match[str]") -> str:
+            n = int(m.group(1))
+            if n not in source:
+                return m.group(0)
+            label = f"[bt709src{sum(len(v) - 1 for v in refs.values())}]"
+            refs.setdefault(n, [m.group(0)]).append(label)
+            return label
+
+        graph = _INPUT_VIDEO_REF.sub(through, str(out[graph_at + 1]))
+        if not refs:
+            die("internal: a BT.709 matrix conversion was requested for a -filter_complex that never reads "
+                "input 0's video as [0:v]", kind="ffmpeg")
+        # one conversion per input, split when the graph reads that input more than once
+        # (speedramp.py trims [0:v] once per segment)
+        chains = [f"{ref}{conv}" + (f",split={len(labels)}" if len(labels) > 1 else "") + "".join(labels)
+                  for ref, *labels in refs.values()]
+        out[graph_at + 1] = ";".join(chains + [graph])
+        return out
+    vf_at = next((k for k, a in enumerate(out[:-1]) if a == "-vf"), None)
+    if vf_at is not None:
+        out[vf_at + 1] = f"{conv},{out[vf_at + 1]}"
+        return out
+    return out[:at] + ["-vf", conv] + out[at:]
+
+
 def color_hex(value: str) -> str:
     """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
     v = str(value).strip().lstrip("#")

package/scripts/_common/decision.py

@@ -14,7 +14,7 @@ import argparse
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
-from _common.color import bt709_tag_args, _sdr_bt709
+from _common.color import bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, rgb_to_bt709_filter, _sdr_bt709
 from _common.emit import die
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_version, hw_platform_reason
 
@@ -497,30 +497,83 @@ def _x264_raw(crf: int, preset: str, keep_bt709: bool = True) -> List[str]:
     return args
 
 
-def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
+def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True,
+              source: Optional[Dict[str, Any]] = None) -> List[str]:
     """SDR H.264 encoder args -- or, when --codec named another encoder, that encoder's SDR args
-    (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it)."""
+    (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it).
+
+    `source`: the probe of the file being re-encoded, when the pixels reaching the encoder are
+    still that file's. A BT.709-tagged line then carries the conversion of a non-BT.709 matrix
+    (bt709_matrix_args); a caller whose graph already outputs BT.709 (--to-sdr) leaves it out."""
     if STATE.codec and STATE.codec != "h264":
-        return encoder_args(STATE.codec, crf, preset, None, keep_bt709)
-    return _maybe_hw("h264", crf, None, keep_bt709, _x264_raw(crf, preset, keep_bt709))
+        args = encoder_args(STATE.codec, crf, preset, None, keep_bt709)
+    else:
+        args = _maybe_hw("h264", crf, None, keep_bt709, _x264_raw(crf, preset, keep_bt709))
+    return args + (bt709_matrix_args(source) if keep_bt709 and STATE.codec != "prores" else [])
 
 
-def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
+def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium", convert_matrix: bool = True,
+               source: Optional[Dict[str, Any]] = None) -> List[str]:
     """Encoder args that preserve what the source is.
 
     SDR sources -> H.264 8-bit tagged BT.709 (x264_args). HDR sources (HDR10/PQ, HLG,
     Dolby Vision base layer, BT.2020) -> HEVC Main10 with the source's own colour tags,
     so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
     washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
+
+    An SDR source tagged with a BT.601 (or another non-BT.709) matrix is converted to BT.709
+    before it is tagged so: the line ends with the `-vf` of bt709_matrix_args(), which run()
+    folds into the tool's own graph (color.fold_bt709_matrix). `convert_matrix=False` is for a
+    tool that mixes several sources and converts each one in its own graph (join, multicam,
+    broll, overlay --video). --codec prores keeps the source's tags, so it converts nothing.
+    An RGB source (a PNG, an image sequence, a qtrle clip) is converted the same way.
+
+    `source`: the probe of the picture the encoder gets when the line is chosen without it
+    (insert.py and sequence.py make a still or a PNG sequence into video on the SDR line,
+    video_args(None)); its RGB or BT.601 pixels are converted to the BT.709 that line is tagged with.
     """
-    if STATE.codec:
-        return encoder_args(STATE.codec, crf, preset, meta)
     v = (meta or {}).get("video") or {}
+    fix = bt709_matrix_args(meta if source is None else source) if convert_matrix and STATE.codec != "prores" else []
+    if STATE.codec:
+        return encoder_args(STATE.codec, crf, preset, meta) + fix
     if not v.get("bt2020_or_hdr"):
-        return x264_args(crf, preset)
+        return x264_args(crf, preset) + fix
     return _maybe_hw("hevc", crf, meta, True, _x265_hdr_default(v, crf, preset))
 
 
+def matrix_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, Any]]) -> str:
+    """For a tool that mixes several sources in one graph and encodes it through
+    video_args(line_meta, convert_matrix=False): the conversion one source's own chain starts
+    with ("<filter>," -- bt709_matrix_filter), or "" when that source needs none or the line does
+    not tag BT.709 (an HDR/BT.2020 line keeps its tags, --codec prores keeps the source's)."""
+    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+        return ""
+    f = bt709_matrix_filter(meta)
+    return f + "," if f else ""
+
+
+def label_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, Any]]) -> str:
+    """For a picture that meets a converted one in a mixing filter (a still over the video, a grid
+    cell beside a converted cell), encoded through video_args(line_meta): the BT.709 label an
+    untagged one's chain starts with ("<setparams>," -- bt709_label_filter), or "" (a tagged, RGB or
+    HDR picture, or a line that does not tag BT.709)."""
+    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+        return ""
+    f = bt709_label_filter(meta)
+    return f + "," if f else ""
+
+
+def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva420p") -> str:
+    """For a picture the tool's own graph has made RGB(A) -- a still's `format=rgba` chain
+    (overlay.py --image, an emoji PNG) or an RGBA composite (waveform.py's --image plate) -- that
+    is encoded through video_args(line_meta): "," + the conversion to BT.709 YUV to end that chain
+    with (rgb_to_bt709_filter), or "" when the line does not tag BT.709 (the lines matrix_chain()
+    leaves alone). Without it the graph's own RGB-to-YUV step used FFmpeg's BT.601 default."""
+    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+        return ""
+    return "," + rgb_to_bt709_filter(pix_fmt)
+
+
 def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium",
                             keep_hevc: bool = False) -> List[str]:
     """video_args(), except that with `keep_hevc` (cut.py --keep-hevc) an SDR HEVC source re-encodes
@@ -530,7 +583,7 @@ def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, prese
     source always takes video_args()'s Main10 line, and --codec always wins."""
     v = (meta or {}).get("video") or {}
     if keep_hevc and not STATE.codec and v.get("codec") == "hevc" and not v.get("bt2020_or_hdr"):
-        return encoder_args("hevc", crf, preset, meta)
+        return encoder_args("hevc", crf, preset, meta) + bt709_matrix_args(meta)
     return video_args(meta, crf, preset)
 
 

package/scripts/_common/emoji.py

@@ -286,12 +286,16 @@ def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]"
 
 
 
-def emoji_filter_chain(plan, base_label, out_label, first_input=1):
+def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", base_chain=""):
     """(chains, inputs) that composite the planned PNGs on top of `base_label`.
 
     `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
     ffmpeg command in order (an overlay that fades needs `-loop 1` on its input so the still has
     a timeline the fade filter can move along; one that does not is a plain `-i`).
+    `to_yuv` ends each PNG's chain: the caller's rgb_chain_to_bt709(meta), so the RGBA asset is
+    converted to the BT.709 the output is tagged with instead of by overlay's BT.601 default;
+    `base_chain` (label_chain(meta, meta): an untagged source's BT.709 label) goes in front of
+    the first overlay, so 7.1+ does not convert the two pictures to one another.
     """
     overlays = plan.get("overlays") or []
     if not overlays:
@@ -329,11 +333,15 @@ def emoji_filter_chain(plan, base_label, out_label, first_input=1):
                 chain += f",fade=t=out:st={max(gstart, gend - fout):.3f}:d={fout:.3f}:alpha=1"
         else:
             inputs.append(["-i", asset])
+        chain += to_yuv
         if len(labels) > 1:
             chain += f",split={len(labels)}"
         chains.append(chain + "".join(f"[{l}]" for l in labels))
         pads[key] = labels
     cur = base_label
+    if base_chain:
+        chains.append(f"[{cur}]{base_chain}null[ebase]")
+        cur = "ebase"
     remaining = {key: list(v) for key, v in pads.items()}
     for j, o in enumerate(overlays):
         label = remaining[_key(o)].pop(0)

package/scripts/_common/runner.py

@@ -878,6 +878,11 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
     ctx = ctx or STATE
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
+        # an encoder line that converts a BT.601 source to the BT.709 it is tagged with carries
+        # that conversion as a -vf; it joins the tool's own graph here, before anything records
+        # or runs the command (color.py imports this module, hence the late import)
+        from _common.color import fold_bt709_matrix
+        cmd = fold_bt709_matrix(cmd)
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
         _check_existing_output(cmd)

package/scripts/broll.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, time_arg, matrix_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 
 
 def main() -> int:
@@ -87,7 +87,7 @@ def main() -> int:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
         if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
             die(f"cutaway {i + 1} at {at:g}s overlaps the previous one (ends {cutaways[-1]['at'] + cutaways[-1]['length']:g}s)")
-        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio"))})
+        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b})
     if args.audio != "a" and not all(c["has_audio"] for c in cutaways):
         die("--audio b/mix needs audio on every B-roll clip")
 
@@ -101,10 +101,14 @@ def main() -> int:
     # A shows through unchanged, so A's timeline is never touched.
     parts: List[str] = []
     cur = "[0:v]"
+    # every clip is converted by its own colour tags to the BT.709 the output is tagged with
+    if matrix_chain(meta_a, meta_a):
+        parts.append(f"[0:v]{matrix_chain(meta_a, meta_a)}null[a709]")
+        cur = "[a709]"
     for i, c in enumerate(cutaways):
         geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
+                     f"{matrix_chain(c['meta'], meta_a)}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
         parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur
@@ -131,7 +135,7 @@ def main() -> int:
     cmd += ["-filter_complex", ";".join(parts), "-map", vout]
     if aout:
         cmd += ["-map", aout]
-    cmd += video_args(meta_a, args.crf, args.preset) + cfr_args(meta_a, None)
+    cmd += video_args(meta_a, args.crf, args.preset, convert_matrix=False) + cfr_args(meta_a, None)
     if aout == "0:a:0":
         cmd += ["-c:a", "copy"]
     elif aout:

package/scripts/caption.py

@@ -44,7 +44,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
                         resolve as resolve_platform)
 from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
-from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs
+from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, label_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
@@ -1562,7 +1562,9 @@ def main() -> int:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
 
     cmd = ffmpeg_base() + ["-i", args.input]
-    chains, emoji_inputs = emoji_filter_chain(emoji_plan or {}, "vsub", "vout") if emoji_plan else ([], [])
+    chains, emoji_inputs = (emoji_filter_chain(emoji_plan or {}, "vsub", "vout", to_yuv=rgb_chain_to_bt709(meta),
+                                               base_chain=label_chain(meta, meta) if rgb_chain_to_bt709(meta) else "")
+                            if emoji_plan else ([], []))
     if chains:
         for spec in emoji_inputs:
             cmd += spec

package/scripts/check.py

@@ -175,10 +175,10 @@ def main() -> int:
                 # untagged 8-bit video is treated as BT.709 by every player and platform; nothing to fix
                 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.
+                # The pixels are BT.601-encoded. A re-encode here converts them to the BT.709 it tags
+                # (bt709_matrix_filter); --retag bt709 is a stream copy and only relabels the matrix.
                 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",
+                    "export.py (any re-encode here converts the BT.601 matrix to BT.709); color.py --retag bt709 only relabels it: 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", shown, "bt709/bt709 tagged (or HDR)", "color.py --retag bt709 when the picture really is 709; color.py --to-sdr when it is HDR")

package/scripts/color.py

@@ -353,7 +353,9 @@ def main() -> int:
         tag = "lut"
 
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
-    cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else [])
+    # --lut/--correct grade the source's own pixels, so a BT.601 source is converted to the BT.709
+    # the line is tagged with; --to-sdr's zscale chain already writes BT.709 and converts nothing more
+    cmd += x264_args(args.crf, args.preset, source=None if args.to_sdr else meta) + cfr_args(meta) + (aac_args() if has_audio else [])
     dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {r['video']['width']}x{r['video']['height']}, "

package/scripts/export.py

@@ -36,7 +36,7 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from _common import STATE, add_common, apply_common, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, resolve as resolve_platform
@@ -216,6 +216,11 @@ def main() -> int:
             cmd += cfr_args(meta)
         if tag_bt709 and not video[video.index("-c:v") + 1].endswith("_videotoolbox"):
             cmd += bt709_tag_args(video[video.index("-c:v") + 1])
+        if args.preset != "prores":
+            # every line but the prores master's says BT.709 (the fixed presets' tags above, an
+            # SDR hevc/av1 line's own): a BT.601 source's pixels are converted to match, in front
+            # of the -vf above (run() folds the two); an untagged, BT.709 or HDR source adds nothing
+            cmd += bt709_matrix_args(meta)
     if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]
     cmd += (p["audio"] if has_audio else ["-an"])

package/scripts/graphics.py

@@ -34,7 +34,7 @@ from typing import List, Optional
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import (aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path,
-                     ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args,
+                     ffmpeg_base, info, label_chain, load_brand, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
@@ -599,7 +599,9 @@ def main() -> int:
                 vf += f":fontsdir={escape_filter_path(fdir)}"
             chains.append(f"[{last}]{vf}[vtxt]")
             last = "vtxt"
-        eo, emoji_inputs = emoji_filter_chain({"overlays": emoji_overlays}, last, "vfinal", first_input=1)
+        eo, emoji_inputs = emoji_filter_chain({"overlays": emoji_overlays}, last, "vfinal", first_input=1,
+                                              to_yuv=rgb_chain_to_bt709(meta),
+                                              base_chain=label_chain(meta, meta) if rgb_chain_to_bt709(meta) else "")
         for spec in emoji_inputs:
             cmd += spec
             asset = spec[-1]

package/scripts/grid.py

@@ -26,7 +26,7 @@ import os
 import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_font_file, default_output, die, emit, X264_PRESETS, fmt_secs, \
-    escape_drawtext, escape_filter_path, ffmpeg_base, info, probe, run, validate_color, video_args
+    escape_drawtext, escape_filter_path, ffmpeg_base, info, label_chain, matrix_chain, probe, run, validate_color, video_args
 
 LABEL_MARGIN = 10
 
@@ -91,6 +91,13 @@ def main() -> int:
     for p in args.inputs:
         cmd += ["-i", p]
 
+    # each cell converted by its own tags to the BT.709 the grid is tagged with (a BT.601 or an RGB
+    # input): without it 5.1/6.1 relabelled them, and 7.1+ converted cells to one another's matrix.
+    # Beside a converted cell an untagged one gets a BT.709 label, so 7.1+'s xstack has nothing to
+    # convert; a grid of untagged/BT.709 clips is what it was.
+    convert = [matrix_chain(m, None) for m in metas]
+    if any(convert):
+        convert = [c or label_chain(m, None) for c, m in zip(convert, metas)]
     parts = []
     for i, p in enumerate(args.inputs):
         chain = [
@@ -109,7 +116,7 @@ def main() -> int:
             chain.append(f"drawtext=text='{escape_drawtext(stem)}':{font_opt}:fontsize={args.font_size}:"
                          f"fontcolor={args.font_color}:x=w-tw-{LABEL_MARGIN}:y=h-th-{LABEL_MARGIN}:"
                          f"box=1:boxcolor=black@0.5:boxborderw=4")
-        parts.append(f"[{i}:v]{','.join(chain)}[v{i}]")
+        parts.append(f"[{i}:v]{convert[i]}{','.join(chain)}[v{i}]")
 
     cw, ch = args.cell_width + args.gap, args.cell_height + args.gap
     layout = "|".join(f"{c * cw}_{r * ch}" for r in range(args.rows) for c in range(args.cols))

package/scripts/insert.py

@@ -116,7 +116,9 @@ def main() -> int:
 
     output = args.output or default_output(args.input, "insert", "mp4")
     cmd = ffmpeg_base() + ["-loop", "1", "-i", args.input, "-t", f"{target:.3f}", "-vf", ",".join(vf)]
-    cmd += video_args(None, args.crf, args.preset)
+    # the SDR line, whatever the image is; its RGB (PNG) or BT.601 (JPEG) pixels are converted to
+    # the BT.709 that line is tagged with
+    cmd += video_args(None, args.crf, args.preset, source=meta)
     cmd += ["-an", output]
     run(cmd)
 

package/scripts/join.py

@@ -39,7 +39,7 @@ import os
 import sys
 from typing import Any, Dict, List, Optional, Tuple
 
-from _common import STATE, AUDIO_MEDIA_EXT, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
+from _common import STATE, AUDIO_MEDIA_EXT, matrix_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -497,7 +497,8 @@ def main() -> int:
     if len(set(chans)) > 1:
         info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
     for i in range(n):
-        parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
+        # a BT.601 clip is converted to the BT.709 the join is tagged with, each clip by its own tags
+        parts.append(f"[{i}:v]{matrix_chain(metas[i], hdr_meta or metas[0])}{geo},setsar=1,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
         parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]")
 
     # pad the shorter stream to the clip's length: the audio with silence, the picture by holding
@@ -541,7 +542,7 @@ def main() -> int:
     # to meet the AAC tail (a 51-frame dissolve came out 52), which newer builds no longer do -- pass
     # the frames through as built, for a plain cut as much as for a transition
     cmd += ["-fps_mode", "passthrough"]
-    cmd += video_args(hdr_meta or metas[0], args.crf, args.preset) + aac_args() + [output]
+    cmd += video_args(hdr_meta or metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + [output]
     run(cmd)
     expected = unpending_length(lens, d)
     r = probe(output, role="output")

package/scripts/multicam.py

@@ -31,7 +31,7 @@ import math
 import sys
 from typing import Dict, List, Tuple
 
-from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
+from _common import matrix_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from sync import measure_offset
 
 ENERGY_WINDOW_S = 0.25  # --switch energy: loudness measured over this window on the reference timeline
@@ -276,7 +276,8 @@ def main() -> int:
         if src_s < 0:
             info(f"warning: camera {c} has not started at reference {s:.2f}s; using camera 0 for that range")
             c, src_s, src_e = 0, s, e
-        parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts=PTS-STARTPTS,{geo}[v{i}]")
+        # each camera converted by its own colour tags to the BT.709 the cut is tagged with
+        parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts=PTS-STARTPTS,{matrix_chain(metas[c], metas[0])}{geo}[v{i}]")
         labels.append(f"[v{i}]")
         project_clips.append({"src": args.inputs[c], "in": round(src_s, 3), "out": round(src_e, 3)})
     parts.append("".join(labels) + f"concat=n={len(filled)}:v=1:a=0[vout]")
@@ -297,7 +298,7 @@ def main() -> int:
 
     output = args.output or default_output(args.inputs[0], "multicam", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + ["-t", f"{ref_dur:.3f}", output]
+    cmd += video_args(metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + ["-t", f"{ref_dur:.3f}", output]
 
     if args.write_project:
         # Same cut decision as the combined render above (project_clips was built alongside the

package/scripts/overlay.py

@@ -25,7 +25,7 @@ import sys
 from typing import List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
-from _common import STATE, script_font_for_text, drawtext_text_opts, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, script_font_for_text, drawtext_text_opts, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, label_chain, matrix_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 
 # Per-edge margins: a platform's UI does not cover the same fraction of every edge (TikTok's
 # like column is 14 % of the width, its description block 22 % of the height), so a position
@@ -266,7 +266,12 @@ def main() -> int:
             ov += f":enable='{enable}'"
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
-        fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
+        # the RGBA still is converted to the BT.709 the output is tagged with (overlay's own
+        # RGB-to-YUV step used BT.601), and an untagged main is labelled BT.709 (tags only) so
+        # 7.1+'s negotiation does not convert one picture to the other's "unknown" matrix
+        base = label_chain(meta, meta) if rgb_chain_to_bt709(meta) else ""
+        fc = (f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS{rgb_chain_to_bt709(meta)}[ov];"
+              + (f"[0:v]{base}null[base];[base]" if base else "[0:v]") + f"[ov]{ov}[out]")
         cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
             # An explicit -t is exact and, unlike -shortest, only bounds the *main* input's
@@ -299,7 +304,10 @@ def main() -> int:
         if enable:
             ov += f":enable='{enable}'"
         cmd = ffmpeg_base() + ["-i", args.input, "-i", args.video]
-        fc = f"[1:v]{','.join(chain)}[ov];[0:v][ov]{ov}[out]"
+        # both pictures converted by their own colour tags to the BT.709 the output is tagged with
+        base = matrix_chain(meta, meta)
+        fc = (f"[1:v]{matrix_chain(pip_meta, meta)}{','.join(chain)}[ov];"
+              + (f"[0:v]{base}null[base];[base]" if base else "[0:v]") + f"[ov]{ov}[out]")
         cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
             # See the --image branch above: -t (exact, bounds only the main input) instead of
@@ -329,7 +337,7 @@ def main() -> int:
         if meta.get("audio"):
             cmd += ["-map", f"0:a:{args.audio_stream}"]
 
-    cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
+    cmd += video_args(meta, args.crf, args.preset, convert_matrix=not args.video) + cfr_args(meta)
     cmd += aac_args() if meta.get("audio") else ["-an"]
     dropped_streams = run_keeping_subtitles(cmd, output)
     if not STATE.dry_run:

package/scripts/sequence.py

@@ -131,7 +131,8 @@ def main() -> int:
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", str(list_path)]
         vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={args.fps:g}"]
         cmd += ["-vf", ",".join(vf)]
-        cmd += video_args(None, args.crf, args.preset)
+        # RGB (PNG) frames are converted to the BT.709 the line is tagged with (the first frame's probe)
+        cmd += video_args(None, args.crf, args.preset, source=frame_meta)
         # The concat demuxer's trailing repeated-last-file trick (needed so the last real file's
         # duration line takes effect) has been observed to produce an extra frame's worth of
         # duration on some ffmpeg builds -- force the exact intended length rather than trust it.

package/scripts/waveform.py

@@ -36,7 +36,7 @@ import sys
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common import (add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base,
-                     info, load_brand, pad_filters, probe, run, STATE, validate_color, video_args, X264_PRESETS,
+                     info, load_brand, pad_filters, probe, rgb_chain_to_bt709, run, STATE, validate_color, video_args, X264_PRESETS,
                      fmt_secs, child_args, run_tool, measured_level_dbfs)
 from _common.emit import absorb_stage_hw
 
@@ -185,7 +185,9 @@ def main() -> int:
         graph = f"[1:v]{plate},format=rgba[plate];[0:a:{args.audio_stream}]{vf},format=rgba"
         if args.opacity < 1.0:
             graph += f",colorchannelmixer=aa={args.opacity:g}"
-        graph += f"[vis];[plate][vis]overlay=x=(W-w)/2:y={vis_y}:format=auto[v]"
+        # the composite is RGBA (the plate is): converted to the BT.709 the output is tagged with,
+        # not by the encoder's BT.601 default
+        graph += f"[vis];[plate][vis]overlay=x=(W-w)/2:y={vis_y}:format=auto{rgb_chain_to_bt709(None, 'yuv420p')}[v]"
         vf = graph
     else:
         # showwaves/showspectrum paint the visualization on a transparent-black canvas; composite