ffmpeg-skill 0.8.5 → 0.10.0

package/scripts/fit.py

@@ -4,14 +4,22 @@
 Duration: --duration N with --method speed (retime video+audio, pitch-preserving
 via atempo chaining) or --method trim (keep the first N seconds, or a centred
 window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
---fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop
-(centre crop). --width sets the output width; height follows the aspect.
+--fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop.
+--width sets the output width; height follows the aspect.
+
+Crop keeps the centre of the frame by default, which is a guess: going from
+16:9 to 9:16 throws away most of the width, and whatever isn't in the middle
+third (a person at the edge, a product held to one side) is cut off. Say what
+to keep with --crop-x / --crop-y (0=left/top, 0.5=centre, 1=right/bottom, or
+a decimal in between) rather than accepting the default silently when the
+subject isn't centred; --fit pad never loses anything if you don't know yet.
 
 Examples:
   python3 fit.py input.mp4 --duration 60                    # speed up/down to exactly 60s
   python3 fit.py input.mp4 --duration 30 --method trim
   python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
   python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
+  python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1   # keep the right edge (e.g. product held stage-right)
 """
 import argparse
 import math
@@ -70,6 +78,8 @@ def main() -> int:
     a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")
     a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect)")
     a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
+    a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")
+    a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")
     e = ap.add_argument_group("encoding")
     e.add_argument("--crf", type=int, default=18)
     e.add_argument("--preset", default="medium")
@@ -80,6 +90,10 @@ def main() -> int:
 
     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")
+    if not 0.0 <= args.crop_x <= 1.0:
+        die(f"--crop-x must be 0..1, got {args.crop_x}")
+    if not 0.0 <= args.crop_y <= 1.0:
+        die(f"--crop-y must be 0..1, got {args.crop_y}")
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -138,7 +152,7 @@ def main() -> int:
         out_h = even(out_w / ratio)
         if args.fit == "crop":
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
-            vf.append(f"crop={out_w}:{out_h}")
+            vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
         else:
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")
             vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")

package/scripts/join.py

@@ -5,19 +5,81 @@ 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.
 
+Audio-only inputs (WAV, FLAC, MP3, M4A, ...) are joined as audio: every clip is
+resampled to one rate and channel layout (the first clip's rate, the widest
+layout; --sample-rate / --channels override), crossfaded with acrossfade or
+butted with concat, and written in the codec the output extension names. The
+output of an audio join must be an audio extension; mixing audio and video
+inputs is refused.
+
 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
+  python3 join.py intro.wav talk.m4a outro.wav -o episode.flac            # audio join, 0.5 s crossfade
+  python3 join.py part1.wav part2.wav --transition none -o full.wav       # butt join, sample rate of part1
 """
 import argparse
 import sys
 from typing import List
 
-from _common import STATE, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
+from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
+LAYOUTS = {1: "mono", 2: "stereo", 6: "5.1", 8: "7.1"}
+
+
+def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
+    """Concatenate audio-only inputs: one sample rate, one channel layout, acrossfade or concat."""
+    n = len(args.inputs)
+    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 and not STATE["dry_run"]:
+            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
+    rates = [m["audio"].get("sample_rate") or 48000 for m in metas]
+    chans = [m["audio"].get("channels") or 2 for m in metas]
+    rate = args.sample_rate or rates[0]
+    channels = args.channels or max(chans)
+    layout = LAYOUTS.get(channels)
+    if layout is None:
+        die(f"{channels}-channel output has no standard layout here (1, 2, 6 or 8); pass --channels")
+    if len(set(rates)) > 1:
+        info(f"sample rates differ ({', '.join(str(r) for r in rates)} Hz); resampling every clip to {rate} Hz")
+    if len(set(chans)) > 1:
+        info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
+    output = args.output or default_output(args.inputs[0], "joined")
+    if not is_audio_output(output):
+        die(f"audio-only inputs cannot fill a video container: give -o an audio extension (.wav, .flac, .mp3, .m4a, .ogg, .opus), not {output}")
+
+    cmd = ffmpeg_base()
+    for p in args.inputs:
+        cmd += ["-i", p]
+    parts = [f"[{i}:a:0]aformat=sample_rates={rate}:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]" for i in range(n)]
+    if args.transition == "none":
+        parts.append("".join(f"[a{i}]" for i in range(n)) + f"concat=n={n}:v=0:a=1[aout]")
+    else:
+        prev = "a0"
+        for i in range(1, n):
+            out = f"ax{i}" if i < n - 1 else "aout"
+            parts.append(f"[{prev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{out}]")
+            prev = out
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[aout]", "-vn"] + audio_codec_for(output) + [output]
+    run(cmd)
+    expected = sum(durs) - d * (n - 1)
+    r = probe(output)
+    a = r.get("audio") or {}
+    if not STATE["dry_run"]:
+        if r.get("video"):
+            die(f"{output} unexpectedly contains a video stream")
+        if a.get("sample_rate") != rate or a.get("channels") != channels:
+            die(f"{output} is {a.get('sample_rate')} Hz {a.get('channels')} ch, expected {rate} Hz {channels} ch")
+    info(f"wrote {output} ({r['duration']:.3f}s, expected ~{expected:.3f}s, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
+         + ("crossfade" if d else "butt join") + ")")
+    emit(output, mode="audio", clips=n, transition=args.transition if d else "none", expected_duration=round(expected, 3),
+         sample_rate=rate, channels=channels, video=False)
+    return 0
 
 
 def main() -> int:
@@ -33,6 +95,9 @@ def main() -> int:
     ap.add_argument("--pad-color", default="black")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
+    aud = ap.add_argument_group("audio-only inputs")
+    aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
+    aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -40,9 +105,15 @@ def main() -> int:
     if len(args.inputs) < 2:
         die("give at least two clips")
     metas = [probe(p) for p in args.inputs]
+    if all(not m.get("video") for m in metas):
+        for p, m in zip(args.inputs, metas):
+            if not m.get("audio"):
+                die(f"{p} has neither a video nor an audio stream")
+        return join_audio(args, metas)
     for p, m in zip(args.inputs, metas):
         if not m.get("video"):
-            die(f"{p} has no video stream")
+            others = [q for q, mm in zip(args.inputs, metas) if mm.get("video")]
+            die(f"{p} has no video stream" + (f" while {others[0]} has one; join audio with audio or give every clip a picture" if others else ""))
     first = metas[0]["video"]
     fw, fh = first["width"], first["height"]
     if first.get("rotation") in (90, -90, 270, -270):
@@ -111,7 +182,7 @@ def main() -> int:
     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))
