ffmpeg-skill 3.2.2 → 3.3.0

package/scripts/export.py

@@ -172,86 +172,11 @@ 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"]}
+# The alpha helpers (#417) live in _common.alpha since color.py, graphics.py, overlay.py and
+# background.py write alpha lines too; the names this module has always had stay bound here.
+from _common.alpha import (ALPHA_PIX as _ALPHA_PIX, ALPHA_TOLERANCE, OPAQUE, alpha_stats,  # noqa: E402
+                           alpha_compare as _alpha_compare, frame_means as _frame_means, rounded as _rounded,
+                           decoder_args_for, vp9_alpha_tagged)
 
 
 def key_path(fill: str) -> str:
@@ -598,6 +523,11 @@ def main() -> int:
         # 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)
+        # a VP9 source stored with alpha on a build whose decoder list was read without libvpx-vp9
+        # is refused (decoder_missing) before it is measured: FFmpeg's own VP9 decoder reads it
+        # opaque, so the source and the written line both measured 255 and the alpha step passed
+        # with the transparency gone (#433 review). An unreadable list keeps the decoder named.
+        dec_args = decoder_args_for(meta, 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):
@@ -640,7 +570,8 @@ def main() -> int:
         # 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 []
+    # (decoder_args_for, above: [] for anything that is not VP9 stored with alpha)
+    dec_args = dec_args 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

package/scripts/graphics.py

@@ -24,6 +24,8 @@ Examples:
   python3 graphics.py reel.mp4 --template sticker --text "NEW" --position top-right --platform tiktok
   python3 graphics.py reel.mp4 --template hook --title "How I cut this in one command" --duration 3
   python3 graphics.py clip.mp4 --template meme --top "when the render" --bottom "finally finishes"
+  python3 background.py --transparent --duration 4 --width 1920 --height 1080 -o canvas.mov
+  python3 graphics.py canvas.mov --template lower-third --name "Ada Lovelace" --keep-alpha -o lower_third.mov
 """
 import argparse
 import os
@@ -41,6 +43,8 @@ from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_
                      EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
                      SAFE_WIDTH_FRACTION, drawtext_draws_newline_glyph, is_multiline, _DRAWTEXT_PENDING)
 from _common.emit import note, warn
+from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
+                           report as alpha_report, source_alpha, tag_args, video_line)
 from _common.fonts import font_choice, record_font_choice
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
@@ -128,6 +132,7 @@ def main(force_route: Optional[str] = None) -> int:
     emo.add_argument("--emoji-max", type=int, default=60, help="most emoji overlays one run may build (default 60)")
     ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
+    add_alpha_args(ap)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -166,6 +171,10 @@ def main(force_route: Optional[str] = None) -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
+    # --keep-alpha: drawn on the source's alpha (a transparent canvas from background.py
+    # --transparent, or any alpha clip), written in an alpha line with the source's tags kept
+    alpha_codec = check_alpha_args(args, args.output)
+    src_alpha = source_alpha(args, meta, args.input)
     audio_streams = meta.get("audio_streams") or []
     if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
         die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
@@ -221,7 +230,7 @@ def main(force_route: Optional[str] = None) -> int:
         has chroma. overlay places a 4:2:0 picture on even rows and columns only: a box that starts on
         an odd one is placed one earlier with a transparent first column/row (`left`, `top`), so it
         covers the rows and columns the drawbox did."""
-        conv = rgb_chain_to_bt709(meta) if draws_chroma([colour], meta) else ""
+        conv = rgb_chain_to_bt709(meta) if (alpha_codec or draws_chroma([colour], meta)) else ""
         if conv:
             converted.append(colour)
         edge = f",pad={w + left}:{h + top}:{left}:{top}:color=black@0" if left or top else ""
@@ -488,7 +497,8 @@ def main(force_route: Optional[str] = None) -> int:
         h = max(3, int(base * 0.008))
         fps = meta['video'].get('fps') or 30
         fc.append(f"{layer_src(primary, 1.0, W, h)}[pb]")
-        if draws_chroma([bg], meta):
+        if draws_chroma([bg], meta) or alpha_codec:
+            # a layer (overlay composites the alpha too; drawbox leaves it as it was)
             fc.append(f"{layer_src(bg, 0.5, W, h, 0, (H - h) % 2)}[pbg]")
             fc.append(f"[0:v][pbg]overlay=x=0:y={(H - h) // 2 * 2}:{en}:eof_action=pass[v1]")
         else:
@@ -603,7 +613,7 @@ def main(force_route: Optional[str] = None) -> int:
              "(FFmpeg 8.0-8.0.1 and 8.1.0; fixed in 8.0.2/8.1.1): drop --text-render drawtext to render it "
              "through libass, or upgrade FFmpeg", "drawtext_newline_glyph", text_render="drawtext")
 
-    output = args.output or default_output(args.input, "gfx")
+    output = args.output or default_output(args.input, "gfx", default_ext(alpha_codec) if alpha_codec else None)
     ass_path = None
     emoji_result = None
     if route == "ass":
@@ -700,7 +710,10 @@ def main(force_route: Optional[str] = None) -> int:
     # The boxes with chroma (layers) go under the text, and the picture they and a converted colour
     # source are overlaid on gets its BT.709 label (an untagged one, tags only), so 7.1+'s overlay
     # converts neither picture to the other's matrix. The text is drawn in BT.709 (drawn_chain).
-    as_layers = any(draws_chroma([b[0]], meta) for b in boxes)
+    # On an alpha line every box is a layer: overlay composites the box's alpha over the picture's,
+    # while drawbox paints the colour and leaves the alpha as it was (a box on a transparent canvas
+    # stayed invisible)
+    as_layers = bool(alpha_codec) or any(draws_chroma([b[0]], meta) for b in boxes)
     drawboxes = []
     for colour, alpha, geo, x, y, w, h, enable, x_expr in boxes:
         if as_layers:
@@ -723,8 +736,16 @@ def main(force_route: Optional[str] = None) -> int:
         fc = [f"[0:v]{base_label}null[gbase]"] + [c.replace("[0:v]", "[gbase]") for c in fc]
     if fc and square:
         fc = [f"[0:v]{square}[gsq]"] + [c.replace("[0:v]", "[gsq]") for c in fc]
-
-    cmd = ffmpeg_base() + ["-i", args.input]
+    if alpha_codec:
+        # the picture is drawn on at 4:4:4 with its alpha plane, and every layer is overlaid at
+        # 4:4:4 (overlay's default is 4:2:0); drawtext and libass (alpha=1) draw into the alpha too
+        fc = [c.replace(":eof_action=pass", ":eof_action=pass:format=yuv444") for c in fc]
+        if fc:
+            fc = ["[0:v]format=yuva444p[ka0]"] + [c.replace("[0:v]", "[ka0]") for c in fc]
+        square = "format=yuva444p" + ("," + square if square else "")
+    finish = finish_chain(alpha_codec, args.alpha_mode, meta) if alpha_codec else ""
+
+    cmd = ffmpeg_base() + (decoder_args_for(meta, args.input) if alpha_codec else []) + ["-i", args.input]
     if route == "ass" or emoji_overlays:
         chains = list(fc) if fc else [f"[0:v]{(square + ',') if square else ''}{text or 'null'}[vout]"]
         last = "vout"
@@ -733,6 +754,8 @@ def main(force_route: Optional[str] = None) -> int:
             fdir = ass_fonts_dir()
             if fdir:
                 vf += f":fontsdir={escape_filter_path(fdir)}"
+            if alpha_codec:
+                vf += ":alpha=1"
             vf = drawn_chain(vf, meta, [el.get(k) for el in elements for k in ("color", "outline_color", "box_color")],
                              labelled=bool(base_label))
             chains.append(f"[{last}]{vf}[vtxt]")
@@ -746,16 +769,31 @@ def main(force_route: Optional[str] = None) -> int:
             if asset not in STATE.plan_inputs:
                 STATE.plan_inputs.append(asset)
         if eo:
+            if alpha_codec:
+                # at 4:4:4 like every other layer here (overlay's default 4:2:0 subsamples the picture)
+                eo = [re.sub(r"(overlay=x=.*?:enable='[^']*')\[", r"\1:format=yuv444[", c) for c in eo]
             chains += eo
             last = "vfinal"
+        if finish:
+            chains.append(f"[{last}]{finish}[ka_v]")
+            last = "ka_v"
         cmd += ["-filter_complex", ";".join(chains), "-map", f"[{last}]",
                 "-map", f"0:a:{args.audio_stream}?"]
     elif fc:
