Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Release 0.3.0: look, silence, join, --dry-run/--json on every script (#3)
kajisho580f62cd62497
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e5074ef..289808d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,13 @@# Changelog+## 0.3.0++- `look.py` (new): contact sheet with timecodes, single-frame extraction, side-by-side before/after PNGs — the agent can inspect its own output.+- `silence.py` (new): silence detection and frame-accurate removal with margins, `--list` and `--edl` cut-list export compatible with `cut.py --segments`.+- `join.py` (new): xfade/acrossfade transitions between clips with automatic normalisation of size, fps, pixel format and audio layout (silent track synthesised when missing).+- `--dry-run` and `--json` on every script: print the ffmpeg commands without running, or emit a structured result (output, probe, commands).+- SKILL.md workflow now includes plan (`--dry-run`) and visual verification (`look.py`) steps.+## 0.2.0- `color.py` (new): HDR10/HLG → SDR BT.709 tone mapping (zscale + tonemap), 3D `.cube` LUTs with strength blending, metadata-only colour retagging.diff --git a/README.md b/README.mdindex e86d075..cbbea09 100644--- a/README.md+++ b/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 |diff --git a/SKILL.md b/SKILL.mdindex f39cfad..cc76f69 100644--- a/SKILL.md+++ b/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 burningtext so captions are sized for the final frame. Re-encode as few times aspossible: if several re-encoding steps are needed, keep intermediates atCRF 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 tothe 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 newfiles 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 framerate; 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]diff --git a/examples/README.md b/examples/README.mdindex 47abedd..cf2e33c 100644--- a/examples/README.md+++ b/examples/README.md@@ -74,6 +74,33 @@ python3 $S/overlay.py final.mp4 --image logo.png --position top-right --scale 22python3 $S/overlay.py final.mp4 --text "Episode 12 — Clean Audio" --position top-left --font-size 48 --box --start 0 --end 4 --fade 0.4```+### "Cut out the pauses"+```bash+python3 $S/silence.py talk.mp4 --list # see what would go+python3 $S/silence.py talk.mp4 --threshold -40 --margin 0.2 # render talk_tight.mp4+python3 $S/silence.py talk.mp4 --edl keep.txt # hand-edit keep.txt, then:+python3 $S/cut.py talk.mp4 --segments "$(paste -sd, keep.txt)" --accurate+```++### "Stitch the clips with a crossfade"+```bash+python3 $S/join.py intro.mp4 main.mp4 outro.mp4 --transition fade --duration 0.5 -o final.mp4+python3 $S/join.py phone.mov camera.mp4 screen.mkv --transition fadeblack --width 1920 --height 1080 --fps 30+```++### "Let me see it" (and let the agent see it)+```bash+python3 $S/look.py final.mp4 # final_sheet.png, 12 tiles with timecodes+python3 $S/look.py final.mp4 --at 4.5 --at 12 # individual frames+python3 $S/look.py before.mp4 --compare after.mp4 --at 4+```++### "Tell me what you'd run first"+```bash+python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run+python3 $S/export.py input.mp4 --preset reels --json # structured result incl. probe of the output+```+### "The iPhone HDR footage looks washed out"```bashpython3 $S/probe.py IMG_0231.MOV --field video.hdr_format # HDR10/PQ, HLG, ...diff --git a/examples/make_demo.sh b/examples/make_demo.shindex bd4d242..7e33a2b 100755--- a/examples/make_demo.sh+++ b/examples/make_demo.sh@@ -67,6 +67,10 @@ step "7/10 sync.py (detect the 2.5 s lav-mic offset, replace camera audio)""$PY" "$SCRIPTS/sync.py" "$OUT/source.mp4" "$OUT/lavmic.wav" --json | tee "$OUT/sync.json""$PY" "$SCRIPTS/sync.py" "$OUT/05_titled.mp4" "$OUT/lavmic.wav" --replace-audio -o "$OUT/06_synced.mp4"+step "7b/10 silence.py (remove dead air) and join.py (crossfade the intro onto it)"+"$PY" "$SCRIPTS/silence.py" "$OUT/06_synced.mp4" --threshold -35 --min-silence 0.4 --preset veryfast -o "$OUT/06a_tight.mp4"+"$PY" "$SCRIPTS/join.py" "$OUT/02_fit.mp4" "$OUT/06a_tight.mp4" --transition fade --duration 0.5 --preset veryfast -o "$OUT/06c_joined.mp4"+step "8/10 audio.py (voice clean-up + ducked music bed) and loudness.py (-14 LUFS, two-pass)"ffmpeg -y -hide_banner -loglevel error -f lavfi -i "aevalsrc='0.3*sin(2*PI*110*t)+0.2*sin(2*PI*165*t)*gt(sin(2*PI*2*t)\,0)':s=48000" -t 12 -c:a aac "$OUT/music.m4a""$PY" "$SCRIPTS/audio.py" "$OUT/06_synced.mp4" --voice --music "$OUT/music.m4a" --duck --fade-out 2 -o "$OUT/06b_audio.mp4"@@ -75,6 +79,9 @@ ffmpeg -y -hide_banner -loglevel error -f lavfi -i "aevalsrc='0.3*sin(2*PI*110*tstep "8b/10 color.py (HDR10 -> SDR BT.709 tone mapping)""$PY" "$SCRIPTS/color.py" "$OUT/hdr10.mp4" --to-sdr --preset veryfast -o "$OUT/07b_sdr.mp4"+step "8c/10 look.py (contact sheet for a visual check)"+"$PY" "$SCRIPTS/look.py" "$OUT/07_loudnorm.mp4" -o "$OUT/07_loudnorm_sheet.png"+step "9/10 export.py (YouTube, Reels, X, ProRes, H.265)""$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset youtube -o "$OUT/08_youtube.mp4""$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset reels --fit crop -o "$OUT/08_reels.mp4"diff --git a/package.json b/package.jsonindex 7e31e3a..ee78611 100644--- a/package.json+++ b/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",diff --git a/scripts/_common.py b/scripts/_common.pyindex 7a37381..5359b08 100755--- a/scripts/_common.py+++ b/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(diff --git a/scripts/audio.py b/scripts/audio.pyindex 3e3246e..9dd2498 100755--- a/scripts/audio.py+++ b/scripts/audio.py@@ -15,7 +15,7 @@ import argparseimport sysfrom 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, runVOICE_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 0diff --git a/scripts/caption.py b/scripts/caption.pyindex 42caba9..e49a258 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -22,7 +22,7 @@ import reimport sysfrom 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_argsALIGN = {"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 0diff --git a/scripts/color.py b/scripts/color.pyindex df8083d..810a52e 100755--- a/scripts/color.py+++ b/scripts/color.py@@ -15,7 +15,7 @@ import osimport sysfrom 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_argsTONEMAPS = ["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 0if 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 0diff --git a/scripts/cut.py b/scripts/cut.pyindex 8e5296b..6d5d236 100755--- a/scripts/cut.py+++ b/scripts/cut.py@@ -16,7 +16,7 @@ import sysimport tempfilefrom 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_argsdef 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: iinfo("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.0if 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 0diff --git a/scripts/export.py b/scripts/export.pyindex 5b1d918..9822bb0 100755--- a/scripts/export.py+++ b/scripts/export.py@@ -22,7 +22,7 @@ import argparseimport sysfrom 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, runPRESETS: 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 0if 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 0diff --git a/scripts/fit.py b/scripts/fit.pyindex e239537..e42db3e 100755--- a/scripts/fit.py+++ b/scripts/fit.py@@ -19,7 +19,7 @@ import sysfrom fractions import Fractionfrom 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_argsASPECT_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 0diff --git a/scripts/join.py b/scripts/join.pynew file mode 100755index 0000000..1998672--- /dev/null+++ b/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())diff --git a/scripts/look.py b/scripts/look.pynew file mode 100755index 0000000..844513a--- /dev/null+++ b/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:[email protected]: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())diff --git a/scripts/loudness.py b/scripts/loudness.pyindex c33bd49..326e487 100755--- a/scripts/loudness.py+++ b/scripts/loudness.py@@ -18,7 +18,7 @@ import osimport reimport 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 0diff --git a/scripts/overlay.py b/scripts/overlay.pyindex fce6147..f68b245 100755--- a/scripts/overlay.py+++ b/scripts/overlay.py@@ -15,7 +15,7 @@ import argparseimport sysfrom 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_argsPOS = {"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 0diff --git a/scripts/silence.py b/scripts/silence.pynew file mode 100755index 0000000..6bf118f--- /dev/null+++ b/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())diff --git a/scripts/sync.py b/scripts/sync.pyindex 9a93477..a158d28 100755--- a/scripts/sync.py+++ b/scripts/sync.py@@ -26,7 +26,7 @@ import subprocessimport sysfrom 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_argsSR = 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:diff --git a/tests/test_all.py b/tests/test_all.pyindex 21214bc..5ec4e68 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -30,6 +30,12 @@ def sh(*cmd, expect_fail=False):return proc+def png_size(path) -> tuple:+ with open(path, "rb") as fh:+ head = fh.read(24)+ return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")++def script(name, *args, **kw):return sh(sys.executable, SCRIPTS / name, *args, **kw)@@ -340,6 +346,85 @@ class FFmpegSkillTests(unittest.TestCase):script("caption.py", self.src, "--srt", srt, "--animate", "fade", "--preset", "veryfast", "-o", out2)self.assertTrue((OUT / "fade.ass").exists())+ # ---------------------------------------------------------------- v0.3: look / silence / join / agent flags+ def test_look_contact_sheet_and_frames(self):+ sheet = OUT / "sheet.png"+ proc = script("look.py", self.src, "--tiles", "4x3", "--width", "1280", "-o", sheet)+ self.assertTrue(sheet.exists())+ self.assertIn("12 frames", proc.stderr)+ w, h = png_size(sheet)+ self.assertGreaterEqual(w, 1280)+ self.assertGreater(h, 500, "three rows of 16:9 tiles")+ proc = script("look.py", self.src, "--at", "2.5", "--at", "0:07", "-o", OUT / "frame")+ frames = [OUT / "frame_2.500s.png", OUT / "frame_7.000s.png"]+ for f in frames:+ self.assertTrue(f.exists(), f)+ self.assertEqual(png_size(frames[0]), (1280, 720))+ cmp_png = OUT / "cmp.png"+ script("look.py", self.src, "--compare", self.src, "--at", "1", "-o", cmp_png)+ self.assertEqual(png_size(cmp_png)[0], 1280)++ def test_silence_removal(self):+ gappy = OUT / "gappy.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", gappy)+ data = json.loads(script("silence.py", gappy, "--list", "--json").stdout)+ self.assertEqual(len(data["silences"]), 3)+ self.assertClose(data["removed_seconds"], 5.25, 0.3)+ out = OUT / "tight.mp4"+ edl = OUT / "keep.txt"+ script("silence.py", gappy, "--preset", "veryfast", "--edl", edl, "-o", out)+ self.assertClose(probe(str(out))["duration"], 6.75, 0.3)+ self.assertEqual(len(edl.read_text().strip().splitlines()), 3)+ # the EDL feeds cut.py --segments directly+ segs = ",".join(edl.read_text().split())+ out2 = OUT / "tight_via_cut.mp4"+ script("cut.py", gappy, "--segments", segs, "--accurate", "--preset", "veryfast", "-o", out2)+ self.assertClose(probe(str(out2))["duration"], 6.75, 0.4)++ def test_join_with_transition_normalises_mismatched_clips(self):+ out = OUT / "joined.mp4"+ # 720p 30fps stereo + rotated portrait + 640x360 mono clip without audio+ silent = OUT / "silent.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", silent)+ script("join.py", self.src, self.rot, silent, "--transition", "fadeblack", "--duration", "0.5", "--preset", "veryfast", "-o", out)+ m = probe(str(out))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))+ self.assertClose(m["video"]["fps"], 30.0, 0.05)+ self.assertEqual(m["audio"]["channels"], 2)+ self.assertClose(m["duration"], 12 + 6 + 4 - 1.0, 0.3)+ out2 = OUT / "joined_cut.mp4"+ script("join.py", self.src, silent, "--transition", "none", "--preset", "veryfast", "-o", out2)+ self.assertClose(probe(str(out2))["duration"], 16.0, 0.3)+ script("join.py", self.src, expect_fail=True)++ def test_dry_run_and_json_on_every_script(self):+ cases = [+ ("cut.py", [self.src, "--start", "1", "--end", "3"]),+ ("fit.py", [self.src, "--duration", "6"]),+ ("caption.py", [self.src, "--srt", OUT / "cues.srt"]),+ ("overlay.py", [self.src, "--image", self.logo]),+ ("export.py", [self.src, "--preset", "x"]),+ ("color.py", [self.src, "--retag", "bt709"]),+ ("audio.py", [self.src, "--denoise"]),+ ("join.py", [self.src, self.src]),+ ]+ if not (OUT / "cues.srt").exists():+ script("caption.py", "--text", self.cues, "--write-srt", OUT / "cues.srt")+ for name, argv in cases:+ out = OUT / f"dry_{name}.mp4"+ proc = script(name, *argv, "-o", out, "--dry-run", "--json")+ self.assertFalse(out.exists(), f"{name} wrote a file in --dry-run")+ data = json.loads(proc.stdout)+ self.assertTrue(data["dry_run"], name)+ self.assertTrue(data["commands"] and all("ffmpeg" in c for c in data["commands"]), name)+ self.assertEqual(data["output"], str(out), name)+ # --json on a real run includes the probe of the output+ out = OUT / "json_cut.mp4"+ data = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", out, "--json").stdout)+ self.assertClose(data["probe"]["duration"], 2.0, 0.6)+# ---------------------------------------------------------------- helpdef test_every_script_has_help(self):for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):