ffmpeg-skill 2.10.9 → 2.10.11

package/README.md

@@ -403,7 +403,7 @@ ffmpeg-skill edits footage you already have, on this machine, with FFmpeg tools
 
 ### Does it validate the filter graph before running?
 
-No. `--dry-run` prints the ffmpeg command a writing tool would run and does not start ffmpeg, so ffmpeg never parses that filter graph. ffprobe still runs when the tool probes an input that exists. Unless `--overwrite` is passed, an existing output is refused (`kind: input`) before ffmpeg. An output that is the same file as an input is refused either way. No media file is written, and `verified` is false; `--plan FILE` does write the plan JSON. A path that is not on disk yet is not measured: the probe is a stub (0×0, duration 0), so a number taken from it is not a measurement. The measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) still run their measurements; only the artifact is skipped, and `silence` with `--filler --transcribe` also runs the speech engine, which may download a model. `verify` accepts `--dry-run` and ignores it: its steps run. `--plan FILE` is that dry run written down — the planned argv, the command lines, and a fingerprint of each existing input (size, plus a sha256 of the first and last 8 MiB). `render.py` and `verify.py` refuse `--plan`. `render.py FILE` runs a plan only when those fingerprints still match, by running the tool again with the planned argv, not by executing the recorded ffmpeg lines; `--dry-run` on that run only prints them. `doctor` reports whether the filters, encoders and bitstream filters the contract names are in this build (`ffmpeg -filters`, `-encoders`, `-bsfs`) and which fonts are installed. A name in that listing is not a check of the graph this command would build, and a listed GPU encoder is not a successful encode.
+No. `--dry-run` prints the ffmpeg command a writing tool would run and does not start ffmpeg, so ffmpeg never parses that filter graph. ffprobe still runs when the tool probes an input that exists. Unless `--overwrite` is passed, an existing output is refused (`kind: input`) before ffmpeg. An output that is the same file as an input is refused either way. No media file is written, and `verified` is false; `--plan FILE` does write the plan JSON. A path that is not on disk yet is not measured: the probe is a stub (0×0, duration 0), so a number taken from it is not a measurement. The measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) still run their measurements; only the artifact is skipped, and `silence` with `--filler --transcribe` also runs the speech engine, which may download a model. `overlay` measures the lines of a multi-line `--text` with one drawtext on a generated frame on FFmpeg 8.0, 8.0.1 and 8.1.0, where it draws them one by one. `verify` accepts `--dry-run` and ignores it: its steps run. `--plan FILE` is that dry run written down — the planned argv, the command lines, and a fingerprint of each existing input (size, plus a sha256 of the first and last 8 MiB). `render.py` and `verify.py` refuse `--plan`. `render.py FILE` runs a plan only when those fingerprints still match, by running the tool again with the planned argv, not by executing the recorded ffmpeg lines; `--dry-run` on that run only prints them. `doctor` reports whether the filters, encoders and bitstream filters the contract names are in this build (`ffmpeg -filters`, `-encoders`, `-bsfs`) and which fonts are installed. A name in that listing is not a check of the graph this command would build, and a listed GPU encoder is not a successful encode.
 
 ### Can it remove burned-in subtitles or logos?
 
@@ -419,7 +419,7 @@ The encode path a tool will actually take is Apple VideoToolbox, for h264, hevc
 
 ## FFmpeg compatibility
 
-The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only); Python 3.10+ is recommended: 3.9 still works but is deprecated since 2.11.0 (CPython 3.9 is end of life), `doctor` and the `npx` installer warn on it, and 3.0 drops it. What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only); Python 3.10+ is recommended: 3.9 still works but is deprecated since 2.10.9 (CPython 3.9 is end of life), `doctor` and the `npx` installer warn on it, and 3.0 drops it. What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
 
 | FFmpeg | `-filters` row layout | Source |
 |---|---|---|

package/SKILL.md

@@ -9,7 +9,7 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
 
 Shared flags (every script): `--dry-run`; `--json` (output path, its probe, the commands run); `--json-brief` (status/output/verified + a `summary`; prefer on writing steps); `--fast` (preview quality); `--progress` (percent/ETA); `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (step 7); `--plan FILE` (a dry run `render.py FILE` runs later; refuses if an input changed). Re-encoding tools also take `--hw` (Apple Silicon GPU, big files; `FFMPEG_SKILL_HW=1` = default, not export), `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264 (`cut.py --keep-hevc`: HEVC source stays HEVC), HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).
 
-Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) may still run ffmpeg/ffprobe, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
+Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`; `overlay` for a multi-line `--text` on FFmpeg 8.0-8.1.0) may still run ffmpeg/ffprobe, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
 
 ## Workflow (in this order)
 

package/bin/install.js

@@ -47,9 +47,9 @@ if (has('--help') || has('-h')) {
 // The probe also prints major.minor, so the installer can warn about a deprecated interpreter.
 const PYTHON_PROBE = ['-c', "import sys; sys.stdout.write('%d.%d' % sys.version_info[:2]); raise SystemExit(0 if sys.version_info >= (3, 9) else 1)"];
 
-// 2.11.0 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; `contract --json`'s
+// 2.10.9 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; `contract --json`'s
 // `deprecated`). The same line as scripts/_contract.py's PY39_DEPRECATION (a test keeps them equal).
-const PY39_DEPRECATION = 'warning: Python 3.9 is deprecated since ffmpeg-skill 2.11.0 (CPython 3.9 reached end of life in October 2025 and gets no security fixes); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.';
+const PY39_DEPRECATION = 'warning: Python 3.9 is deprecated since ffmpeg-skill 2.10.9 (CPython 3.9 reached end of life in October 2025 and gets no security fixes); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.';
 
 function pythonDeprecation(version) {
   return version === '3.9' ? PY39_DEPRECATION : null;

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.9`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.11`) | 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`
@@ -81,12 +81,12 @@ on, the line says so.
 
 `contract --json` carries a top-level `deprecated` list, next to `contract_version`: one entry per
 thing the next major removes, `{"what", "since", "replacement", "removed_in", "where"}` with `where`
-naming the surface (`cli`, `json`, `mcp`, `behaviour`). It was empty in 2.0.0. Since 2.11.0 it lists one
+naming the surface (`cli`, `json`, `mcp`, `behaviour`). It was empty in 2.0.0. Since 2.10.9 it lists one
 entry: **running on Python 3.9** (`where: behaviour`, `removed_in: 3.0.0`). CPython 3.9 reached end of life
 in October 2025 and gets no security fixes, but raising the floor is a break, so 2.x keeps running on 3.9
 (`requirements.python` stays `>=3.9`, and CI keeps testing it). It is deprecated, and Python 3.10+ is
 recommended: on 3.9, `doctor` and the `npx` installer print one stderr line,
-`warning: Python 3.9 is deprecated since ffmpeg-skill 2.11.0 (...); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.`
+`warning: Python 3.9 is deprecated since ffmpeg-skill 2.10.9 (...); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.`
 Like every deprecation warning it is stderr only: `doctor --json`'s document has no key for it.
 `tests/test_contract.py` refuses a package.json major bump that still lists an entry that major should remove, or that
 comes before step 2's window has passed -- unless the waiver is written here, as 2.0.0's is.
@@ -123,12 +123,12 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
 ```json
 {
   "contract_version": "1.0",
-  "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.11.0", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
+  "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.10.9", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.11", "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; 3.9 deprecated since 2.11.0, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
+  "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
   "execution": {"shell": false, "arbitrary_executables": false, "network": false,
                 "model_downloads": {"when": "...", "in_process": {"faster-whisper": "..."},
                                     "child_process": {"parakeet-mlx": "...", "openai-whisper": "..."},
@@ -163,7 +163,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `produces_artifact` | writes a file (media, PNG, HTML, EDL) |
 | `verification` | `{required, tools}`: which tools to run on the output afterwards |
 | `requires_visual_verification` | the picture changed; run `ffmpeg-skill/look` and inspect the PNG |
-| `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`, `color`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched; for `color`, `--strip-dovi` and `--retag` are a stream copy of both (retag only re-encodes if the copy attempt fails), while `--to-sdr` / `--lut` / `--correct` always re-encode both. Several visual tools (`fit`, `overlay`, `graphics`, `join`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
+| `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`, `color`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched; for `color`, `--strip-dovi` and `--retag` are a stream copy of both (retag only re-encodes if the copy attempt fails or ffprobe still reads the old tags on the copy), while `--to-sdr` / `--lut` / `--correct` always re-encode both. Several visual tools (`fit`, `overlay`, `graphics`, `join`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
 | `audio_only` | accepts an audio-only input (WAV, MP3, M4A, FLAC, OGG, Opus) |
 | `video_required` | refuses an input without a video stream ("input has no video stream") |
 | | `join` has `audio_only: true` and `video_required: false` since 0.9.1: audio-only inputs are joined as audio (no `look` needed then); mixing audio and video inputs is refused |
@@ -212,7 +212,9 @@ exceptions are stated per tool in the contract's `dry_run` field: `probe` and `c
 read-only (ffprobe still runs); `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`,
 `loudness` and `stabilize` still run their ffmpeg/ffprobe measurements (the analysis is the
 tool's job; only the artifact is skipped, including side files such as `--edl`, `--sheet` or a
-generated `.ass`), and `verify` does not support dry-run (its steps run). `SKILL.md` and
+generated `.ass`), `overlay` measures the lines of a multi-line `--text` with one drawtext on a
+generated frame on FFmpeg 8.0, 8.0.1 and 8.1.0 (it draws them one by one there), and `verify`
+does not support dry-run (its steps run). `SKILL.md` and
 `references/scripts.md` repeat the same list; the contract is the authority.
 
 `--codec h264|hevc|av1|prores` and `--quality N` (1.8) are on every tool that re-encodes,
@@ -696,7 +698,8 @@ file was written. `probe` prints its measurement document directly.
 Every writing tool also reports what it verified itself (1.7): `verification` lists the
 steps (`{"step": "probe", "ok": true}`; `loudness` with the measured and target values for
 `loudness.py` and the platform presets of `export.py`; `check` with the platform for
-`render.py`), and `verified` is `true` only when the artifact was written, probed and every
+`render.py`; `color_tags` with the tags ffprobe read back for `color.py --retag`, which fails
+with `kind: verification` when they are not the requested ones), and `verified` is `true` only when the artifact was written, probed and every
 listed step met its target. A `--dry-run` document has `verified: false` and an empty list.
 `export.py` whose written file misses the platform's loudness spec stays `completed` (the
 file is valid) with `verified: false` and the fix in `notes`, so a caller keys on one field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.10.9",
+  "version": "2.10.11",
   "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

@@ -179,7 +179,15 @@ these had ever shown up before.
   `ametadata=mode=select`; do not use `aselect` for removal.
 - **FFmpeg 8.0, 8.0.1 and 8.1.0 draw the font's missing-glyph box at each line break of a multi-line
   `drawtext`** (each line is shaped with its newline; fixed in 8.0.2/8.1.1). `ffmpeg_version()` cannot
-  tell 8.1.0 from 8.1.1; `drawtext_draws_newline_glyph()` reads the point release.
+  tell 8.1.0 from 8.1.1; `drawtext_draws_newline_glyph()` reads the point release. graphics.py routes
+  such a label through libass; overlay.py draws one drawtext per line at positions a drawtext run
+  measured (`drawtext_line_metrics()`), since the multi-line block's own `text_w` carries the box.
+- **`-colorspace`/`-color_primaries`/`-color_trc` are not tags on 7.1+.** They feed the filter
+  graph's colourspace negotiation: a bt709-tagged H.264 re-encoded with `smpte170m` options came
+  out with a converted matrix and bt709 primaries/transfer (8.0.1, 8.1.3). Label the frames with
+  `setparams` (or the encoder's own VUI params) instead. On a stream copy they change only the
+  container: H.264/HEVC/MPEG-2/AV1/VP9 keep their own description, which decoders read first, so
+  rewrite it with the codec's `*_metadata` bitstream filter (`color.py --retag`).
 - **Not a 7.1 issue, found while chasing it: `color --correct` desaturates a bt709-*tagged*
   source by ~8 % at identity settings on 6.1 and 7.1 alike** (113.6 → 103.9 saturation_avg):
   the RGB stages (exposure/colortemperature/colorbalance) make swscale go yuv→rgb with the

package/references/scripts.md

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.11.0: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every re-encoding tool and `export.py` also take `--hw`/`--no-hw` (h264/hevc/prores on Apple VideoToolbox, Apple Silicon only, CRF mapped to `-q:v`; AV1 stays on the CPU; a job VideoToolbox itself refuses -- the encoder cannot open or its compression session fails -- is re-encoded on the CPU and reported in `hw.fallback`/`hw.notes`, any other failure is not retried; a GPU encode adds a `notes` line that its quality is not CRF-equivalent; `FFMPEG_SKILL_HW=1` makes it the default for every tool except `export.py`, whose delivery presets need `--hw` itself; `render.py`/`batch.py --hw`/`--no-hw` apply to every stage, export included; results name the `encoder` that ran); every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, default 18 -- 30 for `proxy.py`; up to 63 for av1; ignored by prores). 2.0 removed `--crf` from these tools (it was `--quality`'s alias); `export.py` keeps its own `--crf`, which is not an alias. Every tool refuses (`kind: input`, before anything runs) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither `--codec` nor `--quality`; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize`/`join` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.11.0: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every re-encoding tool and `export.py` also take `--hw`/`--no-hw` (h264/hevc/prores on Apple VideoToolbox, Apple Silicon only, CRF mapped to `-q:v`; AV1 stays on the CPU; a job VideoToolbox itself refuses -- the encoder cannot open or its compression session fails -- is re-encoded on the CPU and reported in `hw.fallback`/`hw.notes`, any other failure is not retried; a GPU encode adds a `notes` line that its quality is not CRF-equivalent; `FFMPEG_SKILL_HW=1` makes it the default for every tool except `export.py`, whose delivery presets need `--hw` itself; `render.py`/`batch.py --hw`/`--no-hw` apply to every stage, export included; results name the `encoder` that ran); every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, default 18 -- 30 for `proxy.py`; up to 63 for av1; ignored by prores). 2.0 removed `--crf` from these tools (it was `--quality`'s alias); `export.py` keeps its own `--crf`, which is not an alias. Every tool refuses (`kind: input`, before anything runs) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither `--codec` nor `--quality`; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize`/`join` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), `overlay` measures a multi-line `--text`'s lines on FFmpeg 8.0, 8.0.1 and 8.1.0 (one drawtext on a generated frame), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Time grammar (every time-taking flag, 1.9)
 
@@ -1497,6 +1497,11 @@ Devanagari/Thai-class scripts and cannot load a colour emoji font: a shaping
 script is refused by name pointing at `caption.py`/`graphics.py`, and
 `--emoji png|color` is refused the same way (`--emoji mono`, the default here,
 draws whatever glyph the text font has; `--emoji none` strips them).
+A multi-line `--text` is one block: the lines are left-aligned and the block is
+placed by `--position`. FFmpeg 8.0, 8.0.1 and 8.1.0 draw the font's missing-glyph box
+at each line break, so on those releases each line gets its own drawtext at the
+place the block puts it (measured by one drawtext run on a generated frame, also
+under `--dry-run`); the picture is the one a fixed release draws.
 
 ### sync.py — offset detection, alignment, drift correction
 ```
@@ -1539,7 +1544,7 @@ them.
 ```
 color.py INPUT --to-sdr [--tonemap hable|mobius|reinhard|bt2390] [--peak 1000] [--desat 0] [-o OUT]
 color.py INPUT --lut grade.cube [--lut-strength 0..1] [-o OUT]
-color.py INPUT --retag bt709|bt2020-pq|bt2020-hlg|bt601 [-o OUT]      # metadata only, stream copy
+color.py INPUT --retag bt709|bt2020-pq|bt2020-hlg|bt601 [-o OUT]      # metadata only, stream copy (checked with ffprobe)
 color.py INPUT --strip-dovi [-o OUT]                                 # drop the Dolby Vision RPU, keep the HLG/HDR10 base layer (stream copy)
 color.py INPUT --correct [--exposure -3..3] [--contrast 0..2] [--saturation 0..2] [--gamma 0.1..10]
          [--temperature 2000..12000] [--tint -1..1] [--lift -1..1] [--gain -1..1]
@@ -1570,6 +1575,20 @@ tetrahedral interpolation (Log→709 conversions, creative looks); blend with
 `--lut-strength`. Everything else in the skill assumes SDR BT.709, so run this
 first on HDR or Log sources.
 
+`--retag` relabels, never converts. H.264, HEVC, MPEG-2, AV1 and VP9 carry
+their colour description in the stream itself, and decoders read that before
+the container's, so the stream copy rewrites it with the codec's
+`*_metadata` bitstream filter (the coded pictures are untouched) as well as
+the container's `colr`/Colour. Every run then probes the output, stream and
+first decoded frame (from FFmpeg 8.1 the two can disagree): when either
+still reads other tags (a codec without such a filter, or a build that lacks
+it) or the copy fails, the video is re-encoded with the tags on its frames
+(`setparams`), `reencoded: true` and a `notes` line say so, and the check is
+`verification`'s `color_tags` step. Tags that are still wrong after the
+re-encode fail the run with `kind: verification`. The re-encode is H.264
+unless `--codec` says otherwise, so an output container that cannot hold it
+(`.webm`) fails with `kind: ffmpeg` instead of completing with the old tags.
+
 ### audio.py — clean-up, music, ducking, layout
 ```
 audio.py INPUT [--voice [light|medium|strong] | --denoise [--denoise-strength 25]] [--gain dB]

package/scripts/_common/__init__.py

@@ -56,7 +56,7 @@ from _common.runner import (
     child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, DEFAULT_TIMEOUT,
     _DRAWTEXT_PENDING, _DRAWTEXT_TMPDIR, _drawtext_tmpdir, dry_run_input_pending, _ENCODERS, _env_timeout,
     ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, ffmpeg_exe, _FFMPEG_RELEASE, _FFMPEG_VERSION,
-    ffmpeg_release, ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
+    ffmpeg_bsfs, ffmpeg_release, ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
     _odd_dimension_retry, _on_signal, _OutputLock, _pid_dead, place_output, PROBE_TIMEOUT, _progress_line,
     read_text_or_die, refuse_output_is_input, _remember_output, require_tool, run, run_analysis, _run_captured,
     run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, sibling_temp, _SIGNALS_INSTALLED, _stage_existing_output,
@@ -96,7 +96,7 @@ from _common.color import (
 )
 from _common.text import (
     ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align,
-    drawtext_draws_newline_glyph, is_multiline, NEWLINE_GLYPH_RELEASES,
+    drawtext_draws_newline_glyph, is_multiline, drawtext_clean, drawtext_line_metrics, NEWLINE_GLYPH_RELEASES,
     drawtext_shaping, drawtext_text_opts, emoji_asset_for, EMOJI_ASSET_HINT, emoji_clusters, emoji_codepoint_name,
     _EMOJI_COLOR_FAMILIES, _emoji_color_font, emoji_filter_chain, _emoji_name_candidates, EMOJI_RANGES,
     _EMOJI_REGIONAL, emoji_support, _EMOJI_SUPPORT_CACHE, _EMOJI_TAIL, escape_drawtext, _family_rank, FC_LANG,
@@ -147,7 +147,7 @@ class _Facade(_types.ModuleType):
     # defining module (audit 14, P1-1); every other name is a plain re-export of the same object.
     _LIVE = {
         "_FFMPEG_VERSION": "runner", "_FFMPEG_RELEASE": "runner", "_FFMPEG_RELEASE_READ": "runner", "_SIGNALS_INSTALLED": "runner",
-        "_DRAWTEXT_TMPDIR": "runner", "_ENCODERS": "runner", "_CURRENT_CTX": "emit",
+        "_DRAWTEXT_TMPDIR": "runner", "_ENCODERS": "runner", "_BSFS": "runner", "_CURRENT_CTX": "emit",
     }
 
     def __getattribute__(self, name):
@@ -190,14 +190,14 @@ __all__ = [
     "BEAT_REFRACTORY_S", "BEAT_WINDOW_S", "BEAT_SUPPORT_DIVISOR", "BEAT_ALIGN_DIVISOR",
     "BEAT_Z_FLOOR", "BEAT_Z_SPAN",
     "_onset_strength", "_pick_onsets", "_autocorrelation_peak", "_grid_score",
-    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align", "drawtext_draws_newline_glyph", "is_multiline", "NEWLINE_GLYPH_RELEASES",
+    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align", "drawtext_draws_newline_glyph", "is_multiline", "drawtext_clean", "drawtext_line_metrics", "NEWLINE_GLYPH_RELEASES",
     "_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
     "dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
     "emoji_codepoint_name", "_EMOJI_COLOR_FAMILIES", "_emoji_color_font", "emoji_filter_chain",
     "_emoji_name_candidates", "EMOJI_RANGES", "_EMOJI_REGIONAL", "emoji_support", "_EMOJI_SUPPORT_CACHE",
     "_EMOJI_TAIL", "encoder_args", "_ENCODERS", "_env_timeout", "ERROR_CODE", "ERROR_RETRYABLE", "escape_drawtext",
     "escape_filter_path", "EVEN_SCALE", "_execute", "_fail", "_family_rank", "FC_LANG", "_fc_list_fonts",
-    "FC_UNKNOWN", "ffmpeg_base", "ffmpeg_encoders", "ffmpeg_exe", "_FFMPEG_RELEASE", "_FFMPEG_VERSION", "ffmpeg_release", "ffmpeg_version", "fingerprint",
+    "FC_UNKNOWN", "ffmpeg_base", "ffmpeg_bsfs", "ffmpeg_encoders", "ffmpeg_exe", "_FFMPEG_RELEASE", "_FFMPEG_VERSION", "ffmpeg_release", "ffmpeg_version", "fingerprint",
     "flush_drawtext_textfiles", "fold_bt709_matrix", "fmt_secs", "fmt_smpte_time", "fmt_srt_time", "font_covers_script",
     "font_family_for_script", "font_family_of_file", "FONT_FLAG_HINT", "font_for_script", "FONT_INSTALL_HINT",
     "fonts_dir_covers_script", "_fraction", "has_emoji", "info", "INSTALL_HINTS", "install_signal_handlers",

package/scripts/_common/drawtext.py

@@ -8,7 +8,7 @@ import os
 import re
 import shutil
 import subprocess
-from typing import Dict, Optional
+from typing import Dict, List, Optional
 from _common.decision import escape_filter_path
 from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_exe, ffmpeg_release, ffmpeg_version
 
@@ -124,6 +124,17 @@ def drawtext_center_align() -> str:
     return ":text_align=C" if ffmpeg_version() >= (6, 1) else ""
 
 
+def drawtext_clean(text: "Optional[str]") -> str:
+    """The text drawtext_text_opts() writes to its file: `\r\n` and `\r` become `\n`, a tab,
+    vertical tab or form feed becomes a space, other control characters are stripped, and trailing
+    newlines are dropped (drawtext ignores one trailing newline and draws a second as a blank
+    line, which would centre the block half a line too high; a label that is only newlines stays
+    as it is)."""
+    cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n")
+    cleaned = re.sub(r"[\x00-\x08\x0e-\x1f\x7f]", "", re.sub(r"[\t\x0b\x0c]", " ", cleaned))
+    return cleaned.rstrip("\n") or cleaned
+
+
 def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     r"""`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
     every character on every build shape this repo uses.
@@ -145,11 +156,7 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     printed plan therefore names a path that no longer exists once the run is over, which is the
     same promise every other temp file in this skill makes.
     """
-    cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n")
-    cleaned = re.sub(r"[\x00-\x08\x0e-\x1f\x7f]", "", re.sub(r"[\t\x0b\x0c]", " ", cleaned))
-    # drawtext ignores one trailing newline and draws a second as a blank line, which would
-    # centre the block half a line too high; a label that is only newlines stays as it is
-    cleaned = cleaned.rstrip("\n") or cleaned
+    cleaned = drawtext_clean(text)
     import hashlib
     name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
     if tmpdir is None:
@@ -157,3 +164,55 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     path = os.path.join(tmpdir, name)
     _DRAWTEXT_PENDING[path] = cleaned
     return f"textfile={escape_filter_path(path)}:expansion=none"
+
+
+def drawtext_line_metrics(lines: "List[str]", font_opt: str, fontsize: int) -> "List[Optional[Dict[str, float]]]":
+    """Each line's drawtext metrics as this ffmpeg measures it ALONE, on one line, where the
+    8.0/8.0.1/8.1.0 newline bug cannot reach it: {w: text_w, top: top_a, bottom: bottom_d, lh},
+    None for an empty line (drawtext measures it as no glyphs).
+
+    The numbers come out of drawtext itself: its y expression print()s them (libavutil's eval
+    function, logged at error level), one drawtext per line on a generated one-frame picture --
+    no input is read and nothing is written but the line files, in a temporary directory that is
+    removed afterwards. It runs under --dry-run too (run_analysis), so a plan places the lines
+    where a run does. The y expression is evaluated at configuration and again per frame; the
+    last value of each line wins."""
+    import tempfile
+    from _common.emit import die
+    from _common.runner import flush_drawtext_textfiles, run_analysis
+    out: "List[Optional[Dict[str, float]]]" = [None] * len(lines)
+    with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-measure-") as td:
+        chain = []
+        for i, line in enumerate(lines):
+            if line:
+                chain.append(f"drawtext={drawtext_text_opts(line, tmpdir=td)}:{font_opt}:fontsize={fontsize}:x=0:"
+                             f"y='print({-(1000 + i)},16)+print(text_w,16)+print(top_a,16)+print(bottom_d,16)+print(lh,16)'")
+        if not chain:
+            return out
+        cmd = [ffmpeg_exe("ffmpeg")[0] or "ffmpeg", "-hide_banner", "-nostdin", "-v", "error", "-f", "lavfi",
+               "-i", "color=c=black:s=16x16:r=1", "-frames:v", "1", "-vf", ",".join(chain), "-f", "null", "-"]
+        try:
+            flush_drawtext_textfiles(cmd)
+            proc = run_analysis(cmd, record=True)
+        finally:
+            for path in [p for p in _DRAWTEXT_PENDING if p.startswith(td)]:
+                del _DRAWTEXT_PENDING[path]
+    current, values = None, {}  # type: Optional[int], Dict[int, List[float]]
+    # 8.x prefixes each value with "[Eval @ 0x...] ", 6.1 prints it bare
+    for m in re.finditer(r"^(?:\[Eval @ [^\]]*\] )?(-?[0-9]+(?:\.[0-9]+)?|-?nan|-?inf)\s*$", proc.stderr, re.M):
+        try:
+            v = float(m.group(1))
+        except ValueError:
+            continue
+        if v <= -1000 and v == int(v):
+            current = int(-v) - 1000
+            values[current] = []
+        elif current is not None:
+            values[current].append(v)
+    for i, line in enumerate(lines):
+        got = values.get(i) if line else None
+        if line and (not got or len(got) != 4):
+            die("could not measure a line of --text with drawtext (no print() output from ffmpeg)", kind="ffmpeg")
+        if got:
+            out[i] = {"w": got[0], "top": got[1], "bottom": got[2], "lh": got[3]}
+    return out

package/scripts/_common/runner.py

@@ -205,6 +205,7 @@ CODECS = ("h264", "hevc", "av1", "prores")
 
 
 _ENCODERS: Optional[set] = None
+_BSFS: Optional[set] = None
 
 
 class Context:
@@ -1372,6 +1373,24 @@ def ffmpeg_encoders() -> set:
     return _ENCODERS
 
 
+def ffmpeg_bsfs() -> set:
+    """Names from `ffmpeg -bsfs`, read once, empty when it cannot be read; from ffprobe under
+    --dry-run, for the reason ffmpeg_encoders() gives. color.py --retag rewrites an H.264/HEVC
+    stream's colour description with h264_metadata/hevc_metadata only when the build has it."""
+    global _BSFS
+    if _BSFS is None:
+        _BSFS = set()
+        tool = "ffprobe" if STATE.dry_run else "ffmpeg"
+        limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+        try:
+            out = subprocess.run([ffmpeg_exe(tool)[0] or tool, "-hide_banner", "-bsfs"], stdout=subprocess.PIPE,
+                                 stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=limit).stdout
+            _BSFS = set(re.findall(r"^\s*([a-z0-9_]+)\s*$", out, re.M))
+        except (OSError, subprocess.SubprocessError):
+            pass
+    return _BSFS
+
+
 def read_text_or_die(path: str, flag: str) -> str:
     """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
     with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""

package/scripts/_common/text.py

@@ -32,7 +32,7 @@ from _common.emoji import (
 from _common.drawtext import (
     drawtext_boxborderw, SHAPING_SCRIPTS, BIDI_SCRIPTS, _SHAPING_BUILD_CACHE, drawtext_shaping, needs_shaping,
     escape_drawtext, drawtext_text_opts, drawtext_center_align, NEWLINE_GLYPH_RELEASES,
-    drawtext_draws_newline_glyph, is_multiline,
+    drawtext_draws_newline_glyph, is_multiline, drawtext_clean, drawtext_line_metrics,
 )
 from _common.wrap import (
     ADVANCE_EM, NO_SPACE_SCRIPTS, NO_BOUNDARY_SCRIPTS, LATIN_EM, LEADING_VOWELS, _is_mark, _char_em,

package/scripts/_contract.py

@@ -185,7 +185,10 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                  video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "color": dict(role="execution", inputs=["video asset", ".cube LUT (--lut)"], outputs=["video artifact with converted colour"],
                   required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut / --correct"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
-                                         {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"},
+                                         {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": "bsf:h264_metadata", "when": "--retag on H.264 (without it the video is re-encoded)"},
+                                         {"capability": "bsf:hevc_metadata", "when": "--retag on HEVC (without it the video is re-encoded)"},
+                                         {"capability": "bsf:mpeg2_metadata", "when": "--retag on MPEG-2 (without it the video is re-encoded)"}, {"capability": "bsf:av1_metadata", "when": "--retag on AV1 (without it the video is re-encoded)"},
+                                         {"capability": "bsf:vp9_metadata", "when": "--retag on VP9 (without it the video is re-encoded)"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"},
                                          {"capability": "filter:exposure", "when": "--correct"}, {"capability": "filter:eq", "when": "--correct"},
                                          {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"},
                                          {"capability": "filter:colorlevels", "when": "--correct with any --levels-*"}, {"capability": "filter:curves", "when": "--correct --curves"}],
@@ -240,6 +243,7 @@ DRY_RUN_ANALYSIS = {
     "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
     "check": "read-only tool; the loudness measurement (or, when it is skipped, the audio row's volumedetect) and the --content decode run under --dry-run too, so every row is present",
     "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
+    "overlay": "only for a multi-line --text on FFmpeg 8.0, 8.0.1 or 8.1.0: one drawtext measures each line on a generated one-frame picture (the input is not read), so the planned per-line positions are the ones a run uses; otherwise no ffmpeg runs and the composited output is never written",
 }
 DRY_RUN_NOTES = {
     "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",
@@ -287,7 +291,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "loudness":  dict(video="never", audio="always"),
     "silence":   dict(video="always", audio="always", note="removing gaps requires cutting on non-keyframe boundaries"),
     "join":      dict(video="always", audio="always"),
-    "color":     dict(video="conditional", audio="conditional", note="--strip-dovi and --retag (when the stream copy succeeds) are -c copy of both streams; --retag falls back to re-encoding only if the copy attempt fails; --to-sdr / --lut / --correct always re-encode both"),
+    "color":     dict(video="conditional", audio="conditional", note="--strip-dovi and --retag (when the stream copy succeeds) are -c copy of both streams; --retag falls back to re-encoding only if the copy attempt fails or ffprobe still reads the old tags on the copy (a codec with no metadata bitstream filter here); --to-sdr / --lut / --correct always re-encode both"),
     "proxy":     dict(video="always", audio="conditional", note="video is always re-encoded at proxy-grade quality; audio is re-encoded when present, dropped entirely with --no-audio or when the source has none"),
     "export":    dict(video="conditional", audio="conditional", note="--preset copy is -c:v copy -c:a copy (no re-encode); every other preset re-encodes both"),
     "check":     dict(video="never", audio="never", note="read-only, no artifact"),
@@ -444,8 +448,6 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given"}}
     elif name == "look":
         extra = {"outputs": {"type": "array", "items": {"type": "string"}}}
-    elif name == "overlay":
-        extra = {"notes": {"type": "array", "items": {"type": "string"}, "description": "a multi-line --text on FFmpeg 8.0, 8.0.1 or 8.1.0, whose drawtext draws a box at each line break (fixed in 8.0.2 and 8.1.1)"}}
     elif name == "render":
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]},
                  "plan": {"type": "string", "description": "when the argument was a plan.json (written by <tool> --plan): its path"},
@@ -473,7 +475,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "color":
         extra = {"dropped_non_av_streams": {"type": "boolean"},
                  "sdr_path": {"enum": ["tonemap", "gamut"], "description": "--to-sdr only: tonemap for PQ / HLG / Dolby Vision (and --force on an untagged file); gamut for BT.2020 primaries on an SDR transfer, converted to BT.709 without a tone map"},
-                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--to-sdr only: which path was taken and why"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--to-sdr: which path was taken and why; --retag: why the video was re-encoded (the stream copy failed, or ffprobe still read the old tags on it)"},
+                 "reencoded": {"type": "boolean", "description": "--retag: true when the stream copy could not carry the tags and the video was re-encoded with them on its frames"},
                  "measurements": {"type": "object", "description": "--correct only: signalstats levels of input and output"}}
     elif name == "loop":
         extra = {"boomerang": {"type": "boolean", "description": "--boomerang: frames 0..N-1 then N-2..1, repeated, so neither turnaround frame is shown twice"},
@@ -832,9 +835,9 @@ def ffmpeg_security(versions: Dict[str, Optional[str]], sources: Optional[Dict[s
     return out
 
 
-# 2.11.0 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; DEPRECATED below). The same
+# 2.10.9 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; DEPRECATED below). The same
 # line is printed by bin/install.js (PY39_DEPRECATION there; a test keeps the two equal).
-PY39_DEPRECATION = ("warning: Python 3.9 is deprecated since ffmpeg-skill 2.11.0 (CPython 3.9 reached end of life "
+PY39_DEPRECATION = ("warning: Python 3.9 is deprecated since ffmpeg-skill 2.10.9 (CPython 3.9 reached end of life "
                     "in October 2025 and gets no security fixes); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.")
 
 
@@ -1404,7 +1407,7 @@ DEPRECATED: List[Dict[str, str]] = [
     # CPython 3.9 reached end of life in October 2025. Raising the floor is a break, so 2.x keeps
     # running on it (CI still tests 3.9) and doctor / bin/install.js print PY39_DEPRECATION.
     {"what": "running on Python 3.9 (the requirements.python floor)",
-     "since": "2.11.0", "removed_in": "3.0.0", "where": "behaviour",
+     "since": "2.10.9", "removed_in": "3.0.0", "where": "behaviour",
      "replacement": "Python 3.10 or later; on 3.9, doctor and the npx installer print a one-line warning"},
 ]
 
@@ -1644,7 +1647,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             },
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"],
         },
-        "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.11.0, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
+        "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
         "execution": {
             "shell": False,
             "arbitrary_executables": False,
@@ -1690,7 +1693,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},
             "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ...}, \"commands\": [...]} when --json was given", "stderr": "human-readable message"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached), color.py --retag (output written, but ffprobe does not read the requested colour tags on it); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,

package/scripts/color.py

@@ -18,11 +18,12 @@ Examples:
   python3 color.py flat.mp4 --correct --levels-in-black 16 --levels-in-white 235 --curves medium_contrast
 """
 import argparse
+import json
 import os
 import sys
-from typing import List
+from typing import List, Optional
 
-from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, ffmpeg_exe, info, probe, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
@@ -193,6 +194,144 @@ def is_bt2020_sdr(v: dict) -> bool:
         and v.get("color_transfer") not in ("smpte2084", "arib-std-b67")
 
 
+# --retag targets: ffprobe's names (colorspace, primaries, transfer) and the ITU-T H.273 code points
+# h264_metadata/hevc_metadata write into the VUI (matrix_coefficients, colour_primaries,
+# transfer_characteristics).
+RETAG = {
+    "bt709": (("bt709", "bt709", "bt709"), (1, 1, 1)),
+    "bt2020-pq": (("bt2020nc", "bt2020", "smpte2084"), (9, 9, 16)),
+    "bt2020-hlg": (("bt2020nc", "bt2020", "arib-std-b67"), (9, 9, 18)),
+    "bt601": (("smpte170m", "smpte170m", "smpte170m"), (6, 6, 6)),
+}
+# codecs whose colour description lives in the bitstream, and the bitstream filter that rewrites it
+# without touching a coded picture (each in every FFmpeg from 5.0: tests/fixtures/ffmpeg_bsfs_*)
+RETAG_BSF = {"h264": "h264_metadata", "hevc": "hevc_metadata", "mpeg2video": "mpeg2_metadata",
+             "av1": "av1_metadata", "vp9": "vp9_metadata"}
+# VP9 has only a colour space (its primaries and transfer are the container's); vp9_metadata's names
+VP9_SPACE = {"bt709": "bt709", "smpte170m": "smpte170", "bt2020nc": "bt2020"}
+
+
+def retag_bsf(meta: dict, target: str) -> List[str]:
+    """`-bsf:v:0 <codec>_metadata=...` writing `target`'s colour description into the first video
+    stream's own headers (H.264/HEVC VUI, MPEG-2 sequence display extension, AV1 sequence header,
+    VP9 frame header), or [] when the codec has no such filter (ProRes, DNxHD, MPEG-4 Part 2 ...)
+    or this build lacks it.
+
+    A stream copy with -colorspace/-color_primaries/-color_trc changes only the container's
+    description (mp4 `colr`, Matroska Colour); decoders, ffprobe included, read the stream's own
+    description first, so a source that already carried tags there kept them while the tool
+    reported success. The filter rewrites those headers and nothing else: the copy stays
+    lossless. Where the filter has a range field it gets the source's probed range (pc/tv),
+    because h264_metadata/hevc_metadata set it to limited when the VUI had no signal type at all;
+    an unknown range is left alone."""
+    v = meta["video"]
+    codec = v.get("codec") or ""
+    bsf = RETAG_BSF.get(codec)
+    if not bsf or bsf not in ffmpeg_bsfs():
+        return []
+    names, (matrix, prim, trc) = RETAG[target]
+    rng = v.get("color_range") if v.get("color_range") in ("tv", "pc") else None
+    if codec == "vp9":
+        opts = f"color_space={VP9_SPACE[names[0]]}" + (f":color_range={rng}" if rng else "")
+    elif codec == "av1":
+        opts = (f"color_primaries={prim}:transfer_characteristics={trc}:matrix_coefficients={matrix}"
+                + (f":color_range={rng}" if rng else ""))
+    else:
+        opts = f"colour_primaries={prim}:transfer_characteristics={trc}:matrix_coefficients={matrix}"
+        if rng and codec != "mpeg2video":
+            opts += f":video_full_range_flag={1 if rng == 'pc' else 0}"
+    return ["-bsf:v:0", f"{bsf}={opts}"]
+
+
+def retag_mismatch(output: str, want: tuple) -> "Optional[str]":
+    """None when the output carries `want` (colorspace, primaries, transfer), else what was read
+    -- the check behind every completed --retag.
+
+    Two readings, because they disagree: ffprobe's stream tags (from 8.1 the container's `colr`
+    wins there over an H.264 VUI that still says bt709, while 6.1 and 8.0 show the VUI) and the
+    first decoded frame's, which is what a player or filter graph gets. Each stream tag must be
+    the requested one; a frame tag must be the requested one or unspecified (8.1's ProRes decoder
+    leaves its frames untagged and players read the container's)."""
+    got = probe(output, role="output")["video"]
+    stream = (got.get("color_space"), got.get("color_primaries"), got.get("color_transfer"))
+    keys = ("color_space", "color_primaries", "color_transfer")
+    proc = run_analysis([ffmpeg_exe("ffprobe")[0] or "ffprobe", "-v", "error", "-select_streams", "v:0", "-show_frames",
+                         "-read_intervals", "%+#1", "-show_entries", "frame=" + ",".join(keys), "-of", "json", output],
+                        check=False)
+    try:
+        frames = json.loads(proc.stdout or "{}").get("frames") or [{}]
+    except ValueError:
+        frames = [{}]
+    frame = tuple(frames[0].get(k) for k in keys)
+    if stream == tuple(want) and all(f in (None, "unknown", w) for f, w in zip(frame, want)):
+        return None
+    shown = "/".join(str(t) for t in stream)
+    return shown if frame in ((None,) * 3, stream) else f"{shown} (decoded frames: {'/'.join(str(t) for t in frame)})"
+
+
+def retag(args: argparse.Namespace, meta: dict, has_audio: bool) -> int:
+    """--retag: rewrite the colour description, never the pixels.
+
+    First a stream copy of every stream: the container options plus, where the codec keeps its
+    own description, its rewrite (retag_bsf). When the copy fails, or ffprobe still reads other
+    tags on its output (a codec with no such filter here), the video is re-encoded with the tags
+    put on the frames (`setparams`): from FFmpeg 7.1 the encoder takes them from the frames and the output options feed the
+    filter graph's colourspace negotiation, which converted the matrix of a tagged source and left
+    its primaries and transfer as they were (measured on 8.0.1 and 8.1.3), while setparams labels
+    the frames on 5.x-8.x alike. Every completed run has been checked: ffprobe reads the requested
+    tags on the output (`verification`'s `color_tags` step), or the run fails with kind `verification`."""
+    names = RETAG[args.retag][0]
+    output = args.output or default_output(args.input, "retag")
+    ext = os.path.splitext(output)[1].lower()
+    tags = ["-colorspace", names[0], "-color_primaries", names[1], "-color_trc", names[2]]
+    bsf = retag_bsf(meta, args.retag)
+    cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy"] + bsf + tags
+    if ext in (".mp4", ".mov", ".m4v"):
+        cmd += ["-movflags", "+faststart"]
+    cmd.append(output)
+    proc = run(cmd, check=False)
+    notes: List[str] = []
+    reencoded = proc.returncode != 0
+    if not reencoded and not STATE.dry_run:
+        wrong = retag_mismatch(output, names)
+        if wrong:
+            reencoded = True
+            notes.append(f"a stream copy cannot rewrite the colour tags of {meta['video'].get('codec')} here "
+                         f"(the output still read {wrong}), so the video was re-encoded with the tags on its frames")
+            info("note: " + notes[-1])
+    elif reencoded:
+        notes.append("the stream copy failed, so the video was re-encoded with the tags on its frames")
+    dropped_streams = False
+    if reencoded:
+        # The copy path (-map 0 -c copy) keeps every stream -- extra audio tracks, subtitles,
+        # chapters, attached pictures -- byte-for-byte; -c:s/-c:d copy here keeps that same
+        # guarantee for subtitle/data streams even though video/audio must be re-encoded. Only if
+        # THAT also fails (e.g. a subtitle codec genuinely incompatible with the target container)
+        # do we drop to video+selected-audio-only, and even then we say so explicitly rather than
+        # silently reporting "completed" with streams missing.
+        info("re-encoding video/audio with the new tags (subtitles/data streams kept)")
+        label = ["-vf", f"setparams=color_primaries={names[1]}:color_trc={names[2]}:colorspace={names[0]}"]
+        enc = x264_args(args.crf, args.preset, keep_bt709=False) + (aac_args() if has_audio else [])
+        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
+                                "-map", "0:s?", "-map", "0:d?"] + label + enc + ["-c:s", "copy", "-c:d", "copy", output]
+        proc2 = run(cmd, check=False)
+        if proc2.returncode != 0:
+            info("re-encode with subtitles/data streams kept also failed; dropping them")
+            dropped_streams = True
+            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"] + label + enc + [output]
+            run(cmd)
+        wrong = None if STATE.dry_run else retag_mismatch(output, names)
+        if wrong:
+            die(f"--retag {args.retag}: the re-encoded output still reads {wrong}, not {'/'.join(names)}",
+                kind="verification", hint=f"the output was written to {output} but is not tagged as asked")
+    info(f"wrote {output} (tags -> {args.retag})")
+    check = [] if STATE.dry_run else [{"step": "color_tags", "ok": True, "color_space": names[0],
+                                       "color_primaries": names[1], "color_transfer": names[2]}]
+    emit(output, reencoded=reencoded, dropped_non_av_streams=dropped_streams, verification=check,
+         **({"notes": notes} if notes else {}))
+    return 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -261,45 +400,7 @@ def main() -> int:
         return 0
 
     if args.retag:
-        tags = {
-            "bt709": ["bt709", "bt709", "bt709"],
-            "bt2020-pq": ["bt2020nc", "bt2020", "smpte2084"],
-            "bt2020-hlg": ["bt2020nc", "bt2020", "arib-std-b67"],
-            "bt601": ["smpte170m", "smpte170m", "smpte170m"],
-        }[args.retag]
-        output = args.output or default_output(args.input, "retag")
-        ext = os.path.splitext(output)[1].lower()
-        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy",
-               "-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]]
-        if ext in (".mp4", ".mov", ".m4v"):
-            cmd += ["-movflags", "+faststart"]
-        cmd.append(output)
-        proc = run(cmd, check=False)
-        dropped_streams = False
-        if proc.returncode != 0:
-            # Some codecs cannot carry retagged colour info without a bitstream filter, so the
-            # stream copy above fails and we fall back to re-encoding video+audio. The copy path
-            # (-map 0 -c copy) keeps every stream -- extra audio tracks, subtitles, chapters,
-            # attached pictures -- byte-for-byte; -c:s/-c:d copy here keeps that same guarantee
-            # for subtitle/data streams even though video/audio must be re-encoded. Only if THAT
-            # also fails (e.g. a subtitle codec genuinely incompatible with the target container)
-            # do we drop to video+selected-audio-only, and even then we say so explicitly rather
-            # than silently reporting "completed" with streams missing.
-            info("stream copy could not rewrite tags, re-encoding video/audio (subtitles/data streams kept)")
-            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
-                                    "-map", "0:s?", "-map", "0:d?"] + x264_args(args.crf, args.preset, keep_bt709=False)
-            cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]]
-            cmd += (aac_args() if has_audio else []) + ["-c:s", "copy", "-c:d", "copy"] + [output]
-            proc2 = run(cmd, check=False)
-            if proc2.returncode != 0:
-                info("re-encode with subtitles/data streams kept also failed; dropping them")
-                dropped_streams = True
-                cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"] + x264_args(args.crf, args.preset, keep_bt709=False)
-                cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
-                run(cmd)
-        info(f"wrote {output} (tags -> {args.retag})")
-        emit(output, reencoded=proc.returncode != 0, dropped_non_av_streams=dropped_streams)
-        return 0
+        return retag(args, meta, has_audio)
 
     measurements = None
     sdr_extra: dict = {}