-        cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", f"0:a:{args.audio_stream}?"]
+        if finish:
+            fc.append(f"[vout]{finish}[ka_v]")
+        cmd += ["-filter_complex", ";".join(fc), "-map", "[ka_v]" if finish else "[vout]", "-map", f"0:a:{args.audio_stream}?"]
+    else:
+        cmd += ["-vf", ",".join(p for p in (square, text, finish) if p) if finish else (square + "," if square else "") + text,
+                "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
+    if alpha_codec:
+        cmd += video_line(alpha_codec) + tag_args(meta) + cfr_args(meta)
+        cmd += audio_line(alpha_codec) if meta.get("audio") else ["-an"]
+        if STATE.hw:
+            note(f"--hw: --alpha-codec {alpha_codec} stays on the CPU (no VideoToolbox encoder writes it with its alpha)")
     else:
-        cmd += ["-vf", (square + "," if square else "") + text, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
-    cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
-    cmd += aac_args() if meta.get("audio") else ["-an"]
+        cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
+        cmd += aac_args() if meta.get("audio") else ["-an"]
     dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {args.template})")
@@ -770,6 +808,9 @@ def main(force_route: Optional[str] = None) -> int:
         extra["emoji"] = emoji_result
     if sliced_atoms:
         extra["broken_inside_word"] = len(sliced_atoms)
+    # drawn layers add coverage: with --keep-alpha the written alpha is at or above the source's
+    # in every frame; without it, an output that lost a used alpha fails the `alpha` step
+    alpha_report(args, alpha_codec, src_alpha, output, extra, composite=True)
     emit(output, **extra)
     return 0
 

package/scripts/overlay.py

@@ -23,6 +23,10 @@ Examples:
   python3 overlay.py input.mp4 --video webcam.mp4 --position bottom-right --scale 480 --opacity 0.9
   python3 overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00 --chromakey-similarity 0.15
   python3 overlay.py talk.mp4 --video cues.mov --position 0,0 --margin 0 --place 0-2.5@12 --place 2.5-6@40
+  python3 overlay.py canvas.mov --image logo.png --position center --keep-alpha -o logo_layer.mov
+
+A VP9 --video layer stored with an alpha layer (a WebM from export.py --preset vp9-alpha) is decoded
+with libvpx-vp9, so its transparency reaches the composite (FFmpeg's own VP9 decoder drops it).
 """
 import argparse
 import re
@@ -33,6 +37,8 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as
 from _common import still_input_args  # noqa: E402
 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, layer_base_chain, matrix_chain, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note, warn
+from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
+                           has_alpha_plane, report as alpha_report, source_alpha, tag_args, video_line)
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _common.wrap import wrap_text
 from _common import text_width_em
@@ -278,6 +284,7 @@ def main() -> int:
     enc = ap.add_argument_group("encoding")
     enc.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
+    add_alpha_args(ap)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -345,6 +352,10 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
+    # --keep-alpha: composited onto the main input's alpha (a transparent canvas from background.py
+    # --transparent, or any alpha clip) and written in an alpha line with the source's tags kept
+    alpha_codec = check_alpha_args(args, args.output)
+    src_alpha = source_alpha(args, meta, args.input)
     audio_streams = meta.get("audio_streams") or []
     if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
         die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
@@ -395,7 +406,7 @@ def main() -> int:
     if args.place and (args.start or args.end or args.fade):
         die("--place sets when each piece shows: drop --start / --end / --fade")
 
-    output = args.output or default_output(args.input, "overlay")
+    output = args.output or default_output(args.input, "overlay", default_ext(alpha_codec) if alpha_codec else None)
     enable = enable_expr(start, end)
     cmd = ffmpeg_base() + ["-i", args.input]
 
@@ -468,7 +479,8 @@ def main() -> int:
             chain.append(f"scale={int(vw * args.scale_percent / 100)}:-2")
         elif args.scale:
             chain.append(f"scale={args.scale}:-2")
-        chain.append("format=yuva420p")
+        # an alpha line composites at 4:4:4: the layer is not taken through 4:2:0 on the way
+        chain.append("format=yuva444p" if alpha_codec else "format=yuva420p")
         if args.chromakey:
             chain.append(f"chromakey={args.chromakey}:{args.chromakey_similarity:g}:{args.chromakey_blend:g}")
         if args.opacity < 1:
@@ -477,11 +489,18 @@ def main() -> int:
         ov = f"overlay={x}:{y}:format=auto"
         if enable:
             ov += f":enable='{enable}'"
-        cmd = ffmpeg_base() + ["-i", args.input, "-i", args.video]
+        # a VP9 layer stored with an alpha layer is decoded with libvpx-vp9: FFmpeg's own decoder
+        # drops the alpha, and the layer covered the picture as an opaque rectangle
+        cmd = ffmpeg_base() + ["-i", args.input] + decoder_args_for(pip_meta, args.video) + ["-i", args.video]
         # both pictures converted by their own colour tags to the BT.709 the output is tagged with;
         # beside a converted one an untagged one gets its BT.709 label, tags only, so 7.1+'s
         # overlay does not convert one to the other's "unknown" (BT.601) matrix
         base, pip = matrix_chain(meta, meta), matrix_chain(pip_meta, meta)
+        if pip and has_alpha_plane(pip_meta, args.video):
+            # an RGB layer with alpha (qtrle, PNG in .mov, a graphics.py/background.py alpha line) is
+            # converted to BT.709 YUV with its alpha plane: the 4:4:4 the conversion ends in had none,
+            # and the layer covered the picture as an opaque rectangle
+            pip = pip.replace("format=yuv444p", "format=yuva444p")
         if base or pip:
             base, pip = base or label_chain(meta, meta), pip or label_chain(pip_meta, meta)
         # overlay mixes samples: a full-range picture is taken to limited range (#410)
@@ -541,13 +560,37 @@ def main() -> int:
     if square and "-filter_complex" in cmd:
         i = cmd.index("-filter_complex") + 1
         cmd[i] = f"[0:v]{square}[sq];" + cmd[i].replace("[0:v]", "[sq]")
-    cmd += video_args(meta, args.crf, args.preset, convert_matrix=not args.video) + cfr_args(meta)
-    cmd += aac_args() if meta.get("audio") else ["-an"]
+    if alpha_codec:
+        # the main picture keeps its alpha plane at 4:4:4, every layer is overlaid at 4:4:4 (overlay
+        # composites the alpha when the main picture has one) and drawtext draws into the alpha too;
+        # the line's pixel format ends the graph so nothing after it can drop the plane
+        finish = finish_chain(alpha_codec, args.alpha_mode, meta)
+        first = cmd.index("-i")
+        cmd[first:first] = decoder_args_for(meta, args.input)
+        if "-filter_complex" in cmd:
+            i = cmd.index("-filter_complex") + 1
+            cmd[i] = ("[0:v]format=yuva444p[ka0];" + cmd[i].replace("[0:v]", "[ka0]").replace(":format=auto", ":format=yuv444")
+                      + f";[out]{finish}[ka_v]")
+            cmd[cmd.index("[out]")] = "[ka_v]"
+        else:
+            i = cmd.index("-vf") + 1
+            cmd[i] = f"format=yuva444p,{cmd[i]},{finish}"
+        cmd += video_line(alpha_codec) + tag_args(meta) + cfr_args(meta)
+        cmd += audio_line(alpha_codec) if meta.get("audio") else ["-an"]
+        if STATE.hw:
+            note(f"--hw: --alpha-codec {alpha_codec} stays on the CPU (no VideoToolbox encoder writes it with its alpha)")
+    else:
+        cmd += video_args(meta, args.crf, args.preset, convert_matrix=not args.video) + cfr_args(meta)
+        cmd += aac_args() if meta.get("audio") else ["-an"]
     dropped_streams = run_keeping_subtitles(cmd, output)
     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, **({"font_used": font_used} if args.text else {}))
+    extra = {"dropped_non_av_streams": dropped_streams, **({"font_used": font_used} if args.text else {})}
+    # a layer adds coverage: with --keep-alpha the written alpha is at or above the main input's in
+    # every frame; without it, an output that lost the main input's used alpha fails the `alpha` step
+    alpha_report(args, alpha_codec, src_alpha, output, extra, composite=True)
+    emit(output, **extra)
     return 0
 
 

package/scripts/probe.py

@@ -8,11 +8,38 @@ Examples:
   python3 probe.py input.mp4
   python3 probe.py a.mp4 b.mov --compact
   python3 probe.py input.mp4 --field duration
+  python3 probe.py input.mp4 --keyframes-near 12.4,47 --keyframe-window 5
+
+--keyframes-near T[,T...] adds `keyframes`: for each time, the video keyframes within
+--keyframe-window seconds of it, and the nearest one at or before it and at or after it -- the
+points a stream copy can start at, and where cut.py --smart's re-encode around a cut ends.
 """
 import argparse
+import math
 import sys
 
-from _common import add_common, analyze_levels, apply_common, print_json, probe
+from _common import add_common, analyze_levels, apply_common, die, keyframe_times, print_json, probe, time_arg
+
+
+def keyframe_candidates(result: dict, times: list, window: float) -> list:
+    """For each time (seconds from the file's start), the keyframes within `window` of it and the
+    nearest of those at or before / at or after it (null when none is within the window), on the
+    same clock (the file's start_time subtracted). The picture is the stream probe() reports (`V`:
+    not a cover picture). A failed read is an error, not an empty neighbourhood."""
+    origin = float(result.get("start_time") or 0.0)
+    out = []
+    for t in times:
+        # keyframe_times() reads past hi (an interval's end is exclusive), so one on the edge is kept
+        read = keyframe_times(result["file"], origin + t - window, origin + t + window, "V:0")
+        if read is None:
+            die(f"ffprobe could not read the keyframes of {result['file']} around {t:g}s", kind="ffmpeg")
+        # the read starts at the keyframe at or before the window, which may lie outside it
+        keys = [k for k in (round(k - origin, 6) for k in read) if t - window - 1e-6 <= k <= t + window + 1e-6]
+        before = [k for k in keys if k <= t + 1e-6]
+        after = [k for k in keys if k >= t - 1e-6]
+        out.append({"at": t, "window": window, "keyframes": keys, "before": before[-1] if before else None,
+                    "after": after[0] if after else None})
+    return out
 
 
 def main() -> int:
@@ -21,11 +48,27 @@ def main() -> int:
     ap.add_argument("--compact", action="store_true", help="one human-readable line per file instead of JSON")
     ap.add_argument("--field", help="print only this top-level field (e.g. duration) or dotted path (video.fps)")
     ap.add_argument("--analyze", action="store_true", help="also sample picture levels (first 20 s) and flag Log-looking footage")
+    ap.add_argument("--keyframes-near", metavar="T[,T...]",
+                    help="also list the video keyframes around these times (seconds, mm:ss or hh:mm:ss.ms): the ones within "
+                         "--keyframe-window and the nearest before and after each, as `keyframes`")
+    ap.add_argument("--keyframe-window", type=float, default=5.0, metavar="S",
+                    help="--keyframes-near: seconds either side of each time to read (default 5)")
     add_common(ap)  # --json / --dry-run / --fast / --progress accepted for uniformity; output is JSON already
     args = ap.parse_args()
     apply_common(args)
 
+    if not math.isfinite(args.keyframe_window) or args.keyframe_window <= 0:
+        die(f"--keyframe-window must be a positive, finite number of seconds, got {args.keyframe_window:g}")
+    if args.keyframes_near is not None and not any(t.strip() for t in args.keyframes_near.split(",")):
+        die("--keyframes-near takes one or more times (e.g. 12.4,47), got none")
     results = [probe(p) for p in args.inputs]
+    if args.keyframes_near:
+        for r in results:
+            fps = (r.get("video") or {}).get("fps")
+            times = [time_arg(t.strip(), "--keyframes-near", fps) for t in args.keyframes_near.split(",") if t.strip()]
+            if any(not math.isfinite(t) or t < 0 for t in times):
+                die("--keyframes-near takes finite times at or after 0")
+            r["keyframes"] = keyframe_candidates(r, times, args.keyframe_window) if r.get("video") else []
     if args.analyze:
         for r in results:
             if r.get("video"):
@@ -58,6 +101,9 @@ def main() -> int:
                 line += f" | audio {a.get('codec')} {a.get('channels')}ch {a.get('sample_rate')}Hz"
             else:
                 line += " | no audio"
+            for k in r.get("keyframes") or []:
+                before, after = ("-" if x is None else f"{x:g}" for x in (k["before"], k["after"]))
+                line += f" | keyframes near {k['at']:g}s: {before}/{after} ({len(k['keyframes'])} within {k['window']:g}s)"
             print(line)
         return 0
 

package/scripts/stabilize.py

@@ -27,7 +27,7 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs
+from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
 
 
 def main() -> int:
@@ -63,7 +63,18 @@ def main() -> int:
         trf_arg = escape_filter_path(trf)
 
         ffmpeg = require_tool("ffmpeg")
-        detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
+        # vid.stab asserts on an odd frame (ffmpeg aborts in pass 1, #438), so both passes see an
+        # even one. Recorded like the runner's own odd-size retry: the output is a pixel narrower
+        # or shorter than the source.
+        v = meta["video"]
+        w, h = int(v.get("width") or 0), int(v.get("height") or 0)
+        if int(v.get("rotation") or 0) % 180 == 90:
+            w, h = h, w
+        even = f"{EVEN_SCALE}," if (w % 2 or h % 2) else ""
+        if even:
+            record_fallback("source has odd dimensions; scaling to even before stabilizing (vid.stab needs it)",
+                            "odd_dimensions_scaled_even", output=output, scale=EVEN_SCALE)
+        detect_vf = f"{even}vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
         if args.tripod:
             # A frame number, not a boolean: frame 1 is the standard reference for "lock to
             # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
@@ -78,7 +89,7 @@ def main() -> int:
                 die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
-        transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
+        transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
         if args.tripod:
             # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
             # camera path makes no sense once every frame is locked to one fixed reference.