Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
fix: --retag rewrites the stream's own colour tags; overlay draws multi-line text per line on 8.0-8.1.0 (#348)
Shogo Kajiyama5c23fc19f0b1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b22f2aa..60b5d2c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,11 @@## Unreleased-(nothing yet)+### Fixed++- **`color.py --retag` changes the tags a player reads, and checks that it did.** A stream copy set only the container's colour tags (`-colorspace`/`-color_primaries`/`-color_trc`). H.264, HEVC, MPEG-2, AV1 and VP9 carry their own colour description in the stream, which decoders and ffprobe read first. So a source already tagged there came out with its old tags while the result said `completed` (FFmpeg 6.1 and 8.0.1 alike). The copy now also rewrites the stream's own description with the codec's bitstream filter (`h264_metadata`, `hevc_metadata`, `mpeg2_metadata`, `av1_metadata`, `vp9_metadata`), so it is still a lossless copy. Every run then probes its output, both the stream's tags and the first decoded frame's, since FFmpeg 8.1's ffprobe shows the container's tag at stream level while the decoder still outputs the VUI's (`verification`: `color_tags`). If either still reads other tags (a codec with no such filter, or a build without it), the video is re-encoded with the tags and `reencoded: true` plus a `notes` line say why. If the re-encode is wrong too, the run fails with `kind: verification`. `contract --json` lists the five filters as optional capabilities of `color`.+- **`color.py --retag`'s re-encode keeps the pixels and writes the tags on FFmpeg 7.1 and later.** It set the tags with output options. From 7.1 those drive the filter graph's colourspace negotiation, so a bt709 source retagged bt601 had its matrix converted and kept bt709 primaries and transfer (measured on 8.0.1 and 8.1.3). The frames are now labelled with `setparams`, which gives identical pixels and the requested tags on 6.1.1, 7.0.2, 8.0.1 and 8.1.3.+- **`overlay.py --text` draws multi-line text without a box at the line breaks on FFmpeg 8.0, 8.0.1 and 8.1.0.** 2.10.9 only warned. On those releases each line now gets its own `drawtext`, placed where one multi-line drawtext puts it on a fixed release. The positions come from one small drawtext run that measures each line alone (width, first line's ascent, last line's descent, line height); it runs under `--dry-run` too, so the plan is the run. Outlines go first, and the `--box` is drawn once at the block's size. The frame is bit-identical to a single multi-line drawtext on 8.1.3 (and on 6.1.1 with the route forced), and 8.0.1's output matches 8.1.3's. A font whose glyph boxes are not whole pixels can sit one row lower. The warning and the `notes` line are gone, and `overlay` is listed among the tools that may measure under `--dry-run`. Other releases plan the same command as before, byte for byte.## 2.10.10diff --git a/README.md b/README.mdindex ae1413a..425fc5e 100644--- a/README.md+++ b/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?diff --git a/SKILL.md b/SKILL.mdindex eef25a7..cc08f2d 100644--- a/SKILL.md+++ b/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)diff --git a/docs/contract.md b/docs/contract.mdindex ee1e719..244d9c1 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -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 `cread-only (ffprobe still runs); `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`,`loudness` and `stabilize` still run their ffmpeg/ffprobe measurements (the analysis is thetool'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 thesteps (`{"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 everylisted 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` (thefile is valid) with `verified: false` and the fix in `notes`, so a caller keys on one field.diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 9138b5b..715c515 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -27,8 +27,10 @@ exists. When a decision changes, edit the entry in the same PR.- **Measurement passes run under `--dry-run`; only writes are skipped.** `probe`, `check`, `sync`,`multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness` and `stabilize` run- ffmpeg/ffprobe to measure, because a plan built on a fake measurement is not a plan. The- contract lists them as `analysis_only`; every other tool runs nothing. Code:+ ffmpeg/ffprobe to measure, because a plan built on a fake measurement is not a plan. So does+ `overlay` for a multi-line `--text` on FFmpeg 8.0, 8.0.1 and 8.1.0 (one drawtext on a generated+ frame; see "a multi-line `overlay.py --text`" below). The contract lists them as+ `analysis_only`; every other tool runs nothing. Code:`_contract.DRY_RUN_ANALYSIS`. Tests: `test_dry_run_never_runs_ffmpeg_and_writes_nothing`,`test_dry_run_plans_rest_on_real_measurements`.- **When a measured input is an intermediate an earlier dry-run stage would have written**@@ -234,6 +236,36 @@ exists. When a decision changes, edit the entry in the same PR.`pad_filters`), and each drawing tool. Tests: `test_a_pad_fill_or_background_lands_in_the_bt709_its_output_is_tagged_with`,`test_drawn_text_and_boxes_land_in_the_bt709_their_output_is_tagged_with`,`test_a_picture_that_only_passes_through_keeps_its_pixels`, `test_drawn_colours_are_drawn_in_bt709`.+- **`color.py --retag` rewrites the colour description the stream itself carries, and checks it.**+ H.264, HEVC, MPEG-2, AV1 and VP9 keep it in the bitstream (VUI, sequence header, frame header).+ Decoders, ffprobe included, read that before the container's `colr`/Colour. Through 2.10.10 the+ stream copy set only the container's tags (`-colorspace`/`-color_primaries`/`-color_trc`), so a+ source that carried tags in the stream kept them and the run said `completed` (6.1 and 8.0.1+ alike). The copy now also runs the codec's `*_metadata` bitstream filter (`-bsf:v:0`, in every+ FFmpeg from 5.0 and in each captured `tests/fixtures/ffmpeg_bsfs_*`). That filter rewrites+ headers only, so the copy stays lossless. The range flag is written as the probed range, because+ `h264_metadata` sets limited when the VUI had no signal type. A missing filter is a re-encode,+ not a refusal. Every run probes its output twice: ffprobe's stream tags and the first decoded+ frame's. From 8.1, ffprobe's stream tags follow the container's `colr` while the H.264 decoder+ still outputs the VUI's, so the stream tags alone passed a container-only copy there. A frame+ tag may be unspecified (8.1's ProRes decoder leaves frames untagged), but not different. Other+ tags after the copy mean a re-encode, said in+ `reencoded` and `notes`; other tags after the re-encode mean `kind: verification`. ProRes has no+ filter that writes every target (its transfer field has no BT.601), and ffprobe reads its+ container tag, so ProRes is a container retag. Code: `color.retag()`, `color.retag_bsf()`.+ Tests: `test_color_retag_rewrites_the_tags_the_stream_itself_carries`,+ `test_color_retag_fallback_keeps_extra_audio_and_subtitles_when_it_can`.+- **`--retag`'s re-encode puts the tags on the frames (`setparams`), not in output options.** From+ FFmpeg 7.1 `-colorspace` feeds the graph's colourspace negotiation and the encoder takes the+ frames' tags. A bt709 source retagged bt601 came out with a converted matrix and bt709+ primaries/transfer on 8.0.1 and 8.1.3, its pixels changed. setparams labels the frames, which+ every version's encoder writes: identical pixels and the requested tags on 6.1.1, 7.0.2, 8.0.1+ and 8.1.3. The same rule as `bt709_tag_args()`: on 7.1+ a tag is never an output option on a+ frame that does not already carry it. The other users of those options (`_cpu_encoder_args`,+ `_x265_hdr_default`, `_vt_args`) pass an HDR source's own probed tags, which its frames carry,+ so they convert nothing; one whose probe lacks a tag gets a default there, and that path is+ unchanged here. Code: `color.retag()`. Test:+ `test_color_retag_reencode_fallback_labels_the_frames`.- **`--correct` converts through bt601 on both legs** (not bt709), because on every testedFFmpeg the 709 round trip through 8-bit 4:2:0 loses ~5 dB more than 601. Code:`color.py _rgb_stage()`. Test: `test_color_correct_identity_holds_on_a_bt709_tagged_source`.@@ -1670,9 +1702,32 @@ not a new file format this tool would have to maintain.- **On 8.0, 8.0.1 and 8.1.0, a multi-line `graphics.py` label goes through libass under`--text-render auto`**, decided after the template has wrapped its labels (so `main()` runsonce more with the route forced). The releases are named, not probed: `--dry-run` may not start- ffmpeg, and a git build without a release number is taken to be fixed. `overlay.py` has no- libass route and warns in `notes` instead of drawing each line with its own `drawtext`, which- would change how a block is aligned. Code: `drawtext_draws_newline_glyph()`. Test:+ ffmpeg, and a git build without a release number is taken to be fixed. Code:+ `drawtext_draws_newline_glyph()`. Test:+ `test_multi_line_text_avoids_drawtext_on_releases_that_draw_the_line_break`.+- **On those releases a multi-line `overlay.py --text` is drawn one line per drawtext, at positions+ measured by a drawtext run, including under `--dry-run`.** overlay has no libass route, and+ libass would set the block differently (its lines are justified by the alignment, drawtext's are+ left-aligned in the block; its line spacing is its own). Through PR #346 overlay only warned in+ `notes`. Splitting the lines needs the block's numbers, and no multi-line drawtext on those+ releases has clean ones: every line but the last carries the box in its width. No filter can+ hand one drawtext's metrics to another either. So `drawtext_line_metrics()` measures each line+ alone: drawtext's own `print()` expression logs `text_w`, `top_a`, `bottom_d` and `lh` on a+ generated one-frame picture. The block is then rebuilt the way drawtext lays one out:+ `text_w` = the widest line, `text_h` = lh*(n-1) + the first line's top_a + the last line's+ bottom_d, lines left-aligned at x, baseline i at y + top_a + i*lh. Each line is drawn at its+ baseline (`y_align=baseline`) with the caller's x/y expressions, `text_w`/`text_h` replaced by+ those numbers. The outlines of all lines go first and the text second, as one drawtext draws+ them; otherwise a descender's outline covers the next line. `--box` is drawn once, by the first+ line, at the block's size (`boxw`/`boxh`). The result is bit-identical to one multi-line drawtext+ on 8.1.3 and 6.1.1 at every position tested, with and without `--box`. The 8.0.1 output is+ bit-identical to 8.1.3's single drawtext with DejaVu Sans. The cost of measuring is one small+ ffmpeg run, also under `--dry-run`, because a plan with guessed positions would not be the+ run's plan. Not exact: a font whose glyph boxes are not whole pixels (unhinted, e.g. FreeSerif+ Bold Italic) sits one row lower, because drawtext reports `top_a` rounded up. A fixed release+ plans the single drawtext it always did, byte for byte. Code: `overlay.per_line_drawtext()`,+ `_common.drawtext_line_metrics()`. Tests: `test_overlay_per_line_route_draws_what_one_multi_line_drawtext_draws`,+ `test_overlay_multi_line_text_draws_no_box_at_the_line_break`,`test_multi_line_text_avoids_drawtext_on_releases_that_draw_the_line_break`.## Unreleased — doctor's FFmpeg advisory and the Python 3.9 deprecationdiff --git a/references/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.mdindex e7f9dc1..fd96b86 100644--- a/references/ci-platform-pitfalls.md+++ b/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 thediff --git a/references/scripts.md b/references/scripts.mdindex d5984d1..02bbce7 100644--- a/references/scripts.md+++ b/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 shapingscript 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 thisfirst 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]diff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.pyindex ae4db2b..8974cf9 100644--- a/scripts/_common/__init__.py+++ b/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",diff --git a/scripts/_common/drawtext.py b/scripts/_common/drawtext.pyindex 576f313..c3ae5b7 100644--- a/scripts/_common/drawtext.py+++ b/scripts/_common/drawtext.py@@ -8,7 +8,7 @@ import osimport reimport shutilimport subprocess-from typing import Dict, Optional+from typing import Dict, List, Optionalfrom _common.decision import escape_filter_pathfrom _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 forevery 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 thesame 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 hashlibname = "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] = cleanedreturn 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 outdiff --git a/scripts/_common/runner.py b/scripts/_common/runner.pyindex 131fedd..7274611 100644--- a/scripts/_common/runner.py+++ b/scripts/_common/runner.py@@ -205,6 +205,7 @@ CODECS = ("h264", "hevc", "av1", "prores")_ENCODERS: Optional[set] = None+_BSFS: Optional[set] = Noneclass 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 inputwith the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""diff --git a/scripts/_common/text.py b/scripts/_common/text.pyindex bfc00c7..cf5068b 100644--- a/scripts/_common/text.py+++ b/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,diff --git a/scripts/_contract.py b/scripts/_contract.pyindex f386734..732b059 100644--- a/scripts/_contract.py+++ b/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[strelif 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"},@@ -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,diff --git a/scripts/color.py b/scripts/color.pyindex feb64b2..fb1850a 100755--- a/scripts/color.py+++ b/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 jsonimport osimport 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_secsTONEMAPS = ["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 0if 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 = Nonesdr_extra: dict = {}diff --git a/scripts/overlay.py b/scripts/overlay.pyindex e217273..ae1c6c5 100755--- a/scripts/overlay.py+++ b/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 reimport sysfrom typing import List, Optionalfrom _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], fadreturn "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 withcolours = [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 0diff --git a/tests/test_contract.py b/tests/test_contract.pyindex d6b7d30..3ded738 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -648,7 +648,7 @@ class ContractTests(unittest.TestCase):silently drifting out of sync with _contract.py again (issue #82). README's FAQ statesthe same list."""analysis_tools = set(_contract.DRY_RUN_ANALYSIS.keys())- self.assertEqual(analysis_tools, {"sync", "multicam", "scenes", "report", "cropdetect", "silence", "loudness", "check", "stabilize"},+ self.assertEqual(analysis_tools, {"sync", "multicam", "scenes", "report", "cropdetect", "silence", "loudness", "check", "stabilize", "overlay"},"the analysis-only dry-run tool set changed -- update SKILL.md/references/scripts.md's exception list to match")# "the name appears somewhere in the file" was too weak: every tool name is in SKILL.md's# request table anyway, so the list drifted twice (#176 -> #179) with this test green.@@ -774,6 +774,12 @@ class ContractTests(unittest.TestCase):self.assertIn("dropped_non_av_streams", doc)self.assertEqual(len(r["audio_streams"]) < 2 or r["subtitle_streams"] == 0, doc["dropped_non_av_streams"],"dropped_non_av_streams must accurately reflect what actually made it into the output")+ # and the re-encode carries the tags it was asked for (setparams on the frames: 7.1+'s+ # negotiation ignored the old output options), checked by the tool itself+ v = r["video"]+ self.assertEqual((v["color_space"], v["color_primaries"], v["color_transfer"]), ("bt709", "bt709", "bt709"))+ self.assertIn({"step": "color_tags", "ok": True, "color_space": "bt709", "color_primaries": "bt709",+ "color_transfer": "bt709"}, doc["verification"])def test_doctor_reports_this_installed_copys_own_version(self):"""`doctor`'s `version` is this installed copy's own version (never fetched from the@@ -1973,7 +1979,7 @@ class ContractTests(unittest.TestCase):if strict:self.assertFalse(marker.exists(), f"{name} --dry-run invoked ffmpeg")self.assertEqual({n for n, s in self.tools.items() if s["dry_run"]["ffmpeg_execution"] == "analysis_only"},- {"sync", "multicam", "scenes", "report", "cropdetect", "silence", "loudness", "check", "stabilize"})+ {"sync", "multicam", "scenes", "report", "cropdetect", "silence", "loudness", "check", "stabilize", "overlay"})# the read-only tools keep working under --dry-run (ffprobe still runs)self.assertEqual(tool("probe", self.src, "--dry-run", env=env).returncode, 0)self.assertEqual(tool("check", self.src, "--platform", "x", "--no-loudness", "--dry-run", env=env).returncode, 0)@@ -2714,7 +2720,9 @@ class ContractTests(unittest.TestCase):but the last (CI on ubuntu-latest: the lower-third's title measured as three yellow bands).graphics.py's auto route sends such a label -- given with a newline or wrapped there --through libass on those releases, keeps drawtext for one line and on fixed releases, and a- pinned --text-render drawtext warns; overlay.py, which has no libass route, says so in notes."""+ pinned --text-render drawtext warns. overlay.py has no libass route: it now draws each line+ with its own drawtext there, at the block's measured positions (PR #346 only warned in+ notes), and plans the single drawtext it always did on a fixed release."""bad = self._release_shim("nl_shim_801", "ffprobe version 8.0.1-3ubuntu2 Copyright (c) 2007-2025")good = self._release_shim("nl_shim_802", "ffprobe version 8.0.2 Copyright (c) 2007-2026")@@ -2735,12 +2743,25 @@ class ContractTests(unittest.TestCase):doc, err = gfx(bad, "--title", "CEO\nand founder", "--text-render", "drawtext")self.assertEqual(doc["text_renderer"], "drawtext")self.assertIn("warning: this ffmpeg's drawtext draws a box", err)- doc = json.loads(tool("overlay", self.src, "--text", "two\nlines", "--dry-run", "--json",- "-o", self.out("nl_ov.mp4"), env=bad).stdout)- self.assertTrue(any("missing-glyph box" in n for n in doc.get("notes", [])), doc.get("notes"))+ # The per-line route measures with drawtext's top_a/bottom_d and draws at y_align=baseline,+ # which FFmpeg has from 6.1; the shim only fakes the release, so the measuring ffmpeg is the+ # real one, and on the 5.1.1 job it cannot run what an 8.0.x build would.+ drawtext_help = subprocess.run(["ffmpeg", "-hide_banner", "-h", "filter=drawtext"],+ capture_output=True, text=True).stdout+ if "y_align" in drawtext_help:+ doc = json.loads(tool("overlay", self.src, "--text", "two\nlines", "--dry-run", "--json",+ "-o", self.out("nl_ov.mp4"), env=bad).stdout)+ self.assertNotIn("notes", doc)+ measure, draw = doc["commands"][0], doc["commands"][-1]+ self.assertIn("print(text_w", measure, "the lines are measured, even under --dry-run")+ self.assertEqual(draw.count("drawtext="), 4, "two lines, outlines then text")+ self.assertEqual(draw.count("y_align=baseline"), 4)+ self.assertNotIn("text_w", draw, "x/y carry the measured block size")doc = json.loads(tool("overlay", self.src, "--text", "two\nlines", "--dry-run", "--json","-o", self.out("nl_ov.mp4"), env=good).stdout)self.assertNotIn("notes", doc)+ self.assertEqual(len(doc["commands"]), 1)+ self.assertEqual(doc["commands"][0].count("drawtext="), 1)def test_fourth_review_p3_regressions(self):"""Fourth review P3 items: render re-encoded a clip at speed 1.0 (#47); a brand's defaultdiff --git a/tests/test_picture.py b/tests/test_picture.pyindex 163b3cb..51f2aab 100644--- a/tests/test_picture.py+++ b/tests/test_picture.py@@ -1078,6 +1078,65 @@ class PictureTests(MediaFixtures):script("overlay.py", self.src, "--text", "Episode 12", "--position", "bottom", "--box", "--start", "1", "--end", "5", "--fade", "0.3", "-o", out2)self.assertClose(probe(str(out2))["duration"], 12.0, 0.15)+ def _gray_clip(self, name):+ clip = OUT / name+ if not clip.exists():+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=0x404040:s=640x360:r=10",+ "-t", "1", "-c:v", "libx264", "-preset", "ultrafast", "-crf", "0", "-pix_fmt", "yuv420p", clip)+ return clip++ @staticmethod+ def _gray_frame(path):+ return subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "gray", "-"],+ stdout=subprocess.PIPE, check=True).stdout++ def test_overlay_multi_line_text_draws_no_box_at_the_line_break(self):+ """FFmpeg 8.0, 8.0.1 and 8.1.0 shape every line of a multi-line drawtext but the last WITH+ its newline, so the font's missing-glyph box was drawn after the line (PR #346 only+ warned). On those releases overlay.py draws each line with its own drawtext; on every+ build, nothing may be drawn to the right of a short first line inside the block."""+ clip, font = self._gray_clip("ov_nl_gray.mp4"), default_font_file("DejaVu Sans")+ common = ("--position", "top-left", "--font-color", "white", "--border", "0", "--quality", "0", "--preset", "ultrafast")+ if font:+ common += ("--font-file", font)+ one, two = OUT / "ov_nl_one.mp4", OUT / "ov_nl_two.mp4"+ script("overlay.py", clip, "--text", "Hi", *common, "-o", one)+ script("overlay.py", clip, "--text", "Hi\nmuch longer second line", *common, "-o", two)+ a, b, w = self._gray_frame(one), self._gray_frame(two), 640+ ink = lambda f, x, y: f[y * w + x] > 0x40 + 60 # noqa: E731+ rows = [y for y in range(360) if any(ink(a, x, y) for x in range(w))]+ right = max(x for x in range(w) for y in rows if ink(a, x, y))+ stray = [(x, y) for y in rows for x in range(right + 3, w) if ink(b, x, y)]+ self.assertEqual(stray, [], "ink after the first line: the line break was drawn")++ @unittest.skipIf(platform.system() == "Windows", "the release shim is a #!/bin/sh ffprobe on a POSIX-only PATH")+ def test_overlay_per_line_route_draws_what_one_multi_line_drawtext_draws(self):+ """The per-line route (taken on 8.0/8.0.1/8.1.0, forced here by an ffprobe that reports+ 8.0.1) must put every line where one multi-line drawtext puts it on a fixed release:+ widest line, first line's ascent, last line's descent, the font's line height, block box+ and outlines included. Runs where drawtext is right (6.1+, not an affected release), so+ the single drawtext is the reference."""+ import _common+ if _common.ffmpeg_version() < (6, 1) or _common.drawtext_draws_newline_glyph():+ self.skipTest("needs y_align (6.1+) and a drawtext that draws multi-line text right")+ shim = OUT / "ov_nl_shim"+ shim.mkdir(exist_ok=True)+ (shim / "ffprobe").write_text("#!/bin/sh\nif [ \"$1\" = \"-version\" ]; then printf 'ffprobe version 8.0.1\\n'; exit 0; fi\n"+ "exec %s \"$@\"\n" % shutil.which("ffprobe"))+ (shim / "ffprobe").chmod(0o755)+ bad = dict(os.environ, PATH=f"{shim}{os.pathsep}{os.environ['PATH']}")+ clip, font = self._gray_clip("ov_nl_gray.mp4"), default_font_file("DejaVu Sans")+ for pos, extra in (("center", ("--box",)), ("bottom-right", ()), ("top", ("--box", "--border", "0"))):+ args = ["--text", "Hello there\ngjy World wide\nÉg", "--position", pos, "--quality", "0", "--preset", "ultrafast", *extra]+ if font:+ args += ["--font-file", font]+ ref, per = OUT / f"ov_nl_ref_{pos}.mp4", OUT / f"ov_nl_per_{pos}.mp4"+ script("overlay.py", clip, *args, "-o", ref)+ doc = json.loads(script("overlay.py", clip, *args, "-o", per, "--json", env=bad).stdout)+ self.assertEqual(doc["commands"][-1].count("drawtext="), 6 if "0" not in extra else 3, pos)+ self.assertNotIn("notes", doc)+ self.assertEqual(self._gray_frame(ref), self._gray_frame(per), pos)+def test_overlay_text_scale_is_refused(self):"""--scale is a layer width. On --text it used to be accepted and ignored, so the drawstayed at fontsize 42 while the result said completed."""@@ -1137,6 +1196,76 @@ class PictureTests(MediaFixtures):self.assertIn("-c copy", proc.stderr)self.assertEqual(probe(str(out))["video"]["color_transfer"], "smpte170m")+ def _tagged(self, name, codec, params):+ src = OUT / name+ if not src.exists():+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=10",+ "-t", "1", "-c:v", codec, "-preset", "ultrafast", "-pix_fmt", "yuv420p", *params, src)+ return src++ @staticmethod+ def _tags(path):+ v = probe(str(path))["video"]+ return v["color_space"], v["color_primaries"], v["color_transfer"]++ @staticmethod+ def _frame_tags(path):+ """What the decoder hands a player: from 8.1 ffprobe's stream tags follow the container's+ colr even while an H.264 VUI still says otherwise."""+ keys = ("color_space", "color_primaries", "color_transfer")+ out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_frames", "-read_intervals", "%+#1",+ "-show_entries", "frame=" + ",".join(keys), "-of", "json", str(path)],+ stdout=subprocess.PIPE, text=True, check=True).stdout+ frame = json.loads(out)["frames"][0]+ return tuple(frame.get(k) for k in keys)++ @staticmethod+ def _pixels(path):+ out = subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-map", "0:v:0", "-f", "framemd5", "-"],+ stdout=subprocess.PIPE, text=True, check=True).stdout+ return [line for line in out.splitlines() if not line.startswith("#")]++ def test_color_retag_rewrites_the_tags_the_stream_itself_carries(self):+ """H.264/HEVC carry their colour description in the SPS VUI, which every decoder reads+ before the container: --retag used to stream-copy with -colorspace/-color_primaries/+ -color_trc (container only), report completed, and ffprobe still read the old tags. The+ copy now rewrites the VUI with h264_metadata/hevc_metadata, stays a copy (same decoded+ frames) and checks the tags it claims."""+ sources = [self._tagged("rt_h264_709.mp4", "libx264", ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"])]+ if "libx265" in __import__("_common").ffmpeg_encoders():+ sources.append(self._tagged("rt_hevc_709.mp4", "libx265",+ ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709:log-level=error"]))+ for src in sources:+ self.assertEqual(self._tags(src), ("bt709", "bt709", "bt709"))+ for target, want in (("bt601", ("smpte170m", "smpte170m", "smpte170m")),+ ("bt2020-hlg", ("bt2020nc", "bt2020", "arib-std-b67"))):+ out = OUT / f"rt_{src.stem}_{target}.mp4"+ doc = json.loads(script("color.py", src, "--retag", target, "-o", out, "--json").stdout)+ self.assertEqual(self._tags(out), want, f"{src.name} -> {target}")+ self.assertEqual(self._frame_tags(out), want, f"{src.name} -> {target}: decoded frames")+ self.assertFalse(doc["reencoded"], src.name)+ self.assertIn("_metadata=", doc["commands"][0])+ self.assertEqual(self._pixels(out), self._pixels(src), "a retag must not touch a picture")++ def test_color_retag_reencode_fallback_labels_the_frames(self):+ """When a copy cannot carry the tags (forced here by taking the bitstream filter away), the+ re-encode puts them on the frames with setparams. Its output options used to do it: from+ FFmpeg 7.1 those feed the graph's colourspace negotiation, which converted the matrix of a+ tagged source and kept its primaries and transfer (8.0.1, 8.1.3: bt709 in, smpte170m/+ bt709/bt709 out). The result says it re-encoded and why."""+ src = self._tagged("rt_h264_709.mp4", "libx264", ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"])+ out = OUT / "rt_fallback_bt601.mp4"+ code = ("import sys; sys.path.insert(0, %r); import color; color.retag_bsf = lambda meta, target: []; "+ "sys.argv = ['color.py', %r, '--retag', 'bt601', '-o', %r, '--json', '--overwrite', '--quality', '0', "+ "'--preset', 'ultrafast']; sys.exit(color.main())" % (str(SCRIPTS), str(src), str(out)))+ doc = json.loads(sh(sys.executable, "-c", code).stdout)+ self.assertTrue(doc["reencoded"])+ self.assertTrue(any("re-encoded with the tags on its frames" in n for n in doc["notes"]), doc.get("notes"))+ self.assertIn("setparams=color_primaries=smpte170m:color_trc=smpte170m:colorspace=smpte170m", doc["commands"][-1])+ self.assertNotIn("-colorspace", doc["commands"][-1])+ self.assertEqual(self._tags(out), ("smpte170m", "smpte170m", "smpte170m"))+ self.assertEqual(self._frame_tags(out), ("smpte170m", "smpte170m", "smpte170m"))+def test_color_audio_stream_selects_the_requested_track_not_always_the_first(self):two = OUT / "color_two_streams.mkv"sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",