ffmpeg-skill 2.10.1 → 2.10.3

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 (a BT.601-matrix 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) |
+| `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.1`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.3`) | 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.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.3", "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"},
@@ -220,7 +220,17 @@ Main10 for HDR), so the flags add no behaviour to a caller that does not pass th
 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()`).
+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 (`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.1",
+  "version": "2.10.3",
   "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

@@ -11,7 +11,12 @@ detail, not an aside.
 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. When `probe.py` reports
+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. 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/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 (a BT.601-matrix source is converted to it, as by every re-encode), 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/_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, matrix_chain, 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_matrix_args, bt709_matrix_filter, bt709_tag_args, color_hex, _COLOR_TOKEN_RE, fold_bt709_matrix,
-    NON_BT709_MATRICES, _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", "matrix_chain", "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

@@ -51,8 +51,26 @@ def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
 # 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")
 
-_MATRIX_FILTER_RE = re.compile(r"^colorspace=ispace=(?:%s):iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709$"
-                               % "|".join(NON_BT709_MATRICES))
+# 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)?\]")
 
 
@@ -67,14 +85,113 @@ def bt709_matrix_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
     (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."""
+    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") or matrix not in NON_BT709_MATRICES:
+    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")
+
+
+# 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_matrix_args, bt709_matrix_filter, bt709_tag_args, _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:
@@ -512,7 +519,8 @@ def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True,
     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", convert_matrix: bool = True) -> 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,
@@ -525,9 +533,14 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
     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.
     """
     v = (meta or {}).get("video") or {}
-    fix = bt709_matrix_args(meta) if convert_matrix and STATE.codec != "prores" else []
+    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"):
@@ -546,6 +559,61 @@ def matrix_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, A
     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 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/_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/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, 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, 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,9 +1562,17 @@ 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") 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/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,8 +33,8 @@ 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,
+                     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,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
@@ -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,18 +629,47 @@ 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)
+        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]
@@ -613,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, 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
 
@@ -91,25 +91,43 @@ 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.
+    # 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) 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]{','.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/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, 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,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, matrix_chain, 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
@@ -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,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"):
@@ -328,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/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/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,8 +35,8 @@ 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,
-                     info, load_brand, pad_filters, probe, run, STATE, validate_color, video_args, X264_PRESETS,
+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
 
@@ -185,13 +185,22 @@ 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
         # 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: