ffmpeg-skill 0.2.0 → 0.3.0

package/README.md

@@ -17,6 +17,10 @@ npx ffmpeg-skill
 - **Probe first, verify last** — the skill forces the agent to read real duration/fps/resolution before editing and to check the result after, so you get "final.mp4: 59.98 s, 1080×1920, 30 fps" instead of guesses.
 - **Lossless when possible** — cuts and joins use stream copy by default; re-encoding only happens when it must (frame-accurate cuts, filters, format changes).
 - **Cut & join** segments with `mm:ss` / `hh:mm:ss.ms` times.
+- **Silence removal / jump cuts** — detect dead air, keep a margin around speech, render frame-accurate in one pass; export the cut list for hand editing.
+- **Join with transitions** — crossfade, wipes, fade-to-black between mismatched clips (any size, fps, audio layout).
+- **Agent eyes** — contact sheets, single frames and before/after comparisons as PNG so the agent verifies caption placement, crops and colour visually.
+- **Plan before render** — every script has `--dry-run` (print the ffmpeg commands) and `--json` (structured result with a probe of the output).
 - **Captions** — burn SRT/ASS with font, size, colour, outline and position control; generate SRT from a plain timed-text file; animated (fade/pop/slide) and word-by-word karaoke highlight styles for short-form video.
 - **Fit** to an exact duration (pitch-preserving speed change or trim) and to 16:9 / 9:16 / 1:1 / 4:5 by padding or cropping; motion-interpolated or blended slow motion.
 - **Real-world footage handling** — variable-frame-rate phone clips are conformed to constant fps automatically, rotation metadata is honoured, 10-bit HEVC and 5.1 sources are handled.
@@ -86,6 +90,9 @@ More examples: [examples/README.md](examples/README.md). To see everything run e
 |--------|--------------|
 | `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format, colour space, rotation, audio channels as JSON |
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
+| `silence.py` | Detect and remove silences (jump cuts), list or export the cut list |
+| `join.py` | Concatenate clips with xfade transitions, normalising size, fps and audio |
+| `look.py` | Contact sheet, single frames, side-by-side comparison as PNG for visual checks |
 | `caption.py` | Burn SRT/ASS (font, size, colour, outline, position); build SRT from timed plain text; animated + karaoke ASS |
 | `fit.py` | Fit to a duration (speed or trim, smooth slow-mo) and/or aspect ratio (pad or crop), force constant fps |
 | `sync.py` | Detect offset between two recordings by audio cross-correlation (1 ms), correct clock drift; output aligned video/audio |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ffmpeg-skill
-description: Professional video editing with local FFmpeg — cut, caption (animated/karaoke), fit to duration/aspect, sync multicam audio with drift correction, HDR-to-SDR and LUT colour, denoise/duck/mix audio, normalise loudness, overlay logos and export platform presets, all from Python stdlib scripts with no cloud or API keys.
+description: Professional video editing with local FFmpeg — cut, remove silences, join with transitions, caption (animated/karaoke), fit to duration/aspect, sync multicam audio with drift correction, HDR-to-SDR and LUT colour, denoise/duck/mix audio, normalise loudness, overlay logos, export platform presets, and inspect frames to verify the result; Python stdlib scripts, no cloud or API keys.
 ---
 
 # ffmpeg-skill
@@ -23,15 +23,19 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
    (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode.
    `cut.py` and `loudness.py` stream-copy video by default; only pass
    `--accurate` to `cut.py` when the user needs frame-exact cuts.
-3. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
+3. **Plan with `--dry-run --json`, then execute.** Every script accepts
+   `--dry-run` (prints the ffmpeg commands, runs nothing) and `--json`
+   (structured result: output path, probe of the output, commands run). Use
+   them to confirm a plan before long encodes and to report exact facts.
+4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
    fit → caption/overlay → sync → audio → loudness → export. Do the destructive/aspect changes before burning
    text so captions are sized for the final frame. Re-encode as few times as
    possible: if several re-encoding steps are needed, keep intermediates at
    CRF 18 (the default) and only use `export.py` for the last step.
-4. **Verify the output.** Run `probe.py` on each result and confirm duration,
+5. **Verify the output.** Run `probe.py` on each result and confirm duration,
    resolution, fps and audio match what was requested. Report those numbers to
    the user (e.g. "final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo").
-5. **Keep the user's originals.** Never overwrite the source file. Write new
+6. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
 
 ## Request → script
@@ -51,6 +55,10 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
 | "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
+| "cut out the pauses / dead air", "tighten it up", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` |
+| "stitch these clips together", "add a crossfade between them" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
+| "show me what it looks like", "check the captions are readable" | `look.py output.mp4` then view the PNG |
+| "what would you run?", "don't render yet" | any script with `--dry-run` |
 | "the colours look washed out / it's an iPhone HDR video" | `color.py input.mov --to-sdr` (probe shows `hdr: true`) |
 | "apply this LUT", "convert the S-Log / V-Log footage" | `color.py input.mp4 --lut grade.cube [--lut-strength 0.7]` |
 | "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (no re-encode) |
@@ -96,6 +104,36 @@ refuses factors beyond `--max-speed`. For slow motion add `--smooth blend`
 the head (or the middle with `--from-center`). `--fps` forces a constant frame
 rate; VFR sources are conformed automatically even without it.
 
+### silence.py — remove dead air / jump cuts
+```
+silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [-o OUT]
+```
+Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
+gaps shorter than `--min-silence`, and re-encodes once with `select`/`aselect`
+(frame accurate). `--list` prints silences, kept ranges and seconds removed
+without rendering; `--edl` saves the kept ranges in `cut.py --segments` format
+so the user can edit the list by hand. Quiet rooms need `--threshold -40`
+to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
+
+### join.py — concatenate with transitions
+```
+join.py CLIP1 CLIP2 [...] [--transition fade|dissolve|wipeleft|slideleft|fadeblack|fadewhite|circleopen|none]
+        [--duration 0.5] [--width W --height H] [--fps N] [--fit pad|crop] [-o OUT]
+```
+Normalises every clip to one frame size, fps, `yuv420p` and 48 kHz stereo
+(silent track generated for clips without audio), then chains `xfade` +
+`acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
+longer than 2 × the transition. Use `--transition none` for a plain cut.
+
+### look.py — see the result
+```
+look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes
+look.py INPUT --at 2.5 [--at 7] [-o basename]                     # single frames -> basename_2.500s.png
+look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame
+```
+Outputs PNG. View it with the Read tool (or any image viewer) and judge the
+frame like an editor would. Use `--compare` to show before/after to the user.
+
 ### caption.py — subtitles (static, animated, karaoke)
 ```
 caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.2.0",
-  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: cut, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
+  "version": "0.3.0",
+  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: cut, silence removal, transitions, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
   "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
   "license": "MIT",
   "author": "kajisho5",

package/scripts/_common.py

@@ -55,10 +55,46 @@ def require_tool(name: str) -> str:
     return ""  # unreachable
 
 
+STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": []}
+
+
+def add_common(ap: "argparse.ArgumentParser") -> None:
+    """Add the flags every script shares."""
+    g = ap.add_argument_group("agent options")
+    g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
+    g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
+
+
+def apply_common(args: "argparse.Namespace") -> None:
+    STATE["dry_run"] = bool(getattr(args, "dry_run", False))
+    STATE["json"] = bool(getattr(args, "json", False))
+
+
+def emit(output: Optional[str], **extra: Any) -> None:
+    """Final stdout line: the output path, or a JSON document with --json."""
+    if STATE["json"]:
+        doc: Dict[str, Any] = {"output": output, "dry_run": STATE["dry_run"], "commands": list(STATE["commands"])}
+        if output and not STATE["dry_run"] and os.path.exists(output):
+            doc["probe"] = probe(output)
+        doc.update(extra)
+        print_json(doc)
+    elif output:
+        print(output)
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
-    """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True."""
+    """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
+
+    With --dry-run, ffmpeg invocations are printed and skipped (ffprobe still runs so
+    scripts can plan); a fake successful CompletedProcess is returned.
+    """
+    is_ffmpeg = os.path.basename(cmd[0]).startswith("ffmpeg")
+    if is_ffmpeg:
+        STATE["commands"].append(" ".join(shell_quote(c) for c in cmd))
     if not quiet:
-        info("$ " + " ".join(shell_quote(c) for c in cmd))
+        info(("[dry-run] $ " if STATE["dry_run"] and is_ffmpeg else "$ ") + " ".join(shell_quote(c) for c in cmd))
+    if STATE["dry_run"] and is_ffmpeg:
+        return subprocess.CompletedProcess(list(cmd), 0, "", "")
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
     if check and proc.returncode != 0:
         tail = "\n".join(proc.stderr.strip().splitlines()[-15:])
@@ -81,6 +117,11 @@ def ffmpeg_base(overwrite: bool = True) -> List[str]:
 def probe(path: str) -> Dict[str, Any]:
     """Return a compact, script-friendly description of a media file."""
     if not os.path.exists(path):
+        if STATE["dry_run"]:
+            return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
+                    "video": {"codec": None, "width": 0, "height": 0, "fps": None, "pix_fmt": None, "hdr": False,
+                              "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
+                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0}
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(

package/scripts/audio.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import audio_codec_for, default_output, die, ffmpeg_base, info, probe, run
+from _common import add_common, apply_common, emit, audio_codec_for, default_output, die, ffmpeg_base, info, probe, run
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
@@ -43,7 +43,9 @@ def main() -> int:
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
     ap.add_argument("--bitrate", default="192k")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
@@ -120,7 +122,7 @@ def main() -> int:
     r = probe(output)
     a = r["audio"]
     info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/caption.py

@@ -22,7 +22,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -176,7 +176,9 @@ def main() -> int:
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
     enc.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if not (args.srt or args.ass or args.text):
         die("give one of --srt, --ass or --text")
@@ -240,7 +242,7 @@ def main() -> int:
     run(cmd)
     result = probe(output)
     info(f"wrote {output} ({result.get('duration'):.3f}s)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/color.py

@@ -15,7 +15,7 @@ import os
 import sys
 from typing import List
 
-from _common import aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
@@ -52,7 +52,9 @@ def main() -> int:
     ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -82,7 +84,7 @@ def main() -> int:
             cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
             run(cmd)
         info(f"wrote {output} (tags -> {args.retag})")
-        print(output)
+        emit(output)
         return 0
 
     if args.to_sdr:
@@ -109,7 +111,7 @@ def main() -> int:
     r = probe(output)
     info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/cut.py

@@ -16,7 +16,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 
 def parse_segments(spec: str) -> List[Tuple[float, float]]:
@@ -52,7 +52,7 @@ 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()}")
-    if not reencode and tolerance >= 0:
+    if not reencode and tolerance >= 0 and not STATE["dry_run"]:
         got = probe(dst).get("duration") or 0.0
         if abs(got - dur) > tolerance:
             info(f"stream copy landed on a keyframe {abs(got - dur):.2f}s away from the requested cut "
@@ -74,7 +74,9 @@ def main() -> int:
     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")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     total = meta.get("duration") or 0.0
@@ -131,7 +133,7 @@ def main() -> int:
     expected = sum(e - s for s, e in segments)
     info(f"wrote {output} ({result.get('duration'):.3f}s, expected ~{expected:.3f}s, "
          + ("re-encoded" if reencoded else "lossless stream copy") + ")")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/export.py

@@ -22,7 +22,7 @@ import argparse
 import sys
 from typing import Dict, List
 
-from _common import cfr_args, default_output, die, ffmpeg_base, info, probe, run
+from _common import add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
 
 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"},
@@ -48,7 +48,9 @@ def main() -> int:
     ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
     ap.add_argument("--crf", type=int, help="override CRF")
     ap.add_argument("--list", action="store_true", help="list presets and exit")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if args.list:
         for name, p in PRESETS.items():
@@ -84,7 +86,7 @@ def main() -> int:
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)
         info(f"wrote {output}")
-        print(output)
+        emit(output)
         return 0
 
     if vf:
@@ -108,7 +110,7 @@ def main() -> int:
     result = probe(output)
     v = result["video"]
     info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/fit.py

@@ -19,7 +19,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, 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)}
 
@@ -74,7 +74,9 @@ def main() -> int:
     e.add_argument("--crf", type=int, default=18)
     e.add_argument("--preset", default="medium")
     e.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 not args.duration and not args.aspect and not args.width and not args.fps:
         die("nothing to do: give --duration, --aspect, --width and/or --fps")
@@ -164,7 +166,7 @@ def main() -> int:
     if abs(factor - 1.0) > 1e-4:
         msg += f", speed {factor:.3f}x"
     info(msg)
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/join.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Join clips with transitions, normalising resolution, frame rate and audio
+layout so mismatched sources (phone + camera + screen recording) cut together.
+
+Transitions (xfade): fade, dissolve, wipeleft, wiperight, wipeup, wipedown,
+slideleft, slideright, circleopen, fadeblack, fadewhite, smoothleft, none.
+
+Examples:
+  python3 join.py a.mp4 b.mp4 c.mp4 -o final.mp4                      # 0.5 s crossfade, size/fps from the first clip
+  python3 join.py *.mp4 --transition fadeblack --duration 1 -o reel.mp4
+  python3 join.py a.mov b.mp4 --transition none --width 1920 --height 1080 --fps 30
+"""
+import argparse
+import sys
+from typing import List
+
+from _common import aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
+
+TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
+               "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="two or more clips in order")
+    ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
+    ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
+    ap.add_argument("--duration", type=float, default=0.5, help="transition length in seconds (default 0.5)")
+    ap.add_argument("--width", type=int, help="output width (default: first clip)")
+    ap.add_argument("--height", type=int, help="output height (default: first clip)")
+    ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
+    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")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if len(args.inputs) < 2:
+        die("give at least two clips")
+    metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        if not m.get("video"):
+            die(f"{p} has no video stream")
+    first = metas[0]["video"]
+    w = args.width or first["width"]
+    h = args.height or first["height"]
+    if first.get("rotation") in (90, -90, 270, -270) and not (args.width or args.height):
+        w, h = h, w
+    fps = args.fps or first.get("fps") or 30.0
+    fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
+    w, h = w - (w % 2), h - (h % 2)
+    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:
+            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+
+    cmd = ffmpeg_base()
+    extra_inputs: List[str] = []
+    parts: List[str] = []
+    n = len(args.inputs)
+    for i, (p, m) in enumerate(zip(args.inputs, metas)):
+        cmd += ["-i", p]
+    # silent audio for clips without an audio track
+    audio_src: List[str] = []
+    for i, m in enumerate(metas):
+        if m.get("audio"):
+            audio_src.append(f"{i}:a:0")
+        else:
+            idx = n + len(extra_inputs)
+            extra_inputs += ["-f", "lavfi", "-t", f"{durs[i]:.3f}", "-i", "anullsrc=r=48000:cl=stereo"]
+            audio_src.append(f"{idx}:a:0")
+    cmd += extra_inputs
+
+    if args.fit == "crop":
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
+    else:
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
+    for i in range(n):
+        parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format=yuv420p,settb=AVTB[v{i}]")
+        parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts=stereo,asetpts=PTS-STARTPTS[a{i}]")
+
+    if args.transition == "none":
+        chain = "".join(f"[v{i}][a{i}]" for i in range(n))
+        parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
+    else:
+        vprev, aprev = "v0", "a0"
+        offset = 0.0
+        for i in range(1, n):
+            offset += durs[i - 1] - d
+            vout = f"vx{i}" if i < n - 1 else "vout"
+            aout = f"ax{i}" if i < n - 1 else "aout"
+            parts.append(f"[{vprev}][v{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
+            parts.append(f"[{aprev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            vprev, aprev = vout, aout
+
+    output = args.output or default_output(args.inputs[0], "joined", "mp4")
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    cmd += x264_args(args.crf, args.preset) + aac_args() + [output]
+    run(cmd)
+    expected = sum(durs) - d * (n - 1)
+    r = probe(output)
+    info(f"wrote {output} ({r['duration']:.3f}s, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
+    emit(output, clips=n, transition=args.transition, expected_duration=round(expected, 3))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/look.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Give the agent eyes: pull frames or a contact sheet out of a video as PNG so
+the result can be inspected (caption placement, logo position, crop, colour).
+
+Examples:
+  python3 look.py final.mp4                          # 12-tile contact sheet with timecodes -> final_sheet.png
+  python3 look.py final.mp4 --tiles 4x5 --width 1600
+  python3 look.py final.mp4 --at 2.5 --at 7          # single frames -> final_2.500s.png, final_7.000s.png
+  python3 look.py before.mp4 --compare after.mp4 --at 4   # side-by-side frame
+Then view the PNG (Read tool / image viewer) and verify before reporting.
+"""
+import argparse
+import os
+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
+
+FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
+
+
+def timecode_filter() -> str:
+    return f"drawtext=text='%{{pts\\:hms}}':{FONT}"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output PNG (contact sheet / compare) or basename for --at frames")
+    ap.add_argument("--at", action="append", help="time of a frame to extract (repeatable)")
+    ap.add_argument("--tiles", default="4x3", help="contact sheet grid COLSxROWS (default 4x3)")
+    ap.add_argument("--width", type=int, default=1280, help="total width of the sheet / compare image (default 1280)")
+    ap.add_argument("--compare", help="second video: place its frame next to the first (needs --at)")
+    ap.add_argument("--no-timecode", action="store_true")
+    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")
+    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()
+    outputs: List[str] = []
+
+    if args.compare:
+        if not args.at:
+            die("--compare needs --at TIME")
+        probe(args.compare)
+        for t in args.at:
+            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
+            fc = (f"[0:v]scale={half}:-2{tc}[a];[1:v]scale={half}:-2{tc}[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,
+                                   "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", out]
+            run(cmd)
+            outputs.append(out)
+    elif args.at:
+        for t in args.at:
+            sec = parse_time(t)
+            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")
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc}", "-frames:v", "1", out]
+            run(cmd)
+            outputs.append(out)
+    else:
+        try:
+            cols, rows = (int(x) for x in args.tiles.lower().split("x"))
+        except ValueError:
+            die("--tiles must look like 4x3")
+        n = cols * rows
+        if not dur:
+            die("cannot build a contact sheet without a known duration")
+        step = dur / n
+        tile_w = max(2, (args.width // cols) // 2 * 2)
+        out = args.output or os.path.join(outdir, f"{stem}_sheet.png")
+        # sample at the middle of each slice so the first/last tiles are not black lead-in/out frames
+        vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc},"
+              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
+        cmd = ffmpeg_base() + ["-ss", f"{step / 2:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
+        run(cmd)
+        outputs.append(out)
+        info(f"contact sheet: {n} frames every {step:.2f}s")
+
+    for o in outputs:
+        info(f"wrote {o}")
+    emit(outputs[0] if len(outputs) == 1 else None, outputs=outputs)
+    if len(outputs) > 1 and not args.json:
+        for o in outputs:
+            print(o)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/loudness.py

@@ -18,7 +18,7 @@ import os
 import re
 import sys
 
-from _common import AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+from _common import add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
 
 
 
@@ -46,7 +46,9 @@ def main() -> int:
     ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
     ap.add_argument("--audio-bitrate", default="192k", help="AAC bitrate when the container is video (default 192k)")
     ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     if not meta.get("audio"):
@@ -76,7 +78,7 @@ def main() -> int:
 
     after = measure(output, args.lufs, args.tp, args.lra)
     info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/overlay.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -100,7 +100,9 @@ def main() -> int:
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
     enc.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -163,7 +165,7 @@ def main() -> int:
     run(cmd)
     result = probe(output)
     info(f"wrote {output} ({result['duration']:.3f}s)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/silence.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Remove silences / dead air (jump-cut editing) or just list them.
+
+Detects quiet stretches with ffmpeg's silencedetect, keeps a margin on each
+side so words are not clipped, drops gaps shorter than --min-silence, and
+writes a frame-accurate re-encode in one pass (select/aselect filters).
+
+Examples:
+  python3 silence.py talk.mp4                                 # -35 dB, gaps >= 0.6 s, 0.15 s margin
+  python3 silence.py talk.mp4 --threshold -40 --min-silence 1 --margin 0.25
+  python3 silence.py talk.mp4 --list                          # print the silences and the resulting cut list, no output
+  python3 silence.py talk.mp4 --edl keep.txt                  # also save the kept ranges (START-END per line, cut.py --segments format)
+"""
+import argparse
+import re
+import sys
+from typing import List, Tuple
+
+from _common import aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args
+
+SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
+
+
+def detect(path: str, threshold: float, min_silence: float) -> List[Tuple[float, float]]:
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af",
+           f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
+    proc = run(cmd, quiet=True, check=False)
+    if proc.returncode != 0:
+        die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}")
+    silences: List[Tuple[float, float]] = []
+    start = None
+    for kind, val in SIL_RE.findall(proc.stderr):
+        if kind == "start":
+            start = float(val)
+        elif start is not None:
+            silences.append((start, float(val)))
+            start = None
+    if start is not None:  # silence runs to the end
+        silences.append((start, float("inf")))
+    return silences
+
+
+def keep_ranges(silences: List[Tuple[float, float]], duration: float, margin: float, min_keep: float) -> List[Tuple[float, float]]:
+    keeps: List[Tuple[float, float]] = []
+    cursor = 0.0
+    for s, e in silences:
+        s_adj = max(cursor, s + margin)
+        if s_adj - cursor >= min_keep:
+            keeps.append((cursor, s_adj))
+        cursor = min(duration, e - margin) if e != float("inf") else duration
+    if duration - cursor >= min_keep:
+        keeps.append((cursor, duration))
+    return keeps
+
+
+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>_tight.<ext>)")
+    ap.add_argument("--threshold", type=float, default=-35.0, help="silence level in dBFS (default -35; use -40..-45 for quiet rooms)")
+    ap.add_argument("--min-silence", type=float, default=0.6, help="only remove gaps at least this long in seconds (default 0.6)")
+    ap.add_argument("--margin", type=float, default=0.15, help="seconds of silence to keep on each side of speech (default 0.15)")
+    ap.add_argument("--min-keep", type=float, default=0.2, help="drop kept pieces shorter than this (default 0.2)")
+    ap.add_argument("--list", action="store_true", help="only print silences and the kept ranges")
+    ap.add_argument("--edl", help="write the kept ranges to this file, one START-END per line")
+    ap.add_argument("--crf", type=int, default=18)
+    ap.add_argument("--preset", default="medium")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    meta = probe(args.input)
+    if not meta.get("audio"):
+        die("input has no audio stream to analyse")
+    duration = meta.get("duration") or 0.0
+    silences = detect(args.input, args.threshold, args.min_silence)
+    keeps = keep_ranges(silences, duration, args.margin, args.min_keep)
+    kept = sum(e - s for s, e in keeps)
+    removed = max(0.0, duration - kept)
+    summary = {
+        "silences": [[round(s, 3), None if e == float("inf") else round(e, 3)] for s, e in silences],
+        "keep": [[round(s, 3), round(e, 3)] for s, e in keeps],
+        "input_duration": round(duration, 3),
+        "kept_duration": round(kept, 3),
+        "removed_seconds": round(removed, 3),
+    }
+    info(f"{len(silences)} silences, keeping {len(keeps)} ranges: {kept:.2f}s of {duration:.2f}s (removing {removed:.2f}s)")
+
+    if args.edl:
+        with open(args.edl, "w", encoding="utf-8") as fh:
+            for s, e in keeps:
+                fh.write(f"{s:.3f}-{e:.3f}\n")
+        info(f"wrote {args.edl}")
+
+    if args.list:
+        if args.json:
+            emit(None, **summary)
+        else:
+            print_json(summary)
+        return 0
+    if not keeps:
+        die("nothing would be kept; raise --threshold (e.g. -45) or check the audio")
+    if not silences or removed < 0.05:
+        info("no removable silence found; output would equal the input")
+
+    output = args.output or default_output(args.input, "tight")
+    expr = "+".join(f"between(t,{s:.3f},{e:.3f})" for s, e in keeps)
+    vf = f"select='{expr}',setpts=N/FRAME_RATE/TB"
+    af = f"aselect='{expr}',asetpts=N/SR/TB"
+    cmd = ffmpeg_base() + ["-i", args.input]
+    if meta.get("video"):
+        cmd += ["-vf", vf] + x264_args(args.crf, args.preset) + cfr_args(meta)
+    cmd += ["-af", af] + aac_args() + [output]
+    run(cmd)
+    r = probe(output)
+    info(f"wrote {output} ({r['duration']:.3f}s, expected ~{kept:.3f}s)")
+    emit(output, **summary)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sync.py

@@ -26,7 +26,7 @@ import subprocess
 import sys
 from typing import List
 
-from _common import aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
+from _common import add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
 
 SR = 8000  # decode sample rate
 
@@ -160,12 +160,13 @@ def main() -> int:
     ap.add_argument("--fine-ms", type=float, default=1.0, help="fine resolution in ms for the refinement pass, 0 to skip (default 1)")
     ap.add_argument("--fix-drift", action="store_true", help="also measure the offset near the END and correct clock drift by resampling the second file")
     ap.add_argument("--drift-window", type=float, default=60.0, help="seconds of audio analysed at each end for drift (default 60)")
-    ap.add_argument("--json", action="store_true", help="print the result as JSON")
     mode = ap.add_mutually_exclusive_group()
     mode.add_argument("--replace-audio", action="store_true", help="write reference video with the second file's audio, aligned")
     mode.add_argument("--trim-second", action="store_true", help="write the second file shifted so it lines up with the reference")
     ap.add_argument("--crf", type=int, default=18)
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     for p in (args.reference, args.second):
         if not probe(p).get("audio"):
@@ -286,7 +287,7 @@ def main() -> int:
         info(f"wrote {output}")
 
     if args.json:
-        print(json.dumps(result, indent=2))
+        emit(result.get("output"), **{k: v for k, v in result.items() if k != "output"})
     else:
         print(f"offset: {result['offset_seconds']:+.3f}s ({result['meaning']}), confidence {result['confidence']:.2f}")
         if drift_info: