ffmpeg-skill 2.10.5 → 2.10.6

package/bin/install.js

@@ -41,21 +41,39 @@ if (has('--help') || has('-h')) {
   process.exit(0);
 }
 
-// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
-if (args[0] === 'contract' || args[0] === 'doctor') {
-  // Windows Python installers commonly expose `python`/`py`, not `python3` (only the
-  // Microsoft Store package does); try python3 first (macOS/Linux convention), then fall
-  // back so `npx ffmpeg-skill doctor` doesn't silently fail with ENOENT on Windows.
-  const candidates = process.platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
-  let py;
+// Windows Python installers commonly expose `python`/`py`, not `python3`. The Microsoft Store
+// app-execution alias is a real python3.exe that spawns (no ENOENT) and exits non-zero, so a
+// missing `error` is not proof an interpreter ran. Probe with a version check, then fall through.
+const PYTHON_PROBE = ['-c', 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'];
+
+function pythonCandidates(platform) {
+  return platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
+}
+
+function runWithPython(scriptArgs, platform, spawn) {
+  const candidates = pythonCandidates(platform);
+  const run = spawn || spawnSync;
+  let last = null;
   for (const cmd of candidates) {
-    py = spawnSync(cmd, [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
-    if (!py.error) break;
+    const probe = run(cmd, PYTHON_PROBE, { stdio: 'ignore', timeout: 15000 });
+    if (probe.error || probe.status !== 0) {
+      last = probe;
+      continue;
+    }
+    return run(cmd, scriptArgs, { stdio: 'inherit' });
   }
-  if (py.error) {
-    console.error(`error: could not find a Python interpreter (tried: ${candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+  return { missing: true, error: last && last.error, status: last && last.status, candidates };
+}
+
+function main() {
+// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
+if (args[0] === 'contract' || args[0] === 'doctor') {
+  const py = runWithPython([path.join(ROOT, 'scripts', '_contract.py'), ...args], process.platform, spawnSync);
+  if (py.missing) {
+    console.error(`error: could not find a Python 3.9+ interpreter (tried: ${py.candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+    process.exit(127);
   }
-  process.exit(py.error ? 127 : py.status);
+  process.exit(py.error ? 127 : (py.status == null ? 1 : py.status));
 }
 
 const home = os.homedir();
@@ -159,3 +177,10 @@ if (!has('--uninstall')) {
   console.log('\nDone. Ask your agent things like "make this video 60 seconds and add captions".');
 }
 process.exit(failed ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { pythonCandidates, runWithPython };

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.10.5`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.6`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.10.5", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.6", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},

package/mcp/server.py

@@ -21,7 +21,7 @@ import os
 import subprocess
 import sys
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 HERE = Path(__file__).resolve().parent
 SCRIPTS = HERE.parent / "scripts"
@@ -90,18 +90,66 @@ def build_argv(name: str, args: Dict[str, Any]) -> List[str]:
     return argv
 
 
+def _timeout_in_argv(argv: List[str]) -> Optional[float]:
+    """The last `--timeout` / `--timeout=N` value in a raw argv list.
+
+    None when the flag is absent or its value is not a number (the child argparse then fails,
+    and the outer ceiling stays the environment default)."""
+    found: Optional[float] = None
+    seen = False
+    i = 0
+    n = len(argv)
+    while i < n:
+        token = argv[i]
+        if token == "--":
+            break
+        if token == "--timeout":
+            if i + 1 >= n:
+                return None
+            raw = argv[i + 1]
+            i += 2
+        elif token.startswith("--timeout="):
+            raw = token.split("=", 1)[1]
+            i += 1
+        else:
+            i += 1
+            continue
+        seen = True
+        try:
+            found = float(raw)
+        except ValueError:
+            return None
+    return found if seen else None
+
+
+def timeout_from_call(args: Dict[str, Any]) -> float:
+    """Per-call seconds for the MCP outer ceiling.
+
+    Structured `timeout` is the canonical key. A raw `argv` list ignores every other key, so
+    `--timeout` has to be read from that list: `--timeout 0` otherwise left the ceiling at 4x
+    the 1800 s default while the child itself ran with no limit. A negative value is 0, matching
+    apply_common (0 means no limit)."""
+    if isinstance(args.get("argv"), list):
+        parsed = _timeout_in_argv([str(a) for a in args["argv"]])
+        if parsed is None:
+            return _common._env_timeout()
+        return max(0.0, parsed)
+    try:
+        return max(0.0, float(args.get("timeout", _common._env_timeout())))
+    except (TypeError, ValueError):
+        return _common._env_timeout()
+
+
 def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     script = SCRIPTS / f"{name}.py"
     if name not in specs() or not script.exists():
         return {"isError": True, "content": [{"type": "text", "text": f"unknown tool {name}"}]}
     argv = build_argv(name, args or {})
     # The child enforces --timeout on each ffmpeg call; this outer ceiling (4x that plus 60 s)
-    # is the only thing that ends a child hung for any other reason. The caller's own `timeout`
-    # argument sets both; otherwise FFMPEG_SKILL_TIMEOUT / the 1800 s default.
-    try:
-        per_call = float((args or {}).get("timeout", _common._env_timeout()))
-    except (TypeError, ValueError):
-        per_call = _common._env_timeout()
+    # is the only thing that ends a child hung for any other reason. Structured `timeout` or
+    # `--timeout` inside a raw argv list sets both (0 = no limit); otherwise
+    # FFMPEG_SKILL_TIMEOUT / the 1800 s default.
+    per_call = timeout_from_call(args or {})
     proc = _common.run_tool([str(script)] + argv, per_call=per_call)
     stdout = proc.stdout.strip()
     text = stdout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.10.5",
+  "version": "2.10.6",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/scripts.md

@@ -755,10 +755,13 @@ An `overlays[]` entry draws one of `"logo": true`, `"image"`, `"text"` or
 `"video"` (#326: a picture-in-picture or green-screen layer, `overlay.py
 --video`), with `position`, `scale`, `opacity`, `start`, `end`, `margin`,
 `platform` (and `fade`, `box`, `font*` for the still/text kinds) mapping to
-overlay.py's flags. `"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
-`"chromakey_blend"` key a colour out of the video layer. The stage runs after
-`fit`, so `"scale": 480` is 480 px of the delivered frame, and a template's
-safe margins apply as they do to a logo. Refused (`kind: input`) before the
+overlay.py's flags. `scale` is the layer width in px for a logo, image or
+video (`"scale": 480` is 480 px of the delivered frame, because the stage
+runs after `fit`). A text entry's size is `font_size`; `scale` on a text-only
+entry is refused (`kind: input`) rather than drawn at the default font size.
+`"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
+`"chromakey_blend"` key a colour out of the video layer. A template's
+safe margins apply as they do to a logo. Also refused before the
 first stage: `video` together with `logo`/`image`/`text` in one entry (a
 logo, image and text together still draw the first of them, as before), a
 `chromakey*` key without `video`, `chromakey_similarity`/`_blend` without
@@ -1464,7 +1467,9 @@ overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--f
 (`scripts/_platforms.py`), so a template's top-left logo clears TikTok's status bar instead of
 sitting 24 px into it; an explicit `--margin` (or a brand `safe_margin`) wins.
 Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps
-playing. `--video` composites a second video as a picture-in-picture layer
+playing. `--scale` / `--scale-percent` set the width of an image, logo or
+`--video` layer. They are refused with `--text`: text size is `--font-size`.
+`--video` composites a second video as a picture-in-picture layer
 (same position/scale/opacity/time-range knobs as `--image`); only the main
 input's audio is kept, the PiP layer's own audio is dropped. `--chromakey`
 (with `--video`) keys out that colour first for green-screen compositing.

package/scripts/fit.py

@@ -198,7 +198,7 @@ def main() -> int:
             darken = 0.0 if meta["video"].get("bt2020_or_hdr") else BLUR_DARKEN
             if not darken:
                 info("--fit blur: HDR source, so the blurred background is not dimmed "
-                     "(an eq on PQ/HLG code values is not the -15%% dim it is on SDR); "
+                     "(an eq on PQ/HLG code values is not the -15% dim it is on SDR); "
                      "run color.py --to-sdr first for the SDR look")
             vf.append(pad_filters(out_w, out_h, "blur", args.pad_color, args.pad_blur, darken))
         else:

package/scripts/overlay.py

@@ -116,8 +116,8 @@ def main() -> int:
     ap.add_argument("--fade", type=float, default=0.0, help="fade-in duration in seconds (at --start or 0); the fade-out happens only at --end")
     ap.add_argument("--opacity", type=float, default=1.0, help="0..1 (default 1)")
     img = ap.add_argument_group("image options")
-    img.add_argument("--scale", type=int, help="scale the image to this width in px (keeps aspect)")
-    img.add_argument("--scale-percent", type=float, help="scale the image to this %% of the video width")
+    img.add_argument("--scale", type=int, help="width in px for an image, logo or video layer (keeps aspect); text size is --font-size")
+    img.add_argument("--scale-percent", type=float, help="width as a %% of the video for an image, logo or video layer (keeps aspect); text size is --font-size")
     txt = ap.add_argument_group("text options")
     txt.add_argument("--font", default="DejaVu Sans", help="fontconfig font name")
     txt.add_argument("--font-file", help="explicit .ttf/.otf/.ttc path (use this for CJK fonts)")
@@ -158,6 +158,10 @@ def main() -> int:
         die("--text is blank -- give the words to draw", kind="input")
     if not (args.image or args.text or args.video):
         die("give --image, --text, --logo or --video")
+    # --scale is a layer width. On a text draw it used to be accepted and ignored (fontsize stayed
+    # at --font-size), so a project that asked for 200 px text completed with the 42 px default.
+    if args.text and not (args.image or args.video) and (args.scale is not None or args.scale_percent is not None):
+        die("--scale and --scale-percent size an image, logo or video layer; text size is --font-size", kind="input")
     if args.brand:
         if args.margin == ap.get_default("margin"):
             args.margin = int(brand.get("safe_margin", args.margin))

package/scripts/render.py

@@ -40,7 +40,9 @@ skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
 An overlay entry draws one of logo, image, text or video (a picture-in-picture
 layer, overlay.py --video; "chromakey", "chromakey_similarity" and
-"chromakey_blend" key a colour out of that video and need "video").
+"chromakey_blend" key a colour out of that video and need "video"). "scale"
+is that layer's width in px for a logo, image or video; a text entry's size
+is "font_size", and "scale" on a text entry is refused.
 
 "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 --
@@ -436,6 +438,10 @@ def check_overlay(ov: Any, label: str) -> None:
         tuned = [k for k in ("chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
         if tuned:
             die(f"{label}: {tuned[0]} tunes \"chromakey\", which this entry does not set")
+    # scale is a layer width (overlay.py --scale). A text entry that carries it used to complete
+    # with the default font size, because the text branch never reads the flag.
+    if ov.get("text") and not any(ov.get(k) for k in ("logo", "image", "video")) and ov.get("scale") is not None:
+        die(f"{label}: scale sizes an image, logo or video layer; text size is font_size", kind="input")
 
 
 def require_object(obj: Any, label: str) -> None:

package/scripts/speedramp.py

@@ -84,9 +84,14 @@ def main() -> int:
     output = args.output or default_output(args.input, "ramp")
 
     vparts, aparts, labels = [], [], []
+    # The coverage check above allows the last end to sit up to 0.5 s off the probed duration.
+    # That slack is for a caller who rounded the duration, not a reason to redraw the tail at
+    # the last factor. The end bound is omitted only when the stated end is the file's end
+    # (within 50 ms): a trim a few milliseconds short of the last packet drops that packet.
+    last_runs_to_eof = abs(segments[-1][1] - dur) <= 0.05
     for i, (start, end, factor) in enumerate(segments):
         vlabel, alabel = f"v{i}", f"a{i}"
-        end_expr = f"{end:.3f}" if i < len(segments) - 1 else None
+        end_expr = f"{end:.3f}" if not (i == len(segments) - 1 and last_runs_to_eof) else None
         trim = f"trim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
         vparts.append(f"[0:v]{trim},setpts=(PTS-STARTPTS)/{factor:.6f}[{vlabel}]")
         labels.append(f"[{vlabel}]")

package/scripts/sync.py

@@ -36,6 +36,17 @@ from _common import video_args, add_common, apply_common, emit, aac_args, audio_
 
 SR = 8000  # decode sample rate
 
+
+def sync_meaning(offset: float) -> str:
+    """The sentence a caller reads next to offset_seconds.
+
+    A zero offset used to take the else branch of `later if offset > 0` and say the second
+    file starts earlier. Values that print as 0.000 s (under half a millisecond) say the two
+    recordings start together; anything larger keeps later/earlier."""
+    if abs(offset) < 5e-4:
+        return "second starts together with the reference"
+    return "second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")
+
 # 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):
 #
@@ -307,7 +318,7 @@ def main() -> int:
             "second": args.second,
             "offset_seconds": offset,
             "confidence": score,
-            "meaning": ("second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")),
+            "meaning": sync_meaning(offset),
             "sources": sources_block,
         }
         if drift_info: