ffmpeg-skill 2.10.2 → 2.10.4

package/README.md

@@ -1,27 +1,34 @@
 <p align="center">
-  <img src="assets/logo.png" alt="FFmpeg Skill: media processing for AI agents" width="760">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/app-icon-dark.png">
+    <img src="brand/app-icon.png" width="128" alt="ffmpeg-skill app icon">
+  </picture>
 </p>
 
-<h1 align="center">ffmpeg-skill</h1>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/logo/ffmpeg-skill-wordmark-white.svg">
+    <img src="brand/logo/ffmpeg-skill-wordmark-black.svg" height="48" alt="ffmpeg-skill">
+  </picture>
+</p>
 
-<p align="center"><strong>Give your coding agent a video editor.</strong></p>
+<p align="center"><b>Give your coding agent a video editor.</b><br>
+Claude Code, Cursor, Codex or any MCP client edits your footage with local FFmpeg, then checks its own output.<br>
+No cloud · No API keys · Python standard library</p>
 
 <p align="center">
-  Local FFmpeg · No cloud · No API keys · Python standard library<br>
-  Claude Code · Cursor · Codex · MCP
+  <a href="#quick-start"><b>Quick start</b></a> ·
+  <a href="docs/demos.md">Demos</a> ·
+  <a href="#tools">Tools</a> ·
+  <a href="#mcp">MCP</a> ·
+  <a href="https://www.npmjs.com/package/ffmpeg-skill">npm</a>
 </p>
 
 <p align="center">
   <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml/badge.svg" alt="tests"></a>
-  <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
   <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/v/ffmpeg-skill" alt="npm"></a>
-  <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/dm/ffmpeg-skill" alt="npm downloads"></a>
-  <a href="https://github.com/kajisho5/ffmpeg-skill/stargazers"><img src="https://img.shields.io/github/stars/kajisho5/ffmpeg-skill" alt="GitHub stars"></a>
-  <a href="https://github.com/kajisho5/ffmpeg-skill/commits/main"><img src="https://img.shields.io/github/last-commit/kajisho5/ffmpeg-skill" alt="last commit"></a>
-  <img src="https://img.shields.io/badge/python-3.9%20%7C%203.13-blue" alt="Python 3.9 and 3.13 tested">
   <a href="#ffmpeg-compatibility"><img src="https://img.shields.io/badge/ffmpeg-5.1%20%7C%206.1%20%7C%207.1%20%7C%208%20%7C%209%20tested-orange" alt="FFmpeg 5.1, 6.1, 7.1, 8 and 9 tested in CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
-  <a href="https://github.com/sponsors/kajisho5"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors" alt="Sponsor"></a>
 </p>
 
 ```bash

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.2`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.4`) | 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.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.4", "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"},
@@ -225,7 +225,12 @@ source adds no filter, and the tags themselves never convert (`bt709_tag_args()`
 `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.
+FFmpeg 7.1+'s colourspace negotiation converts neither (`join`, `multicam`, `broll` and `overlay --video`
+too, beside a converted clip). A colour a tool draws from a hex or named value (a pad, `tpad` or
+`rotate` fill, `drawtext` and libass text and boxes, a `graphics.py` box or bar, `background.py`'s
+`color`/`gradients`, `waveform.py`'s plate and waves) lands in the same BT.709: from FFmpeg 7.1
+an untagged picture is labelled for the drawing filters, before 7.1 the drawing runs on an RGB copy
+and only the pixels it touched are taken from it (`_common.drawn_chain()`); a grey changes nothing.
 `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.2",
+  "version": "2.10.4",
   "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/ci-platform-pitfalls.md

@@ -162,6 +162,11 @@ these had ever shown up before.
   before measuring (40 dB for re-matrixed pixels), and it then flagged the fixed, byte-clean
   output as 26 dB instead. The tests' `_psnr` helper now pins identical colour tags on both
   inputs so every build reports the same number for the same two files.
+- **A test fixture drawn with `scale=out_color_matrix=bt709` is not untagged on 7.1+.** The scale
+  labels its output and x264 writes that label, so an "untagged" clip made that way probes as
+  `color_space=bt709` on the trixie/macOS/Windows jobs and the untagged case silently went untested
+  there (#333's colour fixtures until 2.10.3). Relabel the frames `setparams=colorspace=unknown`
+  before the encode, and assert the probe says unknown.
 - **The conda-forge 7.1.1 build deadlocks on `tpad` + `adelay`/`apad` (pad.py) and ignores
   SIGTERM.** Debian's 7.1.5 in CI does not. Run pad tests against CI, not that build, and note
   that the tools have no subprocess timeout to get an agent out of such a hang.

package/references/gotchas.md

@@ -14,7 +14,9 @@ by every re-encode (through 2.10.0 only the label changed); `color.py --retag bt
 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
+own tags. A colour the tools draw (pad and background colours, text, boxes, captions, waveform
+colours) is drawn in BT.709 too; through 2.10.2 it was BT.601 under the BT.709 tag (pure red
+showed as (255,24,0)). 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/scripts/_ass_overlay.py

@@ -110,7 +110,9 @@ def text_overlay_ass(elements: Sequence[Dict[str, Any]], *, play_w: int, play_h:
     """Write `elements` as an ASS file at `path` and return the path."""
     header = [
         "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}",
-        "WrapStyle: 2", "ScaledBorderAndShadow: yes", "",
+        # YCbCr Matrix: None -- the colours are RGB, to be put in the video's own matrix: FFmpeg 8.x's
+        # ass filter reads an absent header as BT.601 whatever the picture is tagged (drawn_chain)
+        "WrapStyle: 2", "ScaledBorderAndShadow: yes", "YCbCr Matrix: None", "",
         "[V4+ Styles]",
         "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, "
         "BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, "

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, label_chain, matrix_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
+    signed_time_arg, source_codec_video_args, drawn_chain, draws_chroma, 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,8 +91,8 @@ from _common.asr import (
     whisper_word_timings, write_srt
 )
 from _common.color import (
-    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
+    bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, color_hex, _COLOR_TOKEN_RE, drawn_stream_format, fold_bt709_matrix,
+    is_neutral_color, is_rgb, NON_BT709_MATRICES, rgb_island, 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,
@@ -213,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", "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",
+    "source_codec_video_args", "drawn_chain", "draws_chroma", "drawn_stream_format", "is_neutral_color", "rgb_island", "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

@@ -123,6 +123,75 @@ def bt709_label_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
     return "setparams=colorspace=bt709" + ("" if v.get("color_range") == "pc" else ":range=tv")
 
 
+# FFmpeg's named colours that are greys (libavutil/parseutils.c's table): R = G = B.
+_GREY_NAMES = frozenset(("black", "white", "gray", "grey", "silver", "darkgray", "darkgrey", "dimgray", "dimgrey",
+                         "gainsboro", "lightgray", "lightgrey", "whitesmoke"))
+
+
+def _yuv8(rgb: Sequence[int], kr: float, kb: float) -> "Tuple[int, int, int]":
+    """8-bit limited-range YUV of an RGB colour under the matrix (kr, kb), rounded as FFmpeg's
+    drawing code rounds it (ff_draw_color)."""
+    r, g, b = (c / 255 for c in rgb)
+    y = kr * r + (1 - kr - kb) * g + kb * b
+    return (int(16 + 219 * y + 0.5), int(128 + 224 * (b - y) / (2 * (1 - kb)) + 0.5),
+            int(128 + 224 * (r - y) / (2 * (1 - kr)) + 0.5))
+
+
+def is_neutral_color(value: Any) -> bool:
+    """True for a colour whose 8-bit YUV is the same under BT.601 and BT.709, however translucent: a
+    grey (R = G = B; black and white included), or one so near grey that both round to the same
+    bytes (graphics.py's default background 101418). Only another colour lands differently, so only
+    it needs drawn_chain(). A name counts only if it is one of FFmpeg's greys; anything else
+    (`red`, `random`) is not neutral."""
+    v = str(value or "").strip().split("@")[0].lower()
+    if v in _GREY_NAMES:
+        return True
+    v = v[1:] if v.startswith("#") else v[2:] if v.startswith("0x") else v
+    if re.fullmatch(r"[0-9a-f]{6}(?:[0-9a-f]{2})?", v):
+        rgb = (int(v[0:2], 16), int(v[2:4], 16), int(v[4:6], 16))
+        return _yuv8(rgb, 0.299, 0.114) == _yuv8(rgb, 0.2126, 0.0722)
+    return False
+
+
+def drawn_stream_format(meta: Optional[Dict[str, Any]]) -> "Tuple[str, bool]":
+    """(pix_fmt, full range) of the picture a tool draws on, for rgb_island(): the probed source's own
+    8-bit planar YUV format (an RGB source has become yuv444p, BT.709 limited, through
+    bt709_matrix_filter), or yuv420p for anything else (the format the encoder line takes it to)."""
+    v = (meta or {}).get("video") or {}
+    if is_rgb(meta):
+        return "yuv444p", False
+    pf = str(v.get("pix_fmt") or "yuv420p")
+    full = pf.startswith("yuvj") or v.get("color_range") == "pc"
+    if pf not in ("yuv420p", "yuv422p", "yuv444p", "yuvj420p", "yuvj422p", "yuvj444p"):
+        pf = "yuv420p"
+    return pf, full
+
+
+def rgb_island(colour_chain: str, neutral_chain: str = "null", pix_fmt: str = "yuv420p", full: bool = False,
+               tag: str = "d") -> str:
+    """`colour_chain` (filters that draw a colour: drawtext, pad, tpad, rotate's fill, libass) run on
+    an RGB copy of the picture, as one simple filtergraph (one input, one output; `tag` keeps its
+    labels unique in a bigger graph). For FFmpeg < 7.1, whose drawing filters turn every colour into
+    YUV with BT.601 whatever the picture is tagged (`ff_draw_init`), and drawbox on every version:
+    in RGB a colour is written as it is, and the copy goes back to YUV with BT.709.
+
+    Only the pixels the drawing touched come from that copy. The same round trip without the colour
+    (`neutral_chain`: `null`, or the same pad/tpad/rotate with a black fill, which is the same under
+    every matrix) is compared with it plane by plane, and maskedmerge takes the drawn copy where
+    the two differ and the untouched picture (`neutral_chain` on the YUV itself) everywhere else:
+    the RGB round trip is not lossless, so a picture that only passes through keeps its pixels."""
+    rng = "pc" if full else "tv"
+    to_rgb = f"scale=in_color_matrix=bt709:in_range={rng},format=rgb24"
+    to_yuv = f"scale=out_color_matrix=bt709:out_range={rng},format={pix_fmt}"
+    keep = "'255*gt(val,0)'"
+    t = f"_{tag}"
+    return (f"split=3[{t}p][{t}c][{t}n];[{t}p]format={pix_fmt},{neutral_chain}[{t}p1];"
+            f"[{t}c]{to_rgb},{colour_chain},{to_yuv},split[{t}c1][{t}c2];"
+            f"[{t}n]{to_rgb},{neutral_chain},{to_yuv}[{t}n1];"
+            f"[{t}c1][{t}n1]blend=all_mode=difference,lut=c0={keep}:c1={keep}:c2={keep}[{t}m];"
+            f"[{t}p1][{t}c2][{t}m]maskedmerge")
+
+
 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 [].
 

package/scripts/_common/decision.py

@@ -14,12 +14,14 @@ import argparse
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
-from _common.color import bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, rgb_to_bt709_filter, _sdr_bt709
+from _common.color import (bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
+                           is_neutral_color, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
 from _common.emit import die
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_version, hw_platform_reason
 
 
-def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0) -> str:
+def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0,
+                meta: Optional[Dict[str, Any]] = None) -> str:
     """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
 
     fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
@@ -30,7 +32,10 @@ def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken
     needed beyond the usual scale/pad set, and that is already required by redact.py.
     `darken` > 0 also dims that background copy by that much brightness (eq), so the picture in
     front reads as the subject instead of competing with a bright blurred copy of itself --
-    what `fit.py --fit blur` uses (1.14)."""
+    what `fit.py --fit blur` uses (1.14).
+    `meta`: the probe of the picture being padded, when the output is that picture's re-encode: a
+    --pad-color with chroma is then drawn in the BT.709 the line tags (drawn_chain()). Without it
+    (a still made RGB, an export to GIF) the pad is what it always was."""
     if fill == "blur":
         # boxblur rejects a radius larger than half the smaller dimension ("radius 20, must be
         # <= 8" on a 16 px target); clamp instead of failing an otherwise valid request
@@ -40,7 +45,9 @@ def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken
                 f"boxblur={radius}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
                 f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
                 f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
-    return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"
+    pad = f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color="
+    return (f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,"
+            + (pad + color if meta is None else drawn_chain(pad + color, meta, [color], pad + "black", tag="pad")))
 
 
 def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
@@ -574,6 +581,39 @@ def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva
     return "," + rgb_to_bt709_filter(pix_fmt)
 
 
+def draws_chroma(colours: Sequence[Any], line_meta: Optional[Dict[str, Any]]) -> bool:
+    """True when one of `colours` has chroma (is_neutral_color) and the line video_args(line_meta)
+    tags the output BT.709 -- when a drawn colour needs drawn_chain() at all."""
+    return (not all(is_neutral_color(c) for c in colours if c is not None) and STATE.codec != "prores"
+            and not ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"))
+
+
+def drawn_chain(colour_chain: str, meta: Optional[Dict[str, Any]], colours: Sequence[Any], neutral_chain: str = "null",
+                line_meta: Any = "same", tag: str = "d", labelled: bool = False) -> str:
+    """`colour_chain` -- filters that draw a colour into the picture `meta` probes (drawtext's
+    font/box/border colours, pad/tpad's fill, rotate's fillcolor, libass) -- so that a colour of
+    `colours` lands in the BT.709 the line video_args(line_meta) tags the output with (line_meta
+    defaults to meta).
+
+    FFmpeg's drawing filters turn an RGB colour into YUV with a matrix of their own (ff_draw):
+    BT.601 always up to 7.0, the link's colourspace from 7.1 on, "unknown" read as BT.601. Through
+    2.10.2 a drawn colour was BT.601 under a BT.709 tag on every build (pure red decoded as
+    (255,24,0)), and on 5.1/6.1 for a BT.709-tagged source too. From 7.1 an untagged picture gets
+    its BT.709 label (label_chain(): tags only) and the filters follow it; before 7.1 the drawing
+    runs in RGB (rgb_island(), `neutral_chain` being the same filters with a black fill, or null).
+
+    Unchanged: a chain whose colours are all greys (the same YUV under every matrix: the default
+    black pads and white text), a line that does not tag BT.709 (HDR, prores). `labelled`: the
+    caller's graph already labels this picture (label_chain()) earlier in the same chain."""
+    line = meta if line_meta == "same" else line_meta
+    if not draws_chroma(colours, line):
+        return colour_chain
+    if ffmpeg_version() >= (7, 1):
+        return ("" if labelled else label_chain(meta, line)) + colour_chain
+    pix_fmt, full = drawn_stream_format(meta)
+    return rgb_island(colour_chain, neutral_chain, pix_fmt, full, tag)
+
+
 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

package/scripts/background.py

@@ -14,7 +14,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, parse_time, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
 def main() -> int:
@@ -61,9 +61,16 @@ def main() -> int:
         # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
         # motionless the filter allows.
         src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}:seed=0:speed=1e-05"
+        colours = [c0, c1]
     else:
         validate_color(args.color, "--color")
         src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"
+        colours = [args.color]
+    if draws_chroma(colours, None):
+        # the colours are made in RGB and converted to the BT.709 the output is tagged with: left to
+        # the encoder line's own conversion (or `color`'s YUV), they were BT.601 under that tag
+        # (pure red decoded as (255,24,0)); a grey is the same under every matrix
+        src_filter += (",format=rgb24" if not args.gradient else "") + rgb_chain_to_bt709(None, "yuv420p")
 
     output = args.output
     cmd = ffmpeg_base() + ["-f", "lavfi", "-i", src_filter, "-t", f"{target:.3f}"]

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, matrix_chain, 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, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 
 
 def main() -> int:
@@ -101,14 +101,22 @@ 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]")
+    # every clip is converted by its own colour tags to the BT.709 the output is tagged with; beside
+    # a converted clip (or under a --pad-color with chroma) an untagged one gets its BT.709 label,
+    # tags only, so 7.1+'s overlay and pad have nothing to convert or misread
+    convert = [matrix_chain(m, meta_a) for m in [meta_a] + [c["meta"] for c in cutaways]]
+    if any(convert) or draws_chroma([args.pad_color], meta_a):
+        convert = [cv or label_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
+    if convert[0]:
+        parts.append(f"[0:v]{convert[0]}null[a709]")
         cur = "[a709]"
+    pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
     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}"
+        geo = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+               + drawn_chain(pad + args.pad_color, c["meta"], [args.pad_color], pad + "black", line_meta=meta_a,
+                             tag=f"pad{i}", labelled=True))
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     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}]")
+                     f"{convert[i + 1]}{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

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, 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
+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, drawn_chain, 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
@@ -633,7 +633,9 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
     # jump every time the highlight advances (the trap the issue this implements is filed against).
     header = [
         "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}",
-        f"WrapStyle: {2 if word_style else 0}", "ScaledBorderAndShadow: yes", "",
+        # YCbCr Matrix: None -- the colours are RGB, to be put in the video's own matrix: FFmpeg 8.x's
+        # ass filter reads an absent header as BT.601 whatever the picture is tagged (drawn_chain)
+        f"WrapStyle: {2 if word_style else 0}", "ScaledBorderAndShadow: yes", "YCbCr Matrix: None", "",
         "[V4+ Styles]",
         "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
         f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin_l},{margin_r},{margin},1",