+    emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3))
     return 0
 
 

package/scripts/multicam.py

@@ -11,6 +11,14 @@ Switch list format: "START-END:CAM,START-END:CAM,..." with times on the
 reference timeline (seconds or mm:ss) and CAM = input index (0 = reference).
 Gaps fall back to camera 0.
 
+Each camera's `confidence` (in the report, and warned on stderr below 0.1)
+is how well its audio matched the reference's, not a guarantee the cut lands
+in sync: a source with no shared audio event (music-only vs. a silent room,
+or two rooms recording different conversations) can score low and still get
+an offset applied. Check it before trusting a low-confidence multicam edit.
+This aligns audio tracks to each other, the same as sync.py, and does not
+check lip sync (mouth movement vs. audio) at all -- see sync.py's docstring.
+
 Examples:
   python3 multicam.py camA.mp4 camB.mp4 --offsets-only                    # just report the offsets
   python3 multicam.py camA.mp4 camB.mp4 --switch "0-12:0,12-30:1,30-45:0" -o edit.mp4
@@ -108,6 +116,8 @@ def main() -> int:
         ratios.append(ratio)
         conf.append(score)
         info(f"{p}: offset {off:+.3f}s (confidence {score:.2f})" + (f", drift {(ratio - 1) * 1e6:+.0f} ppm" if args.fix_drift else ""))
+        if score < 0.1:
+            info(f"warning: {p} has low correlation confidence ({score:.2f}); check that it shares an audio event with the reference before trusting this offset")
 
     report = {"inputs": args.inputs, "offsets_seconds": [round(o, 4) for o in offsets],
               "confidence": [round(c, 3) for c in conf]}

package/scripts/overlay.py

@@ -165,6 +165,11 @@ def main() -> int:
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
         fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
         cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a:0?", "-shortest"]
+        # -shortest alone is not exact on FFmpeg 7+: the muxer keeps up to shortest_buf_duration (10 s)
+        # of the looped still after the video ended, and the file came out 2 s long on 8.1 / 9.0.
+        # The output must be as long as the main input, so say so explicitly.
+        if meta.get("duration"):
+            cmd += ["-t", f"{meta['duration']:.3f}"]
     else:
         x, y = position_exprs(args.position, args.margin, text_mode=True)
         opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",

package/scripts/render.py

@@ -36,6 +36,12 @@ graphics → overlays → audio → loudness → export → check. Missing stage
 skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
 
+"check" mirrors check.py's own exit code: a delivery-spec FAIL (or check.py
+itself failing to run) exits 1, same as running check.py directly would --
+the render is not silently reported as successful just because every stage
+up to it completed. The output file is still written and `--json`'s
+`check` field still carries the full row-by-row result either way.
+
 Examples:
   python3 render.py --init project.json          # write a commented starter project
   python3 render.py project.json                 # render
@@ -338,14 +344,19 @@ def main() -> int:
     # ---- check
     ck = proj.get("check")
     check_result = None