package/scripts/overlay.py

@@ -21,11 +21,12 @@ Examples:
   python3 overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00 --chromakey-similarity 0.15
 """
 import argparse
+import re
 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, drawtext_draws_newline_glyph, is_multiline, 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
+from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, 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
@@ -87,6 +88,56 @@ def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fad
     return "max(0," + "*".join(parts) + ")"
 
 
+def _num(v: float) -> str:
+    """A measured pixel value as an expression literal (no exponent form)."""
+    return f"{v:.6f}".rstrip("0").rstrip(".")
+
+
+def per_line_drawtext(lines: List[str], x: str, y: str, font_opt: str, args: argparse.Namespace,
+                      box: List[str], timing: List[str]) -> str:
+    """The drawtext chain for a multi-line --text on a release whose drawtext draws a box at each
+    line break (drawtext_draws_newline_glyph): one drawtext per line, each line alone, placed
+    where one multi-line drawtext puts it on a fixed release.
+
+    That block's layout is drawtext's own (measure_text/draw_text): text_w is the widest line,
+    text_h = lh*(lines-1) + the first line's top_a + the last line's bottom_d, the lines are
+    left-aligned at x, and line i's baseline is y + top_a + i*lh. Each line is measured alone
+    (drawtext_line_metrics), so the box the bug adds is in no number; x and y keep the caller's
+    position expressions with text_w/text_h replaced by the block's values, and each line is
+    drawn with y_align=baseline at its own baseline. The outlines of every line are drawn before
+    any line's text, as one drawtext draws them, so a descender's outline never covers the next
+    line's glyphs; the --box is drawn once, by the first line, at the block's size (boxw/boxh).
+    Bit-identical to one multi-line drawtext on 8.1.3 for every named position, with and without
+    --box; a font whose glyph boxes are not whole pixels (no hinting) can sit one row lower, since
+    drawtext reports top_a rounded up."""
+    m = drawtext_line_metrics(lines, font_opt, args.font_size)
+    seen = [d for d in m if d]
+    lh = seen[0]["lh"]
+    width = max(d["w"] for d in seen)
+    # an empty first/last line has no glyphs: drawtext's -32000/64 start values, as it measures them
+    top = m[0]["top"] if m[0] else -500.0
+    bottom = m[-1]["bottom"] if m[-1] else -500.0
+    height = lh * (len(lines) - 1) + top + bottom
+
+    def block(expr: str) -> str:
+        return re.sub(r"\btext_h\b", _num(height), re.sub(r"\btext_w\b", _num(width), expr))
+
+    bx, by = block(x), block(y)
+    passes = ([[f"borderw={args.border}", f"bordercolor={args.border_color}", "fontcolor=black@0"],
+               ["fontcolor=" + args.font_color]] if args.border else [["fontcolor=" + args.font_color]])
+    filters = []
+    for n, paint in enumerate(passes):
+        for i, line in enumerate(lines):
+            if not line:
+                continue
+            opts = [drawtext_text_opts(line), f"fontsize={args.font_size}", f"x={bx}", f"y={by}+{_num(top + i * lh)}",
+                    "y_align=baseline", font_opt] + paint + timing[:1]
+            if box and n == 0 and not filters:
+                opts += box + [f"boxw={_num(width)}", f"boxh={_num(height)}"]
+            filters.append("drawtext=" + ":".join(opts + timing[1:]))
+    return ",".join(filters)
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -144,7 +195,6 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
-    notes: List[str] = []
 
     brand = load_brand(args.brand)
     if args.logo:
@@ -335,29 +385,23 @@ def main() -> int:
         x, y = position_exprs(args.position, args.margin, text_mode=True, margins=safe_margins)
         # 1.15: the text goes in a FILE with expansion off, so `'` and `%` survive verbatim
         # (they used to be dropped by escape_drawtext) and no character can reach the graph parser.
+        font_opt = (f"fontfile={escape_filter_path(args.font_file)}" if args.font_file
+                    else f"font='{escape_drawtext(args.font)}'")
+        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None), end, args.fade)
+        timing = ([f"alpha='{alpha}'"] if alpha != "1" else []) + ([f"enable='{enable}'"] if enable else [])
+        box = ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"] if args.box else []
         if is_multiline(args.text) and drawtext_draws_newline_glyph():
-            # overlay has no libass route to send it to (graphics.py's --text-render auto does)
-            notes.append("this ffmpeg's drawtext (FFmpeg 8.0, 8.0.1 and 8.1.0; fixed in 8.0.2 and 8.1.1) draws "
-                         "the font's missing-glyph box at the end of every line but the last of a multi-line "
-                         "--text: draw multi-line text with graphics.py or caption.py, or upgrade FFmpeg")
-            info("warning: " + notes[-1])
-        opts = [drawtext_text_opts(args.text), f"fontsize={args.font_size}", f"x={x}", f"y={y}",
-                f"borderw={args.border}", f"bordercolor={args.border_color}"]
-        if args.font_file:
-            opts.append(f"fontfile={escape_filter_path(args.font_file)}")
+            # this release's drawtext draws the font's missing-glyph box at every line break and
+            # counts it in text_w: one drawtext per line, placed where one block would put it
+            drawing = per_line_drawtext(drawtext_clean(args.text).split("\n"), x, y, font_opt, args, box, timing)
         else:
-            opts.append(f"font='{escape_drawtext(args.font)}'")
-        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None), end, args.fade)
-        opts.append(f"fontcolor={args.font_color}")
-        if alpha != "1":
-            opts.append(f"alpha='{alpha}'")
-        if args.box:
-            opts += ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"]
-        if enable:
-            opts.append(f"enable='{enable}'")
+            opts = [drawtext_text_opts(args.text), f"fontsize={args.font_size}", f"x={x}", f"y={y}",
+                    f"borderw={args.border}", f"bordercolor={args.border_color}", font_opt,
+                    f"fontcolor={args.font_color}"] + timing[:1] + box + timing[1:]
+            drawing = "drawtext=" + ":".join(opts)
         # 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"]
+        cmd += ["-vf", drawn_chain(drawing, meta, colours), "-map", "0:v:0"]
         if meta.get("audio"):
             cmd += ["-map", f"0:a:{args.audio_stream}"]
 
@@ -367,7 +411,7 @@ def main() -> int:
     if not STATE.dry_run:
         result = probe(output, role="output")
         info(f"wrote {output} ({fmt_secs(result['duration'])})")
-    emit(output, dropped_non_av_streams=dropped_streams, **({"notes": notes} if notes else {}))
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0