@@ -1560,6 +1562,12 @@ def main() -> int:
         vf = f"subtitles={escape_filter_path(srt_path)}:force_style='{force}'"
         if args.fonts_dir:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
+    if generated_ass or not args.ass:
+        # a text/outline/karaoke colour with chroma lands in the BT.709 the output is tagged with
+        # (drawn_chain). A caller's own --ass is burned as libass and FFmpeg read it: its colours,
+        # and its YCbCr Matrix header, are the file's.
+        vf = drawn_chain(vf, meta, [args.color, args.outline_color]
+                         + ([args.highlight_color, args.upcoming_color] if args.karaoke else []))
 
     cmd = ffmpeg_base() + ["-i", args.input]
     chains, emoji_inputs = (emoji_filter_chain(emoji_plan or {}, "vsub", "vout", to_yuv=rgb_chain_to_bt709(meta),

package/scripts/export.py

@@ -165,7 +165,10 @@ def main() -> int:
             if args.fit == "crop":
                 vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=increase", f"crop={p['w']}:{p['h']}"]
             else:
-                vf.append(pad_filters(p["w"], p["h"], args.pad_fill, args.pad_color, args.pad_blur))
+                # a --pad-color with chroma is drawn in the BT.709 the line is tagged with; a GIF is
+                # not tagged, and palettegen reads the pad back with the same BT.601 it was drawn in
+                vf.append(pad_filters(p["w"], p["h"], args.pad_fill, args.pad_color, args.pad_blur,
+                                      meta=None if args.preset == "gif" else meta))
             vf.append("setsar=1")
         else:
             vf.append(f"scale={p['w']}:-2")

package/scripts/fit.py

@@ -202,7 +202,7 @@ def main() -> int:
                      "run color.py --to-sdr first for the SDR look")
             vf.append(pad_filters(out_w, out_h, "blur", args.pad_color, args.pad_blur, darken))
         else:
-            vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur))
+            vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur, meta=meta))
         vf.append("setsar=1")
 
     if args.fps:

package/scripts/graphics.py

@@ -33,7 +33,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,
+                     color_hex, default_font_file, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
                      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,
@@ -42,6 +42,9 @@ from _common import (aac_args, add_common, brand_caption_style, script_font_for_
                      SAFE_WIDTH_FRACTION)
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 
+# where the template's text chain goes in a filter_complex it builds (graphics.main fills it in)
+TEXT = "@TEXT@"
+BOX = "@BOX@"  # a box's place in the filter chain, followed by its index (graphics.main fill_box)
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug", "sticker", "hook", "meme"]
 
 
@@ -185,6 +188,35 @@ def main() -> int:
     en = f"enable='between(t,{s:.3f},{e:.3f})'"
     base = min(W, H) * args.scale  # scale everything from the short side
     filters: List[str] = []
+    rate = f"{meta['video'].get('fps') or 30:g}"
+    # A drawn colour lands in the BT.709 the output is tagged with. When a template's box has
+    # chroma, its boxes are colour sources made in RGB and converted (rgb_chain_to_bt709), overlaid
+    # under the text, in order: drawbox turns its colour into YUV with BT.601 on every FFmpeg (and
+    # blends 4:2:0 chroma four times over, so a translucent box was nearly opaque in colour). A
+    # template whose boxes are all grey keeps its drawboxes, which are the same under every matrix.
+    # The text (drawtext, libass) goes through drawn_chain() at the end.
+    boxes: List[tuple] = []  # (colour, alpha, drawbox geometry, x, y, w, h, enable, x_expr), in order
+    layers: List[tuple] = []  # (colour source chain, overlay position and enable), under the text
+    converted: List[str] = []  # the colour sources layer_src() converted
+
+    def fill_box(colour: str, alpha: float, drawbox_geo: str, x: int, y: int, w: int, h: int, enable: str,
+                 x_expr: Optional[str] = None) -> None:
+        """A filled box: a drawbox (`drawbox_geo`) at its place in the filter chain, or a colour layer
+        of w x h at x, y (or at the per-frame `x_expr`) -- decided for all of a template's boxes."""
+        filters.append(f"{BOX}{len(boxes)}")
+        boxes.append((colour, alpha, drawbox_geo, x, y, w, h, enable, x_expr))
+
+    def layer_src(colour: str, alpha: float, w: int, h: int, left: int = 0, top: int = 0) -> str:
+        """A colour source to overlay (a box, the lower-third bar, the progress fill), converted when it
+        has chroma. overlay places a 4:2:0 picture on even rows and columns only: a box that starts on
+        an odd one is placed one earlier with a transparent first column/row (`left`, `top`), so it
+        covers the rows and columns the drawbox did."""
+        conv = rgb_chain_to_bt709(meta) if draws_chroma([colour], meta) else ""
+        if conv:
+            converted.append(colour)
+        edge = f",pad={w + left}:{h + top}:{left}:{top}:color=black@0" if left or top else ""
+        return (f"color=c=0x{colour}" + (f"@{alpha:g}" if alpha < 1 else "") + f":s={w}x{h}:r={rate},format=rgba"
+                + edge + conv)
     fade_a = f"if(lt(t,{s:.3f}+0.3),(t-{s:.3f})/0.3,if(gt(t,{e:.3f}-0.3),({e:.3f}-t)/0.3,1))"
 
     # --- which renderer draws the text (1.15) --------------------------------------------------
@@ -333,8 +365,8 @@ def main() -> int:
         y0 = H - m_bottom - bar_h
         # slide in from the left over 0.4 s, slide out over 0.3 s (overlay evaluates x per frame)
         x_expr = f"if(lt(t,{s:.3f}+0.4),-{bar_w}+({bar_w}+{m_left})*((t-{s:.3f})/0.4),if(gt(t,{e:.3f}-0.3),{m_left}-({bar_w}+{m_left})*(1-({e:.3f}-t)/0.3),{m_left}))"
-        fc.append(f"color=c=0x{bg}@0.85:s={bar_w}x{bar_h}:r={meta['video'].get('fps') or 30:g},format=rgba[bar]")
-        fc.append(f"color=c=0x{primary}:s={int(base * 0.012)}x{bar_h}:r={meta['video'].get('fps') or 30:g},format=rgba[acc]")
+        fc.append(f"{layer_src(bg, 0.85, bar_w, bar_h)}[bar]")
+        fc.append(f"{layer_src(primary, 1.0, int(base * 0.012), bar_h)}[acc]")
         fc.append(f"[0:v][bar]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v1]")
         fc.append(f"[v1][acc]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v2]")
         tx_pad = int(base * 0.035)
@@ -361,14 +393,16 @@ def main() -> int:
                                      align=7, x=x_rest, y=ty, outline=max(1.0, fs / 16.0),
                                      outline_color="000000", start=max(s, e - 0.3), end=e,
                                      move=(x_rest, ty, x_off, ty, 0, 300), x_expr=tx))
-        fc.append(f"[v2]{','.join(draws)}[vout]" if route != "ass" else "[v2]null[vout]")
+        fc.append(f"[v2]{TEXT}[vout]" if route != "ass" else "[v2]null[vout]")
+        if route != "ass":
+            filters.extend(draws)  # the text chain, which drawn_chain() places at TEXT
 
     elif args.template == "title":
         if not args.title:
             die("title needs --title")
         h1 = int(base * 0.11)
         h2 = int(base * 0.045)
-        filters.append(f"drawbox=x=0:y=0:w=iw:h=ih:color={ff_color(bg, 0.55)}:t=fill:{en}")
+        fill_box(bg, 0.55, "x=0:y=0:w=iw:h=ih", 0, 0, W, H, en)
         # the title is centred as a block, so the bar and the subtitle sit below its last line:
         # `title_h` is the block's height, as the one-line layout has always taken h1; a further
         # subtitle line hangs below the first, whose position the one-line layout fixes
@@ -380,7 +414,9 @@ def main() -> int:
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2,
                  y=H / 2 - (h2 if args.subtitle else 0), outline=max(1.0, h1 / 20.0),
                  outline_color="000000", start=s, end=e, fade=(300, 300))