+    exit_code = 0
     if ck and ck.get("platform") and not STATE["dry_run"]:
         proc = subprocess.run([sys.executable, str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
         try:
             check_result = json.loads(proc.stdout)
         except ValueError:
             check_result = {"error": proc.stderr.strip()[-300:]}
-        if check_result.get("failed"):
+        if check_result.get("error"):
+            info(f"check: could not run check.py — {check_result['error']}")
+            exit_code = 1
+        elif check_result.get("failed"):
             info(f"check: {check_result['failed']} FAIL — " + "; ".join(f"{r['check']}={r['value']} ({r['fix']})" for r in check_result["checks"] if r["status"] == "FAIL"))
+            exit_code = 1
         else:
             info(f"check: OK for {ck['platform']}")
         stages_done.append("check")
@@ -355,7 +366,7 @@ def main() -> int:
         shutil.rmtree(work, ignore_errors=True)
     info(f"rendered {output} via {' → '.join(stages_done)}")
     emit(output, stages=stages_done, check=check_result)
-    return 0
+    return exit_code
 
 
 if __name__ == "__main__":

package/scripts/report.py

@@ -19,7 +19,7 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import add_common, apply_common, die, emit, info, probe
+from _common import STATE, add_common, apply_common, die, emit, info, probe
 
 HERE = Path(__file__).resolve().parent
 
@@ -150,8 +150,11 @@ def main() -> int:
     .foot{color:var(--ink2);font-size:12px;margin-top:36px;border-top:1px solid var(--line);padding-top:10px}
     """
     doc = f"<!doctype html><html><head><meta charset='utf-8'><meta name='viewport' content='width=device-width,initial-scale=1'><title>{html.escape(title)}</title><style>{css}</style></head><body><div class='wrap'>{''.join(parts)}</div></body></html>"
-    Path(output).write_text(doc, encoding="utf-8")
-    info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
+    if STATE.dry_run:
+        info(f"wrote {output}")  # printed as "[dry-run] would write"; nothing is written
+    else:
+        Path(output).write_text(doc, encoding="utf-8")
+        info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
     emit(None, report=output, check=chk)
     if not args.json:
         print(output)

package/scripts/scenes.py

@@ -3,14 +3,19 @@
 agent can plan an edit or a digest without watching the whole file.
 
 Scene cuts come from ffmpeg's scdet; energy peaks from a 0.5 s RMS envelope
-of the audio. Highlight candidates are the scenes ranked by audio energy
-(and, optionally, by motion).
+of the audio. Highlight candidates are scenes ranked by --rank-by: "audio"
+(default, loudest first) or "duration" (longest first). Both are proxies,
+not a judgement of what matters: "audio" misses a quiet but important
+moment (a confession, a punchline landing in silence) and can surface pure
+crowd noise; "duration" just finds long unbroken takes. Neither replaces
+watching the contact sheet (--sheet) before committing to a cut.
 
 Examples:
   python3 scenes.py talk.mp4                                # scenes + peaks, JSON
   python3 scenes.py event.mp4 --highlights 5 --target 60   # 5 candidate ranges summing to ~60 s
   python3 scenes.py event.mp4 --highlights 4 --edl picks.txt   # cut.py --segments compatible list
   python3 scenes.py event.mp4 --sheet scenes.png             # one thumbnail per scene
+  python3 scenes.py talk.mp4 --highlights 5 --rank-by duration  # longest unbroken scenes, not loudest
 """
 import argparse
 import math
@@ -96,6 +101,8 @@ def main() -> int:
     ap.add_argument("--ratio", type=float, default=3.0, help="a cut must exceed this multiple of the neighbouring frames' median score (default 3; lower = more cuts)")
     ap.add_argument("--min-scene", type=float, default=1.0, help="ignore cuts closer than this in seconds (default 1)")
     ap.add_argument("--highlights", type=int, default=0, help="number of highlight ranges to propose")
+    ap.add_argument("--rank-by", choices=["audio", "duration"], default="audio",
+                    help="how to rank scenes for --highlights: audio energy (default) or scene duration")
     ap.add_argument("--target", type=float, help="with --highlights: total seconds the picks should add up to (trims long scenes)")
     ap.add_argument("--max-scene", type=float, default=15.0, help="cap a highlight range at this many seconds (default 15)")
     ap.add_argument("--edl", help="write highlight ranges as START-END lines (cut.py --segments format)")
@@ -136,7 +143,11 @@ def main() -> int:
     info(f"{len(scenes)} scenes, {len(peaks)} audio peaks over {dur:.1f}s")
 
     if args.highlights:
-        ranked = sorted(scenes, key=lambda sc: (-sc["audio_rms"], sc["start"]))[: args.highlights]
+        if args.rank_by == "duration":
+            rank_key = lambda sc: (-sc["duration"], sc["start"])
+        else:
+            rank_key = lambda sc: (-sc["audio_rms"], sc["start"])
+        ranked = sorted(scenes, key=rank_key)[: args.highlights]
         picks: List[Tuple[float, float]] = []
         budget = args.target if args.target else None
         per = (budget / max(1, len(ranked))) if budget else args.max_scene
@@ -156,6 +167,7 @@ def main() -> int:
         picks.sort()
         result["highlights"] = [{"start": s, "end": e, "duration": round(e - s, 2)} for s, e in picks]
         result["highlights_total"] = round(sum(e - s for s, e in picks), 2)
+        result["highlights_rank_by"] = args.rank_by
         info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
         if args.edl:
             with open(args.edl, "w", encoding="utf-8") as fh:

package/scripts/sync.py

@@ -9,6 +9,14 @@ Python (coarse, 20 ms), then refined by direct correlation at 1 ms.
 Offset semantics: a positive offset means the SECOND input starts LATER
 than the reference, i.e. `second` must be shifted earlier by that amount.
 
+This aligns two AUDIO tracks to each other; it does not check or guarantee
+lip sync (mouth movement matching the audio). It assumes each recording's
+own audio is already correctly timed against its own picture, which holds
+for ordinary cameras and phones (same device, same clock) but not for a
+capture device with its own internal audio/video offset. There is no
+face or mouth detection anywhere in this codebase to verify that; the only
+way to confirm the final result actually looks in sync is to watch it.
+
 Examples:
   python3 sync.py camera.mp4 lavmic.wav                       # print offset only
   python3 sync.py camera.mp4 lavmic.wav --replace-audio -o synced.mp4