ffmpeg-skill 0.12.0 → 0.16.12

package/scripts/export.py

@@ -26,7 +26,7 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
+from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color
 
 PRESETS: Dict[str, Dict] = {
     "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
@@ -63,6 +63,7 @@ def main() -> int:
         return 0
     if not args.input or not args.preset:
         die("input and --preset are required (or use --list)")
+    validate_color(args.pad_color, "--pad-color")
 
     p = PRESETS[args.preset]
     meta = probe(args.input)

package/scripts/fit.py

@@ -37,7 +37,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, x264_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
 
 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)}
 
@@ -114,6 +114,7 @@ def main() -> int:
         die(f"--crop-x must be 0..1, got {args.crop_x}")
     if not 0.0 <= args.crop_y <= 1.0:
         die(f"--crop-y must be 0..1, got {args.crop_y}")
+    validate_color(args.pad_color, "--pad-color")
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -193,8 +194,18 @@ def main() -> int:
             out_h = even(args.height)
             out_w = even(out_h * ratio) if ratio else args.height
         elif ratio and src_ratio:
-            out_w = even(sw if ratio <= src_ratio else sh * ratio)
-            out_h = even(out_w / ratio)
+            # No explicit --width/--height: size the canvas to the new aspect without exceeding
+            # the source's own resolution in either dimension. A narrower/taller target than the
+            # source (e.g. 9:16 from a 16:9 source) must be bounded by the source's HEIGHT, not
+            # its width -- bounding by width there multiplies the height by src_ratio/ratio (a
+            # 1920x1080 source asked for 9:16 used to come out 1920x3414, a ~3.16x upscale in
+            # both fit=pad and fit=crop, entirely unrequested).
+            if ratio <= src_ratio:
+                out_h = even(sh)
+                out_w = even(out_h * ratio)
+            else:
+                out_w = even(sw)
+                out_h = even(out_w / ratio)
         else:
             out_w, out_h = even(sw), even(sh)
         if args.fit == "crop":
@@ -225,15 +236,24 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd += post + [output]
-    run(cmd)
+    cmd += post
+    if abs(factor - 1.0) > 1e-4:
+        # A subtitle/data stream stream-copied by run_keeping_subtitles keeps the source's
+        # original timestamps; --method speed retimes video (setpts) and audio (atempo) but has
+        # no equivalent way to retime a copied subtitle track, so it would desync from the
+        # now-faster/slower picture. Drop them here rather than ship a captions track that lies
+        # about when a line is spoken.
+        run(cmd + [output])
+        dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
+    else:
+        dropped_streams = run_keeping_subtitles(cmd, output)
 
     result = probe(output, role="output")
     msg = f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})"
     if abs(factor - 1.0) > 1e-4:
         msg += f", speed {factor:.3f}x"
     info(msg)
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/freeze.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Freeze on one frame for a number of seconds -- an end-card hold, a comedic beat, a pause.
+
+--at is the timestamp to freeze (default: the last frame). --hold is how
+long the freeze lasts. --mode insert (default) inserts the hold into the
+clip at --at, pushing everything after it later by --hold seconds; --mode
+extend only works with --at at (or past) the end of the clip and simply
+makes the last frame last --hold seconds longer, without touching anything
+earlier. Audio is silent during the held frame in --mode insert (there is
+no source audio for a frozen moment that didn't exist before); --mode
+extend has no audio to extend either, since it only makes sense at the
+clip's end.
+
+Examples:
+  python3 freeze.py interview.mp4 --hold 2                        # hold the last frame 2s longer
+  python3 freeze.py sketch.mp4 --at 12.5 --hold 1.5                # 1.5s freeze inserted at 12.5s
+  python3 freeze.py outro.mp4 --hold 3 --mode extend                # extend only the very end by 3s
+"""
+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
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_freeze.<ext>)")
+    ap.add_argument("--at", type=float, help="timestamp to freeze, in seconds (default: the last frame)")
+    ap.add_argument("--hold", type=float, required=True, help="how long the freeze lasts, in seconds")
+    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")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.hold <= 0:
+        die(f"--hold must be > 0, got {args.hold:g}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    dur = meta.get("duration") or 0.0
+    fps = meta["video"].get("fps") or 30.0
+    at = args.at if args.at is not None else dur
+    if at < 0 or at > dur:
+        die(f"--at {at:g} is outside the clip (0..{dur:.3f})")
+    if args.mode == "extend" and at < dur - 0.01:
+        die(f"--mode extend needs --at at or after the clip's end ({dur:.3f}), got {at:g}")
+    has_audio = bool(meta.get("audio"))
+    output = args.output or default_output(args.input, "freeze")
+
+    if args.mode == "extend":
+        # tpad's stop_duration clones the last frame for the given duration; no PTS surgery
+        # needed since it only ever appends past the real end.
+        vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
+        cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+        if has_audio:
+            cmd += ["-map", "0:a:0?", "-af", f"apad=pad_dur={args.hold:.3f}"]
+    elif at == 0:
+        # A freeze at the very start has no preceding "head" segment to hold on to (the
+        # split/trim/concat approach below needs a non-empty head, which trim=end=0 can't give
+        # it -- ffmpeg fails filtering an empty stream). Symmetric to --mode extend at the other
+        # end: tpad's start_duration clones the *first* frame backwards instead.
+        vf = f"tpad=start_mode=clone:start_duration={args.hold:.3f}"
+        cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+        if has_audio:
+            cmd += ["-map", "0:a:0?", "-af", f"adelay={int(args.hold * 1000)}:all=1"]
+    else:
+        # freeze N frames at `at` by holding on that one source frame for --hold seconds, then
+        # resuming the rest of the clip: split the timeline at `at`, freeze-frame the first
+        # part's last frame for --hold seconds via tpad, concat with the remainder.
+        n = max(1, round(args.hold * fps))
+        # The video hold length is rounded to a whole number of frames (n / fps), but the audio
+        # side used to pad by the raw --hold value -- up to half a frame duration off from what
+        # the video actually holds for, a permanent A/V drift from this point on. Pad audio by
+        # the same, frame-rounded duration the video actually gets.
+        actual_hold = n / fps
+        vf = (f"[0:v]split[a][b];[a]trim=end={at:.3f},setpts=PTS-STARTPTS[head];"
+              f"[b]trim=start={at:.3f},setpts=PTS-STARTPTS[tail];"
+              f"[head]tpad=stop_mode=clone:stop={n}[frozen];"
+              f"[frozen][tail]concat=n=2:v=1:a=0[outv]")
+        cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", "[outv]"]
+        if has_audio:
+            af = (f"[0:a]asplit[aa][ab];[aa]atrim=end={at:.3f},asetpts=PTS-STARTPTS[ahead];"
+                  f"[ab]atrim=start={at:.3f},asetpts=PTS-STARTPTS[atail];"
+                  f"[ahead]apad=pad_dur={actual_hold:.6f}[afrozen];"
+                  f"[afrozen][atail]concat=n=2:v=0:a=1[outa]")
+            cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", f"{vf};{af}", "-map", "[outv]", "-map", "[outa]"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    dropped_streams = run_keeping_subtitles(cmd, output)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, froze {args.hold:g}s at {at:g}s, mode={args.mode})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, video_args
+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
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -33,7 +33,10 @@ def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
 def font_opts(brand: dict, font: Optional[str], font_file: Optional[str]) -> str:
     if font_file or brand.get("font_file"):
         return f"fontfile={escape_filter_path(font_file or brand['font_file'])}"
-    return f"font='{font or brand.get('font', 'DejaVu Sans')}'"
+    resolved = default_font_file(font or brand.get("font", "DejaVu Sans"))
+    if resolved:
+        return f"fontfile={escape_filter_path(resolved)}"
+    return f"font='{escape_drawtext(font or brand.get('font', 'DejaVu Sans'))}'"
 
 
 def main() -> int:
@@ -163,11 +166,10 @@ def main() -> int:
         cmd += ["-vf", ",".join(filters), "-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.append(output)
-    run(cmd)
+    dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {args.template})")
-    emit(output, template=args.template)
+    emit(output, template=args.template, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/grid.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Composite several video clips into one COLSxROWS grid, e.g. a 4x2 wall of
+takes, angles, or A/B renders side by side.
+
+Every cell is letterboxed (not stretched) to a common --cell-width/--cell-height
+so clips of different aspect ratios and resolutions line up cleanly. By default
+each cell gets its source filename (extension stripped) burnt into the bottom
+right corner -- --label none turns that off. The grid has no audio unless
+--audio-from picks one input's track to carry through; mixing every clip's
+audio together is rarely what a comparison grid is for, so this tool never
+does it silently.
+
+The grid runs only as long as its shortest clip by default, or is padded to
+the longest clip's duration with --pad (each shorter cell holds its last
+frame, and --audio-from's track is padded with silence, out to that length);
+a mismatched frame rate across sources is conformed to --fps first so cells
+stay in sync.
+
+Examples:
+  python3 grid.py take1.mp4 take2.mp4 take3.mp4 take4.mp4 take5.mp4 take6.mp4 take7.mp4 take8.mp4 --cols 4 --rows 2
+  python3 grid.py a.mp4 b.mp4 c.mp4 d.mp4 --cols 2 --rows 2 --label none -o compare.mp4
+  python3 grid.py cam1.mp4 cam2.mp4 --cols 2 --rows 1 --audio-from 0 --pad
+"""
+import argparse
+import os
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_font_file, default_output, die, emit, \
+    escape_drawtext, escape_filter_path, ffmpeg_base, info, probe, run, validate_color, video_args
+
+LABEL_MARGIN = 10
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="video clips, filled into the grid left-to-right, top-to-bottom")
+    ap.add_argument("-o", "--output", help="output file (default: <first name>_grid.<ext>)")
+    ap.add_argument("--cols", type=int, required=True, help="grid columns")
+    ap.add_argument("--rows", type=int, required=True, help="grid rows")
+    ap.add_argument("--cell-width", type=int, default=480, help="each cell's width in px, must be even (default 480)")
+    ap.add_argument("--cell-height", type=int, default=270, help="each cell's height in px, must be even (default 270)")
+    ap.add_argument("--fps", type=float, default=30.0, help="output frame rate every cell is conformed to (default 30)")
+    ap.add_argument("--label", choices=["auto", "none"], default="auto",
+                     help="auto (default): burn each cell's filename (extension stripped) into its bottom-right corner; none: no label")
+    ap.add_argument("--font", default="DejaVu Sans", help="label font (fontconfig family name, default DejaVu Sans)")
+    ap.add_argument("--font-size", type=int, default=16, help="label font size (default 16)")
+    ap.add_argument("--font-color", default="white", help="label text colour (default white)")
+    ap.add_argument("--pad", action="store_true", help="hold each shorter cell's last frame (and pad --audio-from's track with silence) out to the longest clip's duration, instead of stopping at the shortest")
+    ap.add_argument("--audio-from", type=int, help="0-based index into inputs to take audio from (default: no audio)")
+    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")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    n = args.cols * args.rows
+    if args.cols <= 0 or args.rows <= 0:
+        die(f"--cols/--rows must be > 0, got cols={args.cols} rows={args.rows}")
+    if len(args.inputs) != n:
+        die(f"--cols {args.cols} --rows {args.rows} needs exactly {n} inputs, got {len(args.inputs)}")
+    if args.cell_width <= 0 or args.cell_height <= 0:
+        die(f"--cell-width/--cell-height must be > 0, got width={args.cell_width} height={args.cell_height}")
+    if args.cell_width % 2 or args.cell_height % 2:
+        die(f"--cell-width/--cell-height must be even (4:2:0 chroma), got width={args.cell_width} height={args.cell_height}")
+    if args.fps <= 0:
+        die(f"--fps must be > 0, got {args.fps:g}")
+    if args.gap < 0 or args.gap % 2:
+        die(f"--gap must be >= 0 and even, got {args.gap}")
+    validate_color(args.background, "--background")
+    if args.font_color:
+        validate_color(args.font_color, "--font-color")
+    if args.audio_from is not None and not 0 <= args.audio_from < n:
+        die(f"--audio-from {args.audio_from}: must be an input index 0..{n - 1}")
+
+    metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        if not m.get("video"):
+            die(f"{p}: input has no video stream")
+    if args.audio_from is not None and not metas[args.audio_from].get("audio"):
+        die(f"--audio-from {args.audio_from}: {args.inputs[args.audio_from]} has no audio stream")
+
+    durations = [m.get("duration") or 0.0 for m in metas]
+    target_duration = max(durations) if args.pad else min(durations)
+
+    font_file = default_font_file(args.font)
+    output = args.output or default_output(args.inputs[0], "grid")
+
+    cmd = ffmpeg_base()
+    for p in args.inputs:
+        cmd += ["-i", p]
+
+    parts = []
+    for i, p in enumerate(args.inputs):
+        chain = [
+            f"fps={args.fps:g}",
+            f"scale={args.cell_width}:{args.cell_height}:force_original_aspect_ratio=decrease",
+            f"pad={args.cell_width}:{args.cell_height}:(ow-iw)/2:(oh-ih)/2:color={args.background}",
+            "setsar=1",
+        ]
+        if args.pad and durations[i] < target_duration:
+            chain.append(f"tpad=stop_mode=clone:stop_duration={target_duration - durations[i]:.3f}")
+        elif not args.pad:
+            chain.append(f"trim=duration={target_duration:.3f}")
+        if args.label == "auto":
+            stem = os.path.splitext(os.path.basename(p))[0]
+            font_opt = f"fontfile={escape_filter_path(font_file)}" if font_file else f"font='{escape_drawtext(args.font)}'"
+            chain.append(f"drawtext=text='{escape_drawtext(stem)}':{font_opt}:fontsize={args.font_size}:"
+                         f"fontcolor={args.font_color}:x=w-tw-{LABEL_MARGIN}:y=h-th-{LABEL_MARGIN}:"
+                         f"box=1:boxcolor=black@0.5:boxborderw=4")
+        parts.append(f"[{i}:v]{','.join(chain)}[v{i}]")
+
+    cw, ch = args.cell_width + args.gap, args.cell_height + args.gap
+    layout = "|".join(f"{c * cw}_{r * ch}" for r in range(args.rows) for c in range(args.cols))
+    parts.append("".join(f"[v{i}]" for i in range(n)) + f"xstack=inputs={n}:layout={layout}:fill={args.background}[out]")
+    if args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
+        parts.append(f"[{args.audio_from}:a:0]apad,atrim=duration={target_duration:.3f}[aout]")
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[out]"]
+
+    if args.audio_from is not None:
+        audio_source = "[aout]" if (args.pad and durations[args.audio_from] < target_duration) else f"{args.audio_from}:a:0"
+        cmd += ["-map", audio_source]
+    cmd += video_args(None, args.crf, args.preset)
+    cmd += cfr_args(None, args.fps)
+    if args.audio_from is not None:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd += ["-t", f"{target_duration:.3f}", output]
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {args.cols}x{args.rows} grid, "
+         f"{n} clips, {'padded to longest' if args.pad else 'stopped at shortest'})")
+    emit(output, cols=args.cols, rows=args.rows, clips=n)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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
+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
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -101,9 +101,12 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
 
     if len(args.inputs) < 2:
         die("give at least two clips")
+    validate_color(args.pad_color, "--pad-color")
     metas = [probe(p) for p in args.inputs]
     if all(not m.get("video") for m in metas):
         for p, m in zip(args.inputs, metas):

package/scripts/look.py

@@ -15,7 +15,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from _common import add_common, apply_common, die, emit, escape_drawtext, ffmpeg_base, info, parse_time, probe, run
+from _common import add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run
 
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
@@ -26,8 +26,8 @@ def fmt_hms(sec: float) -> str:
     return f"{int(h):02d}:{int(m):02d}:{s_:06.3f}"
 
 
-def timecode_filter() -> str:
-    return f"drawtext=text='%{{pts\\:hms}}':{FONT}"
+def timecode_filter(font_prefix: str) -> str:
+    return f"drawtext=text='%{{pts\\:hms}}':{font_prefix}{FONT}"
 
 
 def main() -> int:
@@ -49,7 +49,12 @@ def main() -> int:
     dur = meta.get("duration") or 0.0
     stem = Path(args.input).stem
     outdir = str(Path(args.output).parent) if args.output else str(Path(args.input).parent)
-    tc = "" if args.no_timecode else "," + timecode_filter()
+    # a resolvable font file, given as fontfile=, is the only form confirmed not to crash drawtext's
+    # own fontconfig resolution on some real Windows ffmpeg builds (#100); font= is the fallback when
+    # nothing can be resolved, unchanged from before this existed.
+    default_font = default_font_file("DejaVu Sans")
+    font_prefix = f"fontfile={escape_filter_path(default_font)}:" if default_font else ""
+    tc = "" if args.no_timecode else "," + timecode_filter(font_prefix)
     # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
     if meta["video"].get("hdr"):
         v = meta["video"]
@@ -67,8 +72,8 @@ def main() -> int:
             sec = parse_time(t)
             out = args.output or os.path.join(outdir, f"{stem}_vs_{Path(args.compare).stem}_{sec:.3f}s.png")
             half = args.width // 2
-            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{FONT}"
-            tcs = tc.replace("," + timecode_filter(), "") + stamp
+            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
+            tcs = tc.replace("," + timecode_filter(font_prefix), "") + stamp
             fc = (f"[0:v]scale={half}:-2{tcs}[a];[1:v]scale={half}:-2{tcs}[b];"
                   f"[a][b]scale2ref=w=iw:h=ih[a2][b2];[a2][b2]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-ss", f"{sec:.3f}", "-i", args.compare,
@@ -81,8 +86,8 @@ def main() -> int:
             if dur and sec > dur:
                 die(f"--at {t} is beyond the duration ({dur:.2f}s)")
             out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
-            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{FONT}"
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(), '')}{stamp}", "-frames:v", "1", out]
+            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", out]
             run(cmd)
             outputs.append(out)
     else:

package/scripts/loop.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Loop a clip a number of times, or to a target duration.
+
+For a background loop, an ambient bed, or filling a fixed slot length with
+a short clip. --times repeats the whole clip that many times back to back;
+--duration instead loops (and, on the last repeat, trims) to hit an exact
+target length. Audio loops along with the video when present. This tool
+does not smooth the loop point (no crossfade at the seam) -- a clip that
+doesn't already loop cleanly will show a visible cut/pop at each repeat;
+that's a judgement call about the source material, not something a --times
+or --duration flag can fix.
+
+Examples:
+  python3 loop.py bg_loop.mp4 --times 3
+  python3 loop.py texture.mp4 --duration 30
+"""
+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
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_loop.<ext>)")
+    group = ap.add_mutually_exclusive_group(required=True)
+    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")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    src_dur = meta.get("duration") or 0.0
+    if src_dur <= 0:
+        die("input has no measurable duration to loop")
+    has_audio = bool(meta.get("audio"))
+    output = args.output or default_output(args.input, "loop")
+
+    if args.times is not None:
+        if args.times < 2:
+            die(f"--times must be >= 2 (1 is just the original clip), got {args.times}")
+        target = None
+        stream_loop = args.times - 1
+    else:
+        target = parse_time(args.duration)
+        if target <= src_dur:
+            die(f"--duration ({target:g}s) must be longer than the source ({src_dur:.3f}s) -- use cut.py to trim instead")
+        stream_loop = math.ceil(target / src_dur) - 1
+
+    # -stream_loop repeats the whole input read (video and audio together) at the demuxer level
+    # -- exact and lossless-in-intent for a re-encode target, unlike a filter-graph loop that
+    # would need separate video/audio filters kept in lockstep by hand.
+    cmd = ffmpeg_base() + ["-stream_loop", str(stream_loop), "-i", args.input]
+    if target is not None:
+        cmd += ["-t", f"{target:.3f}"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd.append(output)
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, source {src_dur:.3f}s looped)")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/multicam.py

@@ -73,6 +73,8 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
 
     n = len(args.inputs)
     if n < 2:
@@ -134,6 +136,8 @@ def main() -> int:
     if args.switch:
         cuts = parse_switch(args.switch, n)
     elif args.auto:
+        if args.auto <= 0:
+            die(f"--auto must be a positive number of seconds, got {args.auto:g}")
         cams = [i for i, m in enumerate(metas) if m.get("video")]
         cuts, t, k = [], 0.0, 0
         while t < ref_dur:
@@ -184,13 +188,17 @@ def main() -> int:
     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
-    afx = []
+    # a_start is a trim point in the source's own, pre-drift-correction time axis, so it must be
+    # applied before asetrate/aresample rescale that axis -- otherwise the trim lands at the wrong
+    # point once the stream's timebase has already been stretched/compressed by the drift ratio
+    # (mirrors sync.py, which seeks with -ss, an input-level operation, before its drift_af filters).
+    afx = [f"atrim=start={a_start:.4f}", "asetpts=PTS-STARTPTS"]
     if abs(ratios[a] - 1.0) > 1e-7:
         sr = metas[a]["audio"].get("sample_rate") or 48000
         afx += [f"asetrate={sr * ratios[a]:.6f}", f"aresample={sr}"]
     if offsets[a] > 0:
         afx.append(f"adelay={int(round(offsets[a] * 1000))}:all=1")
-    afx += [f"atrim=start={a_start:.4f}", "asetpts=PTS-STARTPTS", f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
+    afx += [f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
     parts.append(f"[{a}:a]{','.join(afx)}[aout]")
 
     output = args.output or default_output(args.inputs[0], "multicam", "mp4")