-        filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{title_h // 2}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
+        acc_w, acc_h = int(base * 0.12), max(2, int(base * 0.006))
+        fill_box(primary, 1.0, f"x=(iw-{acc_w})/2:y=(ih)/2+{title_h // 2}:w={acc_w}:h={acc_h}",
+                 (W - acc_w) // 2, H // 2 + title_h // 2, acc_w, acc_h, en)
         if args.subtitle:
             add_text(args.subtitle,
                      f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{sub_y + sub_extra // 2}:alpha='{fade_a}':{en}",
@@ -412,8 +448,12 @@ def main() -> int:
     elif args.template == "progress":
         h = max(3, int(base * 0.008))
         fps = meta['video'].get('fps') or 30
-        fc.append(f"color=c=0x{primary}:s={W}x{h}:r={fps:g},format=rgba[pb]")
-        fc.append(f"[0:v]drawbox=x=0:y=ih-{h}:w=iw:h={h}:color={ff_color(bg, 0.5)}:t=fill:{en}[v1]")
+        fc.append(f"{layer_src(primary, 1.0, W, h)}[pb]")
+        if draws_chroma([bg], meta):
+            fc.append(f"{layer_src(bg, 0.5, W, h, 0, (H - h) % 2)}[pbg]")
+            fc.append(f"[0:v][pbg]overlay=x=0:y={(H - h) // 2 * 2}:{en}:eof_action=pass[v1]")
+        else:
+            fc.append(f"[0:v]drawbox=x=0:y=ih-{h}:w=iw:h={h}:color={ff_color(bg, 0.5)}:t=fill:{en}[v1]")
         fc.append(f"[v1][pb]overlay=x='-w+w*min(1,max(0,(t-{s:.3f})/{e - s:.3f}))':y={H - h}:{en}:eof_action=pass[vout]")
 
     elif args.template == "sticker":
@@ -465,14 +505,15 @@ def main() -> int:
         # drawing white text on the bare video. The band is clipped at the frame edges.
         band_h = min(H, max(int(base * 0.30), block_h(hook_title, h1) + int(h1 * 0.7)))
         y0 = (H - band_h) // 2
-        filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
+        fill_box(bg, 0.78, f"x=0:y={y0}:w=iw:h={band_h}", 0, y0, W, band_h, hen)
         add_text(hook_title,
                  f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}"
                  f"{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2, y=H / 2,
                  outline=max(1.0, h1 / 20.0), outline_color="000000", start=s, end=he)
-        filters.append(f"drawbox=x=0:y=0:w='iw*max(0,1-(t-{s:.3f})/{max(0.001, he - s):.3f})':h={bar_h}:"
-                       f"color={ff_color(primary)}:t=fill:{hen}")
+        # the bar empties from the right: the overlay slides a full-width bar out to the left
+        fill_box(primary, 1.0, f"x=0:y=0:w='iw*max(0,1-(t-{s:.3f})/{max(0.001, he - s):.3f})':h={bar_h}", 0, 0, W, bar_h,
+                 hen, x_expr=f"'-W*min(1,max(0,(t-{s:.3f})/{max(0.001, he - s):.3f}))'")
 
     elif args.template == "meme":
         # The classic layout: heavy white upper-case lines with a black outline, top and bottom,
@@ -588,15 +629,42 @@ def main() -> int:
                         "clusters": sorted({emoji_codepoint_name(cl) for _i, cl in emoji_clusters(all_text)}),
                         "assets": emoji_assets, "missing": [], "overlays": 0}
 
+    # The boxes with chroma (layers) go under the text, and the picture they and a converted colour
+    # source are overlaid on gets its BT.709 label (an untagged one, tags only), so 7.1+'s overlay
+    # converts neither picture to the other's matrix. The text is drawn in BT.709 (drawn_chain).
+    as_layers = any(draws_chroma([b[0]], meta) for b in boxes)
+    drawboxes = []
+    for colour, alpha, geo, x, y, w, h, enable, x_expr in boxes:
+        if as_layers:
+            layers.append((layer_src(colour, alpha, w, h, x % 2, y % 2), f"x={x_expr or x - x % 2}:y={y - y % 2}:{enable}"))
+        drawboxes.append(f"drawbox={geo}:color={ff_color(colour, alpha)}:t=fill:{enable}")
+    filters = [("" if as_layers else drawboxes[int(f[len(BOX):])]) if f.startswith(BOX) else f for f in filters]
+    filters = [f for f in filters if f]
+    base_label = label_chain(meta, meta) if (layers or converted) else ""
+    text = (drawn_chain(",".join(filters), meta, re.findall(r"color=([0-9A-Za-z#@.]+)", ",".join(filters)),
+                        labelled=bool(base_label)) if filters else "")
+    if layers:
+        cur = "0:v"
+        for k, (src, pos) in enumerate(layers):
+            fc.append(f"{src}[gl{k}]")
+            fc.append(f"[{cur}][gl{k}]overlay={pos}:eof_action=pass[gv{k}]")
+            cur = f"gv{k}"
+        fc.append(f"[{cur}]{TEXT}[vout]")
+    fc = [c.replace(TEXT, text or "null") for c in fc]
+    if fc and base_label:
+        fc = [f"[0:v]{base_label}null[gbase]"] + [c.replace("[0:v]", "[gbase]") for c in fc]
+
     cmd = ffmpeg_base() + ["-i", args.input]
     if route == "ass" or emoji_overlays:
-        chains = list(fc) if fc else [f"[0:v]{','.join(filters) if filters else 'null'}[vout]"]
+        chains = list(fc) if fc else [f"[0:v]{text or 'null'}[vout]"]
         last = "vout"
         if route == "ass":
             vf = f"ass={escape_filter_path(ass_path)}"
             fdir = ass_fonts_dir()
             if fdir:
                 vf += f":fontsdir={escape_filter_path(fdir)}"
+            vf = drawn_chain(vf, meta, [el.get(k) for el in elements for k in ("color", "outline_color", "box_color")],
+                             labelled=bool(base_label))
             chains.append(f"[{last}]{vf}[vtxt]")
             last = "vtxt"
         eo, emoji_inputs = emoji_filter_chain({"overlays": emoji_overlays}, last, "vfinal", first_input=1,
@@ -615,7 +683,7 @@ def main() -> int:
     elif fc:
         cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", f"0:a:{args.audio_stream}?"]
     else:
-        cmd += ["-vf", ",".join(filters), "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
+        cmd += ["-vf", text, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
     cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += aac_args() if meta.get("audio") else ["-an"]
     dropped_streams = run_keeping_subtitles(cmd, output)

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, label_chain, matrix_chain, probe, run, validate_color, video_args
+    draws_chroma, drawn_chain, escape_drawtext, escape_filter_path, ffmpeg_base, info, label_chain, matrix_chain, probe, run, validate_color, video_args
 
 LABEL_MARGIN = 10
 
@@ -95,28 +95,39 @@ def main() -> int:
     # 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.
+    # A --background or --font-color with chroma is drawn in the BT.709 the grid is tagged with
+    # (drawn_chain): every untagged cell is labelled for it too, and the gaps are each cell's own
+    # pad instead of xstack's fill, which 5.1/6.1 draw in BT.601 (a grey needs neither).
+    colours = [args.background] + ([args.font_color] if args.label == "auto" else [])
+    chroma = draws_chroma(colours, None)
     convert = [matrix_chain(m, None) for m in metas]
-    if any(convert):
+    if any(convert) or chroma:
         convert = [c or label_chain(m, None) for c, m in zip(convert, metas)]
     parts = []
     for i, p in enumerate(args.inputs):
-        chain = [
-            f"fps={args.fps:g}",
-            f"scale={args.cell_width}:{args.cell_height}:force_original_aspect_ratio=decrease",
-            f"pad={args.cell_width}:{args.cell_height}:(ow-iw)/2:(oh-ih)/2:color={args.background}",
-            "setsar=1",
+        drawn = [  # (with this colour, with black)
+            (f"pad={args.cell_width}:{args.cell_height}:(ow-iw)/2:(oh-ih)/2:color={args.background}",
+             f"pad={args.cell_width}:{args.cell_height}:(ow-iw)/2:(oh-ih)/2:color=black"),
+            ("setsar=1",) * 2,
         ]
         if args.pad and durations[i] < target_duration:
-            chain.append(f"tpad=stop_mode=clone:stop_duration={target_duration - durations[i]:.3f}")
+            drawn.append((f"tpad=stop_mode=clone:stop_duration={target_duration - durations[i]:.3f}",) * 2)
         elif not args.pad:
-            chain.append(f"trim=duration={target_duration:.3f}")
+            drawn.append((f"trim=duration={target_duration:.3f}",) * 2)
         if args.label == "auto":
             stem = os.path.splitext(os.path.basename(p))[0]
             font_opt = f"fontfile={escape_filter_path(font_file)}" if font_file else f"font='{escape_drawtext(args.font)}'"
-            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]{convert[i]}{','.join(chain)}[v{i}]")
+            drawn.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", "null"))
+        gap_r = args.gap if i % args.cols < args.cols - 1 else 0
+        gap_b = args.gap if i // args.cols < args.rows - 1 else 0
+        if chroma and (gap_r or gap_b):
+            drawn.append((f"pad=iw+{gap_r}:ih+{gap_b}:0:0:color={args.background}", f"pad=iw+{gap_r}:ih+{gap_b}:0:0:color=black"))
+        chain = f"fps={args.fps:g},scale={args.cell_width}:{args.cell_height}:force_original_aspect_ratio=decrease,"
+        chain += drawn_chain(",".join(c for c, _n in drawn), metas[i], colours, ",".join(n for _c, n in drawn),
+                             line_meta=None, tag=f"c{i}", labelled=True)
+        parts.append(f"[{i}:v]{convert[i]}{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/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, 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
+from _common import STATE, AUDIO_MEDIA_EXT, draws_chroma, drawn_chain, label_chain, 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"]
@@ -478,14 +478,26 @@ def main() -> int:
             added += 1
     cmd += extra_inputs
 
-    if args.fit == "crop":
-        geo = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
-    else:
-        geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
     # Any HDR input makes the join HDR (10-bit, HEVC via video_args on that clip's tags): an SDR
     # first clip used to drag an HDR second clip down to 8-bit without a tone map.
     hdr_meta = next((m for m in metas if (m.get("video") or {}).get("bt2020_or_hdr")), None)
     pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
+    line = hdr_meta or metas[0]
+    # a BT.601 or RGB clip is converted to the BT.709 the join is tagged with, each clip by its own
+    # tags; beside a converted clip (or under a --pad-color with chroma) an untagged one gets its
+    # BT.709 label, tags only, so 7.1+'s concat/xfade and pad have nothing to convert or misread
+    convert = [matrix_chain(m, line) for m in metas]
+    chroma_pad = args.fit != "crop" and draws_chroma([args.pad_color], line)
+    if any(convert) or chroma_pad:
+        convert = [c or label_chain(m, line) for c, m in zip(convert, metas)]
+
+    def geo(i: int) -> str:
+        if args.fit == "crop":
+            return f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
+        pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
+        return (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+                + drawn_chain(pad + args.pad_color, metas[i], [args.pad_color], pad + "black", line_meta=line,
+                              tag=f"pad{i}", labelled=True))
     # the audio-only join keeps the widest layout; the video join used to force stereo and
     # silently dropped the centre/LFE of 5.1 material. A pending input's stub has no measured
     # layout: plan from the inputs that exist, as join_audio() does.
@@ -497,8 +509,7 @@ 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):
-        # 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"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,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

package/scripts/multicam.py

@@ -31,7 +31,7 @@ import math
 import sys
 from typing import Dict, List, Tuple
 
-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 _common import label_chain, 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
@@ -269,6 +269,12 @@ def main() -> int:
     parts: List[str] = []
     labels: List[str] = []
     project_clips: List[Dict] = []
+    # each camera converted by its own colour tags to the BT.709 the cut is tagged with; beside a
+    # converted camera an untagged one gets its BT.709 label, tags only, so 7.1+'s concat does not
+    # convert one to the other's "unknown" (BT.601) matrix
+    convert = [matrix_chain(m, metas[0]) for m in metas]
+    if any(convert):
+        convert = [c or label_chain(m, metas[0]) for c, m in zip(convert, metas)]
     for i, (s, e, c) in enumerate(filled):
         # reference time t maps to source time (t - offset_c) * ratio_c
         src_s = (s - offsets[c]) * ratios[c]
@@ -276,8 +282,7 @@ 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
-        # 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}]")
+        parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts=PTS-STARTPTS,{convert[c]}{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]")

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, 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
+from _common import STATE, script_font_for_text, drawtext_text_opts, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, 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
@@ -304,9 +304,13 @@ def main() -> int:
         if enable:
             ov += f":enable='{enable}'"
         cmd = ffmpeg_base() + ["-i", args.input, "-i", args.video]
-        # 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];"
+        # both pictures converted by their own colour tags to the BT.709 the output is tagged with;
+        # beside a converted one an untagged one gets its BT.709 label, tags only, so 7.1+'s
+        # overlay does not convert one to the other's "unknown" (BT.601) matrix
+        base, pip = matrix_chain(meta, meta), matrix_chain(pip_meta, meta)
+        if base or pip:
+            base, pip = base or label_chain(meta, meta), pip or label_chain(pip_meta, meta)
+        fc = (f"[1:v]{pip}{','.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"):
@@ -333,7 +337,9 @@ def main() -> int:
             opts += ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"]
         if enable:
             opts.append(f"enable='{enable}'")
-        cmd += ["-vf", "drawtext=" + ":".join(opts), "-map", "0:v:0"]
+        # a font/border/box colour with chroma lands in the BT.709 the output is tagged with
+        colours = [args.font_color] + ([args.border_color] if args.border else []) + ([args.box_color] if args.box else [])
+        cmd += ["-vf", drawn_chain("drawtext=" + ":".join(opts), meta, colours), "-map", "0:v:0"]
         if meta.get("audio"):
             cmd += ["-map", f"0:a:{args.audio_stream}"]
 

package/scripts/pad.py

@@ -16,7 +16,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
 
 
 def main() -> int:
@@ -46,7 +46,10 @@ def main() -> int:
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, "pad")
 
-    vf = f"tpad=start_duration={args.start:.3f}:stop_duration={args.end:.3f}:color={args.color}"
+    tpad = f"tpad=start_duration={args.start:.3f}:stop_duration={args.end:.3f}:color="
+    # a --color with chroma lands in the BT.709 the output is tagged with (tpad's own YUV is BT.601
+    # before FFmpeg 7.1, and for an untagged picture after it); black is the same under every matrix
+    vf = drawn_chain(tpad + args.color, meta, [args.color], tpad + "black")
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
     if has_audio:
         af = f"adelay={int(args.start * 1000)}:all=1,apad=pad_dur={args.end:.3f}"

package/scripts/straighten.py

@@ -22,7 +22,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, fmt_secs
 
 
 def main() -> int:
@@ -63,8 +63,10 @@ def main() -> int:
 
     radians = math.radians(args.degrees)
     if args.fit == "pad":
-        rotate = (f"rotate={radians:.8f}:fillcolor={args.fill_color}:"
-                  f"ow=trunc(rotw({radians:.8f})/2)*2:oh=trunc(roth({radians:.8f})/2)*2")
+        geometry = f"ow=trunc(rotw({radians:.8f})/2)*2:oh=trunc(roth({radians:.8f})/2)*2"
+        # a --fill-color with chroma lands in the BT.709 the output is tagged with (drawn_chain)
+        rotate = drawn_chain(f"rotate={radians:.8f}:fillcolor={args.fill_color}:{geometry}", meta, [args.fill_color],
+                             f"rotate={radians:.8f}:fillcolor=black:{geometry}")
     else:
         # Pre-scale the frame up by a safe, conservative factor (|cos|+|sin|, the exact growth
         # factor for a square, over-generous for a rectangle) so the rotated content fully

package/scripts/waveform.py

@@ -35,7 +35,7 @@ import os
 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,
+from _common import (add_common, apply_common, aac_args, default_output, die, draws_chroma, emit, ffmpeg_base,
                      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
@@ -193,7 +193,14 @@ def main() -> int:
         # showwaves/showspectrum paint the visualization on a transparent-black canvas; composite
         # it over an explicit solid background instead of assuming that canvas already matches
         # --background.
-        vf = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}[bg];[0:a:{args.audio_stream}]{vf}[vis];[bg][vis]overlay=format=auto"
+        bg, vis = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}", vf
+        if draws_chroma([args.background] + (args.color.split("|") if args.style == "waveform" else []), None):
+            # the background and the RGBA waves are converted to the BT.709 the output is tagged
+            # with (the encoder line's own RGB-to-YUV step used BT.601); the spectrum is YUV of its
+            # own and only gets the label the background carries, so 7.1+'s overlay converts neither
+            bg += ",format=rgb24" + rgb_chain_to_bt709(None, "yuv420p")
+            vis += rgb_chain_to_bt709(None, "yuva420p") if args.style == "waveform" else ",setparams=colorspace=bt709"
+        vf = f"{bg}[bg];[0:a:{args.audio_stream}]{vis}[vis];[bg][vis]overlay=format=auto"
 
     render = output
     if args.title or args.srt or args.text: