ffmpeg-skill 1.4.4 → 1.4.6

package/scripts/cut.py

@@ -30,7 +30,11 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run
+from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run, X264_PRESETS, keyframes_near
+
+# keyframe timestamps found next to a requested cut that the tolerance turned into a re-encode
+# (reported so the caller can choose a lossless cut at one of them next time)
+NEAREST_KEYFRAMES: list = []
 
 
 def parse_segments(spec: str) -> List[Tuple[float, float]]:
@@ -113,11 +117,18 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
-    if not reencode and tolerance >= 0 and not STATE["dry_run"]:
+    if not reencode and tolerance >= 0 and not STATE.dry_run:
         got = probe(dst).get("duration") or 0.0
         if abs(got - dur) > tolerance:
+            near = keyframes_near(src, start)
+            alt = ""
+            if near:
+                closest = min(near, key=lambda k: abs(k - start))
+                alt = (f"; for a lossless cut move --start to a keyframe (nearest: {closest:.3f}s"
+                       + (f", others within 5 s: {', '.join(f'{k:.3f}' for k in near if k != closest)}" if len(near) > 1 else "") + ")")
+                NEAREST_KEYFRAMES.extend(k for k in near if k not in NEAREST_KEYFRAMES)
             info(f"stream copy landed on a keyframe {abs(got - dur):.2f}s away from the requested cut "
-                 f"(> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy")
+                 f"(> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy{alt}")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
     return reencode
 
@@ -134,7 +145,7 @@ def main() -> int:
     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)")
     ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset when re-encoding")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset when re-encoding")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -198,7 +209,7 @@ def main() -> int:
     expected = sum(e - s for s, e in segments)
     precision = precision_of(meta, output, reencoded)
     got = result.get("duration")
-    error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE["dry_run"] else None
+    error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE.dry_run else None
     # mode: "copy" (untouched lossless), "accurate" (--accurate was asked for), "hybrid" (asked for
     # lossless but the keyframe snap exceeded --tolerance so this segment silently re-encoded instead)
     mode = "copy" if not reencoded else ("accurate" if args.accurate else "hybrid")
@@ -211,7 +222,8 @@ def main() -> int:
          requested_segments=[[round(s, 6), round(e, 6)] for s, e in segments] if len(segments) > 1 else None,
          requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None else None,
          duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,
-         mode=mode, keyframe_snapped=keyframe_snapped)
+         mode=mode, keyframe_snapped=keyframe_snapped,
+         nearest_keyframes=sorted(NEAREST_KEYFRAMES) if NEAREST_KEYFRAMES else None)
     return 0
 
 

package/scripts/deinterlace.py

@@ -22,7 +22,7 @@ Examples:
 import argparse
 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
+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
 
 MODES = {"frame": 0, "field": 1}
 PARITIES = {"auto": -1, "tff": 0, "bff": 1}
@@ -41,7 +41,7 @@ def main() -> int:
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (default 0)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/denoise.py

@@ -18,7 +18,7 @@ Examples:
 import argparse
 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
+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
 
 # hqdn3d's own AVOptions default to 0 (off); these tested presets are the light/medium/heavy
 # starting points its own documentation and common usage recommend (spatial then temporal,
@@ -43,7 +43,7 @@ def main() -> int:
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (default 0)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)
     args = ap.parse_args()

package/scripts/export.py

@@ -100,7 +100,7 @@ def main() -> int:
     video = list(p["video"])
     if args.crf is not None and "-crf" in video:
         video[video.index("-crf") + 1] = str(args.crf)
-    if STATE["fast"] and "-preset" in video:
+    if STATE.fast and "-preset" in video:
         video[video.index("-preset") + 1] = "veryfast"
     cmd += video
     if args.preset != "copy":

package/scripts/fit.py

@@ -38,7 +38,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
 
@@ -101,7 +101,7 @@ def main() -> int:
     r.add_argument("--flip", choices=["h", "v"], help="mirror the picture horizontally (h) or vertically (v)")
     e = ap.add_argument_group("encoding")
     e.add_argument("--crf", type=int, default=18)
-    e.add_argument("--preset", default="medium")
+    e.add_argument("--preset", default="medium", choices=X264_PRESETS)
     e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)
     args = ap.parse_args()
@@ -159,7 +159,7 @@ def main() -> int:
         if target <= 0:
             die("target duration must be > 0")
         if args.method == "speed":
-            if src_dur <= 0 and STATE["dry_run"]:
+            if src_dur <= 0 and STATE.dry_run:
                 src_dur = target  # planning against an intermediate that does not exist yet
             factor = src_dur / target  # >1 = speed up
             if factor > args.max_speed or factor < 1 / args.max_speed:
@@ -175,7 +175,7 @@ def main() -> int:
                 if has_audio:
                     af.append(atempo_chain(factor))
             post += ["-t", f"{target:.3f}"]
-            STATE["duration_hint"] = target
+            STATE.duration_hint = target
         else:
             if target < src_dur:
                 start = (src_dur - target) / 2 if args.from_center else 0.0

package/scripts/freeze.py

@@ -19,7 +19,7 @@ Examples:
 import argparse
 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
+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
 
 
 def main() -> int:
@@ -31,7 +31,7 @@ def main() -> int:
     ap.add_argument("--mode", choices=["insert", "extend"], default="insert",
                      help="insert (default): hold pushes the rest of the clip later; extend: only valid at/after the clip's end, makes the last frame last longer with nothing pushed")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/graphics.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw
+from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -62,7 +62,7 @@ def main() -> int:
     ap.add_argument("--font-file")
     ap.add_argument("--scale", type=float, default=1.0, help="size multiplier (default 1)")
     ap.add_argument("--crf", type=int, default=18)
-    ap.add_argument("--preset", default="medium")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/grid.py

@@ -25,7 +25,7 @@ import argparse
 import os
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_font_file, default_output, die, emit, \
+from _common import add_common, apply_common, aac_args, cfr_args, default_font_file, default_output, die, emit, X264_PRESETS, \
     escape_drawtext, escape_filter_path, ffmpeg_base, info, probe, run, validate_color, video_args
 
 LABEL_MARGIN = 10
@@ -50,7 +50,7 @@ def main() -> int:
     ap.add_argument("--gap", type=int, default=0, help="gap between cells in px, must be even (default 0, cells touch)")
     ap.add_argument("--background", default="black", help="colour of the gap/pad borders (default black)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/insert.py

@@ -27,7 +27,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS
 
 
 def even(n: float) -> int:
@@ -47,7 +47,7 @@ def main() -> int:
     ap.add_argument("--zoom-amount", type=float, default=1.3, help="end (zoom in) or start (zoom out) zoom factor, > 1.0 (default 1.3)")
     ap.add_argument("--pan", choices=["left", "right", "up", "down"], help="drift the visible window this direction while zoomed (needs --zoom)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/join.py

@@ -23,7 +23,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, validate_color
+from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, validate_color, X264_PRESETS
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -36,7 +36,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
     for p, dur in zip(args.inputs, durs):
-        if d and dur <= d * 2 and not STATE["dry_run"]:
+        if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
     rates = [m["audio"].get("sample_rate") or 48000 for m in metas]
     chans = [m["audio"].get("channels") or 2 for m in metas]
@@ -70,7 +70,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     expected = sum(durs) - d * (n - 1)
     r = probe(output)
     a = r.get("audio") or {}
-    if not STATE["dry_run"]:
+    if not STATE.dry_run:
         if r.get("video"):
             die(f"{output} unexpectedly contains a video stream")
         if a.get("sample_rate") != rate or a.get("channels") != channels:
@@ -94,7 +94,7 @@ def main() -> int:
     ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
     ap.add_argument("--pad-color", default="black")
     ap.add_argument("--crf", type=int, default=18)
-    ap.add_argument("--preset", default="medium")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     aud = ap.add_argument_group("audio-only inputs")
     aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
     aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
@@ -137,7 +137,7 @@ def main() -> int:
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
     for p, dur in zip(args.inputs, durs):
-        if d and dur <= d * 2 and not STATE["dry_run"]:
+        if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
 
     cmd = ffmpeg_base()

package/scripts/loop.py

@@ -18,7 +18,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS
 
 
 def main() -> int:
@@ -29,7 +29,7 @@ def main() -> int:
     group.add_argument("--times", type=int, help="repeat the whole clip this many times (2 = original + 1 repeat)")
     group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/loudness.py

@@ -23,7 +23,7 @@ from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_c
 
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
-    if STATE["dry_run"]:
+    if STATE.dry_run:
         return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]

package/scripts/metadata.py

@@ -30,7 +30,7 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, STATE
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, STATE, read_text_or_die
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -39,7 +39,7 @@ TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
 def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
     """`TIME TITLE` per line -> [{"start", "end", "title"}], validated: ascending starts, every
     start inside the file, the last chapter running to the file's end."""
-    text = Path(path).read_text(encoding="utf-8")
+    text = read_text_or_die(path, "--chapters")
     entries: List[Dict[str, Any]] = []
     for n, raw in enumerate(text.splitlines(), start=1):
         line = raw.strip()
@@ -136,9 +136,9 @@ def main() -> int:
 
     result = probe(output, role="output")
     written = result.get("chapters") or []
-    if chapters is not None and not STATE["dry_run"] and len(written) != len(chapters):
+    if chapters is not None and not STATE.dry_run and len(written) != len(chapters):
         die(f"wrote {len(written)} chapters but {len(chapters)} were asked for", kind="output")
-    if args.clear_chapters and not STATE["dry_run"] and written:
+    if args.clear_chapters and not STATE.dry_run and written:
         die(f"{len(written)} chapters survived --clear-chapters", kind="output")
     info(f"wrote {output} ({len(written)} chapters, tags: {', '.join(sorted(tags)) or 'unchanged'}, streams copied)")
     emit(output, chapters=written, tags=result.get("tags") or {}, streams_copied=True)

package/scripts/multicam.py

@@ -29,7 +29,7 @@ import argparse
 import sys
 from typing import List, Tuple
 
-from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args, X264_PRESETS
 from sync import measure_offset
 
 
@@ -69,7 +69,7 @@ def main() -> int:
     ap.add_argument("--height", type=int, help="output height (default: reference)")
     ap.add_argument("--fps", type=float, help="output fps (default: reference)")
     ap.add_argument("--crf", type=int, default=18)
-    ap.add_argument("--preset", default="medium")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/overlay.py

@@ -24,7 +24,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args
+from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -119,7 +119,7 @@ def main() -> int:
     txt.add_argument("--box-color", default="black@0.5")
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
-    enc.add_argument("--preset", default="medium")
+    enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/pad.py

@@ -16,7 +16,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS
 
 
 def main() -> int:
@@ -27,7 +27,7 @@ def main() -> int:
     ap.add_argument("--end", type=float, default=0.0, help="seconds of padding to add after the clip (default 0)")
     ap.add_argument("--color", default="black", help="padding colour (default black)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/redact.py

@@ -20,7 +20,7 @@ Examples:
 import argparse
 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
+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
 
 
 def main() -> int:
@@ -37,7 +37,7 @@ def main() -> int:
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (default 0)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)
     args = ap.parse_args()

package/scripts/render.py

@@ -51,12 +51,11 @@ Examples:
 import argparse
 import json
 import os
-import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool
 
 HERE = Path(__file__).resolve().parent
 
@@ -80,18 +79,26 @@ TEMPLATE = {
 
 def sh(script: str, *argv: Any, extra: List[str] = None) -> str:
     """Run a sibling script, forwarding --fast / --dry-run, returning its printed output path."""
-    cmd = [sys.executable, str(HERE / script)] + [str(a) for a in argv] + (extra or []) + child_args()
-    info("→ " + " ".join(os.path.basename(c) if i < 2 else c for i, c in enumerate(cmd)))
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    cmd = [str(HERE / script)] + [str(a) for a in argv] + (extra or []) + child_args() + ["--json"]
+    info("→ " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd[:-1])))
+    proc = run_tool(cmd)
     for line in proc.stderr.splitlines():
         if line.startswith("$ ") or line.startswith("[dry-run]"):
-            STATE["commands"].append(line[2:] if line.startswith("$ ") else line)
+            STATE.commands.append(line[2:] if line.startswith("$ ") else line)
         elif line.strip():
             info("    " + line)
+    try:
+        doc = json.loads(proc.stdout.strip() or "{}")
+    except ValueError:
+        doc = {}
     if proc.returncode != 0:
-        die(f"{script} failed")
-    out = proc.stdout.strip().splitlines()
-    return out[-1] if out else ""
+        # Re-raise the stage's own failure: its kind, exit code and hint are what the caller
+        # needs (a timeout inside audio.py is a timeout, not an "input" error of render.py).
+        err = doc.get("error") or {}
+        extra_fields = {"hint": err["hint"]} if err.get("hint") else {}
+        die(f"{script} failed: {err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]}",
+            code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script, **extra_fields)
+    return str(doc.get("output") or "")
 
 
 def main() -> int:
@@ -144,7 +151,7 @@ def main() -> int:
     parts: List[str] = []
     for i, c in enumerate(clips):
         src = rel(c["src"])
-        if not STATE["dry_run"]:
+        if not STATE.dry_run:
             probe(src)
         needs_cut = c.get("in") is not None or c.get("out") is not None
         part = str(work / f"clip{i:02d}.mp4")
@@ -159,7 +166,7 @@ def main() -> int:
             part = src
         if c.get("speed"):
             spd = float(c["speed"])
-            dur = (probe(part).get("duration") or 0.0) if not STATE["dry_run"] else 10.0
+            dur = (probe(part).get("duration") or 0.0) if not STATE.dry_run else 10.0
             fitted = str(work / f"clip{i:02d}_speed.mp4")
             sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)
             part = fitted
@@ -340,7 +347,7 @@ def main() -> int:
         sh("export.py", *argv)
         stages_done.append("export")
     else:
-        if not STATE["dry_run"]:
+        if not STATE.dry_run:
             import shutil
             shutil.copyfile(current, output)
         info(f"copied final stage to {output}")
@@ -350,8 +357,8 @@ def main() -> int:
     ck = proj.get("check")
     check_result = None
     exit_code = 0
-    if ck and ck.get("platform") and not STATE["dry_run"]:
-        proc = subprocess.run([sys.executable, str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if ck and ck.get("platform") and not STATE.dry_run:
+        proc = run_tool([str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"])
         try:
             check_result = json.loads(proc.stdout)
         except ValueError:

package/scripts/report.py

@@ -13,13 +13,12 @@ import base64
 import html
 import json
 import os
-import subprocess
 import sys
 import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe
+from _common import STATE, add_common, apply_common, die, emit, info, probe, read_text_or_die, run_tool
 
 HERE = Path(__file__).resolve().parent
 
@@ -27,15 +26,14 @@ HERE = Path(__file__).resolve().parent
 def sheet_b64(path: str, tiles: str = "4x2", width: int = 1200) -> Optional[str]:
     with tempfile.TemporaryDirectory(prefix="ffskill_report_") as tmp:
         png = os.path.join(tmp, "sheet.png")
-        proc = subprocess.run([sys.executable, str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png],
-                              stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png])
         if proc.returncode != 0 or not os.path.exists(png):
             return None
         return base64.b64encode(Path(png).read_bytes()).decode("ascii")
 
 
 def loudness(path: str) -> Dict[str, Any]:
-    proc = subprocess.run([sys.executable, str(HERE / "loudness.py"), path, "--measure-only"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"])
     try:
         d = json.loads(proc.stdout)
         return {"lufs": round(float(d["input_i"]), 1), "tp": round(float(d["input_tp"]), 1), "lra": round(float(d["input_lra"]), 1)}
@@ -44,11 +42,18 @@ def loudness(path: str) -> Dict[str, Any]:
 
 
 def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
-    proc = subprocess.run([sys.executable, str(HERE / "check.py"), path, "--platform", platform, "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"])
     try:
-        return json.loads(proc.stdout)
+        doc = json.loads(proc.stdout)
     except ValueError:
+        doc = None
+    if not isinstance(doc, dict) or "checks" not in doc:
+        # check.py could not run at all (missing ffmpeg, unreadable file): its failure document
+        # has no rows to render. A failed *verification* still carries its rows and is shown.
+        reason = ((doc or {}).get("error") or {}).get("message") or (proc.stderr.strip().splitlines() or ["?"])[-1]
+        info(f"check.py could not run: {reason[:200]}")
         return None
+    return doc
 
 
 def fmt_dur(sec: Optional[float]) -> str:
@@ -99,8 +104,8 @@ def main() -> int:
             sheets["before"] = sheet_b64(args.before)
         if after.get("video"):
             sheets["after"] = sheet_b64(args.after)
-    commands = Path(args.commands).read_text(encoding="utf-8").splitlines() if args.commands else []
-    notes = Path(args.notes).read_text(encoding="utf-8") if args.notes else ""
+    commands = read_text_or_die(args.commands, "--commands").splitlines() if args.commands else []
+    notes = read_text_or_die(args.notes, "--notes") if args.notes else ""
     title = args.title or f"Delivery report — {Path(args.after).name}"
     output = args.output or str(Path(args.after).with_name(Path(args.after).stem + "_report.html"))
 

package/scripts/reverse.py

@@ -14,7 +14,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS
 
 
 def main() -> int:
@@ -23,7 +23,7 @@ def main() -> int:
     ap.add_argument("-o", "--output", help="output file (default: <name>_reverse.<ext>)")
     ap.add_argument("--no-audio", action="store_true", help="drop audio instead of reversing it")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)

package/scripts/scenes.py

@@ -21,11 +21,10 @@ import argparse
 import math
 import os
 import re
-import struct
 import sys
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis
+from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis, decode_pcm_mono, rms_envelope
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -87,19 +86,9 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
 
 
 def audio_envelope(path: str, step_s: float) -> List[float]:
-    ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"],
-                        check=False, text=False)
-    n = len(proc.stdout) // 2
-    if n == 0:
-        return []
-    samples = struct.unpack(f"<{n}h", proc.stdout[: n * 2])
-    step = max(1, int(8000 * step_s))
-    env = []
-    for i in range(0, n, step):
-        block = samples[i:i + step]
-        env.append(math.sqrt(sum(x * x for x in block) / len(block)) / 32768.0)
-    return env
+    """RMS level per step_s window at 8 kHz, absolute (a loud scene scores higher); [] when the
+    audio cannot be decoded (the cut scoring then runs on the picture alone)."""
+    return rms_envelope(decode_pcm_mono(path, 8000, check=False), int(8000 * step_s))
 
 
 def main() -> int:

package/scripts/sequence.py

@@ -19,7 +19,7 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS
 
 
 def even(n: float) -> int:
@@ -43,7 +43,7 @@ def main() -> int:
     ap.add_argument("--width", type=int, help="output width in px; with --height also given, both are used directly")
     ap.add_argument("--height", type=int, help="output height in px; with --width also given, both are used directly")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
-    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)