ffmpeg-skill 0.12.5 → 0.16.12

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

@@ -36,7 +36,7 @@ def font_opts(brand: dict, font: Optional[str], font_file: Optional[str]) -> str
     resolved = default_font_file(font or brand.get("font", "DejaVu Sans"))
     if resolved:
         return f"fontfile={escape_filter_path(resolved)}"
-    return f"font='{font or brand.get('font', 'DejaVu Sans')}'"
+    return f"font='{escape_drawtext(font or brand.get('font', 'DejaVu Sans'))}'"
 
 
 def main() -> int:

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/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")

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, 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
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -163,6 +163,11 @@ def main() -> int:
         die("--opacity must be within 0..1")
     if args.chromakey and not args.video:
         die("--chromakey needs --video")
+    if args.chromakey:
+        validate_color(args.chromakey, "--chromakey")
+    validate_color(args.font_color, "--font-color")
+    validate_color(args.border_color, "--border-color")
+    validate_color(args.box_color, "--box-color")
     if not 0 < args.chromakey_similarity <= 1:
         die("--chromakey-similarity must be within (0, 1]")
     if not 0 <= args.chromakey_blend <= 1:
@@ -242,7 +247,7 @@ def main() -> int:
         if args.font_file:
             opts.append(f"fontfile={escape_filter_path(args.font_file)}")
         else:
-            opts.append(f"font='{args.font}'")
+            opts.append(f"font='{escape_drawtext(args.font)}'")
         alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None),
                            end if end is not None else ((meta.get("duration") or None) if args.fade > 0 else None), args.fade)
         opts.append(f"fontcolor={args.font_color}")

package/scripts/pad.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Add black video / silent audio at the start and/or end of a clip.
+
+Distinct from fit.py --fit pad, which pads the FRAME (letterbox/pillarbox
+bars around each existing frame to reach a target aspect ratio) -- this
+tool pads the TIMELINE (extra seconds of solid colour and silence before
+and/or after the clip's existing content). Common uses: a beat of black
+before a title card starts, room for a fade-in, aligning a clip to a fixed
+slot length.
+
+Examples:
+  python3 pad.py clip.mp4 --start 1.5                 # 1.5s of black+silence before the clip
+  python3 pad.py clip.mp4 --end 2                      # 2s of black+silence after the clip
+  python3 pad.py clip.mp4 --start 1 --end 1 --color 0x101010
+"""
+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
+
+
+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>_pad.<ext>)")
+    ap.add_argument("--start", type=float, default=0.0, help="seconds of padding to add before the clip (default 0)")
+    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")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.start < 0 or args.end < 0:
+        die(f"--start/--end must be >= 0, got start={args.start:g} end={args.end:g}")
+    if args.start == 0 and args.end == 0:
+        die("--start and/or --end must be > 0 (nothing to pad)")
+    validate_color(args.color, "--color")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio"))
+    output = args.output or default_output(args.input, "pad")
+
+    vf = f"tpad=start_duration={args.start:.3f}:stop_duration={args.end:.3f}:color={args.color}"
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    if has_audio:
+        af = f"adelay={int(args.start * 1000)}:all=1,apad=pad_dur={args.end:.3f}"
+        cmd += ["-map", "0:a:0?", "-af", af]
+    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']}, +{args.start:g}s start / +{args.end:g}s end)")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/redact.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Blur or pixelate an exact pixel rectangle for the whole clip (privacy redaction, license plates, faces).
+
+{x, y, width, height} are literal pixel offsets and dimensions in the SOURCE
+frame, the same convention as crop.py -- this tool needs the rectangle
+already known (a saved detection box, a hand-picked region); it does not
+locate faces or plates itself. The rest of the frame is untouched.
+
+--mode blur (default) applies a strong box blur inside the rectangle;
+--mode pixelate mosaics it into large blocks -- the more recognisable,
+unmistakably-redacted look often wanted for compliance/legal footage.
+The region stays --mode blur/pixelate for the whole clip; for a region that
+only needs covering part of the timeline, cut the clip into segments first
+(cut.py) and redact only the relevant one.
+
+Examples:
+  python3 redact.py interview.mp4 --x 820 --y 140 --width 240 --height 240
+  python3 redact.py dashcam.mp4 --x 0 --y 900 --width 400 --height 120 --mode pixelate --block-size 16
+"""
+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>_redact.<ext>)")
+    ap.add_argument("--x", type=int, required=True, help="left edge of the rectangle, in source pixels")
+    ap.add_argument("--y", type=int, required=True, help="top edge of the rectangle, in source pixels")
+    ap.add_argument("--width", type=int, required=True, help="rectangle width in px (must be even)")
+    ap.add_argument("--height", type=int, required=True, help="rectangle height in px (must be even)")
+    ap.add_argument("--mode", choices=["blur", "pixelate"], default="blur", help="blur (default) or pixelate the rectangle")
+    ap.add_argument("--blur-strength", type=int, default=20, help="box-blur radius in px, --mode blur only (default 20)")
+    ap.add_argument("--block-size", type=int, default=12, help="mosaic block size in px, --mode pixelate only (default 12)")
+    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("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    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 args.x < 0 or args.y < 0:
+        die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")
+    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}")
+    if args.blur_strength <= 0:
+        die(f"--blur-strength must be > 0, got {args.blur_strength}")
+    if args.block_size <= 1:
+        die(f"--block-size must be > 1, got {args.block_size}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        sw, sh = sh, sw
+    if args.x + args.width > sw or args.y + args.height > sh:
+        die(f"redaction rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
+    has_audio = bool(meta.get("audio"))
+    audio_streams = meta.get("audio_streams") or []
+    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+    if args.audio_stream and not audio_streams:
+        die("--audio-stream needs an input with audio streams")
+
+    output = args.output or default_output(args.input, "redact")
+    crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
+    if args.mode == "blur":
+        region = f"{crop},boxblur={args.blur_strength}:{args.blur_strength}"
+    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"
+    fc = f"[0:v]split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}[out]"
+    cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}?"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps)
+    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']}, {args.mode} at x={args.x} y={args.y} {args.width}x{args.height})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/render.py

@@ -130,7 +130,14 @@ def main() -> int:
     if not clips:
         die("project.clips is empty")
     output = rel(proj.get("output") or "final.mp4")
-    work = Path(args.work) if args.work else Path(str(Path(output).with_suffix("")) + "_work")
+    # The default work dir name comes only from the output path, with no PID or timestamp --
+    # two concurrent render.py runs targeting the same output (a batch.py "project" recipe
+    # processing several files in parallel, or simply running render.py twice by mistake) shared
+    # the same work directory and clobbered each other's same-named intermediates (clip00.mp4,
+    # fit.mp4, ...) mid-run. An explicit --work is left as given (the caller asked for that exact,
+    # shared path, e.g. to inspect intermediates across runs); only the auto-derived default is
+    # made unique per process, since it's the one that's also auto-deleted at the end.
+    work = Path(args.work) if args.work else Path(f"{Path(output).with_suffix('')}_work_{os.getpid()}")
     work.mkdir(parents=True, exist_ok=True)
     frame = proj.get("frame") or {}
     trans = proj.get("transition") or {}
@@ -204,12 +211,14 @@ def main() -> int:
         fit.setdefault("aspect", frame["aspect"])
     if frame.get("width") and len(parts) == 1:
         fit.setdefault("width", frame["width"])
+    if frame.get("height") and len(parts) == 1:
+        fit.setdefault("height", frame["height"])
     if frame.get("fps") and len(parts) == 1:
         fit.setdefault("fps", frame["fps"])
     if fit:
         nxt = str(work / "fit.mp4")
         argv = [current, "-o", nxt]
-        for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("fps", "--fps"), ("smooth", "--smooth")):
+        for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("height", "--height"), ("fps", "--fps"), ("smooth", "--smooth")):
             if fit.get(k) is not None:
                 argv += [flag, str(fit[k])]
         sh("fit.py", *argv)
@@ -361,7 +370,12 @@ def main() -> int:
             info(f"check: OK for {ck['platform']}")
         stages_done.append("check")
 
-    if not args.keep and not args.work and not STATE["dry_run"]:
+    if not args.keep and not args.work:
+        # Also clean up on --dry-run: a dry run still creates this directory (and some steps,
+        # e.g. caption.py's .ass sidecar, write into it even under --dry-run), and now that the
+        # default name carries this process's PID, nothing else will ever reuse -- and so
+        # implicitly clean up -- a leftover dry-run directory the way a same-named real run used
+        # to before the PID suffix was added.
         import shutil
         shutil.rmtree(work, ignore_errors=True)
     info(f"rendered {output} via {' → '.join(stages_done)}")