ffmpeg-skill 3.2.2 → 3.2.3

package/scripts/color.py

@@ -16,6 +16,15 @@ Examples:
   python3 color.py flat.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05
   python3 color.py flat.mp4 --correct --gamma 1.2 --lift 0.04 --gain -0.03   # three-way shadows/gamma/highlights
   python3 color.py flat.mp4 --correct --levels-in-black 16 --levels-in-white 235 --curves medium_contrast
+  python3 color.py logo_4444.mov --correct --exposure 0.3 --keep-alpha -o logo_graded.mov   # alpha kept, ProRes 4444
+  python3 color.py graded.mp4 --correct --legalize ebu-r103            # clamp only: no correction values given
+  python3 color.py log.mov --lut to709.cube --legalize bt709           # the LUT, then the clamp, one encode
+
+--legalize bt709|ebu-r103 (with --to-sdr, --lut or --correct) clamps every luma and chroma sample into
+the standard's legal range after the picture has become 8-bit 4:2:0, the last filter before the
+encoder, then measures the written file the way check.py --levels does (`legalize` in the JSON): the
+encoder's error around clamped edges can leave a few decoded samples out, and the legal_levels step
+passes with up to 1 % of one frame's luma or chroma samples out of range.
 """
 import argparse
 import json
@@ -24,8 +33,11 @@ import sys
 from typing import List, Optional
 
 from _common.runner import fail_if_classified
-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, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
-from _common.emit import warn
+from _common import STATE, add_common, analyze_levels, LEGAL_RANGE_CHOICES, legal_limits, measure_signal_range, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, 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,
+                           report as alpha_report, source_alpha, tag_args, video_line)
+from _common.decision import keeps_source_tags
 
 # the curves of FFmpeg's CPU `tonemap` filter (every version from 5.1 to 9). bt2390 was listed
 # until 2.24 but exists only in tonemap_opencl/libplacebo, so choosing it always failed.
@@ -84,7 +96,7 @@ def _checked_levels(args: argparse.Namespace, flag: str) -> int:
     return value
 
 
-def correction_chain(args: argparse.Namespace) -> str:
+def correction_chain(args: argparse.Namespace, out_fmt: str = "yuv420p") -> str:
     """Always-present filter stages, in a fixed order chosen so each stage sees a picture already
     corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint/
     lift/gain, so contrast/saturation act on colour-balanced footage) -> contrast/saturation/gamma
@@ -124,7 +136,7 @@ def correction_chain(args: argparse.Namespace) -> str:
         # "unchanged" adds no term at all
         rgb.append(f"colortemperature=temperature={temperature:g}")
     rgb.append(f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}")
-    terms = [_rgb_stage(rgb), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
+    terms = [_rgb_stage(rgb, out_fmt), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
     rgb2 = []
     if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
         rimin, rimax = in_black / 255.0, in_white / 255.0
@@ -138,11 +150,11 @@ def correction_chain(args: argparse.Namespace) -> str:
     if args.curves:
         rgb2.append(f"curves=preset={args.curves}")
     if rgb2:
-        terms.append(_rgb_stage(rgb2))
+        terms.append(_rgb_stage(rgb2, out_fmt))
     return ",".join(terms)
 
 
-def _rgb_stage(filters: list) -> str:
+def _rgb_stage(filters: list, out_fmt: str = "yuv420p") -> str:
     """Wrap a run of RGB-only filters in explicit, matching YUV<->RGB conversions.
 
     exposure/colortemperature/colorbalance/colorlevels/curves take RGB, so libavfilter inserts a
@@ -154,16 +166,17 @@ def _rgb_stage(filters: list) -> str:
     identity on every source (39 dB, the same as an untagged one always got); bt601 on both
     sides measured better than bt709 on both (34 dB) because swscale's 601 path round-trips
     8-bit 4:2:0 more exactly. The matrix here is only the working space of the conversion pair,
-    never a tag: the output carries the encoder's BT.709 tags as before."""
+    never a tag: the output carries the encoder's BT.709 tags as before. `out_fmt` is yuv444p for
+    an alpha line (--keep-alpha), whose 4:4:4 master would otherwise get 4:2:0 chroma."""
     return ("scale=in_color_matrix=bt601,format=gbrpf32le," + ",".join(filters)
-            + ",scale=out_color_matrix=bt601,format=yuv420p")
+            + f",scale=out_color_matrix=bt601,format={out_fmt}")
 
 
 # swscale's names for the non-BT.709 matrices a --codec prores re-encode keeps (it does not convert)
 _SWS_MATRIX = {"smpte170m": "bt601", "bt470bg": "bt601", "smpte240m": "smpte240m", "fcc": "fcc"}
 
 
-def lut_legs(meta=None) -> "tuple":
+def lut_legs(meta=None, out_fmt: str = "yuv420p") -> "tuple":
     """(to RGB, back to YUV) around --lut's lut3d: explicit BT.709 conversions through float RGB,
     the matrix the picture holds when it reaches them (an untagged or BT.709 source as it is, a
     BT.601 or RGB one after x264_args(source=...)'s conversion), limited range on the way out.
@@ -175,13 +188,14 @@ def lut_legs(meta=None) -> "tuple":
     _rgb_stage) these legs use the BT.709 the picture is: an identity LUT then returns every sample
     as --lut-strength 0, which applies none, does (6.1, BT.709/BT.601/untagged, limited and full
     range, 8- and 10-bit). The input range is read from the frames, as every scale here reads it."""
-    # --codec prores keeps a BT.601 (or other non-BT.709) source's matrix and tags instead of
-    # converting it (decision.video_args), so the legs use that matrix (#416 review)
+    # --codec prores (and an alpha line, --keep-alpha) keeps a BT.601 (or other non-BT.709)
+    # source's matrix and tags instead of converting it (decision.video_args), so the legs use
+    # that matrix (#416 review)
     matrix = "bt709"
-    if STATE.codec == "prores":
+    if keeps_source_tags():
         matrix = _SWS_MATRIX.get(((meta or {}).get("video") or {}).get("color_space"), "bt709")
     return (f"scale=in_color_matrix={matrix},format=gbrpf32le",
-            f"scale=out_color_matrix={matrix}:out_range=tv,format=yuv420p")
+            f"scale=out_color_matrix={matrix}:out_range=tv,format={out_fmt}")
 
 
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
@@ -300,7 +314,7 @@ def retag_mismatch(output: str, want: tuple) -> "Optional[str]":
     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:
+def retag(args: argparse.Namespace, meta: dict, has_audio: bool, src_alpha=lambda: None) -> 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
@@ -360,11 +374,53 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool) -> int:
     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 {}))
+    extra = {"reencoded": reencoded, "dropped_non_av_streams": dropped_streams, "verification": check}
+    if reencoded:
+        # the fallback re-encode is H.264, which holds no alpha: on a source whose alpha is used the
+        # `alpha` step fails (a stream copy keeps every pixel, alpha included, and needs no step)
+        alpha_report(args, None, src_alpha(), output, extra, composite=False)
+    emit(output, **extra, **({"notes": notes} if notes else {}))
     return 0
 
 
+def correction_is_identity(args: argparse.Namespace) -> bool:
+    """--correct with every value at its no-op default and no --curves: nothing to correct."""
+    return (all(getattr(args, k) == CORRECTION[k][0] for k in CORRECTION)
+            and all(getattr(args, k) == LEVELS[k][0] for k in LEVELS) and args.curves is None)
+
+
+def legal_clamp(standard: str) -> str:
+    """lutyuv clamping an 8-bit 4:2:0 picture into `standard`'s legal codes (legal_limits)."""
+    lim = legal_limits(standard, 8)
+    (ylo, yhi), (clo, chi) = lim["y"], lim["c"]
+    return f"lutyuv=y='clip(val\\,{ylo}\\,{yhi})':u='clip(val\\,{clo}\\,{chi})':v='clip(val\\,{clo}\\,{chi})'"
+
+
+# --legalize: the share of one frame's luma (or chroma) samples the encode may leave out of range
+# before the legal_levels step fails -- the same allowance check.py --levels gives by default. The
+# clamp holds every sample the encoder receives; a lossy encoder's error around a clipped edge can
+# still land a few decoded samples a code or two outside, which is what this measures.
+LEGALIZE_TOLERANCE_PCT = 1.0
+
+
+def legalize_report(standard: str, output: str) -> "tuple":
+    """Measure the written file against `standard` ({standard, limits, output}, verification list)."""
+    doc = measure_signal_range(output, standard, window=0, bit_depth=8)
+    if doc is None:
+        return ({"standard": standard, "output": None},
+                [{"step": "legal_levels", "ok": False, "reason": "the written file did not decode for the measurement"}])
+    worst = doc["worst_frame"]
+    ok = worst["y_pct"] <= LEGALIZE_TOLERANCE_PCT and worst["chroma_pct"] <= LEGALIZE_TOLERANCE_PCT
+    pct = doc["out_of_range_pct"]
+    if pct["y"] or pct["chroma"]:
+        warn(f"--legalize {standard}: the encoded file still has {pct['y']:.4f}% of luma and {pct['chroma']:.4f}% of chroma "
+             f"samples out of range (the encoder's error around clamped areas; worst frame {worst['y_pct']:.4f}% / "
+             f"{worst['chroma_pct']:.4f}%)", "legalize_residual")
+    return ({"standard": standard, "reference": doc["reference"], "legal": doc["legal"], "output": doc},
+            [{"step": "legal_levels", "ok": ok, "standard": standard, "out_of_range_pct": pct,
+              "worst_frame": worst, "tolerance_pct": LEGALIZE_TOLERANCE_PCT}])
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -375,6 +431,10 @@ def main() -> int:
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
     mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint/--gamma/--lift/--gain/--levels-*/--curves")
+    ap.add_argument("--legalize", choices=LEGAL_RANGE_CHOICES, default=None,
+                    help="with --to-sdr, --lut or --correct: clamp luma and chroma into the bt709 (16-235 / 16-240) or ebu-r103 "
+                         "(luma 14-241, chroma 5-251) legal range after the 8-bit 4:2:0 conversion, then measure the written "
+                         "file's out-of-range share (JSON legalize). --correct with no correction values clamps only")
     ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
@@ -401,6 +461,7 @@ def main() -> int:
                           "a successful --retag stream-copy all streams untouched, so the flag has nothing to select there.")
     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)
