Skip to content

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.

Release 0.3.0: look, silence, join, --dry-run/--json on every script (#3)

kajisho580f62cd62497
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.md
index 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 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]
diff --git a/examples/README.md b/examples/README.md
index 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 22
python3 $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"
```bash
python3 $S/probe.py IMG_0231.MOV --field video.hdr_format # HDR10/PQ, HLG, ...
diff --git a/examples/make_demo.sh b/examples/make_demo.sh
index 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*t
step "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.json
index 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.py
index 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.py
index 3e3246e..9dd2498 100755
--- a/scripts/audio.py
+++ b/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
diff --git a/scripts/caption.py b/scripts/caption.py
index 42caba9..e49a258 100755
--- a/scripts/caption.py
+++ b/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
diff --git a/scripts/color.py b/scripts/color.py
index df8083d..810a52e 100755
--- a/scripts/color.py
+++ b/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
diff --git a/scripts/cut.py b/scripts/cut.py
index 8e5296b..6d5d236 100755
--- a/scripts/cut.py
+++ b/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
diff --git a/scripts/export.py b/scripts/export.py
index 5b1d918..9822bb0 100755
--- a/scripts/export.py
+++ b/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
diff --git a/scripts/fit.py b/scripts/fit.py
index e239537..e42db3e 100755
--- a/scripts/fit.py
+++ b/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
diff --git a/scripts/join.py b/scripts/join.py
new file mode 100755
index 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.py
new file mode 100755
index 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.py
index c33bd49..326e487 100755
--- a/scripts/loudness.py
+++ b/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
diff --git a/scripts/overlay.py b/scripts/overlay.py
index fce6147..f68b245 100755
--- a/scripts/overlay.py
+++ b/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
diff --git a/scripts/silence.py b/scripts/silence.py
new file mode 100755
index 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.py
index 9a93477..a158d28 100755
--- a/scripts/sync.py
+++ b/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:
diff --git a/tests/test_all.py b/tests/test_all.py
index 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)
+
# ---------------------------------------------------------------- help
def test_every_script_has_help(self):
for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):