ffmpeg-skill 0.8.5 → 0.10.0

package/bin/install.js

@@ -12,6 +12,8 @@
  *   npx ffmpeg-skill --dir ./skills  # custom parent directory
  *   npx ffmpeg-skill --project       # ./.claude/skills/ffmpeg-skill in the current project
  *   npx ffmpeg-skill --uninstall     # remove from the selected targets
+ *   npx ffmpeg-skill contract --json # machine-readable execution contract (see docs/contract.md)
+ *   npx ffmpeg-skill doctor [--json] # which required ffmpeg capabilities this machine has
  */
 'use strict';
 
@@ -22,7 +24,7 @@ const { spawnSync } = require('child_process');
 
 const SKILL_NAME = 'ffmpeg-skill';
 const ROOT = path.resolve(__dirname, '..');
-const PAYLOAD = ['SKILL.md', 'scripts', 'references', 'mcp'];
+const PAYLOAD = ['SKILL.md', 'scripts', 'references', 'mcp', 'package.json'];
 
 const args = process.argv.slice(2);
 const has = (flag) => args.includes(flag);
@@ -36,6 +38,12 @@ 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') {
+  const py = spawnSync('python3', [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
+  process.exit(py.error ? 127 : py.status);
+}
+
 const home = os.homedir();
 const targets = [];
 const want = { claude: has('--claude'), cursor: has('--cursor'), codex: has('--codex') };
@@ -69,7 +77,7 @@ function checkFfmpeg() {
   const r = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8' });
   if (r.error || r.status !== 0) {
     console.warn('\n  warning: ffmpeg was not found on PATH. The skill needs FFmpeg to run:');
-    console.warn('    macOS:   brew install ffmpeg');
+    console.warn('    macOS:   brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)');
     console.warn('    Ubuntu:  sudo apt install ffmpeg');
     console.warn('    Windows: winget install Gyan.FFmpeg\n');
     return false;

package/mcp/server.py

@@ -1,8 +1,10 @@
 #!/usr/bin/env python3
 """ffmpeg-skill as an MCP server (stdio, JSON-RPC 2.0) — standard library only.
 
-Every script in ../scripts becomes a tool; arguments are passed as an argv list
-or as a flat object of flags. Results are the script's --json output.
+Every public script in ../scripts becomes a tool. Tool names, order, inputSchema and the
+structured-argument mapping all come from the contract (scripts/_contract.py); this file
+is only the transport. Arguments are passed as a flat object (keys = argparse dests) or,
+for CLI compatibility, as an argv list. Results are the script's --json output.
 
 Run:
   python3 mcp/server.py                         # stdio transport
@@ -20,41 +22,45 @@ HERE = Path(__file__).resolve().parent
 SCRIPTS = HERE.parent / "scripts"
 PROTOCOL_VERSION = "2024-11-05"
 
-TOOLS: Dict[str, str] = {
-    "probe": "Inspect a media file: duration, fps/VFR, resolution, codecs, HDR, rotation, audio. Args: inputs (list), analyze (bool), compact (bool).",
-    "cut": "Cut a range or several segments, lossless when possible. Args: input, start, end, duration, segments, accurate, output.",
-    "fit": "Fit to a duration (speed/trim) and/or aspect (pad/crop). Args: input, duration, method, aspect, fit, width, fps, smooth, output.",
-    "caption": "Burn SRT/ASS or timed text; animated/karaoke styles; brand. Args: input, srt, ass, text, animate, karaoke, font, size, position, brand, output.",
-    "overlay": "Composite a logo/image/text with timing and fade. Args: input, image, text, logo, position, start, end, fade, opacity, scale, brand, output.",
-    "graphics": "Motion-graphics templates: lower-third, title, chapter, progress, countdown, bug. Args: input, template, name, title, subtitle, start, end, brand, output.",
-    "sync": "Detect offset between two recordings by audio, optional drift fix. Args: reference, second, fix_drift, replace_audio, trim_second, output.",
-    "multicam": "Align N cameras/recorders and switch between them. Args: inputs (list), switch, auto, audio, fix_drift, output.",
-    "audio": "Denoise/voice chain, music bed with ducking, fades, downmix, replace. Args: input, voice, denoise, music, duck, music_volume, fade_in, fade_out, downmix, replace, output.",
-    "loudness": "Two-pass EBU R128 normalisation. Args: input, lufs, tp, measure_only, output.",
-    "silence": "Remove dead air / list silences. Args: input, threshold, min_silence, margin, list, edl, output.",
-    "join": "Concatenate clips with transitions, normalising size/fps/audio. Args: inputs (list), transition, duration, width, height, fps, output.",
-    "color": "HDR→SDR tone mapping, LUTs, retag, strip Dolby Vision. Args: input, to_sdr, lut, retag, strip_dovi, tonemap, output.",
-    "export": "Platform presets: youtube, youtube4k, reels, x, prores, h265, gif. Args: input, preset, fit, output.",
-    "check": "Pre-delivery compliance per platform. Args: input, platform, no_loudness.",
-    "scenes": "Scene changes, audio peaks, highlight proposals. Args: input, highlights, target, edl, sheet.",
-    "look": "Contact sheet / frames / before-after PNG for visual checks. Args: input, at (list), tiles, compare, output.",
-    "render": "Render a whole edit from project.json. Args: project, fast, stop_after, init.",
-    "verify": "Run the toolchain on real files and report PASS/FAIL. Args: paths (list), quick, report.",
-    "report": "HTML delivery report. Args: after, before, platform, commands, notes, title, output.",
-}
-POSITIONAL = {"probe": ["inputs"], "sync": ["reference", "second"], "multicam": ["inputs"], "join": ["inputs"], "verify": ["paths"], "render": ["project"]}
+sys.path.insert(0, str(SCRIPTS))
+import _contract  # noqa: E402  (the contract is the only source of tool names, schemas and argument mapping)
+
+_SPECS: Dict[str, Dict[str, Any]] = {}
+
+
+def specs() -> Dict[str, Dict[str, Any]]:
+    """ToolSpecs from the contract, generated once per process (argparse -> ToolSpec -> here)."""
+    if not _SPECS:
+        for spec in _contract.build(detect=False)["tools"]:
+            _SPECS[spec["name"]] = spec
+    return _SPECS
+
+
+class _Positional(dict):
+    """Positional argument names per tool, read from the contract (kept as a mapping for compatibility)."""
+
+    def __missing__(self, name: str) -> List[str]:
+        return list(specs()[name]["mcp"]["positional"]) if name in specs() else ["input"]
+
+    def get(self, name: str, default: Any = None) -> Any:  # type: ignore[override]
+        return self[name] if name in specs() else default
+
+
+POSITIONAL: Dict[str, List[str]] = _Positional()
 
 
 def build_argv(name: str, args: Dict[str, Any]) -> List[str]:
+    """Structured arguments -> argv, using the mapping the contract states (invocation.structured)."""
     if isinstance(args.get("argv"), list):
         argv = [str(a) for a in args["argv"]]
-        if name not in ("look", "probe") and "--json" not in argv and "--help" not in argv:
+        if name not in _contract.MCP_JSON_EXEMPT and "--json" not in argv and "--help" not in argv:
             argv.append("--json")
         return argv
+    spec = specs().get(name)
+    exceptions = spec["mcp"]["argument_exceptions"] if spec else {}
     argv: List[str] = []
     args = dict(args)
-    pos = POSITIONAL.get(name, ["input"])
-    for key in pos:
+    for key in POSITIONAL[name]:
         val = args.pop(key, None)
         if val is None:
             continue
@@ -65,11 +71,7 @@ def build_argv(name: str, args: Dict[str, Any]) -> List[str]:
     for key, val in args.items():
         if val is None or val is False:
             continue
-        flag = "--" + key.replace("_", "-")
-        if key == "output":
-            flag = "-o"
-        if key == "lufs" and name == "loudness":
-            flag = "-I"
+        flag = exceptions.get(key, "--" + key.replace("_", "-"))
         if val is True:
             argv.append(flag)
         elif isinstance(val, list):
@@ -77,14 +79,14 @@ def build_argv(name: str, args: Dict[str, Any]) -> List[str]:
                 argv += [flag, str(v)]
         else:
             argv += [flag, str(val)]
-    if name not in ("look", "probe") and "--json" not in argv and "--help" not in argv:
+    if name not in _contract.MCP_JSON_EXEMPT and "--json" not in argv and "--help" not in argv:
         argv.append("--json")
     return argv
 
 
 def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     script = SCRIPTS / f"{name}.py"
-    if not script.exists():
+    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 {})
     proc = subprocess.run([sys.executable, str(script)] + argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -108,14 +110,8 @@ def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def tool_list() -> List[Dict[str, Any]]:
-    out = []
-    for name, desc in TOOLS.items():
-        out.append({
-            "name": name,
-            "description": desc + " Pass either named args (flags without dashes, underscores for hyphens) or argv (raw CLI list). Media paths must be absolute.",
-            "inputSchema": {"type": "object", "properties": {"argv": {"type": "array", "items": {"type": "string"}, "description": "raw CLI arguments"}}, "additionalProperties": True},
-        })
-    return out
+    """tools/list: one entry per ToolSpec, in the contract's order, inputSchema derived from ToolSpec.input_schema."""
+    return [_contract.mcp_tool(spec) for spec in specs().values()]
 
 
 def handle(req: Dict[str, Any]) -> Dict[str, Any]:
@@ -142,7 +138,7 @@ def version() -> str:
 def main() -> int:
     if "--list" in sys.argv:
         for t in tool_list():
-            print(f"{t['name']:10s} {t['description'].split(' Pass either')[0]}")
+            print(f"{t['name']:10s} {t['description'].split(' Structured arguments:')[0]}")
         return 0
     if "--call" in sys.argv:  # debugging helper: --call NAME '{"input": "..."}'
         i = sys.argv.index("--call")

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.8.5",
-  "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"],
+  "version": "0.10.0",
+  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 21 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",
+    "video",
+    "video-editing",
+    "video-processing",
+    "audio",
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp",
+    "skill"
+  ],
   "license": "MIT",
   "author": "kajisho5",
   "repository": {
@@ -24,9 +36,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "python3 tests/test_all.py",
+    "test": "python3 tests/test_all.py && python3 tests/test_contract.py",
     "release-check": "bash tests/release_check.sh",
-    "demo": "bash examples/make_demo.sh"
+    "demo": "bash examples/make_demo.sh",
+    "contract": "python3 scripts/_contract.py --json",
+    "doctor": "python3 scripts/_contract.py doctor"
   },
   "engines": {
     "node": ">=16"

package/scripts/_common.py

@@ -16,8 +16,18 @@ from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence
 
+# Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,
+# arrows). On Windows the console streams default to a legacy code page and raise
+# UnicodeEncodeError; make them UTF-8 with replacement so a --help never crashes on encoding.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
 INSTALL_HINTS = {
-    "Darwin": "  brew install ffmpeg",
+    "Darwin": "  brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
     "Linux": (
         "  Debian/Ubuntu: sudo apt install ffmpeg\n"
         "  Fedora:        sudo dnf install ffmpeg\n"
@@ -31,8 +41,12 @@ INSTALL_HINTS = {
 }
 
 
-def die(msg: str, code: int = 1) -> "None":
+def die(msg: str, code: int = 1, kind: str = "input") -> "None":
+    """Exit with a message. Under --json also print a machine-readable failure document
+    (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged."""
     sys.stderr.write(f"error: {msg}\n")
+    if STATE.json:
+        print_json({"status": "failed", "error": {"kind": kind, "message": msg}})
     sys.exit(code)
 
 
@@ -53,7 +67,7 @@ def require_tool(name: str) -> str:
     die(
         f"'{name}' was not found on PATH.\n"
         f"Install FFmpeg (which includes ffprobe) for {system}:\n{hint}",
-        code=127,
+        code=127, kind="missing_tool",
     )
     return ""  # unreachable
 
@@ -122,7 +136,7 @@ def apply_common(args: "argparse.Namespace") -> None:
 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)}
+        doc: Dict[str, Any] = {"status": "completed", "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)
@@ -141,7 +155,7 @@ def _is_ffmpeg(cmd: Sequence[str]) -> bool:
 
 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)
+    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1, kind="ffmpeg")
 
 
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
@@ -318,6 +332,16 @@ def probe(path: str) -> Dict[str, Any]:
             "sample_rate": _to_int(audio.get("sample_rate")),
             "bitrate": _to_int(audio.get("bit_rate")),
         }
+        # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
+        out["audio_streams"] = [{
+            "index": n,
+            "codec": a.get("codec_name"),
+            "channels": _to_int(a.get("channels")),
+            "channel_layout": a.get("channel_layout"),
+            "sample_rate": _to_int(a.get("sample_rate")),
+            "language": (a.get("tags") or {}).get("language"),
+            "title": (a.get("tags") or {}).get("title"),
+        } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
     return out
 
 
@@ -352,10 +376,21 @@ def fmt_srt_time(seconds: float) -> str:
 
 
 def escape_filter_path(path: str) -> str:
-    """Escape a path for use inside an ffmpeg filter graph option value."""
+    """Escape a file path for use as a filter option value (subtitles=, ass=, lut3d=file=, fontfile=, fontsdir=).
+
+    A filter option value is parsed twice: the graph parser splits filters on `,` / `;` and options
+    on `:`, then the filter's own option parser splits key=value pairs on `:` again. A character that
+    must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is
+    written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
+    ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
+    Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
+    never has to be escaped itself; `'`, `,`, `;`, `[` and `]` are graph-level characters.
+    """
     p = str(Path(path))
     p = p.replace("\\", "/")
-    p = p.replace(":", "\\:").replace("'", "\\'").replace(",", "\\,").replace("[", "\\[").replace("]", "\\]")
+    p = p.replace(":", "\\\\:")
+    for ch in ("'", ",", ";", "[", "]"):
+        p = p.replace(ch, "\\" + ch)
     return p
 
 
@@ -432,6 +467,19 @@ def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str
     return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
 
 
+def is_audio_output(output_path: str) -> bool:
+    """True when the output extension is an audio-only container (.wav, .flac, .mp3, .m4a, .aac, .ogg, .opus).
+
+    Such a file cannot hold a video stream and, for .wav, cannot hold compressed audio: scripts use
+    this to drop the picture (-vn) and to pick the codec from the extension instead of AAC.
+    """
+    return os.path.splitext(output_path)[1].lower() in AUDIO_CODECS
+
+
+def db_to_linear(db: float) -> float:
+    return 10 ** (db / 20.0)
+
+
 def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.