@@ -415,6 +476,35 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
+    if args.legalize and (args.strip_dovi or args.retag):
+        die(f"--legalize changes pixels, so it needs a mode that re-encodes (--to-sdr, --lut or --correct); "
+            f"{'--strip-dovi' if args.strip_dovi else '--retag'} is a stream copy")
+    if args.legalize and STATE.codec not in (None, "h264"):
+        die(f"--legalize clamps the 8-bit 4:2:0 picture the H.264 line encodes; --codec {STATE.codec} converts it again "
+            f"after the clamp (another depth or chroma format), which can move samples back out of range. Leave --codec "
+            f"unset, or run check.py --levels on that encode")
+    if args.legalize and args.keep_alpha:
+        # the clamp and its measurement are defined on the 8-bit 4:2:0 picture the H.264 line encodes;
+        # the alpha line grades at 4:4:4 and every --alpha-codec converts that picture again after the
+        # clamp (10-bit ProRes 4444, RGB qtrle/PNG, VP9's yuva420p) -- the same reason --codec is refused
+        die("--legalize clamps the 8-bit 4:2:0 picture the H.264 line encodes; --keep-alpha grades at 4:4:4 and its "
+            "--alpha-codec converts the picture again after the clamp (10-bit, RGB or yuva420p), which can move samples "
+            "back out of range",
+            kind="input", hint="legalize the opaque delivery (--drop-alpha, or no alpha flag), or run check.py --levels "
+                               "on the alpha master")
+    if args.keep_alpha and not (args.correct or args.lut):
+        # --retag and --strip-dovi are stream copies, which keep an alpha channel as they keep every
+        # pixel; --to-sdr's tone map ends in the SDR line's own 4:2:0 (an HDR alpha master is not a case here)
+        die("--keep-alpha applies to --correct and --lut (--retag and --strip-dovi copy the stream, alpha included)",
+            kind="input")
+    if args.drop_alpha and not (args.correct or args.lut or args.to_sdr):
+        die("--drop-alpha applies to the re-encodes (--correct, --lut, --to-sdr); --retag and --strip-dovi copy the stream, "
+            "alpha included", kind="input")
+    alpha_codec = check_alpha_args(args, args.output)
+    src_alpha = source_alpha(args, meta, args.input) if (args.correct or args.lut or args.to_sdr) else None
+    # an alpha line is graded at 4:4:4: its master would otherwise come back with 4:2:0 chroma
+    out_fmt = "yuv444p" if alpha_codec else "yuv420p"
+    ext = default_ext(alpha_codec) if alpha_codec else None
 
     if args.strip_dovi:
         output = args.output or default_output(args.input, "nodv")
@@ -433,7 +523,7 @@ def main() -> int:
         return 0
 
     if args.retag:
-        return retag(args, meta, has_audio)
+        return retag(args, meta, has_audio, lambda: source_alpha(args, meta, args.input))
 
     measurements = None
     sdr_extra: dict = {}
@@ -443,22 +533,22 @@ def main() -> int:
         if is_bt2020_sdr(v):
             vf = bt2020_sdr_to_bt709_chain(meta)
             sdr_path = "gamut"
-            note = (f"BT.2020 primaries on an SDR transfer ({v.get('color_transfer')}): converted the gamut to BT.709 "
+            sdr_note = (f"BT.2020 primaries on an SDR transfer ({v.get('color_transfer')}): converted the gamut to BT.709 "
                     f"without a tone map (--tonemap/--peak/--desat do not apply)")
         else:
             vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
             sdr_path = "tonemap"
-            note = f"tone-mapped {v.get('hdr_format') or 'untagged input as PQ (--force)'} to SDR BT.709 with {args.tonemap}"
-        info(f"note: {note}")
-        sdr_extra = {"sdr_path": sdr_path, "notes": [note]}
+            sdr_note = f"tone-mapped {v.get('hdr_format') or 'untagged input as PQ (--force)'} to SDR BT.709 with {args.tonemap}"
+        info(f"note: {sdr_note}")
+        sdr_extra = {"sdr_path": sdr_path, "notes": [sdr_note]}
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
     elif args.correct:
         if v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is HDR ({v.get('hdr_format')}); --correct works on SDR pixels and would tag PQ/HLG data as BT.709 "
                 f"without a tone map (sweep F10). Run --to-sdr first, or --force to grade the raw values anyway")
-        vf = correction_chain(args)
-        output = args.output or default_output(args.input, "correct")
+        vf = "" if args.legalize and correction_is_identity(args) else correction_chain(args, out_fmt)
+        output = args.output or default_output(args.input, "correct", ext)
         tag = "correct"
         # OBSERVED technical measurements (signalstats: luma / saturation distribution), never a
         # "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
@@ -472,26 +562,47 @@ def main() -> int:
         if not (0.0 <= args.lut_strength <= 1.0):
             die(f"--lut-strength {args.lut_strength:g} is outside 0..1")
         lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"
-        to_rgb, to_yuv = lut_legs(meta)
+        to_rgb, to_yuv = lut_legs(meta, out_fmt)
         if args.lut_strength == 0.0:
             # 0 means "no LUT at all" -- without this branch, 0 (falling outside the open interval
             # below) landed in the same "apply the LUT at full strength" fallback as an out-of-range
             # value did before the guard above existed: the one strength value documented to mean
             # "don't grade it" instead silently graded it at 100%, the opposite of what was asked.
-            vf = "format=yuv420p"
+            vf = f"format={out_fmt}"
         elif args.lut_strength < 1.0:
             # blend graded and original
             # blended in RGB, both pictures through the same two legs
             vf = f"{to_rgb},split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},{to_yuv}"
         else:
             vf = f"{to_rgb},{lut},{to_yuv}"
-        output = args.output or default_output(args.input, "lut")
+        output = args.output or default_output(args.input, "lut", ext)
         tag = "lut"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
-    # --lut/--correct grade the source's own pixels, so a BT.601 source is converted to the BT.709
-    # the line is tagged with; --to-sdr's zscale chain already writes BT.709 and converts nothing more
-    cmd += x264_args(args.crf, args.preset, source=None if args.to_sdr else meta) + cfr_args(meta) + (aac_args() if has_audio else [])
+    if args.legalize:
+        # the last filter before the encoder, on the 4:2:0 picture it encodes: a clamp ahead of the
+        # chroma subsampling would let the subsampling filter's overshoot put samples back out
+        # a full-range picture (yuvj420p, or tagged pc) is converted to limited range first: its codes
+        # span 0-255 by design, and clamping them as they are would crush its blacks and whites into
+        # the limits instead of scaling them there. A limited-range source gets the chain it always had.
+        full = v.get("color_range") == "pc" or str(v.get("pix_fmt") or "").startswith("yuvj")
+        vf = ((vf + "," if vf else "") + ("scale=out_range=tv," if full else "")
+              + "format=yuv420p," + legal_clamp(args.legalize))
+    if alpha_codec:
+        # --keep-alpha: the grade works on the colour and never touches the alpha, which is split off
+        # the source, kept as it is and merged back (alphamerge) in front of the alpha line; the
+        # source's colour tags are kept, as --codec prores keeps them (no BT.709 conversion)
+        fc = (f"[0:v]split[ka_c][ka_a];[ka_c]{vf}[ka_g];[ka_a]alphaextract[ka_m];"
+              f"[ka_g][ka_m]alphamerge,{finish_chain(alpha_codec, args.alpha_mode, meta)}[ka_v]")
+        cmd = ffmpeg_base() + decoder_args_for(meta, args.input) + ["-i", args.input, "-filter_complex", fc,
+                                                                     "-map", "[ka_v]", "-map", f"0:a:{args.audio_stream}?"]
+        cmd += video_line(alpha_codec) + tag_args(meta) + cfr_args(meta) + (audio_line(alpha_codec) if has_audio else [])
+        if STATE.hw:
+            note(f"--hw: --alpha-codec {alpha_codec} stays on the CPU (no VideoToolbox encoder writes it with its alpha)")
+    else:
+        cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
+        # --lut/--correct grade the source's own pixels, so a BT.601 source is converted to the BT.709
+        # the line is tagged with; --to-sdr's zscale chain already writes BT.709 and converts nothing more
+        cmd += x264_args(args.crf, args.preset, source=None if args.to_sdr else meta) + cfr_args(meta) + (aac_args() if has_audio else [])
     dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {r['video']['width']}x{r['video']['height']}, "
@@ -500,6 +611,12 @@ def main() -> int:
     if measurements is not None:
         measurements["output"] = analyze_levels(output)
         extra["measurements"] = measurements
+    # the source's alpha against the output's: kept (--keep-alpha), or lost and failing the `alpha`
+    # step (an opaque line on a source whose alpha is used), or dropped on purpose (--drop-alpha)
+    alpha_report(args, alpha_codec, src_alpha, output, extra, composite=False)
+    if args.legalize and not STATE.dry_run:
+        extra["legalize"], check = legalize_report(args.legalize, output)
+        extra["verification"] = extra.get("verification", []) + check
     emit(output, **extra)
     return 0
 

package/scripts/cut.py

@@ -63,7 +63,7 @@ from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT
 from _common import require_tool
 from _common.probe import TS_EXTS, signatures_match, stream_signature
 from _common.decision import grid_at_or_after
-from _common import warn, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
+from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
 DROPPED_STREAMS: List[str] = []
@@ -1303,6 +1303,70 @@ def _join_workspace():
                 pass
 
 
+def run_smart(args, segments, output: str, meta: dict, forced: List[str], hold_needed: bool, total: float) -> dict:
+    """--smart: the keyframe-aware cut (_smartcut), written beside the output and moved into place once
+    verified. Returns the `smart` document; {applied: false, reason, reason_code} when it could not be
+    made or did not verify, and the caller re-encodes the whole cut."""
+    import _smartcut
+
+    def fallback(reason: str, code: str) -> dict:
+        return {"applied": False, "reason": reason, "reason_code": code}
+
+    # an existing output is refused before the parts are rendered and checked, not at placement
+    refuse_existing_outputs([output])
+    video = meta.get("video") or {}
+    if not video or is_audio_output(output):
+        return fallback("the cut has no picture to copy (an audio output or an audio-only source)", "no_video")
+    if dry_run_input_pending(args.input):
+        return fallback("the input does not exist yet, so its keyframes cannot be read", "pending_input")
+    for why in forced:
+        if why in ("vfr", "vfr_inconclusive"):
+            return fallback("the source's frame timing is variable or could not be measured; a copy of it cannot be "
+                            "placed frame-accurately", "vfr")
+        if why == "codec":
+            return fallback("--codec asks for another codec, so nothing can be copied", "codec")
+    if hold_needed:
+        return fallback("a segment runs past the end of the video, and only a re-encode can hold its last frame",
+                        "hold")
+    if meta.get("audio") and len(segments) > JOIN_CHUNK:
+        # the sound of every segment is one input of the join command; past this many the command
+        # line can outgrow Windows' limit, and the full re-encode joins in chunks of this size
+        return fallback(f"{len(segments)} segments with sound: the smart join takes at most {JOIN_CHUNK}, the "
+                        "full re-encode joins them in chunks", "segments")
+    ext = os.path.splitext(output)[1] or ".mp4"
+    params = _smartcut.stream_params(args.input)
+    bad = _smartcut.ineligible(params, meta, ext)
+    if bad:
+        return fallback(*bad)
+    packets = video_packets(args.input, segments, 0.5, total)
+    if not packets:
+        return fallback("the source's video packets could not be read", "packets")
+    with _join_workspace() as (tmp, temps):
+        dst = output if STATE.dry_run else sibling_temp(output, "smart")
+        if not STATE.dry_run:
+            temps.append(dst)
+        try:
+            doc = _smartcut.execute(args.input, segments, dst, meta, params, packets, args.crf, args.preset, tmp,
+                                    vend=video_end(args.input, meta), gop_is_open=gop_is_open, landing=seek_keyframe,
+                                    origin=file_origin, declick=DECLICK_S, seek_margin=SEEK_MARGIN)
+        except _smartcut.SmartFallback as exc:
+            return fallback(exc.reason, exc.code)
+        if not STATE.dry_run:
+            place_output(dst, output, move=True)
+    if meta.get("subtitle_streams") or meta.get("data_streams"):
+        DROPPED_STREAMS.append(output)
+    return doc
+
+
+def smart_verification(doc: dict) -> List[dict]:
+    """The --smart checks as verification steps (all passed: a failed one fell back before this)."""
+    c = doc["checks"]
+    return [{"step": "smart_frames", "ok": True, "frames": c["frames"], "grid_worst_seconds": c["grid_worst_seconds"]},
+            {"step": "smart_packets", "ok": True, "copied_packets_equal": c["copied_packets_equal"]},
+            {"step": "smart_decode", "ok": True, "frames_decoded_equal": c["frames_decoded_equal"]},
+            {"step": "smart_params", "ok": True, "time_base": c["time_base"]}]
+
+
 def main() -> int:
     global DECLICK_S
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
@@ -1316,6 +1380,11 @@ def main() -> int:
     ap.add_argument("--remove", metavar="START-END[,...]",
                     help="the inverse of --segments: drop these ranges and keep the rest, joined in order "
                          "(e.g. '1:20-2:05,10:00-10:30'); overlapping ranges merge")
+    ap.add_argument("--smart", action="store_true",
+                    help="keyframe-aware cut of an H.264 source: re-encode only from each cut point to the next keyframe "
+                         "(and from the last keyframe to the end point), matched to the source's profile, level, pixel "
+                         "format, reorder depth and colour tags, and stream-copy the whole GOPs between; verified (frame "
+                         "grid, copied packets, decoded frames) or re-encoded in full with the reason in smart.reason")
     ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate (video) / sample-accurate (audio) cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")
     el = ap.add_mutually_exclusive_group()
     el.add_argument("--edit-list", action="store_true",
@@ -1368,6 +1437,9 @@ def main() -> int:
     total = meta.get("duration") or 0.0
     # why every segment re-encodes, if one of these forces it; `requested` is read before the
     # guards below overwrite args.accurate, so a forced re-encode is never reported as asked for
+    if args.smart and args.accurate:
+        die("--smart re-encodes only the partial GOPs at each cut and copies the rest; --accurate re-encodes all of it: "
+            "choose one")
     forced: List[str] = ["requested"] if args.accurate else []
     if STATE.codec:
         # "cut this and make it HEVC": a stream copy keeps the source codec, so the request is a
@@ -1512,7 +1584,21 @@ def main() -> int:
     outcomes: List[dict] = []
     join_reencoded = False
     join_check = None
-    if len(segments) == 1:
+    smart_doc = None
+    if args.smart:
+        smart_doc = run_smart(args, segments, output, meta, forced, hold_needed, total)
+        if not smart_doc["applied"]:
+            # the stated fallback: the full re-encode --accurate makes, with the reason reported
+            record_fallback(f"--smart: {smart_doc['reason']}; re-encoding the whole cut instead", "smart_fallback",
+                            reason_code=smart_doc["reason_code"])
+            join_notes.append(f"--smart fell back to a full re-encode: {smart_doc['reason']}")
+            args.accurate = True
+            forced.append("smart_fallback")
+    if smart_doc is not None and smart_doc["applied"]:
+        # every part copied and no sound (a silent source cut on keyframes) re-encodes nothing
+        smart_encoded = bool(smart_doc["reencoded_frames"] or meta.get("audio"))
+        outcomes = [_outcome(meta, output, smart_encoded, ["smart"] if smart_encoded else []) for _ in segments]
+    elif len(segments) == 1:
         outcomes.append(cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance, meta,
                                 edit_list_ok=not args.no_edit_list))
     elif hold_needed or args.accurate:
@@ -1676,7 +1762,8 @@ def main() -> int:
     # mode: "copy" (nothing re-encoded at any stage, the join included), "accurate" (--accurate was
     # asked for or forced), "hybrid" (asked for lossless but a segment or the join re-encoded anyway;
     # reencode_reason says why)
-    mode = "copy" if not reencoded else ("accurate" if args.accurate else "hybrid")
+    mode = ("smart" if smart_doc is not None and smart_doc["applied"] else
+            "copy" if not reencoded else ("accurate" if args.accurate else "hybrid"))
     notes: List[str] = vfr_notes + join_notes + [n for o in outcomes for n in o.get("notes") or []]
     single = outcomes[0] if len(outcomes) == 1 else {}
     stored = single.get("stored_preroll_seconds")
@@ -1737,15 +1824,16 @@ def main() -> int:
          edit_list=bool(single.get("edit_list")), stored_preroll_seconds=stored, av_start_skew_seconds=skew,
          join_check=join_check, segment_end_snap_seconds=end_snaps,
          # the joins were faded only where the concat filter re-encoded them
-         declick_ms=(DECLICK_S * 1000 if len(segments) > 1 and (join_reencoded or args.accurate) and meta.get("audio")
-                     else None),
+         declick_ms=(DECLICK_S * 1000 if len(segments) > 1 and meta.get("audio")
+                     and (join_reencoded or args.accurate or mode == "smart") else None),
          notes=notes, **({"vfr_check": vfr_check} if vfr_check else {}),
          nearest_keyframes=sorted(NEAREST_KEYFRAMES) if NEAREST_KEYFRAMES else None,
          # the trade the caller can offer instead of a re-encode (eval e02: "without losing quality")
          lossless_alternative=(f"--start {min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])):.3f} lands on a keyframe: "
                                f"stream copy with no re-encode, {abs(min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])) - segments[0][0]):.2f}s off the requested start")
          if mode == "hybrid" and NEAREST_KEYFRAMES and len(segments) == 1 else None,
-         snap=snap_result)
+         snap=snap_result, **({"smart": smart_doc} if smart_doc is not None else {}),
+         **({"verification": smart_verification(smart_doc)} if smart_doc is not None and smart_doc.get("checks") else {}))
     return 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