ffmpeg-skill 2.10.10 → 2.11.0

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"),
@@ -393,6 +397,37 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     return schema
 
 
+# The collector's records (docs/design-decisions.md, "Nothing happens silently"): on success and
+# failure documents alike, present only when one list is not empty.
+DIAGNOSTICS_SCHEMA = {
+    "type": "object",
+    "description": "what the run decided on its own, recorded as it happened (each also a stderr line): warnings (something went "
+                   "other than asked), fallbacks (another route was taken and the run went on), skipped (a step that would "
+                   "normally run did not). Each entry is {code, message, ...facts}; an entry a render.py stage reported carries "
+                   "`stage`. Absent when all three are empty",
+    "properties": {k: {"type": "array", "items": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}
+                   for k in ("warnings", "fallbacks", "skipped")},
+}
+
+# error.reason: a stable code for why a refusal happened, beside `kind` (which says what class of
+# failure it is). Every refuse() call in scripts/ names one of these (a test reads the sources).
+ERROR_REASONS = {
+    "output_exists": "an output already exists and --overwrite was not given; details.outputs: [{path, resolved, size, mtime_ns}]",
+    "output_is_input": "the output resolves to the same file as an input; details: {output, input, resolved}",
+    "output_is_directory": "the output path is a directory; details: {output}",
+    "output_dir_missing": "the output's directory does not exist; details: {output, directory}",
+    "output_dir_not_writable": "the output's directory is not writable; details: {output, directory}",
+    "output_locked": "another run holds the output's lock; details: {lock, output, pid, pid_alive, deadline, why}",
+    "plan_inputs_changed": "render.py PLAN: a fingerprinted input is missing or changed; details: {plan, plan_sha256, checked_at, "
+                           "inputs: [{path, status: unchanged|changed|missing, expected: {size, sha256_head_tail}, actual: {size, "
+                           "sha256_head_tail} | \"missing\"}], unbound_inputs, audit_log}",
+    "plan_version_unsupported": "render.py PLAN: plan_version is not one this version executes; details: {plan, plan_sha256, checked_at, plan_version, supported, audit_log}",
+    "plan_unknown_tool": "render.py PLAN: the plan names no tool render.py can run; details: {plan, plan_sha256, checked_at, tool, audit_log}",
+    "plan_cwd_missing": "render.py PLAN: the directory the plan was made in is gone; details: {plan, plan_sha256, checked_at, cwd, audit_log}",
+    "plan_argv_invalid": "render.py PLAN: argv is not a list; details: {plan, plan_sha256, checked_at, argv_type, audit_log}",
+}
+
+
 def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str, Any]:
     """What the tool prints on stdout with --json (keys observed in the implementation). `hw`: the
     tool takes --hw, so its `notes` can also carry a VideoToolbox encode's quality line."""
@@ -407,7 +442,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
             "hw": {"type": "object", "description": "present when VideoToolbox was asked for (--hw, $FFMPEG_SKILL_HW, a render.py stage, a batch.py item), on export.py when $FFMPEG_SKILL_HW=1 is set but its delivery preset does not take it, and when this ffmpeg build has no libx264/libx265 and an encode ran on VideoToolbox instead: {requested: whether this run's encodes were asked onto VideoToolbox (false for that export, and for the build without libx264/libx265), source: flag|env|auto (auto: nobody asked, the build has no libx264/libx265 and this Apple Silicon machine ran VideoToolbox in its place), used: true|false whether the encoder that ran last is VideoToolbox, null under --dry-run (nothing ran) and when this process ran no encode itself (batch.py: its stages are child processes; its top-level hw gathers the items' requested/source/fallback/notes and each results row carries its item's encoder and hw), fallback: a job VideoToolbox refused (encoder open or compression session failure; nothing else is retried) was re-encoded on the CPU, notes: why an encode stayed on or fell back to the CPU, and, when $FFMPEG_SKILL_HW chose the GPU and it ran, what that costs and that --no-hw opts out}. A VideoToolbox encode also adds a top-level notes line: its quality is not CRF-equivalent. A kind: ffmpeg failure under --hw / $FFMPEG_SKILL_HW carries encoder and hw too"},
             "plan": {"type": "string", "description": "with --plan FILE: the plan document written (the run itself is a dry run)"},
             "verified": {"type": "boolean", "description": "true only when the artifact was written, probed, and every self-check the tool ran (verification) met its target; false under --dry-run"},
-            "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets) or check (render)"}}
+            "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets) or check (render)"},
+            "diagnostics": DIAGNOSTICS_SCHEMA}
     extra: Dict[str, Any] = {}
     if name == "check":
         extra = {"platform": {"type": "string"}, "ok": {"type": "boolean"}, "failed": {"type": "integer"}, "warnings": {"type": "integer"},
@@ -444,11 +480,11 @@ 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"},
+                 "plan_sha256": {"type": ["string", "null"], "description": "plan execution: sha256 of the plan file as executed"},
+                 "unbound_inputs": {"type": "array", "items": {"type": "string"}, "description": "plan execution: inputs that did not exist when the plan was made, so carry no fingerprint and were not checked (also a diagnostics.warnings entry, code plan_unbound_inputs)"},
                  "tool": {"type": "string", "description": "plan execution: the tool the plan ran"},
                  "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"},
                  "timeline": {"type": "object", "description": "--export-timeline: format, rate, duration, frames, clips, transition, "
@@ -473,7 +509,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"},
@@ -1689,8 +1726,22 @@ 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"},
+            "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ..., \"code\": ..., \"retryable\": false}, \"commands\": [...]} when --json was given; a refusal adds error.reason (error_reasons) and error.details (the facts the message is written from), and a run that recorded warnings, fallbacks or skipped steps before failing carries diagnostics", "stderr": "human-readable message",
+                        "error": {"kind": "error_kinds", "message": "the reason in prose", "code": "a static relabelling of kind", "retryable": "always false",
+                                  "hint": "optional: the flag change that would make a retry meaningful",
+                                  "reason": "optional, on refusals: a stable code from error_reasons",
+                                  "details": "optional, with reason: an object of the facts behind the refusal (paths, expected and actual values)"},
+                        "diagnostics": DIAGNOSTICS_SCHEMA["description"]},
+            "error_reasons": ERROR_REASONS,
+            "audit_log": {"format": "JSON lines, appended: {ts, tool, event, pid, plan_sha256 (plan events), details}",
+                          "events": {"plan_rejected": "render.py refused a plan (details: the refusal's error.details plus reason)",
+                                     "lock_takeover": "a stale output lock was taken over (details: lock, output, pid, pid_alive, deadline, why)",
+                                     "output_unlocked": "no output lock could be created and the run went on without one",
+                                     "output_is_input_refused": "the output-is-input refusal (only when an audit log was named)"},
+                          "location": "render.py --audit-log FILE when given; otherwise a refused plan's <plan>.audit.jsonl, and a lock event's "
+                                      "hidden .<output>.ffskill-audit.jsonl beside the output. Never written under --dry-run; a write that "
+                                      "fails is a diagnostics.warnings entry (audit_log_unwritable), never a failure"},
+            "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