ffmpeg-skill 3.8.12 → 3.8.14

package/scripts/multicam.py

@@ -30,9 +30,9 @@ import json
 import math
 import os
 import sys
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 
-from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
+from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.decision import av_trim, conform_output_t, conform_to_length, rebase_project_paths
 from _common.probe import display_size, square_pixels, square_pixels_note
@@ -60,8 +60,19 @@ def parse_switch(spec: str, n: int) -> List[Tuple[float, float, int]]:
             die(f"camera {c} does not exist (inputs are 0..{n - 1})")
         if e <= s:
             die(f"switch entry '{raw}': end must be after start")
+        if round(e, 3) <= round(s, 3):
+            # the cut list (--edl, `cuts`) is written to the millisecond: this range was its
+            # "0.000-0.000", a line cut.py --segments refuses (the scenes.py --edl sibling)
+            die(f"switch entry '{raw}': shorter than a millisecond, the precision the cut list is written in",
+                kind="input")
         out.append((s, e, c))
     out.sort()
+    # A132: ranges on one timeline cannot overlap. The fill below kept both, so the picture of the
+    # overlap played twice while the sound played once, and every later cut ran behind it
+    for (s0, e0, _c0), (s1, e1, _c1) in zip(out, out[1:]):
+        if s1 < e0:
+            die(f"--switch ranges overlap: {fmt_secs(s0)}-{fmt_secs(e0)} and {fmt_secs(s1)}-{fmt_secs(e1)} "
+                "(on the reference timeline each moment has one camera)", kind="input")
     return out
 
 
@@ -158,7 +169,7 @@ def main() -> int:
         media_out = args.output or default_output(args.inputs[0], "multicam", "mp4")
         guard_sidecar(args.edl, *args.inputs, siblings=(args.write_project, media_out))
         guard_sidecar(args.write_project, *args.inputs, siblings=(media_out,))
-        if args.edl or args.write_project:  # they are written before the cut: refuse its output first
+        if args.edl or args.write_project:  # refused up front with them, before any decode
             guard_sidecar(media_out, *args.inputs)
     if args.analyze_seconds > 900:
         die(f"--analyze-seconds {args.analyze_seconds:g}: the window is decoded into memory; 900 s is the ceiling")
@@ -272,17 +283,26 @@ def main() -> int:
         cursor = max(cursor, e)
     if cursor < ref_dur:
         filled.append((cursor, ref_dur, 0))
+    # a gap or a clipped range under a millisecond is nothing at the precision the cut list is
+    # written in (--switch "0.0004-3:1" left a leading "0.000-0.000", the line cut.py --segments
+    # refuses, and a 0.4 ms trim in the render): its neighbour takes it, so the timeline stays whole
+    whole: List[Tuple[float, float, int]] = []
+    carry: Optional[float] = None
+    for s, e, c in filled:
+        if carry is not None:
+            s, carry = carry, None
+        if round(e, 3) <= round(s, 3):
+            if whole:
+                whole[-1] = (whole[-1][0], e, whole[-1][2])
+            else:
+                carry = s
+            continue
+        whole.append((s, e, c))
+    filled = whole
     for s, e, c in filled:
         if not metas[c].get("video"):
             die(f"camera {c} ({args.inputs[c]}) has no video; it can only be used with --audio")
 
-    if args.edl:
-        if not STATE.dry_run:
-            with open(args.edl, "w", encoding="utf-8") as fh:
-                for s, e, _c in filled:
-                    fh.write(f"{s:.3f}-{e:.3f}\n")
-        info(f"wrote {args.edl}")
-
     v0 = metas[0]["video"]
     # camera 0's displayed frame: rotation applied, non-square pixels squared (#411)
     w, h = args.width or display_size(v0)[0], args.height or display_size(v0)[1]
@@ -322,9 +342,18 @@ def main() -> int:
             c, src_s, src_e = 0, s, e
         rendered.append((s, e, c))
         sq = (square_pixels(metas[c]["video"]) + ",") if square_pixels(metas[c]["video"]) else ""
-        parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts=PTS-STARTPTS,{convert[c]}{sq}{geo}[v{i}]")
+        # A130: a drift-corrected camera's range is (e - s) * ratio of its own time; played at that
+        # rate it lasts e - s on the reference, as its sound does (asetrate) -- at its own rate the
+        # picture ran (ratio - 1) * (e - s) long and every later cut fell behind the sound
+        retime = f"(PTS-STARTPTS)/{ratios[c]:.9f}" if abs(ratios[c] - 1.0) > 1e-7 else "PTS-STARTPTS"
+        parts.append(f"[{c}:v]trim=start={src_s:.4f}:end={src_e:.4f},setpts={retime},{convert[c]}{sq}{geo}[v{i}]")
         labels.append(f"[v{i}]")
-        project_clips.append({"src": args.inputs[c], "in": round(src_s, 3), "out": round(src_e, 3)})
+        clip = {"src": args.inputs[c], "in": round(src_s, 3), "out": round(src_e, 3)}
+        if abs(ratios[c] - 1.0) > 1e-7:
+            # render.py plays a clip at clips[].speed (its length / speed), as the retime above
+            # does: without it a drift-corrected camera's clip ran (ratio - 1) * (e - s) long
+            clip["speed"] = round(ratios[c], 9)
+        project_clips.append(clip)
     parts.append("".join(labels) + f"concat=n={len(filled)}:v=1:a=0[vout]")
     a = args.audio
     a_start = -offsets[a] if offsets[a] < 0 else 0.0
@@ -358,17 +387,29 @@ def main() -> int:
         # render.py project instead of the direct render this tool already does -- additive, not
         # a replacement: the combined output below is still written as usual.
         project = {"output": default_output(args.inputs[0], "multicam_project", "mp4"),
-                   "clips": project_clips}
+                   "clips": project_clips,
+                   # a switch is a cut: render.py's default is a 0.5 s crossfade at every join,
+                   # which shortens the timeline by 0.5 s a switch and moves every later one
+                   "transition": {"type": "none"}}
         # the inputs are named as given, relative to the working directory, and render.py reads a
         # project's relative paths against the project file's directory: written elsewhere
         # (--write-project out/cut.json), they named files that are not there
         project = rebase_project_paths(project, os.getcwd())
+
+    run(cmd)
+    # the EDL and the project record the cut: written once it exists, not before an encode that then
+    # failed (#462 A41, the silence.py --edl sibling)
+    if args.edl:
+        if not STATE.dry_run:
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e, _c in filled:
+                    fh.write(f"{s:.3f}-{e:.3f}\n")
+        info(f"wrote {args.edl}")
+    if args.write_project:
         if not STATE.dry_run:
             with open(args.write_project, "w", encoding="utf-8") as fh:
                 fh.write(json.dumps(project, indent=2) + "\n")
         info(f"wrote {args.write_project}")
-
-    run(cmd)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {len(filled)} cuts, audio from input {a})")
     extra = {"switch_mode": "energy", "min_shot": args.min_shot} if energy_mode else {}

package/scripts/overlay.py

@@ -35,7 +35,7 @@ from typing import Any, Dict, List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 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, overlay_format, 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 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, overlay_format, 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, probe, run_keeping_subtitles, validate_color, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb
 from _common.decision import length_output_t, window_expr, windowed_overlay_x

package/scripts/probe.py

@@ -15,10 +15,11 @@ Examples:
 points a stream copy can start at, and where cut.py --smart's re-encode around a cut ends.
 """
 import argparse
+import json
 import math
 import sys
 
-from _common import add_common, analyze_levels, apply_common, die, keyframe_times, print_json, probe, time_arg
+from _common import STATE, add_common, analyze_levels, apply_common, die, keyframe_times, print_json, probe, time_arg
 
 
 def keyframe_candidates(result: dict, times: list, window: float) -> list:
@@ -87,7 +88,17 @@ def main() -> int:
             cur = r
             for key in args.field.split("."):
                 cur = cur.get(key) if isinstance(cur, dict) else None
-            print(cur if cur is not None else "")
+            # a string as itself; anything else as JSON (true, null, {"codec": ...}), not Python's
+            # repr (True, None, {'codec': ...}), which no caller can parse (through 3.8.8, A123).
+            # Under --json (or --json-brief, which implies it) a missing field is null and a string
+            # is quoted: every line is JSON. Without either a missing field is an empty line, as it
+            # always was, so `[ -z "$(probe.py f --field x)" ]` keeps working
+            if isinstance(cur, str) and not STATE.json:
+                print(cur)
+            elif cur is None and not STATE.json:
+                print("")
+            else:
+                print(json.dumps(cur, ensure_ascii=False))
         return 0
 
     if args.compact:

package/scripts/proxy.py

@@ -5,7 +5,8 @@ editing-decision workflows that only need to look at (or feed a model) a
 much smaller stand-in for the original.
 
 Resizes to --width (default 640px, height follows the source aspect) or by
---scale factor, re-encodes at a proxy-grade --quality (default 30 - well above any
+--scale factor, never wider than the source (a proxy is not upscaled) and
+never under 2px, re-encodes at a proxy-grade --quality (default 30 - well above any
 delivery preset's 18-24 in export.py, since a proxy trades visual quality for
 size and speed), and always uses the fastest x264/x265 preset. Keeps the
 source's own dynamic range (an HDR source proxies to HEVC10, same as every
@@ -65,7 +66,15 @@ def main() -> int:
         note(square_pixels_note(meta["video"]))
     has_audio = bool(meta.get("audio")) and not args.no_audio
 
-    out_w = even(sw * args.scale) if args.scale is not None else even(args.width)
+    # A proxy is never wider than its source, and never under 2 px: through 3.8.8 the default
+    # --width 640 upscaled a smaller source, and a --scale that rounded to 0 became scale=0, which
+    # ffmpeg reads as "the input's width" (a full-size proxy, audit A162)
+    asked = even(sw * args.scale) if args.scale is not None else even(args.width)
+    ceiling = max(2, sw - sw % 2) if sw else asked
+    out_w = max(2, min(asked, ceiling))
+    if out_w != asked:
+        note(f"proxy width {out_w}px, not {asked}px: "
+             + (f"the source is {sw}px wide and a proxy is not upscaled" if asked > ceiling else "2px is the smallest width"))
     output = args.output or default_output(args.input, "proxy")
 
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", (square + "," if square else "") + f"scale={out_w}:-2"]

package/scripts/redact.py

@@ -113,7 +113,11 @@ def main() -> int:
             # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
             # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
             radius = max(1, min(args.blur_strength, min(args.width, args.height) // 2 - 1))
-            chroma = max(1, min(radius // 2, min(args.width, args.height) // 4 - 1))
+            # at least 1 wherever the chroma plane can hold it: radius // 2 alone was 0 at
+            # --blur-strength 1, which left colour-only detail readable (review of #521). (FFmpeg
+            # 7.1 refuses a chroma radius of 1 on a 2 px chroma plane, a 4 px wide region; 6.1
+            # took it.) 0 is only a plane too small to blur: the luma still is
+            chroma = max(0, min(max(1, radius // 2), (min(args.width, args.height) // 2 - 1) // 2))
             region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
         else:
             region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"

package/scripts/scenes.py

@@ -110,6 +110,48 @@ def speech_music_ratio(samples: "List[float]", rate: int, step_s: float = SPEECH
     return [{"time": round(i * step_s, 2), "speech_music_ratio": round(z / med, 3)} for i, z in enumerate(zcrs)]
 
 
+# A --sheet picks one frame a scene with select. One expression summing a term a scene was refused
+# by FFmpeg 7.1 and later at 3,000 scenes ("Error while parsing expression", ENOMEM) and taken by
+# 6.1. No expression here grows with the scene count: the scenes are dealt round-robin to branches
+# of at most SHEET_SELECT_TERMS terms, each summed as a balanced tree (at most
+# ceil(log2(SHEET_SELECT_TERMS)) = 6 nested parentheses), and the branches' frames are merged back in
+# time order by interleave. Round-robin keeps the branches level, so interleave holds about one
+# thumbnail a branch.
+SHEET_SELECT_TERMS = 64
+
+
+def _first_at(t: float) -> str:
+    """The select term for the first frame at or after `t`. The starts are presentation times, so
+    the frame is chosen by its time, not by start x fps as a frame number -- on a
+    variable-frame-rate source that number is another frame (#411)."""
+    a = f"{max(0.0, t - 0.0006):.4f}"
+    return f"gte(t\\,{a})*(isnan(prev_t)+lt(prev_t\\,{a}))"
+
+
+def _balanced_sum(terms: List[str]) -> str:
+    if len(terms) == 1:
+        return terms[0]
+    mid = len(terms) // 2
+    return f"({_balanced_sum(terms[:mid])}+{_balanced_sum(terms[mid:])})"
+
+
+def sheet_graph(starts: List[float], src: str, thumb: str, tile: str) -> str:
+    """The --sheet filter graph: exactly one frame a scene (the first at or after its start), each
+    made a thumbnail by `thumb`, laid out by `tile`, out as [sheet]."""
+    # no scene (a dry run whose input an earlier step has yet to write, a clip of under one scene):
+    # the sheet is its one tile, the first frame, as the 1x1 layout the caller sized for it
+    starts = starts or [0.0]
+    k = max(1, math.ceil(len(starts) / SHEET_SELECT_TERMS))
+    if k == 1:
+        return f"{src}select='{_balanced_sum([_first_at(t) for t in starts])}',{thumb},{tile}[sheet]"
+    parts = [f"{src}split={k}" + "".join(f"[s{j}]" for j in range(k))]
+    for j in range(k):
+        expr = _balanced_sum([_first_at(t) for t in starts[j::k]])
+        parts.append(f"[s{j}]select='{expr}',{thumb}[t{j}]")
+    parts.append("".join(f"[t{j}]" for j in range(k)) + f"interleave=nb_inputs={k},{tile}[sheet]")
+    return ";".join(parts)
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -305,6 +347,7 @@ def main() -> int:
             rank_key = lambda sc: (-sc["audio_rms"], sc["start"])
         ranked = sorted(scenes, key=rank_key)[: args.highlights]
         picks: List[Tuple[float, float]] = []
+        empty: List[Tuple[float, float]] = []
         budget = args.target if args.target else None
         per = (budget / max(1, len(ranked))) if budget else args.max_scene
         for sc in ranked:
@@ -314,36 +357,44 @@ def main() -> int:
             if env and length < sc["duration"]:
                 best, best_s = -1.0, sc["start"]
                 win = max(1, int(length / step_s))
-                lo, hi = int(sc["start"] / step_s), max(int(sc["start"] / step_s) + 1, int(sc["end"] / step_s) - win)
-                for i in range(lo, hi + 1):
+                # A139: a window starts at the scene's start or on the step grid after it, and
+                # ends inside the scene. The grid point at or before the start (floor) was a
+                # candidate, so a pick opened up to one step (0.5 s) early, on the previous shot
+                latest = sc["end"] - length
+                starts = [sc["start"]] + [i * step_s for i in range(math.ceil(sc["start"] / step_s - 1e-9),
+                                                                      math.floor(latest / step_s + 1e-9) + 1)
+                                          if sc["start"] < i * step_s <= latest]
+                for t in starts:
+                    i = int(t / step_s + 1e-9)
                     val = sum(env[i:i + win])
                     if val > best:
-                        best, best_s = val, i * step_s
-            picks.append((round(best_s, 2), round(min(sc["end"], best_s + length), 2)))
+                        best, best_s = val, t
+            # to the hundredth the result and the EDL are written in, inward: a start of 3.333
+            # written as 3.33 opened on the frame before the cut
+            pick_s = math.ceil(best_s * 100 - 1e-6) / 100
+            pick_e = math.floor(min(sc["end"], pick_s + length) * 100 + 1e-6) / 100
+            if pick_e <= pick_s:
+                # no hundredth fits inside it: written as 0.00-0.00 it was a range cut.py refuses
+                empty.append((sc["start"], sc["end"]))
+                continue
+            picks.append((pick_s, pick_e))
+        if empty and not picks:
+            die(f"--highlights found no range of at least 0.01 s, the precision the ranges are written in "
+                f"(each pick is at most {min(per, args.max_scene):g} s, or its scene is shorter)",
+                kind="input", hint="raise --target (or drop it), or lower --highlights")
+        for s, e in empty:
+            note(f"--highlights: the scene {s:.3f}-{e:.3f}s holds no range of at least 0.01 s and has no pick")
         picks.sort()
         result["highlights"] = [{"start": s, "end": e, "duration": round(e - s, 2)} for s, e in picks]
         result["highlights_total"] = round(sum(e - s for s, e in picks), 2)
         result["highlights_rank_by"] = args.rank_by
         info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
-        if args.edl:
-            if not STATE.dry_run:  # the contract says --edl is not written under --dry-run
-                with open(args.edl, "w", encoding="utf-8") as fh:
-                    for s, e in picks:
-                        fh.write(f"{s:.2f}-{e:.2f}\n")
-            info(f"wrote {args.edl}")
 
     if args.sheet:
         n = len(scenes)
         cols = min(4, max(1, n))
         rows = max(1, math.ceil(n / cols))
         tile_w = 1280 // cols // 2 * 2
-        # exactly one frame per scene: the first frame at or after the scene start. The starts are
-        # presentation times, so the frame is chosen by its time, not by start x fps as a frame
-        # number -- on a variable-frame-rate source that number is another frame (#411)
-        def first_at(t: float) -> str:
-            a = f"{max(0.0, t - 0.0006):.4f}"
-            return f"gte(t\\,{a})*(isnan(prev_t)+lt(prev_t\\,{a}))"
-        expr = "+".join(first_at(sc["start"]) for sc in scenes)
         stamp = ""
         if not args.no_timecode and ffmpeg_filters() and "drawtext" not in ffmpeg_filters():
             # as look.py (#394): the sheet needs drawtext only for its stamps
@@ -360,13 +411,23 @@ def main() -> int:
         # a non-square-pixel source is squared at its display aspect (#411)
         lab = bt709_label_filter(meta)
         square = square_pixels(meta["video"])
-        vf = (f"select='{expr}'," + (lab + "," if lab else "") + (square + "," if square else "")
-              + f"scale={tile_w}:-2{stamp},"
-              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        run(ffmpeg_base() + ["-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-an", "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
+        thumb = (lab + "," if lab else "") + (square + "," if square else "") + f"scale={tile_w}:-2{stamp}"
+        graph = sheet_graph([sc["start"] for sc in scenes], f"[0:{PROBED_VIDEO}]", thumb,
+                            f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
+        run(ffmpeg_base() + ["-i", args.input, "-filter_complex", graph, "-map", "[sheet]", "-an",
+                             "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
         info(f"wrote {args.sheet}")
         result["sheet"] = args.sheet
 
+    # after the sheet, as silence.py writes its EDL after the cut (#462 A41): a --sheet refused as an
+    # existing file, or failed, left the EDL behind, and the corrected retry was then refused for it
+    if args.highlights and args.edl:
+        if not STATE.dry_run:  # the contract says --edl is not written under --dry-run
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e in picks:
+                    fh.write(f"{s:.2f}-{e:.2f}\n")
+        info(f"wrote {args.edl}")
+
     if STATE.json:  # --json-brief too: emit() is what adds the diagnostics (scenes_sheet_no_drawtext)
         emit(None, **result)
     else:

package/scripts/silence.py

@@ -33,7 +33,7 @@ from _common.runner import parse_json, replace_checked
 from _common import guard_sidecar, refuse_existing_outputs, refuse_output_is_input, _check_output_path
 from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
-from _common.decision import frame_rate, stream_starts
+from _common.decision import frame_rate, grid_at_or_after, stream_starts
 from _common.probe import PROBED_AUDIO
 from _common.emit import input_length
 
@@ -163,21 +163,47 @@ def speech_aware_silences(path: str, threshold: float, min_silence: float) -> "T
     return boundaries, breaths
 
 
+# how close to the start or the end of the sound a silence's edge may sit and still be where the sound
+# starts or ends: silencedetect closes a silence that runs to the end at its last decoded block (7.509
+# for a sound probed as 7.500), and an AAC stream's stated start sits a priming frame off its samples
+SOUND_EDGE = 0.05
+
+
+def sound_span(meta: Dict[str, Any], duration: float) -> Tuple[float, float]:
+    """Where the sound starts and ends on the clock silencedetect reports on (the file's), for
+    inside_margin(): its start, and its own end (the file's length when that is not stated). The
+    end is stream_end()'s: a Matroska DURATION tag is already where the sound ends, and adding the
+    start to it put the end of a sound from 1 s to 6 s at 7 s."""
+    from _common.emit import file_origin, stream_end
+    a0 = stream_starts(meta)[1]
+    end = stream_end(meta, "audio")
+    return a0, (end - file_origin(meta)) if end is not None else duration
+
+
 def inside_margin(silences: List[Tuple[float, float]], duration: float, margin: float,
-                  lead: Optional[float] = None) -> List[Tuple[float, float]]:
+                  lead: Optional[float] = None,
+                  sound: Optional[Tuple[float, float]] = None) -> List[Tuple[float, float]]:
     """Each silence with a margin kept on both sides: the stretch actually removed. `margin` is
     kept after the speech that ends where the silence starts (--margin-tail), `lead` before the
     speech that starts where it ends (--margin-lead; the same as `margin` when not given). A
     silence too short to hold both removes nothing (it is dropped, never turned inside out).
 
+    A silence with no speech on one side keeps no margin on that side (#462 A40): one that starts
+    where the sound does (`sound`, from sound_span()) is removed from the file's start, and one
+    that runs to where the sound ends (or that silencedetect never closed, `inf`) to the file's end.
+    A margin there kept dead air as a piece of its own, with a jump cut after it; FFmpeg 6.1 closes
+    a silence at the end of the file, so the `inf` end alone never caught the last one.
+
     The margin is applied to the silences alone, before they are merged with filler spans (#414):
     a filler word's span is the word itself plus --filler-pad, and taking a 0.2 s margin off each
     side of it turned every word narrower than 2 x --margin inside out -- kept, and still counted
     as removed."""
     out: List[Tuple[float, float]] = []
     for s, e in silences:
-        a = s + margin
-        b = duration if e == float("inf") else min(duration, e - (margin if lead is None else lead))
+        opens = sound is not None and s <= sound[0] + SOUND_EDGE
+        closes = e == float("inf") or (sound is not None and e >= sound[1] - SOUND_EDGE)
+        a = 0.0 if opens else s + margin
+        b = duration if closes else min(duration, e - (margin if lead is None else lead))
         if b > a:
             out.append((a, b))
     return out
@@ -215,7 +241,10 @@ def rendered_ranges(keeps: List[Tuple[float, float]], meta: Dict[str, Any], dura
     v0 = stream_starts(meta)[0]
 
     def snap(t: float) -> float:
-        return min(v0 + round((t - v0) * rate) / rate, duration)
+        # a video that starts after the sound puts frame times before 0 on its grid's extension: a
+        # bound there moves to the first one at or after 0, which is where the re-cut starts (#462 A43)
+        t = v0 + round((t - v0) * rate) / rate
+        return min(t if t >= 0 else grid_at_or_after(0.0, v0, rate), duration)
     return [(a, b) for a, b in ((snap(s), snap(e)) for s, e in keeps) if b > a]
 
 
@@ -307,8 +336,10 @@ def cut_levels(path: str, tm: Dict[str, Any], duration: float,
     out = []
     with tempfile.TemporaryDirectory(prefix="silence-levels-") as tmp:
         raw = os.path.join(tmp, "pcm.s16le")
+        # padded from the file's start, as decode_pcm_mono() pads it: the windows are read at
+        # t x rate, so a sound that starts late was read that far after each cut (#462 A42)
         proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path,
-                             "-map", f"0:{PROBED_AUDIO}", "-vn",
+                             "-map", f"0:{PROBED_AUDIO}", "-vn", "-af", "aresample=async=1:first_pts=0",
                              "-ac", str(channels), "-ar", str(CUT_LEVEL_RATE), "-f", "s16le", "-y", raw],
                             check=False, text=False)
         if proc.returncode != 0 or not os.path.isfile(raw) or not os.path.getsize(raw):
@@ -624,8 +655,9 @@ def main() -> int:
     fil.add_argument("--filler-list", action="store_true",
                      help="report what --filler would remove and write nothing")
     fil.add_argument("--max-cuts", type=int, default=400,
-                     help="refuse above this many removal ranges: the filter graph grows with them "
-                          "(default 400)")
+                     help="refuse to render above this many removal ranges (default 400): that many cuts usually "
+                          "means --threshold, --min-silence or the filler list is catching speech. --list and "
+                          "--filler-list report them without the limit")
     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_common(ap)
@@ -686,6 +718,7 @@ def main() -> int:
     if not meta.get("audio"):
         die("input has no audio stream to analyse")
     duration = input_length(meta)
+    sound = sound_span(meta, duration)
     breaths: List[Tuple[float, float]] = []
     if args.speech_aware:
         silences, breaths = speech_aware_silences(args.input, args.threshold, args.min_silence)
@@ -717,10 +750,10 @@ def main() -> int:
     def margined(spans: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
         """The stretch of each silence that is removed: its own tail for one after a sentence end."""
         if not by_sentence:
-            return inside_margin(spans, duration, tail, lead)
+            return inside_margin(spans, duration, tail, lead, sound)
         out: List[Tuple[float, float]] = []
         for span, pos in zip(spans, positions):
-            out += inside_margin([span], duration, sentence_tail if pos == "sentence_end" else tail, lead)
+            out += inside_margin([span], duration, sentence_tail if pos == "sentence_end" else tail, lead, sound)
         return out
     # One sorted, merged removal list through the graph the tool already has: filler removal IS
     # time-range removal, so it reuses keep_ranges() and the same select chain.
@@ -730,7 +763,9 @@ def main() -> int:
     keeps = keep_ranges(removals, duration, 0.0, args.min_keep)
     # what the render holds (on a picture, each bound on its nearest frame): the report, the EDL
     # and the time map all describe these, so a re-cut or a sum of `keep` is the rendered edit
-    video_out = bool(meta.get("video")) and not (media_out and is_audio_output(media_out))
+    # from the -o given, under --list and --filler-list too (which write no media): a list for an
+    # audio -o reported frame-snapped ranges that the audio run does not cut (#462 A48)
+    video_out = bool(meta.get("video")) and not is_audio_output(args.output or "")
     held = rendered_ranges(keeps, meta, duration, video_out)
     kept = sum(e - s for s, e in held)
     removed = max(0.0, duration - kept)
@@ -787,10 +822,6 @@ def main() -> int:
         # an English-only transcript made on an assumption (asr.assumed_english_note): the
         # bridge already logged the warning; the result document carries it at the top level
         summary["notes"] = list(args._asr_notes)
-    if len(keeps) > args.max_cuts:
-        die(f"{len(keeps)} keep ranges is above --max-cuts {args.max_cuts}: the filter graph grows "
-            "with every range and a graph this size is slow and fragile. Raise --max-cuts if you "
-            "mean it, or use --min-silence/--filler-pad to merge the short ones.", kind="input")
     filler_only = args.filler and not args.speech_aware and not by_sentence
     if filler_only:
         info(f"--filler only (no --speech-aware): skipping generic silence detection, "
@@ -812,6 +843,14 @@ def main() -> int:
         info("hint: " + summary["hint"])
 
     tm = time_map(held, duration)
+    cuts = len(tm["removed"])
+    if cuts > args.max_cuts and not (args.list or args.filler_list):
+        # the removal ranges, as --max-cuts says, not the kept ones; a list renders nothing and is
+        # how the caller sees what the limit is about (#462 A49)
+        die(f"{cuts} removal ranges is above --max-cuts {args.max_cuts}: that many cuts usually means "
+            "--threshold, --min-silence or the filler list is catching speech. Check them with --list, then "
+            "raise --max-cuts if you mean it, or use --min-silence/--filler-pad to merge the short ones.",
+            kind="input")
     points: Any = False  # False: not measured (a dry run over a pending input); None: the decode failed
     if not (STATE.dry_run and not os.path.exists(args.input)):
         points = cut_levels(args.input, tm, duration, list(filler_ranges))
@@ -841,7 +880,12 @@ def main() -> int:
             info(f"wrote {args.timemap}")
         summary["timemap"] = args.timemap
 
-    if args.edl:
+    def finish_edl() -> None:
+        """Written with the time map, once the cut exists (or under --list): an EDL left by a
+        refused run (an existing -o, -o the input, nothing kept) or a failed encode described
+        media never made, and then blocked the corrected retry as an existing file (#462 A41)."""
+        if not args.edl:
+            return
         if not STATE.dry_run:  # the EDL is an artifact like the cut itself: a plan writes nothing
             with open(args.edl, "w", encoding="utf-8") as fh:
                 on_frames = bool(video_out and frame_rate(meta))
@@ -852,6 +896,7 @@ def main() -> int:
         info(f"wrote {args.edl}")
 
     if args.list or args.filler_list:
+        finish_edl()
         finish_time_map()
         if args.json:
             emit(None, **summary)
@@ -883,6 +928,7 @@ def main() -> int:
         _cut.join_from_source(args.input, held, output, meta, args.crf, args.preset, tmp)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{kept:.3f}s)")
+    finish_edl()
     finish_time_map()
     emit(output, **summary)
     return 0

package/scripts/sphere.py

@@ -6,7 +6,8 @@ turning an equirectangular (or other spherical-projection) source into an
 ordinary flat video pointed at a chosen direction -- the same "look this way"
 operation a VR headset or a 360 video player's viewport does, baked into a
 real file. --yaw/--pitch/--roll aim the camera; --h-fov/--v-fov set how wide
-the view is.
+the view is (without --v-fov, the vertical view is the one that keeps the
+output's pixels square).
 
 This tool does not decide WHERE to point the camera -- there is no subject
 detection or tracking here, only the typed rotation/FOV you give it (see this
@@ -29,9 +30,11 @@ Examples:
   python3 sphere.py gopro_max.mp4 --input-projection fisheye --yaw -45 --pitch 10 -o angle.mp4
 """
 import argparse
+import math
 import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
+from _common.emit import note
 
 # v360's own AVOption names for the input projections real 360 cameras/exports actually
 # produce (ffmpeg -h filter=v360 documents 24 total; this is the subset a caller is likely
@@ -59,7 +62,9 @@ def main() -> int:
     aim.add_argument("--roll", type=float, default=0.0, help="tilt/roll rotation in degrees, -180..180 (default 0)")
     fov = ap.add_argument_group("field of view")
     fov.add_argument("--h-fov", type=float, default=90.0, help="output horizontal field of view in degrees, 1..170 (default 90)")
-    fov.add_argument("--v-fov", type=float, default=60.0, help="output vertical field of view in degrees, 1..170 (default 60)")
+    fov.add_argument("--v-fov", type=float, default=None,
+                     help="output vertical field of view in degrees, 1..170 (default: the one that keeps pixels square at "
+                          "--h-fov and --width/--height, 58.7 at the defaults)")
     out = ap.add_argument_group("output frame")
     out.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
     out.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
@@ -81,12 +86,27 @@ def main() -> int:
         die(f"--roll must be -180..180, got {args.roll}")
     if not 1 <= args.h_fov <= 170:
         die(f"--h-fov must be 1..170, got {args.h_fov}")
-    if not 1 <= args.v_fov <= 170:
+    if args.v_fov is not None and not 1 <= args.v_fov <= 170:
         die(f"--v-fov must be 1..170, got {args.v_fov}")
     if args.width <= 0 or args.height <= 0:
         die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
     if args.width % 2 or args.height % 2:
         die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+    # A rectilinear view has square pixels when tan(v/2) / tan(h/2) = H / W. Through 3.8.8 the
+    # default was a fixed 60 degrees, which at 90 x 1920x1080 squashed the view 2.6 % vertically
+    # (audit A163); the vertical FOV now follows from the other three unless it is given.
+    square_v = math.degrees(2 * math.atan(math.tan(math.radians(args.h_fov) / 2) * args.height / args.width))
+    if args.v_fov is None:
+        if not 1 <= square_v <= 170:
+            die(f"--h-fov {args.h_fov:g} at {args.width}x{args.height} needs a vertical field of view of {square_v:.1f} "
+                "degrees for square pixels, outside 1..170", hint="give --v-fov, or a lower --h-fov")
+        args.v_fov = round(square_v, 4)
+    else:
+        stretch = math.tan(math.radians(args.v_fov) / 2) / math.tan(math.radians(square_v) / 2)
+        if abs(stretch - 1) > 0.005:
+            note(f"--h-fov {args.h_fov:g} / --v-fov {args.v_fov:g} at {args.width}x{args.height} is not square-pixel: the view is "
+                 f"{'squashed' if stretch > 1 else 'stretched'} {abs(stretch - 1) * 100:.1f} % vertically "
+                 f"(--v-fov {square_v:.2f} keeps it square; omit --v-fov to get it)")
 
     meta = probe(args.input)
     if not meta.get("video"):

package/scripts/stabilize.py

@@ -29,7 +29,7 @@ from pathlib import Path
 
 from _common.probe import PROBED_VIDEO
 from _common.runner import ffmpeg_failure_extra, default_selection_maps, require_filter
-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
+from _common import 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:
@@ -96,7 +96,10 @@ def main() -> int:
                 die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
-        transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
+        # optzoom=0: the zoom is --zoom and nothing else. vidstab's default (optzoom=1) adds its own
+        # "optimal" zoom on top, so --zoom 0 did not keep the original framing and --crop black
+        # rarely had an edge to fill (through 3.8.8, audit A156)
+        transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=0"
         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.