ffmpeg-skill 3.1.7 → 3.2.0

package/scripts/export.py

@@ -15,6 +15,13 @@ Presets:
   youtube-av1 1080p AV1 (libsvtav1, libaom fallback); missing_tool when neither is built
   x         1280x720 H.264 CRF 22, AAC 128k, max 140 s (Twitter/X)
   prores    ProRes 422 HQ .mov, PCM 16-bit audio (editing master)
+  dnxhr-lb / dnxhr-sq / dnxhr-hq   DNxHR 8-bit 4:2:2 .mov, PCM 16-bit audio
+  dnxhr-hqx DNxHR HQX 10-bit 4:2:2;  dnxhr-444  DNxHR 444 10-bit 4:4:4
+            (editing masters at the source's size and rate, like prores)
+  key-fill  fill + key pair (<out>, <out stem>_key.mov) from an alpha source
+  prores4444 / prores4444xq / qtrle / vp9-alpha / hap-alpha
+            masters that keep the source's alpha (refused without one);
+            --alpha-mode straight|premultiplied; alpha read back after
   h265      HEVC CRF 24 (libx265) with hvc1 tag for Apple compatibility
   gif       480px wide palette-optimised GIF at 12 fps (short previews)
   copy      stream copy, no re-encode: same codecs, container and colour
@@ -25,6 +32,7 @@ Examples:
   python3 export.py final.mp4 --preset reels --fit crop
   python3 export.py final.mp4 --preset reels --normalize   # meet the platform's loudness in the same call
   python3 export.py final.mp4 --preset prores -o master.mov
+  python3 export.py final.mp4 --preset dnxhr-hq -o master.mov
   python3 export.py final.mp4 --preset copy -o delivered.mp4
   python3 export.py --list
 """
@@ -38,11 +46,13 @@ import tempfile
 from pathlib import Path
 from typing import Dict, List
 
+from _common.runner import child_exit_code, fail_if_classified, kept_clause, mark_delivered
 from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import square_pixels, square_pixels_note
-from _common.runner import subtitle_codec_for
+from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, run_analysis as _run_analysis, subtitle_codec_for
+from _common.emit import file_identity
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
@@ -90,7 +100,44 @@ PRESETS: Dict[str, Dict] = {
     "youtube4k": dict(_from_table("youtube", w=3840, h=2160, max=None), ext="mp4", video=_H264_HIGH, audio=_AAC_192, desc="2160p H.264, AAC 192k"),
     "reels": dict(_from_table("reels"), ext="mp4", video=_social(), audio=_AAC_128, desc="9:16 1080x1920, 30fps, max 90s (Instagram Reels)"),
     "x": dict(_from_table("x"), ext="mp4", video=_social("22"), audio=["-c:a", "aac", "-b:a", "128k", "-ar", "44100"], desc="720p H.264, max 140s (Twitter/X)"),
-    "prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},
+    "prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "intermediate": True,
+               "expect": {"codec": "prores", "profile": "HQ", "pix_fmt": "yuv422p10le"}, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},
+    # DNxHR (the dnxhd encoder's resolution-independent profiles): editing masters like prores, at
+    # the source's size and rate; the written profile and pixel format are checked after the write
+    **{f"dnxhr-{name}": {"w": None, "h": None, "ext": "mov",
+                         "video": ["-c:v", "dnxhd", "-profile:v", f"dnxhr_{name}", "-pix_fmt", pix],
+                         "audio": ["-c:a", "pcm_s16le"], "max": None, "intermediate": True,
+                         "expect": {"codec": "dnxhd", "profile": f"DNXHR {name.upper()}", "pix_fmt": pix},
+                         "desc": f"DNxHR {name.upper()} master ({desc}), PCM audio, source resolution"}
+       for name, pix, desc in (("lb", "yuv422p", "8-bit 4:2:2, low bandwidth"), ("sq", "yuv422p", "8-bit 4:2:2, standard"),
+                               ("hq", "yuv422p", "8-bit 4:2:2, high quality"), ("hqx", "yuv422p10le", "10-bit 4:2:2"),
+                               ("444", "yuv444p10le", "10-bit 4:4:4"))},
+    # Alpha masters (#417): editing masters that keep the source's alpha channel; the alpha is read
+    # back from a written frame and compared with the source's. A source without alpha is refused.
+    "prores4444": {"w": None, "h": None, "ext": "mov", "alpha": True, "intermediate": True,
+                   "video": ["-c:v", "prores_ks", "-profile:v", "4", "-vendor", "apl0", "-pix_fmt", "yuva444p10le", "-alpha_bits", "16"],
+                   "audio": ["-c:a", "pcm_s16le"], "max": None, "expect": {"codec": "prores", "profile": "4444"},
+                   "desc": "ProRes 4444 with alpha (16-bit alpha), PCM audio, source resolution"},
+    "prores4444xq": {"w": None, "h": None, "ext": "mov", "alpha": True, "intermediate": True,
+                     "video": ["-c:v", "prores_ks", "-profile:v", "5", "-vendor", "apl0", "-pix_fmt", "yuva444p10le", "-alpha_bits", "16"],
+                     "audio": ["-c:a", "pcm_s16le"], "max": None, "expect": {"codec": "prores", "profile": "XQ"},
+                     "desc": "ProRes 4444 XQ with alpha (16-bit alpha), PCM audio, source resolution"},
+    "qtrle": {"w": None, "h": None, "ext": "mov", "alpha": True, "intermediate": True,
+              "video": ["-c:v", "qtrle", "-pix_fmt", "argb"], "audio": ["-c:a", "pcm_s16le"], "max": None,
+              "expect": {"codec": "qtrle", "pix_fmt": "argb"}, "desc": "QuickTime Animation (lossless RGB + alpha), PCM audio"},
+    "vp9-alpha": {"w": None, "h": None, "ext": "webm", "alpha": True, "intermediate": True,
+                  "video": ["-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-crf", "20", "-b:v", "0", "-row-mt", "1"],
+                  "audio": ["-c:a", "libopus", "-b:a", "128k"], "max": None, "expect": {"codec": "vp9"},
+                  "desc": "WebM VP9 with alpha (CRF 20), Opus audio, source resolution"},
+    "hap-alpha": {"w": None, "h": None, "ext": "mov", "alpha": True, "intermediate": True,
+                  "video": ["-c:v", "hap", "-format", "hap_alpha"], "audio": ["-c:a", "pcm_s16le"], "max": None,
+                  "expect": {"codec": "hap"}, "desc": "HAP Alpha (needs an ffmpeg built with snappy; size a multiple of 4), PCM audio"},
+    # Key and fill for a switcher's downstream keyer (#418): two ProRes 422 HQ files from one alpha
+    # source, the fill (colour) and the key (the alpha as a luma matte), frame for frame.
+    "key-fill": {"w": None, "h": None, "ext": "mov", "alpha": True, "intermediate": True, "keyfill": True,
+                 "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"],
+                 "audio": ["-c:a", "pcm_s16le"], "max": None,
+                 "desc": "fill + key pair (<out> and <out stem>_key.mov), ProRes 422 HQ, frame for frame, for a switcher's keyer"},
     "h265": {"w": None, "h": None, "ext": "mp4", "video": ["-c:v", "libx265", "-preset", "medium", "-crf", "24", "-pix_fmt", "yuv420p", "-tag:v", "hvc1"], "audio": ["-c:a", "aac", "-b:a", "160k"], "max": None, "desc": "HEVC CRF 24, hvc1 tag, source resolution"},
     "gif": {"w": 480, "h": None, "ext": "gif", "video": [], "audio": [], "max": None, "desc": "480px palette GIF, 12fps"},
     "copy": {"w": None, "h": None, "ext": None, "video": ["-c:v", "copy"], "audio": ["-c:a", "copy"], "max": None, "desc": "stream copy, no re-encode (source codecs/container/colour tags unchanged)"},
@@ -125,6 +172,188 @@ PLATFORM_OF["youtube4k"] = PLATFORM_TABLE["youtube"]["check"]
 PRESET_CHOICES: List[str] = sorted(set(PRESETS) | {a for a in _ALIASES if resolve_platform(a) in PRESETS})
 
 
+# A pixel format that carries an alpha plane (yuva*, rgba, argb, gbrap, ya8/ya16, ...).
+_ALPHA_PIX = re.compile(r"^(yuva|gbrap|ya\d|rgba|bgra|argb|abgr|rgba64|bgra64)")
+
+
+def vp9_decoder_args(codec: "str | None") -> List[str]:
+    """The input option that decodes a VP9 stream with libvpx-vp9: FFmpeg's native vp9 decoder
+    drops the alpha layer (a WebM's yuva420p comes out yuv420p, fully opaque). [] for any other
+    codec, or when this build has no libvpx (its encoder list stands in for the decoder's)."""
+    return ["-c:v", "libvpx-vp9"] if codec == "vp9" and "libvpx-vp9" in ffmpeg_encoders() else []
+
+
+def vp9_alpha_tagged(path: str) -> bool:
+    """True when the first video stream is VP9 stored with an alpha layer (Matroska/WebM's
+    ALPHA_MODE=1 stream tag): ffprobe reports such a stream as yuv420p, so the pixel format alone
+    does not show the alpha. A metadata read, so a dry run can decide without decoding."""
+    proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "v:0", "-show_entries",
+                "stream=codec_name:stream_tags", "-of", "json", path], quiet=True)
+    try:
+        streams = json.loads(proc.stdout or "{}").get("streams") or []
+    except ValueError:
+        return False
+    s = streams[0] if streams else {}
+    return s.get("codec_name") == "vp9" and any(k.lower() == "alpha_mode" and str(v).strip() == "1"
+                                                for k, v in (s.get("tags") or {}).items())
+
+
+_MEASURE_W, _MEASURE_H = 64, 36  # the measuring copy: small enough to read every frame, large enough for exact edges
+
+
+def _frame_means(cmd_head: List[str], path: str, chain: str) -> "Dict[str, object] | None":
+    """Every decoded frame of `path` through `chain` to a 64x36 grey copy: {mean (over every frame),
+    min (the lowest frame's mean), frames, per_frame (each frame's mean, in decode order)}. None
+    when no frame decodes."""
+    w, h = _MEASURE_W, _MEASURE_H
+    cmd = cmd_head + ["-i", path, "-map", "0:v:0", "-vf", f"{chain},scale={w}:{h}:flags=area,format=gray",
+                      "-f", "rawvideo", "-"]
+    proc = _run_analysis(cmd, check=False, text=False)
+    data = proc.stdout or b""
+    size = w * h
+    if proc.returncode != 0 or len(data) < size:
+        return None
+    frames = [sum(data[i:i + size]) / size for i in range(0, len(data) - size + 1, size)]
+    return {"mean": sum(frames) / len(frames), "min": min(frames), "frames": len(frames), "per_frame": frames}
+
+
+def alpha_stats(path: str, codec: "str | None" = None) -> "Dict[str, object] | None":
+    """The alpha (0-255) of every decoded frame, on a 64x36 copy: {mean, min, frames, per_frame}.
+    255.0 is fully opaque, and a picture with no alpha plane reads 255 too (format=rgba fills it).
+    Every frame, not the first: a clip that opens fully opaque and turns transparent later would
+    read as opaque from its first frame, in the source and in a written file that lost its alpha.
+    A VP9 file is decoded with libvpx-vp9 (vp9_decoder_args). None when no frame decodes."""
+    head = [require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin"] + vp9_decoder_args(codec)
+    return _frame_means(head, path, "format=rgba,alphaextract")
+
+
+ALPHA_TOLERANCE = 2.0  # of 255, per frame (or on the mean and the most transparent frame, below)
+OPAQUE = 254.5         # a frame whose mean alpha is at least this is fully opaque
+
+
+def _alpha_compare(written, source) -> Dict[str, object]:
+    """The written file's alpha against the source's. With the same number of frames, frame by
+    frame (frame i against frame i, each within ALPHA_TOLERANCE): an aggregate let a loss confined
+    to a few frames through (one of 200 frames turned opaque moves the mean by ~1). With a
+    different count (a variable-rate source conformed to a constant rate repeats or drops frames,
+    so indices no longer pair), the mean and the most transparent frame, and `paired: false`
+    says so. {ok, paired, worst_delta, worst_frame}."""
+    if written is None or source is None:
+        return {"ok": False, "paired": None, "worst_delta": None, "worst_frame": None}
+    w, s = written.get("per_frame") or [], source.get("per_frame") or []
+    if w and len(w) == len(s):
+        deltas = [abs(a - b) for a, b in zip(w, s)]
+        worst = max(range(len(deltas)), key=deltas.__getitem__)
+        return {"ok": deltas[worst] <= ALPHA_TOLERANCE, "paired": True, "worst_delta": round(deltas[worst], 2),
+                "worst_frame": worst}
+    delta = max(abs(written["mean"] - source["mean"]), abs(written["min"] - source["min"]))
+    return {"ok": delta <= ALPHA_TOLERANCE, "paired": False, "worst_delta": round(delta, 2), "worst_frame": None}
+
+
+def _rounded(st) -> "Dict[str, float] | None":
+    return None if st is None else {"mean": round(st["mean"], 2), "min": round(st["min"], 2), "frames": st["frames"]}
+
+
+def key_path(fill: str) -> str:
+    stem, _ = os.path.splitext(fill)
+    return f"{stem}_key.mov"
+
+
+def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[str], has_audio: bool,
+              source_alpha, notes: List[str], subs: List[Dict], data: List[Dict]) -> int:
+    """--preset key-fill: one decode split into the fill (the colour, straight or premultiplied)
+    and the key (alphaextract: alpha 255 is video white, 0 black), both ProRes 422 HQ in one ffmpeg
+    run so they hold the same frames; the source's start timecode is written on both. Checked
+    after: the same frame count, size, rate and length, the key's mean level against the source's
+    alpha, and both files hashed (output_identity, key.identity)."""
+    key = key_path(output)
+    # both files are this run's outputs, but ffmpeg's last argument (which run() guards and stages)
+    # is only the key: the fill is checked here the same way -- not the input under another
+    # spelling, not someone's file without --overwrite -- and written through a hidden temp file
+    guard_sidecar(output, args.input, siblings=[key])
+    guard_sidecar(key, args.input, siblings=[output])
+    if STATE.hw and "-c:v" in p["video"]:
+        note(f"--hw: --preset {args.preset} stays on {p['video'][p['video'].index('-c:v') + 1]}: one ffmpeg run writes "
+             "the fill and the key as a pair, and VideoToolbox's ProRes encoder is not used for it")
+    fill_chain = ",".join(vf + (["premultiply=inplace=1"] if args.alpha_mode == "premultiplied" else []) + ["format=yuv422p10le"])
+    key_chain = ",".join(vf + ["alphaextract", "format=yuv422p10le"])
+    tc = ((meta.get("timecode") or {}).get("value"))
+    tc_args = ["-timecode", tc] if tc else []
+    cmd = cmd + ["-filter_complex", f"[0:v:0]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
+    cmd += ["-map", "[fill]"] + (["-map", "0:a:0"] if has_audio else []) + p["video"] + tc_args + cfr_args(meta)
+    # the fill is always written to a hidden sibling and moved into place only after the encode
+    # succeeds: run() stages and cleans up only ffmpeg's last output (the key), so a failed encode
+    # left a partial new fill (the retry was refused as output_exists) or truncated an existing one
+    fill_tmp = None
+    if not STATE.dry_run:
+        d, base = os.path.split(output)
+        stem, ext = os.path.splitext(base)
+        fill_tmp = os.path.join(d, f".{stem}.ffskill-fill-{os.getpid()}{ext}")
+    cmd += (p["audio"] if has_audio else ["-an"]) + [fill_tmp or output]
+    cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key]
+    try:
+        run(cmd)
+        if fill_tmp:
+            os.replace(fill_tmp, output)
+    finally:
+        if fill_tmp:
+            # the command is recorded with the path the caller asked for, not the temp name
+            STATE.commands[:] = [c.replace(fill_tmp, output) for c in STATE.commands]
+            if os.path.exists(fill_tmp):
+                os.remove(fill_tmp)
+    remember_written(output, key)
+    extra: Dict[str, object] = {"alpha_mode": args.alpha_mode or "straight", "key": {"output": key}}
+    # a fill and a key for a switcher carry the picture and the sound; the source's subtitle and
+    # data streams are not written, and the document says so (as for a GIF)
+    non_av = _non_av_report(subs, [], data, ["subtitle", "data"], output, "key_fill")
+    extra["non_av_streams"] = non_av
+    extra["dropped_non_av_streams"] = bool(non_av["dropped"])
+    if non_av["dropped"]:
+        notes.append(f"a key/fill pair holds the picture and the sound only: the source's {len(non_av['dropped'])} "
+                     "subtitle/data stream(s) were not written; non_av_streams lists them")
+    if STATE.dry_run:
+        emit(output, **extra, **({"notes": notes} if notes else {}))
+        return 0
+    fill_m, key_m = probe(output, role="output"), probe(key, role="output")
+    fv, kv = fill_m["video"], key_m["video"]
+    pair = {k: [fv.get(k), kv.get(k)] for k in ("width", "height", "nb_frames", "r_frame_rate")}
+    # the video streams' lengths: the fill's container also counts its sound, which may run longer
+    # than the picture, and the key has none
+    pair["duration"] = [round(v.get("duration") or v.get("tagged_duration") or 0, 3) for v in (fv, kv)]
+    same = all(a == b and a not in (None, 0) for a, b in pair.values())
+    steps = [{"step": "key_fill_pair", "property": "frames_size_rate_length", "ok": same, "measured": pair,
+              "provenance": "output_measurement"}]
+    key_level = _luma_stats(key)
+    level = _alpha_compare(key_level, source_alpha)
+    steps.append({"step": "key_level", "property": "key_mean_vs_source_alpha", "ok": level["ok"], "comparison": level,
+                  "expected": None if source_alpha is None else round(source_alpha["mean"], 2),
+                  "measured": None if key_level is None else round(key_level["mean"], 2), "tolerance": ALPHA_TOLERANCE,
+                  "frames": {"expected": _rounded(source_alpha), "measured": _rounded(key_level)},
+                  "provenance": "input_premeasurement"})
+    extra["key"] = {"output": key, "identity": file_identity(key), "sha256": _sha256(key), "timecode": tc}
+    extra["fill_sha256"] = _sha256(output)
+    info(f"wrote {output} (fill) and {key} (key), {fv['width']}x{fv['height']}, {fv.get('nb_frames')} frames each")
+    emit(output, verification=steps, expect_streams={"video": 1, "audio": 1 if has_audio else 0}, **extra,
+         **({"notes": notes} if notes else {}))
+    return 0
+
+
+def _sha256(path: str) -> str:
+    """The whole file's SHA-256: a key/fill pair is handed to a playout system as two files that
+    must stay a pair, and the hashes let it check that neither was replaced."""
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _luma_stats(path: str) -> "Dict[str, float] | None":
+    """The level (0-255) of every frame of a file, on a 64x36 grey copy: {mean, min, frames}."""
+    return _frame_means([require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin"], path, "format=gray")
+
+
 def _loudness_unmeasured(extra: Dict[str, object], notes: List[str], platform: str, spec: Dict, normalized: bool = False) -> None:
     """The written file's loudness could not be read (ffmpeg's loudnorm JSON did not parse): the
     platform's loudness was not verified, and the document says so -- a `loudness` block with null
@@ -183,6 +412,9 @@ def _run_keeping_non_av(cmd: List[str], output: str, sub_codecs: List[str], data
         attempt = run(cmd + extra + [output], check=False)
         if attempt.returncode == 0:
             return dropped
+        # a full disk or a missing encoder fails every rung the same way: that error, not a
+        # fallback that blames the subtitles and encodes again (#415, #389's rule)
+        fail_if_classified(attempt)
         error = " | ".join([ln.strip() for ln in (attempt.stderr or "").splitlines() if ln.strip()][-3:])[-500:]
         going = rungs[n + 1][1]
         record_fallback(f"{os.path.basename(output)} could not hold the source's {' and '.join(t for t in ('subtitle', 'data') if t in going)} "
@@ -311,6 +543,9 @@ def main() -> int:
                     help="fit the file under MB megabytes (MiB): a two-pass x264 encode at the video bitrate the "
                          "running time leaves after the audio, measured afterwards (H.264 presets; not with --crf or --hw)")
     ap.add_argument("--normalize", action="store_true", help="youtube/youtube4k/reels/x: when the written file misses the platform's loudness spec, run loudness.py on it (audio re-encoded, video copied) so one export delivers")
+    ap.add_argument("--alpha-mode", choices=["straight", "premultiplied"],
+                    help="alpha presets (prores4444, prores4444xq, qtrle, vp9-alpha, hap-alpha): write the colour straight "
+                         "(default, as decoded) or premultiplied by the alpha; written to the result as alpha_mode")
     ap.add_argument("--list", action="store_true", help="list presets and exit")
     add_common(ap, codec=False)  # the preset decides the codec; --codec would only be refused
     args = ap.parse_args()
@@ -340,14 +575,39 @@ def main() -> int:
         die(f"--preset {args.preset} delivers HDR and this source is SDR ({meta['video'].get('codec')}, "
             f"{meta['video'].get('color_transfer') or 'untagged'})",
             hint="use --preset youtube for an SDR delivery; there is no way to invent HDR range from an SDR master")
-    if meta["video"].get("bt2020_or_hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
+    if meta["video"].get("bt2020_or_hdr") and not p.get("intermediate") and args.preset not in ("copy", "youtube-hdr"):
         # 2.0: `hdr` is a real PQ/HLG/DV signal; bt2020_or_hdr also covers BT.2020 SDR, which is
         # not HDR but still needs converting before BT.709 tags describe it (eval 24 h1)
         kind = "HDR" if meta["video"].get("hdr") else "wide-gamut SDR, not HDR"
         notes.append("source is %s (%s). This preset outputs SDR BT.709 tags without converting it; run color.py --to-sdr first for correct colours." % (kind, meta["video"].get("hdr_format")))
         warn(notes[-1], "colour_not_converted", preset=args.preset, hdr_format=meta["video"].get("hdr_format"))
     has_audio = bool(meta.get("audio"))
-    output = args.output or default_output(args.input, args.preset, p["ext"])
+    source_alpha = None
+    if p.get("alpha"):
+        encoder = p["video"][p["video"].index("-c:v") + 1]
+        encoders = ffmpeg_encoders()
+        if encoders and encoder not in encoders:
+            die(f"--preset {args.preset} needs the {encoder} encoder and this ffmpeg build has none"
+                + (" (HAP needs an ffmpeg built with snappy)" if encoder == "hap" else ""),
+                kind="missing_tool", error_extra={"reason": "encoder_missing", "details": {"name": encoder}},
+                hint="python3 scripts/_contract.py doctor lists the encoders this build has")
+        if encoder == "hap" and (meta["video"]["width"] % 4 or meta["video"]["height"] % 4):
+            die(f"--preset hap-alpha needs a width and height that are multiples of 4 (HAP's texture blocks); "
+                f"this source is {meta['video']['width']}x{meta['video']['height']}",
+                hint="crop or pad it first (crop.py, pad.py)")
+        # a pixel format with an alpha plane, or a VP9 stream stored with one (probed as yuv420p);
+        # a dry run decides on these metadata reads alone and decodes nothing
+        has_alpha_plane = bool(_ALPHA_PIX.match(meta["video"].get("pix_fmt") or "")) or vp9_alpha_tagged(args.input)
+        if not STATE.dry_run:
+            source_alpha = alpha_stats(args.input, meta["video"].get("codec"))
+        if not has_alpha_plane and (STATE.dry_run or source_alpha is None or source_alpha["min"] >= OPAQUE):
+            die(f"--preset {args.preset} keeps an alpha channel and this source has none "
+                f"({meta['video'].get('pix_fmt')}, fully opaque): use prores or dnxhr-* for an opaque master")
+    elif args.alpha_mode:
+        die("--alpha-mode applies only to the alpha presets (prores4444, prores4444xq, qtrle, vp9-alpha, hap-alpha)")
+    # copy keeps the source's container, so its default name keeps the source's extension (as
+    # metadata.py's does): default_output()'s .webm -> .mp4 is for the re-encoding presets
+    output = args.output or default_output(args.input, args.preset, p["ext"] or Path(args.input).suffix.lstrip(".") or None)
     out_ext = Path(output).suffix.lstrip(".").lower()
 
     vf: List[str] = []
@@ -376,7 +636,12 @@ def main() -> int:
     if args.max_mb is not None and args.preset == "gif":
         # the GIF branch below returns before the size is ever applied or measured
         die("--max-mb runs a two-pass x264 encode; --preset gif does not encode with x264 (shorten or shrink the GIF instead)")
-    cmd = ffmpeg_base() + (REPAIR_INPUT_ARGS if args.repair else []) + ["-i", args.input]
+    if args.max_mb is not None and p.get("keyfill"):
+        # the key/fill branch below writes ProRes and returns before the size is applied or measured
+        die("--max-mb runs a two-pass x264 encode; --preset key-fill writes ProRes (a fill and a key), which has no size target")
+    # an alpha source in VP9 is decoded with libvpx-vp9, or its alpha never reaches the encoder
+    dec_args = vp9_decoder_args(meta["video"].get("codec")) if p.get("alpha") else []
+    cmd = ffmpeg_base() + (REPAIR_INPUT_ARGS if args.repair else []) + dec_args + ["-i", args.input]
     # Subtitle and data streams (a soft-subtitle track muxed upstream, a camera's timecode) are
     # kept where the container can hold them: ffmpeg's default stream selection takes one video
     # and one audio stream only, and through 2.22.1 every preset dropped the rest without a word.
@@ -384,7 +649,7 @@ def main() -> int:
     subs = meta.get("subtitle_stream_details") or []
     data = _data_streams(args.input) if meta.get("data_streams") else []
     sub_codecs = [_subtitle_codec(s.get("codec") or "", out_ext) for s in subs]
-    if args.preset != "gif" and (subs or data):
+    if args.preset != "gif" and not p.get("keyfill") and (subs or data):
         cmd += ["-map", "0:V:0"] + (["-map", "0:a:0"] if has_audio else [])
 
     if args.preset == "gif":
@@ -399,6 +664,10 @@ def main() -> int:
         emit(output, non_av_streams=non_av, dropped_non_av_streams=bool(non_av["dropped"]), **({"notes": notes} if notes else {}))
         return 0
 
+    if p.get("keyfill"):
+        return _key_fill(args, p, meta, output, cmd, vf, has_audio, source_alpha, notes, subs, data)
+    if p.get("alpha") and args.alpha_mode == "premultiplied":
+        vf.append("premultiply=inplace=1")
     if vf:
         cmd += ["-vf", ",".join(vf)]
     video = list(p["video"])
@@ -419,9 +688,14 @@ def main() -> int:
         video[video.index("-crf") + 1] = str(args.crf)
     if STATE.fast and "-preset" in video and not p.get("codec"):
         video[video.index("-preset") + 1] = "veryfast"
-    # a fixed preset's line is tagged BT.709 (prores, an editing master, keeps the source's tags)
-    tag_bt709 = args.preset not in ("prores",) and not p.get("codec")
-    if not p.get("codec") and video:
+    # a fixed preset's line is tagged BT.709 (prores and dnxhr, editing masters, keep the source's tags)
+    tag_bt709 = not p.get("intermediate") and not p.get("codec")
+    if p.get("alpha") and STATE.hw and video and video[video.index("-c:v") + 1] == "prores_ks":
+        # VideoToolbox's ProRes line is 422 HQ: under --hw a 4444 alpha master would come out
+        # opaque, so these presets stay on prores_ks and say so
+        note(f"--hw: --preset {args.preset} stays on prores_ks: VideoToolbox's ProRes encoder writes 422 HQ, "
+             "without the alpha this preset keeps")
+    elif not p.get("codec") and video:
         # --hw (never $FFMPEG_SKILL_HW here) puts a fixed preset on VideoToolbox: the same codec,
         # its CRF mapped to -q:v, the preset's frame rate kept; tags come with the VT line itself.
         # A build without libx264/libx265 has no other encoder, so it goes there without --hw too
@@ -437,8 +711,8 @@ def main() -> int:
             cmd += cfr_args(meta)
         if tag_bt709 and not video[video.index("-c:v") + 1].endswith("_videotoolbox"):
             cmd += bt709_tag_args(video[video.index("-c:v") + 1])
-        if args.preset != "prores":
-            # every line but the prores master's says BT.709 (the fixed presets' tags above, an
+        if not p.get("intermediate"):
+            # every line but an editing master's (prores, dnxhr) says BT.709 (the fixed presets' tags above, an
             # SDR hevc/av1 line's own): a BT.601 source's pixels are converted to match, in front
             # of the -vf above (run() folds the two); an untagged, BT.709 or HDR source adds nothing
             cmd += bt709_matrix_args(meta)
@@ -466,10 +740,36 @@ def main() -> int:
         dropped = _run_keeping_non_av(cmd, output, sub_codecs, len(data)) if (subs or data) else []
         if not (subs or data):
             run(cmd + [output])
+    if not STATE.dry_run:
+        # the export is on disk: a stop in the reads and the --normalize pass that follow keeps it,
+        # and says so (#415)
+        mark_delivered(output)
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']})")
     extra: Dict[str, object] = {"trimmed": trimmed} if trimmed else {}
+    encoder = video[video.index("-c:v") + 1] if "-c:v" in video else None
+    if p.get("expect") and not STATE.dry_run and encoder == p["video"][p["video"].index("-c:v") + 1]:
+        # an editing master is asked for by codec, profile and pixel format: read all three back
+        # (a VideoToolbox prores line under --hw writes its own pixel format, so it is not compared)
+        measured = {k: v.get(k) for k in p["expect"]}
+        extra.setdefault("verification", []).append(
+            {"step": "codec", "property": "codec_profile_pix_fmt", "ok": measured == p["expect"],
+             "expected": dict(p["expect"]), "measured": measured, "provenance": "specification"})
+    if p.get("alpha"):
+        extra["alpha_mode"] = args.alpha_mode or "straight"
+        if not STATE.dry_run:
+            # the alpha survived when every written frame's alpha matches the source frame's (an
+            # encoder, decoder or muxer that drops it reads fully opaque); premultiplying changes
+            # colour, not alpha
+            written_alpha = alpha_stats(output, v.get("codec"))
+            cmp = _alpha_compare(written_alpha, source_alpha)
+            extra.setdefault("verification", []).append(
+                {"step": "alpha", "property": "alpha_mean", "ok": cmp["ok"], "comparison": cmp,
+                 "expected": None if source_alpha is None else round(source_alpha["mean"], 2),
+                 "measured": None if written_alpha is None else round(written_alpha["mean"], 2), "tolerance": ALPHA_TOLERANCE,
+                 "frames": {"expected": _rounded(source_alpha), "measured": _rounded(written_alpha)},
+                 "provenance": "input_premeasurement"})
     platform = PLATFORM_OF.get(args.preset)
     if platform and has_audio and not STATE.dry_run:
         # Every eval run that exported for a platform then had to come back with loudness.py: the
@@ -508,7 +808,12 @@ def main() -> int:
                     err = child.get("error") or {}
                     if os.path.exists(tmp):
                         os.remove(tmp)
-                    die(f"--normalize: loudness.py failed: {err.get('message') or proc.stderr.strip()[-300:]}",
+                    # the child's "nothing was written" is about its own temp file; this run's export is
+                    # on disk, and the child's exit code (124 timeout, 130/143 interrupted) is the
+                    # run's, as render.py and waveform.py pass a stage's on (#415)
+                    why = (err.get("message") or proc.stderr.strip()[-300:]).replace("; nothing was written", "")
+                    die(f"--normalize: loudness.py failed: {why} ({kept_clause()})",
+                        code=child_exit_code(child, proc.returncode) if proc.returncode else 1,
                         kind=err.get("kind") or "ffmpeg", output=output, hint=err.get("hint"))
                 os.replace(tmp, output)
                 m = measure_loudness(output)

package/scripts/look.py

@@ -8,6 +8,7 @@ Examples:
   python3 look.py final.mp4 --at 2.5 --at 7          # single frames -> final_2.500s.png, final_7.000s.png
   python3 look.py before.mp4 --compare after.mp4 --at 4   # side-by-side frame
   python3 look.py reel.mp4 --safe tiktok --at 3          # shade what TikTok's own UI covers
+  python3 look.py show.mp4 --guides title,action,4:3 --at 10   # broadcast safe-area outlines
 Then view the PNG (Read tool / image viewer) and verify before reporting.
 """
 import argparse
@@ -25,6 +26,36 @@ from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter  # noqa: E402
 from _common.probe import display_size, square_pixels, square_pixels_note  # noqa: E402
 
+# --guides: broadcast safe areas as outlines, in fractions of the frame (a tile as much as a frame).
+# Action and title safe are SMPTE ST 2046-1's 93 % and 90 % of a 16:9 picture; the 4:3 centre cut
+# is the 4:3 window of a 16:9 frame with SD's own 90 % action / 80 % title safe inside it.
+GUIDES = {"action": 0.93, "title": 0.90}
+GUIDE_43 = {"action": 0.90, "title": 0.80}
+GUIDE_COLOURS = {"action": "yellow", "title": "cyan", "4:3": "white"}
+
+
+def guide_boxes(names) -> "tuple":
+    """drawbox outlines for --guides and the fractions they stand for (the result's `guides`)."""
+    t = "max(1\\,ih/270)"
+    boxes, described = [], []
+    for name in names:
+        if name in GUIDES:
+            f = GUIDES[name]
+            m = (1 - f) / 2
+            boxes.append(f"drawbox=x=iw*{m:g}:y=ih*{m:g}:w=iw*{f:g}:h=ih*{f:g}:color={GUIDE_COLOURS[name]}@0.9:t={t}")
+            described.append({"guide": name, "fraction": f, "of": "frame"})
+        else:  # "4:3": the centre-cut window, then its own action and title safe
+            w = "ih*4/3"
+            boxes.append(f"drawbox=x=(iw-{w})/2:y=0:w={w}:h=ih:color=white@0.9:t={t}")
+            for sub, f in GUIDE_43.items():
+                m = (1 - f) / 2
+                boxes.append(f"drawbox=x=(iw-{w})/2+{w}*{m:g}:y=ih*{m:g}:w={w}*{f:g}:h=ih*{f:g}:"
+                             f"color={GUIDE_COLOURS[sub]}@0.6:t={t}")
+            described.append({"guide": "4:3", "window": "centre 4:3 of the frame", "action": GUIDE_43["action"],
+                              "title": GUIDE_43["title"]})
+    return boxes, described
+
+
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
 
@@ -157,6 +188,10 @@ def main() -> int:
     ap.add_argument("--no-timecode", action="store_true")
     ap.add_argument("--safe", choices=PLATFORM_CHOICES, help="shade the zones this platform's UI covers (its description bar, "
                                                        "like column, status bar) so you can see whether anything readable is under them")
+    ap.add_argument("--guides", metavar="LIST",
+                    help="draw broadcast safe-area outlines on the PNG (a preview only; nothing is written into a video): "
+                         "a comma list of action (93%%), title (90%%) and 4:3 (the 4:3 centre cut of a 16:9 frame, "
+                         "with its 90%% action and 80%% title safe)")
     ap.add_argument("--ink", action="store_true", help="measure non-background pixels in each written PNG (bbox, "
                                                  "ink_fraction, row_bands per tile for a contact sheet) instead of "
                                                  "just eyeballing it -- a pixel-only signal, not a legibility judgement")
@@ -217,6 +252,17 @@ def main() -> int:
         safe_filter = "," + ",".join(boxes) if boxes else ""
         info(f"--safe {args.safe}: shaded top {z['top'] * 100:.0f}% / bottom {z['bottom'] * 100:.0f}% / "
              f"left {z['left'] * 100:.0f}% / right {z['right'] * 100:.0f}% of the frame -- keep text out of those")
+    guides = None
+    if args.guides:
+        names = [g.strip() for g in args.guides.split(",") if g.strip()]
+        bad = [g for g in names if g not in ("action", "title", "4:3")]
+        if bad or not names:
+            die(f"--guides takes action, title and 4:3, got {args.guides!r}")
+        dw, dh = display_size(meta["video"])
+        if "4:3" in names and dw and dh and dw / dh < 4 / 3 + 0.01:
+            die(f"--guides 4:3 draws the 4:3 centre cut of a wider frame; this source is {dw}x{dh}")
+        boxes, guides = guide_boxes(list(dict.fromkeys(names)))
+        safe_filter += "," + ",".join(boxes)
     tc = safe_filter + tc
     # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
     if meta["video"].get("bt2020_or_hdr"):
@@ -242,6 +288,11 @@ def main() -> int:
         if not args.at:
             die("--compare needs --at TIME")
         cmeta = probe(args.compare)
+        if guides and any(g.get("guide") == "4:3" for g in guides):
+            # the guides are drawn on both pictures: the second must be wider than 4:3 as well
+            cw, ch = display_size(cmeta.get("video") or {})
+            if cw and ch and cw / ch < 4 / 3 + 0.01:
+                die(f"--guides 4:3 draws the 4:3 centre cut of a wider frame; the --compare clip is {cw}x{ch}")
         lab2 = bt709_label_filter(cmeta)
         lab2 = lab2 + "," if lab2 else ""
         csq = (square_pixels(cmeta.get("video")) + ",") if square_pixels(cmeta.get("video")) else ""
@@ -256,15 +307,18 @@ def main() -> int:
                 out = os.path.join(outdir, f"{stem_part}_vs_{Path(args.compare).stem}_{idx}_{sec:.3f}s.png")
             half = args.width // 2
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
-            tcs = tc.replace("," + timecode_filter(font_prefix), "") + stamp
+            # the tone map and the --safe / --guides boxes go on each picture as scaled, before the
+            # pad: drawn after it, a picture letterboxed in the box got guides from the padded
+            # height (a 2:1 clip beside a 16:9 one); the timecode stamp is drawn on the box
+            pre = tc.replace("," + timecode_filter(font_prefix), "")
             # each picture keeps its own aspect inside a half-width box as tall as the taller of the
             # two (letterboxed, not stretched): through 3.1.3 scale2ref forced the first to the
             # second's size, so a 4:3 beside a 16:9 came out squashed (#411)
             box_h = max(_half_height(half, display_size(meta["video"])),
                         _half_height(half, display_size(cmeta.get("video"))))
-            fit = (f"scale={half}:{box_h}:force_original_aspect_ratio=decrease,"
-                   f"pad={half}:{box_h}:(ow-iw)/2:(oh-ih)/2:color=0x202020,setsar=1")
-            fc = (f"[0:v]{lab}{sq}{fit}{tcs}[a];[1:v]{lab2}{csq}{fit}{tcs}[b];"
+            fit = (f"scale={half}:{box_h}:force_original_aspect_ratio=decrease{pre},"
+                   f"pad={half}:{box_h}:(ow-iw)/2:(oh-ih)/2:color=0x202020,setsar=1{stamp}")
+            fc = (f"[0:v]{lab}{sq}{fit}[a];[1:v]{lab2}{csq}{fit}[b];"
                   f"[a][b]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-ss", f"{sec:.3f}", *still_input_args(args.compare), "-i", args.compare,
                                    "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", "-update", "1", out]
@@ -341,7 +395,8 @@ def main() -> int:
         else:
             ink = {"frames": [measure_ink(o) for o in outputs]}
 
-    emit(outputs[0] if len(outputs) == 1 else None, outputs=outputs, **({"ink": ink} if ink is not None else {}))
+    emit(outputs[0] if len(outputs) == 1 else None, outputs=outputs, **({"ink": ink} if ink is not None else {}),
+         **({"guides": guides} if guides else {}))
     if len(outputs) > 1 and not args.json:
         for o in outputs:
             print(o)