ffmpeg-skill 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: MCP server, batch processing, declarative project rendering, brand kits, motion-graphics templates, HTML delivery reports, scene detection, delivery checks, cut, silence removal, transitions, multicam, 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",

package/scripts/_common.py

@@ -37,6 +37,9 @@ def die(msg: str, code: int = 1) -> "None":
 
 
 def info(msg: str) -> None:
+    # under --dry-run nothing is written; do not let scripts claim otherwise
+    if msg.startswith("wrote ") and STATE.dry_run:
+        msg = "[dry-run] would write " + msg[len("wrote "):]
     sys.stderr.write(f"{msg}\n")
 
 
@@ -56,7 +59,46 @@ def require_tool(name: str) -> str:
 
 
 X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
-STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": [], "progress": False, "fast": False, "duration_hint": None}
+
+
+class Context:
+    """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
+
+    Scripts read it as attributes (``STATE.dry_run``) or, for older call sites, like a dict
+    (``STATE["dry_run"]``). Keeping it a single explicit object rather than module globals makes
+    it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
+    """
+
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
+    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
+
+    def __init__(self) -> None:
+        self.reset()
+
+    def reset(self) -> None:
+        self.dry_run = False      # print ffmpeg commands, run nothing (ffprobe still runs)
+        self.json = False         # emit() prints a JSON document instead of the output path
+        self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
+        self.fast = False         # x264 preset forced to veryfast
+        self.duration_hint: Optional[float] = None  # expected output length, for the progress percent
+        self.commands: List[str] = []               # every ffmpeg command line, for --json and --dry-run
+
+    # mapping-style access kept for backwards compatibility
+    def __getitem__(self, key: str) -> Any:
+        if key not in self._KEYS:
+            raise KeyError(key)
+        return getattr(self, key)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if key not in self._KEYS:
+            raise KeyError(key)
+        setattr(self, key, value)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return getattr(self, key, default) if key in self._KEYS else default
+
+
+STATE = Context()
 
 
 def add_common(ap: "argparse.ArgumentParser") -> None:
@@ -69,19 +111,19 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
 
 
 def apply_common(args: "argparse.Namespace") -> None:
-    STATE["dry_run"] = bool(getattr(args, "dry_run", False))
-    STATE["json"] = bool(getattr(args, "json", False))
-    STATE["progress"] = bool(getattr(args, "progress", False))
-    STATE["fast"] = bool(getattr(args, "fast", False))
-    if STATE["fast"] and getattr(args, "preset", None) in X264_PRESETS:
+    STATE.dry_run = bool(getattr(args, "dry_run", False))
+    STATE.json = bool(getattr(args, "json", False))
+    STATE.progress = bool(getattr(args, "progress", False))
+    STATE.fast = bool(getattr(args, "fast", False))
+    if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
 
 
 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):
+    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)
@@ -89,32 +131,58 @@ def emit(output: Optional[str], **extra: Any) -> None:
         print(output)
 
 
+def _cmdline(cmd: Sequence[str]) -> str:
+    return " ".join(shell_quote(c) for c in cmd)
+
+
+def _is_ffmpeg(cmd: Sequence[str]) -> bool:
+    return os.path.basename(cmd[0]).startswith("ffmpeg")
+
+
+def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
+    tail = "\n".join(stderr.strip().splitlines()[-15:])
+    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1)
+
+
 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.
 
-    With --dry-run, ffmpeg invocations are printed and skipped (ffprobe still runs so
-    scripts can plan); a fake successful CompletedProcess is returned.
+    ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
+    (a fake successful CompletedProcess is returned so scripts can keep planning), and run
+    with a progress readout under --progress. ffprobe and other tools always run.
     """
-    is_ffmpeg = os.path.basename(cmd[0]).startswith("ffmpeg")
+    is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
-        STATE["commands"].append(" ".join(shell_quote(c) for c in cmd))
+        STATE.commands.append(_cmdline(cmd))
     if not quiet:
-        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:
+        info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
+    if STATE.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
-    if STATE["progress"] and is_ffmpeg and cmd[-1] != "-":
+    if STATE.progress and is_ffmpeg and cmd[-1] != "-":
         return _run_with_progress(list(cmd), check)
+    return _run_captured(list(cmd), check)
+
+
+def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
+    """Plain run with stdout/stderr captured."""
     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:])
-        die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
+        _fail(cmd, proc.returncode, proc.stderr)
     return proc
 
 
+def _progress_line(done: float, total: float, elapsed: float) -> str:
+    if total > 0:
+        pct = min(99.9, done / total * 100)
+        eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
+        return f"\r  {pct:5.1f}%  {done:7.1f}s / {total:.1f}s  ETA {eta:4.0f}s"
+    return f"\r  {done:7.1f}s encoded"
+
+
 def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr."""
     import time
-    total = STATE.get("duration_hint") or 0.0
+    total = STATE.duration_hint or 0.0
     full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
     t0 = time.time()
     proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -126,13 +194,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
                 done = int(line.split("=")[1]) / 1_000_000
             except ValueError:
                 continue
-            if total > 0:
-                pct = min(99.9, done / total * 100)
-                elapsed = time.time() - t0
-                eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
-                msg = f"\r  {pct:5.1f}%  {done:7.1f}s / {total:.1f}s  ETA {eta:4.0f}s"
-            else:
-                msg = f"\r  {done:7.1f}s encoded"
+            msg = _progress_line(done, total, time.time() - t0)
             if msg != last:
                 sys.stderr.write(msg)
                 sys.stderr.flush()
@@ -140,11 +202,9 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
     _, err = proc.communicate()
     if last:
         sys.stderr.write("\r" + " " * len(last) + "\r")
-    result = subprocess.CompletedProcess(full, proc.returncode, "", err)
     if check and proc.returncode != 0:
-        tail = "\n".join(err.strip().splitlines()[-15:])
-        die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
-    return result
+        _fail(cmd, proc.returncode, err)
+    return subprocess.CompletedProcess(full, proc.returncode, "", err)
 
 
 def shell_quote(s: str) -> str:

package/scripts/overlay.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import load_brand, video_args, 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
+from _common import STATE, load_brand, video_args, 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}"),
@@ -150,11 +150,13 @@ def main() -> int:
             chain.append(f"scale={args.scale}:-1")
         if args.opacity < 1:
             chain.append(f"colorchannelmixer=aa={args.opacity:g}")
-        if args.fade > 0 and (start is not None or end is not None):
+        if args.fade > 0:
+            # no --start/--end: fade in at 0 and out at the end of the video
             s = start if start is not None else 0.0
+            e = end if end is not None else (meta.get("duration") or 0.0)
             chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
-            if end is not None:
-                chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
+            if e > args.fade:
+                chain.append(f"fade=t=out:st={e - args.fade:.3f}:d={args.fade:g}:alpha=1")
         x, y = position_exprs(args.position, args.margin, text_mode=False)
         ov = f"overlay={x}:{y}:format=auto"
         if enable:
@@ -171,7 +173,8 @@ def main() -> int:
             opts.append(f"fontfile={escape_filter_path(args.font_file)}")
         else:
             opts.append(f"font='{args.font}'")
-        alpha = alpha_expr(args.opacity, start, end, args.fade)
+        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None),
+                           end if end is not None else ((meta.get("duration") or None) if args.fade > 0 else None), args.fade)
         opts.append(f"fontcolor={args.font_color}")
         if alpha != "1":
             opts.append(f"alpha='{alpha}'")
@@ -185,8 +188,9 @@ def main() -> int:
     cmd += aac_args() if meta.get("audio") else ["-an"]
     cmd.append(output)
     run(cmd)
-    result = probe(output)
-    info(f"wrote {output} ({result['duration']:.3f}s)")
+    if not STATE.dry_run:
+        result = probe(output)
+        info(f"wrote {output} ({result['duration']:.3f}s)")
     emit(output)
     return 0
 

package/scripts/sync.py

@@ -30,6 +30,22 @@ from _common import video_args, add_common, apply_common, emit, aac_args, audio_
 
 SR = 8000  # decode sample rate
 
+# Scoring constants for coarse alignment. Both come from tests/bench_sync.py on real dialogue and
+# music with +/-30 s offsets, gain, noise and EQ (see evals/results and CHANGELOG 0.8.0):
+#
+# MIN_OVERLAP_FRACTION: lags whose overlap with the other track is shorter than this share of the
+#   shorter track are never candidates. With the documented rule "analysis window >= 4x the largest
+#   expected offset" a true offset keeps >= 75 % overlap, so 0.35 costs nothing there, while the
+#   coincidental peaks on quasi-periodic material (music, tone beds) live below it. Raising it to
+#   0.5 started rejecting true 28 s offsets in 60 s windows; lowering it to 0.2 let the partial
+#   matches back in (86 % -> 95 % of 60 s stress cases fixed by this alone).
+# OVERLAP_WEIGHT_EXP: normalised similarity is multiplied by (overlap fraction) ** exponent so a
+#   perfect match over 55 % of the window cannot tie a perfect match over 100 %. 0.5 keeps a true
+#   75 % overlap at x0.87 and a 53 % one (28 s in 60 s) at x0.73 while a coincidental 40 % match
+#   drops to x0.63; exponent 1.0 over-penalised large true offsets, 0.25 left exact ties.
+MIN_OVERLAP_FRACTION = 0.35
+OVERLAP_WEIGHT_EXP = 0.5
+
 
 def decode_mono(path: str, seconds: float, start: float = 0.0) -> List[float]:
     ffmpeg = require_tool("ffmpeg")
@@ -119,10 +135,7 @@ def cross_correlate(ref: List[float], other: List[float], max_lag: int):
     lr, lo = len(ref), len(other)
     max_lag = min(max_lag, n // 2 - 1)
     best_lag, best_val, second = 0, -float("inf"), -float("inf")
-    # ignore lags with less than 35 % overlap: with the documented rule (analysis window >= 4x the
-    # largest expected offset) true offsets always keep >= 75 % overlap, while short-overlap lags are
-    # where coincidental matches on quasi-periodic material (music, tone beds) live
-    min_overlap = max(10, int(0.35 * min(lr, lo)))
+    min_overlap = max(10, int(MIN_OVERLAP_FRACTION * min(lr, lo)))  # see constants above
     scores = []
     for lag in range(-max_lag, max_lag + 1):
         # corr[lag] = sum_i ref[i] * other[i - lag]  -> ref index range and other index range overlap:
@@ -135,10 +148,8 @@ def cross_correlate(ref: List[float], other: List[float], max_lag: int):
         if denom <= 0:
             continue
         val = corr[lag % n].real / denom
-        # mild preference for longer overlaps: a perfect match over 55 % of the window must not tie
-        # with a perfect match over 100 % (quasi-periodic material). Exponent 0.5: with the window rule (>= 4x offset) a true match keeps >= 75 % overlap (x0.87) while a coincidental 55 % match drops to x0.74; keeps large true
-        # offsets (28 s in 60 s = 53 % overlap -> x0.94) competitive while still breaking exact ties.
-        val *= ((r1 - r0) / min(lr, lo)) ** 0.5
+        val *= ((r1 - r0) / min(lr, lo)) ** OVERLAP_WEIGHT_EXP  # longer overlap wins ties
+
         scores.append((val, lag))
         if val > best_val:
             second = best_val