ffmpeg-skill 3.2.1 → 3.2.3

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/scenes.py

@@ -31,6 +31,7 @@ from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter  # noqa: E402
 from _common.probe import square_pixels  # noqa: E402
+from _common import dry_run_input_pending  # noqa: E402
 
 SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
 SHOT_W, SHOT_H = 48, 27  # decode size for --shots (16:9-ish; enough blocks, still a few KB/shot)
@@ -148,8 +149,25 @@ def main() -> int:
         guard_sidecar(args.edl, args.input, siblings=(args.sheet,))
 
     meta = probe(args.input)
-    if not meta.get("video"):
-        die("input has no video stream")
+    # Under --dry-run in a render.py/batch.py plan the input may be an earlier stage's output that
+    # was never written: every measurement is skipped (diagnostics.skipped measurement_input_pending)
+    # and the document keeps its shape with nothing measured, as loudness.py/cut.py do -- not an
+    # ffmpeg failure that stops the plan from being written.
+    pending = dry_run_input_pending(args.input)
+    # An audio-only file (WAV/FLAC/MP3 ...) is measured too (after 3.2.0): the beat grid, the loudness
+    # peaks and the speech ratio are measurements of the sound, and a music bed is usually
+    # delivered without a picture. It has no picture to cut, so it is one scene from 0 to its
+    # duration -- the same answer a video with no cut in it gets -- and the result says
+    # audio_only: true. What needs a picture (--sheet, --shots) is refused, not skipped.
+    audio_only = not meta.get("video")
+    if audio_only:
+        if not meta.get("audio"):
+            die("input has no video or audio stream")
+        picture_flags = [f for f, on in (("--sheet", args.sheet), ("--shots", args.shots)) if on]
+        if picture_flags:
+            die(f"{' and '.join(picture_flags)} need{'s' if len(picture_flags) == 1 else ''} a video stream; "
+                "this file is audio-only (input has no video stream). --beats, --audio-peaks, --speech "
+                "and --highlights measure the sound alone.", kind="input")
     # Only parsed when it is going to be used: --beat-range is a --beats flag, and a run that
     # never asked for beats should not be able to die on one.
     beat_range = parse_beat_range(args.beat_range) if args.beats else (60.0, 200.0)
@@ -159,18 +177,22 @@ def main() -> int:
         if args.beat_step <= 0:
             die("--beat-step must be greater than 0", kind="input")
     dur = meta.get("duration") or 0.0
-    cuts = detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
+    cuts = [0.0] if (audio_only or pending) else detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
+    has_audio = bool(meta.get("audio")) and not pending
     bounds = cuts + [dur]
     step_s = 0.5
     # With --beats the file is decoded once, at the finer rate, and both envelopes come from that
     # one pass: the 0.5 s scene blocks are an exact multiple of the 10 ms onset blocks.
     beat_rate = 22050
     need_fine = args.beats or args.audio_peaks or args.speech
-    fine_samples = decode_pcm_mono(args.input, beat_rate, check=False) if (need_fine and meta.get("audio")) else None
+    # --beats decodes with check=True: a decode that fails is an ffmpeg failure, not an empty
+    # envelope reported as "no steady pulse in this audio" (the scene scoring alone tolerates it
+    # and runs on the picture)
+    fine_samples = decode_pcm_mono(args.input, beat_rate, check=bool(args.beats)) if (need_fine and has_audio) else None
     if fine_samples is not None:
         env = audio_envelope(args.input, step_s, rate=beat_rate, samples=fine_samples)
     else:
-        env = audio_envelope(args.input, step_s) if meta.get("audio") else []
+        env = audio_envelope(args.input, step_s) if has_audio else []
 
     scenes = []
     for i in range(len(bounds) - 1):
@@ -192,6 +214,8 @@ def main() -> int:
         peaks.sort(key=lambda p: p["time"])
 
     result: Dict = {"file": args.input, "duration": round(dur, 3), "scene_count": len(scenes), "scenes": scenes, "audio_peaks": peaks}
+    if audio_only:
+        result["audio_only"] = True
     info(f"{len(scenes)} scenes, {len(peaks)} audio peaks over {dur:.1f}s")
 
     if args.shots:
@@ -203,7 +227,7 @@ def main() -> int:
         info(f"--shots: {len(shots)} shots (" + ", ".join(f"{v} {k}" for k, v in sorted(counts.items())) + ")")
 
     if args.audio_peaks:
-        if not meta.get("audio"):
+        if not has_audio:
             result["audio_peaks_db"] = []
             info("--audio-peaks: no audio stream, nothing to measure")
         else:
@@ -212,7 +236,7 @@ def main() -> int:
             info(f"--audio-peaks: {len(result['audio_peaks_db'])} peaks")
 
     if args.speech:
-        if not meta.get("audio"):
+        if not has_audio:
             result["speech"] = []
             info("--speech: no audio stream, nothing to measure")
         else:
@@ -224,9 +248,15 @@ def main() -> int:
         # A beat grid is a measurement of the music's periodicity, not a statement about where a
         # cut belongs. scenes.py reports what it measured, including a low confidence: reporting a
         # weak measurement is honest, and only a tool that CHANGES a file refuses to act on one.
-        fine = rms_envelope(fine_samples or [], max(1, int(round(beat_rate * args.beat_step))))
-        grid = beat_grid(fine, args.beat_step, bpm_range=beat_range,
-                         min_confidence=args.min_confidence, duration=dur)
+        # The envelope's real step is a whole number of samples: 220 / 22050 = 9.977 ms for the
+        # default 10 ms. Timing the onsets as if it were 10 ms stretched every measured time by
+        # 0.23 % -- 68 ms by the end of a 30 s track, the "40-60 ms off" a click track showed --
+        # so the grid is timed (and step_s reported) at the step the envelope actually has.
+        beat_block = max(1, round(beat_rate * args.beat_step))
+        fine = rms_envelope(fine_samples or [], beat_block)
+        grid = beat_grid(fine, beat_block / beat_rate, bpm_range=beat_range,
+                         min_confidence=args.min_confidence, duration=dur,
+                         pcm=fine_samples, pcm_rate=beat_rate)
         result["beats"] = grid["beats"]
         result["beat_grid"] = {
             # The regular grid AND the subset a measured onset supports. A tool that MOVES
@@ -238,8 +268,13 @@ def main() -> int:
             "onsets": len(grid["onsets"]), "supported": grid["supported"],
             "unsupported": grid["unsupported"], "method": grid["method"],
             "step_s": grid["step_s"], "range_bpm": grid["range_bpm"], "usable": grid["usable"],
+            # after 3.2.0, additive: how each onset was timed below the envelope step
+            # ("pcm-window-ratio": placed on the decoded samples; null: at the step)
+            "onset_refinement": grid["onset_refinement"],
         }
-        if grid["tempo_bpm"] is None:
+        if pending:
+            info("--beats: [dry-run] the input does not exist yet, nothing measured")
+        elif grid["tempo_bpm"] is None:
             info(f"--beats: no steady pulse in this audio (confidence {grid['confidence']:.2f}) -- "
                  "speech, ambience or rubato has no tempo to measure")
         else: