ffmpeg-skill 0.2.0 → 0.4.0

package/scripts/probe.py

@@ -12,7 +12,7 @@ Examples:
 import argparse
 import sys
 
-from _common import print_json, probe
+from _common import analyze_levels, print_json, probe
 
 
 def main() -> int:
@@ -20,9 +20,14 @@ def main() -> int:
     ap.add_argument("inputs", nargs="+", help="media file(s) to inspect")
     ap.add_argument("--compact", action="store_true", help="one human-readable line per file instead of JSON")
     ap.add_argument("--field", help="print only this top-level field (e.g. duration) or dotted path (video.fps)")
+    ap.add_argument("--analyze", action="store_true", help="also sample picture levels (first 20 s) and flag Log-looking footage")
     args = ap.parse_args()
 
     results = [probe(p) for p in args.inputs]
+    if args.analyze:
+        for r in results:
+            if r.get("video"):
+                r["levels"] = analyze_levels(r["file"])
 
     if args.field:
         for r in results:
@@ -41,6 +46,10 @@ def main() -> int:
                 line += f" | {v.get('width')}x{v.get('height')} @ {v.get('fps')}fps {v.get('codec')} {v.get('pix_fmt')}"
                 if v.get("variable_frame_rate_suspected"):
                     line += " (VFR?)"
+                if v.get("hdr"):
+                    line += f" [{v.get('hdr_format')}]"
+                if r.get("levels", {}).get("looks_like_log"):
+                    line += " [Log?]"
             else:
                 line += " | no video"
             if a:

package/scripts/silence.py

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

package/scripts/sync.py

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

package/scripts/verify.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Real-footage verification kit: run the whole toolchain against your own
+files (phone HDR, GoPro, OBS screen captures, Log footage, Zoom recordings)
+and get a pass/fail table. Synthetic test media never shows what a real
+container does; this does.
+
+Every file gets: probe, lossless cut, accurate cut, fit (9:16 pad), caption
+burn, overlay text, loudness measurement, silence listing, export (x preset),
+look (contact sheet), plus color --to-sdr when the file is HDR and
+audio --downmix when it has more than 2 channels.
+
+Examples:
+  python3 verify.py ~/Footage/*.MOV ~/Footage/*.mp4
+  python3 verify.py fixtures/ --quick --report verify.md
+  python3 verify.py clip.mov --keep --out ./verify_out
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Dict, List
+
+from _common import add_common, apply_common, die, emit, info, probe
+
+HERE = Path(__file__).resolve().parent
+MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}
+
+
+def collect(paths: List[str]) -> List[Path]:
+    files: List[Path] = []
+    for p in paths:
+        pp = Path(p)
+        if pp.is_dir():
+            files += sorted(x for x in pp.rglob("*") if x.suffix.lower() in MEDIA_EXT and x.is_file())
+        elif pp.is_file():
+            files.append(pp)
+        else:
+            die(f"not found: {p}")
+    if not files:
+        die("no media files found")
+    return files
+
+
+def step(name: str, argv: List[str], timeout: float) -> Dict:
+    t0 = time.time()
+    try:
+        proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=timeout)
+        ok = proc.returncode == 0
+        err = "" if ok else (proc.stderr.strip().splitlines() or ["?"])[-1][:200]
+    except subprocess.TimeoutExpired:
+        ok, err = False, f"timeout after {timeout:.0f}s"
+    return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("paths", nargs="+", help="media files and/or folders")
+    ap.add_argument("--out", help="directory for outputs (default: temp dir, deleted unless --keep)")
+    ap.add_argument("--keep", action="store_true", help="keep the outputs")
+    ap.add_argument("--quick", action="store_true", help="probe, copy cut, fit, caption, export only")
+    ap.add_argument("--seconds", type=float, default=6.0, help="length of the test cut taken from each file (default 6)")
+    ap.add_argument("--timeout", type=float, default=600.0, help="per-step timeout in seconds")
+    ap.add_argument("--report", help="write a Markdown report here")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    files = collect(args.paths)
+    tmp = None
+    if args.out:
+        outdir = Path(args.out)
+        outdir.mkdir(parents=True, exist_ok=True)
+    else:
+        tmp = tempfile.TemporaryDirectory(prefix="ffskill_verify_")
+        outdir = Path(tmp.name)
+
+    results = []
+    for f in files:
+        info(f"=== {f}")
+        entry: Dict = {"file": str(f), "steps": []}
+        try:
+            meta = probe(str(f))
+        except SystemExit:
+            entry["steps"].append({"step": "probe", "ok": False, "seconds": 0, "error": "ffprobe failed"})
+            results.append(entry)
+            continue
+        entry["probe"] = {k: meta.get(k) for k in ("duration", "format")}
+        entry["probe"]["video"] = {k: (meta.get("video") or {}).get(k) for k in ("codec", "width", "height", "fps", "pix_fmt", "hdr_format", "rotation", "variable_frame_rate_suspected")}
+        entry["probe"]["audio"] = {k: (meta.get("audio") or {}).get(k) for k in ("codec", "channels", "sample_rate")}
+        entry["steps"].append({"step": "probe", "ok": True, "seconds": 0, "error": ""})
+        dur = meta.get("duration") or 0.0
+        has_v, has_a = bool(meta.get("video")), bool(meta.get("audio"))
+        stem = outdir / f.stem
+        cut = f"{stem}_cut.mp4"
+        seg_end = min(dur, args.seconds) if dur else args.seconds
+        fast = ["--fast"]
+        plan = []
+        plan.append(("cut copy", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "-o", cut]))
+        if has_v:
+            plan.append(("cut accurate", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "--accurate", "-o", f"{stem}_acc.mp4"] + fast))
+            plan.append(("fit 9:16", ["fit.py", cut, "--aspect", "9:16", "--width", "720", "-o", f"{stem}_fit.mp4"] + fast))
+            cues = outdir / f"{f.stem}_cues.txt"
+            cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")
+            plan.append(("caption", ["caption.py", cut, "--text", str(cues), "--animate", "pop", "--karaoke", "-o", f"{stem}_cap.mp4"] + fast))
+            if not args.quick:
+                plan.append(("overlay text", ["overlay.py", cut, "--text", "verify", "--position", "top-left", "-o", f"{stem}_ovl.mp4"] + fast))
+                plan.append(("look sheet", ["look.py", cut, "-o", f"{stem}_sheet.png"]))
+                if (meta.get("video") or {}).get("hdr"):
+                    plan.append(("color to-sdr", ["color.py", cut, "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
+                plan.append(("probe analyze", ["probe.py", cut, "--analyze"]))
+            plan.append(("export x", ["export.py", cut, "--preset", "x", "-o", f"{stem}_x.mp4"]))
+        if has_a and not args.quick:
+            plan.append(("loudness measure", ["loudness.py", str(f), "--measure-only"]))
+            plan.append(("silence list", ["silence.py", cut, "--list"]))
+            if (meta.get("audio") or {}).get("channels", 0) > 2:
+                plan.append(("audio downmix", ["audio.py", cut, "--downmix", "-o", f"{stem}_st.mp4"]))
+        for name, argv in plan:
+            r = step(name, argv, args.timeout)
+            entry["steps"].append(r)
+            info(f"  {'PASS' if r['ok'] else 'FAIL'}  {name:16s} {r['seconds']:6.1f}s  {r['error']}")
+        results.append(entry)
+
+    total = sum(len(e["steps"]) for e in results)
+    failed = sum(1 for e in results for s in e["steps"] if not s["ok"])
+    lines = ["# ffmpeg-skill verification", "", f"{len(files)} files, {total} steps, {failed} failed", ""]
+    for e in results:
+        p = e.get("probe", {})
+        v, a = p.get("video", {}), p.get("audio", {})
+        lines.append(f"## {e['file']}")
+        lines.append(f"{p.get('duration')}s, {v.get('codec')} {v.get('width')}x{v.get('height')} @ {v.get('fps')} {v.get('pix_fmt')}"
+                     + (f" [{v.get('hdr_format')}]" if v.get("hdr_format") else "") + (" [VFR?]" if v.get("variable_frame_rate_suspected") else "")
+                     + (f" rot {v.get('rotation')}" if v.get("rotation") else "") + f", audio {a.get('codec')} {a.get('channels')}ch")
+        lines.append("")
+        lines.append("| step | result | time | error |")
+        lines.append("|---|---|---|---|")
+        for s in e["steps"]:
+            lines.append(f"| {s['step']} | {'PASS' if s['ok'] else 'FAIL'} | {s['seconds']}s | {s['error']} |")
+        lines.append("")
+    report = "\n".join(lines)
+    if args.report:
+        Path(args.report).write_text(report, encoding="utf-8")
+        info(f"wrote {args.report}")
+    if args.json:
+        emit(None, report=args.report, files=results, failed=failed, total=total)
+    else:
+        print(report)
+    if tmp and not args.keep:
+        tmp.cleanup()
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())