Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Machine-readable execution contract: contract --json, doctor, ToolSpecs, contract tests (#18)
Shogo Kajiyamaa3882fd8cb68
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e315cfc..86adf53 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,16 @@# Changelog+## 0.9.0 — machine-readable execution contract++`ffmpeg-skill contract --json` (`python3 scripts/_contract.py --json`) describes the skill for agent frameworks: `contract_version` 1.0 separate from the skill version; one ToolSpec per public script (`ffmpeg-skill/<name>`) with an input schema generated from its argparse parser, an output schema, role (analysis / analysis_and_execution / execution / verification), required and conditional ffmpeg capabilities, dry-run support, `mutates_input: false`, the verification tools to run afterwards, and whether a visual check is required. `ffmpeg-skill doctor` reports which capabilities the machine has. `docs/contract.md` explains the fields and how a planner consumes them.++- `--json` results now carry `"status": "completed"`; failures under `--json` also print `{"status": "failed", "error": {"kind", "message"}}` on stdout (stderr message and exit codes unchanged).+- `--dry-run` no longer writes the generated SRT (`caption.py --text`) or the HTML (`report.py`).+- MCP server lists `batch` (the one script it was missing); `tools/list` now equals the contract's tool list, and a test keeps it that way.+- Installer copies `package.json` so an installed skill knows its version, and answers `contract` / `doctor`.+- `tests/test_contract.py` (unit + integration, including a fake-ffmpeg dry-run guard and the real-device corpus when present), `evals/contract/`, `npm run release-check` extended.+- No new editing features; no script changed its media behaviour.+## 0.8.5 — audio-only inputs, spelled out- SKILL.md: "Audio-only files" section. WAV, FLAC, MP3, M4A/AAC, OGG and Opus go through `probe`, `cut`, `silence`, `loudness`, `audio`, `sync` and `check --platform podcast` unchanged; the output extension picks the codec; `Look: not needed`; picture scripts refuse with "input has no video stream". Six audio-only request→script rows.diff --git a/README.md b/README.mdindex 2ee98cf..9ffff41 100644--- a/README.md+++ b/README.md@@ -140,13 +140,22 @@ python3 tests/corpus.py --fetch --verify # ~1.4 GB download, then verify (slpython3 tests/bench_sync.py --cases 100```+## Machine-readable contract++```bash+npx ffmpeg-skill contract --json # every tool as a ToolSpec: schema from argparse, role, capabilities, verification, dry-run+npx ffmpeg-skill doctor # which required ffmpeg components this machine has+```++For agent frameworks that treat ffmpeg-skill as an execution skill: `contract --json` lists the 21 tools as `ffmpeg-skill/<name>` with input/output schemas, `analysis` / `execution` / `verification` roles, the ffmpeg encoders and filters each one needs, whether the result must be probed, checked or looked at, and that no tool modifies its input or runs a shell. `contract_version` (1.0) is separate from the skill version. Details in [docs/contract.md](docs/contract.md).+## MCP```json{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/Users/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}```-`python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.+`python3 mcp/server.py --list` prints the tools (the same set as `contract --json`); `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.## Requirementsdiff --git a/bin/install.js b/bin/install.jsindex 56a437e..c434d0f 100755--- a/bin/install.js+++ b/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') };diff --git a/docs/contract.md b/docs/contract.mdnew file mode 100644index 0000000..f4dd243--- /dev/null+++ b/docs/contract.md@@ -0,0 +1,189 @@+# ffmpeg-skill execution contract++`ffmpeg-skill contract --json` (or `python3 scripts/_contract.py --json`) prints a+machine-readable description of this skill: which tools exist, what each one needs,+takes and writes, how its result is verified, and what an agent may assume about+dry-run, input preservation and repeatability. It is the interface a planning agent+consumes instead of reading `SKILL.md`, which stays written for a coding agent that+follows the workflow by hand.++The contract is derived from the code that runs, not maintained beside it:++- the tool list is every script in `scripts/` that does not start with `_`;+- every `input_schema` is generated from the script's own `argparse` parser at the+ moment the contract is printed, so a new flag appears in the contract with no other edit;+- the facts a parser cannot express (role, required ffmpeg components, verification+ policy, visual-check policy) live in one table in `scripts/_contract.py` and are+ checked against the scripts, the MCP server and the installer by `tests/test_contract.py`.++## Versions++| 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 (`0.9.0`) | 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`+for provenance.++## Skill++```json+{+ "contract_version": "1.0",+ "skill": {"id": "ffmpeg-skill", "version": "0.9.0", "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"},+ "execution": {"shell": false, "arbitrary_executables": false, "network": false, "input_mutation": false}+}+```++ffmpeg-skill is an execution skill. It measures, transforms and verifies media with+local FFmpeg. It does not reason, plan, decide, or hold a project model; those belong+to the agent that calls it.++## ToolSpec++One entry per tool under `tools`, sorted by id. Tool ids are stable:+`ffmpeg-skill/<script name>` (`ffmpeg-skill/cut`, `ffmpeg-skill/loudness`, …).++| Field | Meaning |+|---|---|+| `id`, `name`, `version`, `executable` | `ffmpeg-skill/cut`, `cut`, skill version, `scripts/cut.py` |+| `role` | `analysis`, `analysis_and_execution`, `execution` or `verification` (see below) |+| `capabilities.required` | ffmpeg components the tool always needs |+| `capabilities.optional[]` | `{capability, when}`: needed only for that flag or input |+| `inputs`, `outputs` | asset kinds consumed and artifact kinds produced, in words |+| `input_schema` | generated from argparse: `properties` keyed by dest with `type`, `cli`, `enum`, `default`, `description`; `required`; `positional` (order); `mutually_exclusive` |+| `output_schema` | what `--json` prints on stdout |+| `supports_dry_run`, `dry_run` | whether `--dry-run` plans without running ffmpeg or writing files |+| `supports_json` | whether `--json` exists |+| `mutates_input` | always `false`: no tool overwrites its input |+| `produces_artifact` | writes a file (media, PNG, HTML, EDL) |+| `verification` | `{required, tools}`: which tools to run on the output afterwards |+| `requires_visual_verification` | the picture changed; run `ffmpeg-skill/look` and inspect the PNG |+| `audio_only` | accepts an audio-only input (WAV, MP3, M4A, FLAC, OGG, Opus) |+| `video_required` | refuses an input without a video stream ("input has no video stream") |+| `deterministic_inputs`, `idempotency_hint` | see Repeatability |+| `mcp` | the MCP tool name and its positional arguments |++### Roles++| Role | Tools |+|---|---|+| `analysis` (measures, writes no media) | probe, scenes |+| `analysis_and_execution` (measures by default or with a flag, can also write) | silence (`--list`), loudness (`--measure-only`), sync (offset JSON without `-o`) |+| `execution` (writes a new artifact) | cut, fit, caption, overlay, graphics, multicam, audio, join, color, export, render, batch |+| `verification` (checks or shows an artifact) | check, look, verify, report |++### Verification policy++The workflow in `SKILL.md` is "probe first, verify last". The contract states it per tool:++| Tool | After it wrote an artifact, run |+|---|---|+| cut, silence, audio, sync, batch | probe |+| loudness | probe, check |+| export | probe, check |+| fit, caption, overlay, graphics, color, join, multicam | probe, look |+| render | probe, check, look |+| probe, check, look, scenes, verify, report | nothing (they are the verification) |++`requires_visual_verification` is `true` exactly for the tools that change the picture+(fit, caption, overlay, graphics, color, join, multicam, render). Audio-only tools and+audio-only inputs never need `look`; the report line is `Look: not needed`. `check`+rows carry `kind: format` (fix it) or `kind: judgement` (decide with the user).++### Dry run++`supports_dry_run` is measured, not declared: `tests/test_contract.py` runs every tool+with `--dry-run` behind a fake `ffmpeg` that records any call, and asserts that no+call happened and no file appeared. Under `--dry-run` a tool prints the command lines+it would run, reports `dry_run: true`, and never reports an output probe. Two+exceptions are stated in the contract: `probe` and `check` are read-only (ffprobe+still runs), and `verify` does not support dry-run (its steps run).++### Repeatability++No tool keeps state or uses randomness. `deterministic_inputs` is `false` only for+`verify`, whose output includes timings. `idempotency_hint` says what "same inputs"+gives you:++| Hint | Tools |+|---|---|+| `bit_exact` | probe, check, scenes, look |+| `content_equivalent` (same media, bytes may differ between encoder builds) | every encoding tool, cut, sync, report |+| `cached` | batch (content-hash cache, re-runs skip unchanged inputs) |+| `environment_dependent` | verify |++## Capabilities++Names: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,+`external:whisper`. `capabilities.required` is the union of every tool's required list;+`optional` the union of the conditional ones. With detection (the default)+`available`, `missing` and `missing_optional` are added from `doctor`, which reads+`ffmpeg -encoders / -filters / -bsfs` and looks for a local whisper. Pass `--static`+to omit detection. Nothing from the environment other than those lists and the+ffmpeg/ffprobe/python versions is printed; no environment variables, no paths.++`ffmpeg-skill doctor` exits non-zero when a required capability is missing.++## Invocation++Structured arguments are the canonical way to call a tool, on the CLI or through MCP.+The mapping is stated in `invocation.structured.argument_mapping`: positionals in+`input_schema.positional` order, `key` → `--key` with `_` → `-`, booleans as bare flags,+arrays repeated, `output` → `-o`, `loudness.lufs` → `-I`. `--json` is appended for every+tool except `probe` (JSON by default) and `look`.++The MCP server also accepts `{"argv": [...]}` for CLI compatibility. That path is+marked `canonical: false`: it is still bound to the named script and never reaches a+shell, but an agent ecosystem should use the structured form. No tool, CLI or MCP,+runs a shell, evaluates strings, or executes anything other than the named script,+`ffmpeg` and `ffprobe`.++## JSON output++Success (`exit 0`): one document matching `output_schema`, always with+`status: "completed"`, `output`, `dry_run`, `commands`, and `probe` of the output when a+file was written. `probe` prints its measurement document directly.++Failure (non-zero exit; 127 when ffmpeg/ffprobe is missing): the message on stderr as+before, and, when `--json` was given, on stdout:++```json+{"status": "failed", "error": {"kind": "input | ffmpeg | missing_tool", "message": "..."}}+```++## MCP relationship++`mcp/server.py` is a transport. Its `tools/list` is the same set of names as the+contract's tools (tested), and its argument mapping is the one the contract describes.+The MCP `inputSchema` is deliberately loose; the contract's `input_schema` is the+semantic definition. Do not treat the MCP schema as a second source of truth.++## Consuming the contract from an agent++A planning agent (for example video-production-agent's SkillRegistry) can:++1. run `ffmpeg-skill contract --json` once and register the skill by `skill.id` and the+ tools by `id`;+2. resolve `capabilities.required` against `capabilities.available` before planning;+3. pick a tool by `role`, `inputs`/`outputs`, `video_required` and `audio_only`;+4. build the call from `input_schema` and the argument mapping, plan with `--dry-run`;+5. run, parse `output_schema`, then run `verification.tools`, adding `look` when+ `requires_visual_verification` is true.++The measurement documents (`probe`, `check`, `scenes`, `sync`) are ffmpeg-skill's own+shapes, not another system's Observation model; convert them in the agent's adapter.+ffmpeg-skill contains no agent-specific code.++## Where things live++- `scripts/_contract.py`: the generator (`--json`, `--static`, `doctor`)+- `bin/install.js`: `ffmpeg-skill contract` and `ffmpeg-skill doctor`+- `tests/test_contract.py`: schema, consistency (scripts = MCP = installer), dry-run, JSON shapes, verification policy, real-media run+- `evals/contract/`: questions an agent must answer from the contract alone, with the expected answers checked against the live contract+- `tests/release_check.sh`: runs the contract from the packed and installed copies before a releasediff --git a/evals/contract/README.md b/evals/contract/README.mdnew file mode 100644index 0000000..68a08be--- /dev/null+++ b/evals/contract/README.md@@ -0,0 +1,18 @@+# Contract evals++Can an agent understand ffmpeg-skill from `contract --json` alone, without reading+`SKILL.md`, the scripts or a shell command?++`questions.json` holds ten questions with the field of the contract that answers each+and the expected answer: picking the right tool id, naming a required capability,+deciding whether a visual check is needed, whether the input is preserved, whether+`--dry-run` is available, telling analysis / execution / verification apart, building an+argv from the input schema and mapping, and the stability of tool ids.++- `check.py` (deterministic, run in `release-check`): recomputes every expected answer+ from the live contract, so the questions can never drift from the ToolSpecs.+- Agent run: give a model the contract (`python3 scripts/_contract.py --json --static`)+ and `questions.json`, ask for `{"<id>": "<answer>"}`, and grade with+ `python3 evals/contract/check.py --grade answers.json`.++Results: `../results/contract-<date>.json`.diff --git a/evals/contract/check.py b/evals/contract/check.pynew file mode 100644index 0000000..ee1dd02--- /dev/null+++ b/evals/contract/check.py@@ -0,0 +1,72 @@+#!/usr/bin/env python3+"""Contract evals, deterministic half: every expected answer in questions.json must be+derivable from the live contract. Run before a release and after any ToolSpec change.++ python3 evals/contract/check.py # exits non-zero when the contract and the answers disagree+ python3 evals/contract/check.py --grade answers.json # grade an agent's answers {"id": "answer", ...}++The agent half (README.md here) gives a model the contract JSON and questions.json and+records its answers; grade them with --grade.+"""+import json+import re+import subprocess+import sys+from pathlib import Path++HERE = Path(__file__).resolve().parent+ROOT = HERE.parent.parent+QUESTIONS = json.loads((HERE / "questions.json").read_text(encoding="utf-8"))+++def contract():+ out = subprocess.run([sys.executable, str(ROOT / "scripts" / "_contract.py"), "--json", "--static"], stdout=subprocess.PIPE, text=True, check=True).stdout+ return json.loads(out)+++def derive(doc):+ """Recompute every expected answer from the contract itself."""+ tools = {t["name"]: t for t in doc["tools"]}+ yn = lambda b: "yes" if b else "no" # noqa: E731+ return {+ "q1-tool-for-task": tools["silence"]["id"],+ "q2-required-capability": [c for c in tools["loudness"]["capabilities"]["required"] if c not in ("ffmpeg", "ffprobe", "encoder:aac")][0],+ "q3-visual-verification": yn(tools["caption"]["requires_visual_verification"]),+ "q4-no-visual-for-audio": yn(tools["loudness"]["requires_visual_verification"]),+ "q5-input-preserved": yn(tools["cut"]["mutates_input"]),+ "q6-dry-run": yn(tools["export"]["supports_dry_run"]),+ "q7-roles": f"probe={tools['probe']['role']}, cut={tools['cut']['role']}, check={tools['check']['role']}",+ "q8-no-shell-needed": "clip.mp4 --start 0:10 --end 0:20 -o out.mp4 --json",+ "q9-stable-ids": ", ".join(tools[n]["id"] for n in ("probe", "loudness", "export", "look")),+ "q10-verification-tools": ", ".join(tools["export"]["verification"]["tools"]),+ }+++def norm(s):+ return re.sub(r"[\s`'\"]+", " ", str(s)).strip().lower().rstrip(".")+++def main():+ doc = contract()+ derived = derive(doc)+ bad = [q["id"] for q in QUESTIONS if norm(derived[q["id"]]) != norm(q["expected"])]+ if bad:+ for b in bad:+ print(f"MISMATCH {b}: contract says {derived[b]!r}, questions.json expects {[q for q in QUESTIONS if q['id']==b][0]['expected']!r}")+ return 1+ print(f"contract evals: {len(QUESTIONS)} expected answers agree with the contract")+ if "--grade" in sys.argv:+ answers = json.loads(Path(sys.argv[sys.argv.index("--grade") + 1]).read_text(encoding="utf-8"))+ score = 0+ for q in QUESTIONS:+ got = norm(answers.get(q["id"], ""))+ ok = norm(q["expected"]) in got or got == norm(q["expected"])+ score += ok+ print(f"{'PASS' if ok else 'FAIL'} {q['id']}: {answers.get(q['id'], '')!r}")+ print(f"{score}/{len(QUESTIONS)}")+ return 0 if score == len(QUESTIONS) else 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/evals/contract/questions.json b/evals/contract/questions.jsonnew file mode 100644index 0000000..def282d--- /dev/null+++ b/evals/contract/questions.json@@ -0,0 +1,12 @@+[+ {"id": "q1-tool-for-task", "question": "A planner needs to remove dead air from talk.wav. Which tool id from the contract does it pick?", "answer_from": "tools[].id where role covers silence removal", "expected": "ffmpeg-skill/silence"},+ {"id": "q2-required-capability", "question": "Which ffmpeg capability does ffmpeg-skill/loudness always require besides ffmpeg and ffprobe? Give the capability name exactly as the contract writes it.", "answer_from": "tools[loudness].capabilities.required", "expected": "filter:loudnorm"},+ {"id": "q3-visual-verification", "question": "After running ffmpeg-skill/caption, must the agent look at the picture (run ffmpeg-skill/look)? Answer yes or no.", "answer_from": "tools[caption].requires_visual_verification", "expected": "yes"},+ {"id": "q4-no-visual-for-audio", "question": "After running ffmpeg-skill/loudness on a WAV, must the agent run ffmpeg-skill/look? Answer yes or no.", "answer_from": "tools[loudness].requires_visual_verification / audio_only", "expected": "no"},+ {"id": "q5-input-preserved", "question": "Does ffmpeg-skill/cut modify or overwrite its input file? Answer yes or no.", "answer_from": "tools[cut].mutates_input", "expected": "no"},+ {"id": "q6-dry-run", "question": "Can ffmpeg-skill/export be planned with --dry-run so that no ffmpeg runs and no file is written? Answer yes or no.", "answer_from": "tools[export].supports_dry_run", "expected": "yes"},+ {"id": "q7-roles", "question": "Classify these three tools by their contract role: ffmpeg-skill/probe, ffmpeg-skill/cut, ffmpeg-skill/check. Answer as probe=<role>, cut=<role>, check=<role>.", "answer_from": "tools[].role", "expected": "probe=analysis, cut=execution, check=verification"},+ {"id": "q8-no-shell-needed", "question": "To run ffmpeg-skill/cut on clip.mp4 from 0:10 to 0:20 into out.mp4 with a JSON result, what is the full argv (after 'python3 scripts/cut.py') using only the contract's input_schema and argument mapping? Do not write a shell command.", "answer_from": "tools[cut].input_schema + invocation.structured.argument_mapping", "expected": "clip.mp4 --start 0:10 --end 0:20 -o out.mp4 --json"},+ {"id": "q9-stable-ids", "question": "List the tool ids for these scripts: probe.py, loudness.py, export.py, look.py.", "answer_from": "tools[].id", "expected": "ffmpeg-skill/probe, ffmpeg-skill/loudness, ffmpeg-skill/export, ffmpeg-skill/look"},+ {"id": "q10-verification-tools", "question": "Which verification tools does the contract say to run after ffmpeg-skill/export wrote its artifact? Give the tool ids.", "answer_from": "tools[export].verification.tools", "expected": "ffmpeg-skill/probe, ffmpeg-skill/check"}+]diff --git a/evals/results/contract-2026-09-04.json b/evals/results/contract-2026-09-04.jsonnew file mode 100644index 0000000..7049b74--- /dev/null+++ b/evals/results/contract-2026-09-04.json@@ -0,0 +1,30 @@+{+ "eval": "contract",+ "date": "2026-09-04",+ "contract_version": "1.0",+ "skill_version": "0.9.0",+ "method": "each model got the contract JSON (--static) and evals/contract/questions.json only; answers graded by evals/contract/check.py --grade",+ "runs": [+ {+ "model": "claude-sonnet",+ "score": "10/10"+ },+ {+ "model": "claude-haiku-4-5",+ "score": "10/10"+ }+ ],+ "deterministic_check": "evals/contract/check.py: 10 expected answers agree with the live contract",+ "questions": [+ "tool for a task",+ "required capability",+ "visual verification needed",+ "no visual check for audio",+ "input preserved",+ "dry-run available",+ "analysis/execution/verification roles",+ "argv from schema without a shell",+ "stable tool ids",+ "verification tools after export"+ ]+}\ No newline at end of filediff --git a/mcp/server.py b/mcp/server.pyindex 674d4cd..1c7bc99 100755--- a/mcp/server.py+++ b/mcp/server.py@@ -39,10 +39,11 @@ TOOLS: Dict[str, str] = {"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.",+ "batch": "Apply a step recipe or render project to every file in a folder (content-hash cached). Args: folder, recipe, force, watch, work.","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"]}+POSITIONAL = {"probe": ["inputs"], "sync": ["reference", "second"], "multicam": ["inputs"], "join": ["inputs"], "verify": ["paths"], "render": ["project"], "batch": ["folder"]}def build_argv(name: str, args: Dict[str, Any]) -> List[str]:diff --git a/package.json b/package.jsonindex 527fc33..88296fc 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.8.5",+ "version": "0.9.0","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",@@ -24,9 +24,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"diff --git a/scripts/_common.py b/scripts/_common.pyindex b63cd27..bbffde1 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -31,8 +31,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 +57,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 +126,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 +145,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:diff --git a/scripts/_contract.py b/scripts/_contract.pynew file mode 100644index 0000000..f47bf4d--- /dev/null+++ b/scripts/_contract.py@@ -0,0 +1,506 @@+#!/usr/bin/env python3+"""Machine-readable execution contract for ffmpeg-skill (internal module, not a tool).++ python3 scripts/_contract.py --json # the contract, with detected capabilities+ python3 scripts/_contract.py --json --static # same, without environment detection+ python3 scripts/_contract.py doctor [--json] # which required capabilities this machine has+ ffmpeg-skill contract --json # the same through the npm entry point++The contract describes every public tool in scripts/ (one ToolSpec per script that does+not start with "_"): what it needs, what it takes, what it writes, how to verify the+result, and whether an agent can plan it with --dry-run. Input schemas are generated+from each script's argparse parser, so the CLI stays the single source of truth; the+per-tool facts that cannot be read from a parser (role, verification policy, required+ffmpeg components) live in TOOL_META below and are checked against the scripts by+tests/test_contract.py.++The contract has its own version (CONTRACT_VERSION) that only changes when the shape of+this document changes; the skill version comes from package.json.+"""+import argparse+import importlib.util+import json+import os+import re+import shutil+import subprocess+import sys+from pathlib import Path+from typing import Any, Dict, List, Optional++HERE = Path(__file__).resolve().parent+ROOT = HERE.parent+SKILL_ID = "ffmpeg-skill"+CONTRACT_VERSION = "1.0"++ROLES = {+ "analysis": "reads media and reports measurements; writes no media",+ "analysis_and_execution": "measures by default or with a flag, and can also write a transformed artifact",+ "execution": "writes a new media artifact from the input(s); the input is never modified",+ "verification": "checks or shows an artifact (probe numbers, compliance rows, contact sheets); writes no media",+}++# Facts that are not derivable from the argparse parsers. Capability names:+# ffmpeg / ffprobe the binaries on PATH+# encoder:<name> `ffmpeg -encoders`+# filter:<name> `ffmpeg -filters`+# bsf:<name> `ffmpeg -bsfs`+# external:whisper a local whisper engine (whisper.cpp / faster-whisper / openai-whisper)+# "optional" entries name the flag or condition under which the capability is needed.+FF = ["ffmpeg", "ffprobe"]+X264 = "encoder:libx264"+X265 = "encoder:libx265"+AAC = "encoder:aac"+HDR_X265 = {"capability": X265, "when": "the source is HDR (kept as HEVC Main10)"}+AUDIO_OUT = [+ {"capability": "encoder:libmp3lame", "when": "output extension is .mp3"},+ {"capability": "encoder:libopus", "when": "output extension is .opus"},+ {"capability": "encoder:libvorbis", "when": "output extension is .ogg"},+ {"capability": "encoder:flac", "when": "output extension is .flac"},+]++TOOL_META: Dict[str, Dict[str, Any]] = {+ "probe": dict(role="analysis", inputs=["media (video or audio, any container ffprobe reads)"], outputs=["measurement JSON on stdout (no file)"],+ required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "--analyze"}, {"capability": "filter:signalstats", "when": "--analyze"}],+ video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),+ "cut": dict(role="execution", inputs=["video or audio asset"], outputs=["cut video/audio artifact (same container family)"],+ required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}],+ video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],+ required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"}],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "caption": dict(role="execution", inputs=["video asset", "SRT/ASS file or timed text (--text)"], outputs=["video artifact with burnt-in captions", "generated .srt / .ass sidecar"],+ required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"}],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "overlay": dict(role="execution", inputs=["video asset", "image (--image / --logo) or text (--text)"], outputs=["video artifact with the overlay composited"],+ required=FF + [X264, AAC], optional=[{"capability": "filter:drawtext", "when": "--text"}, HDR_X265],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "graphics": dict(role="execution", inputs=["video asset"], outputs=["video artifact with the drawn template"],+ required=FF + [X264, AAC, "filter:drawtext"], optional=[HDR_X265],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "sync": dict(role="analysis_and_execution", inputs=["reference recording (video or audio)", "second recording (video or audio)"], outputs=["offset / drift JSON on stdout", "aligned artifact with --replace-audio / --trim-second / --fix-drift -o"],+ required=FF, optional=[{"capability": AAC, "when": "writing a video container"}] + AUDIO_OUT,+ video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "multicam": dict(role="execution", inputs=["reference camera", "other cameras / recorders"], outputs=["switched multicam video artifact"],+ required=FF + [X264, AAC], optional=[HDR_X265],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)"], outputs=["artifact with the processed audio (video stream-copied)"],+ required=FF + [AAC], optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"}] + AUDIO_OUT,+ video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "loudness": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["loudness measurement JSON (--measure-only)", "normalised artifact (video stream-copied)"],+ required=FF + ["filter:loudnorm", AAC], optional=AUDIO_OUT,+ video_required=False, audio_only=True, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],+ required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"}] + AUDIO_OUT,+ video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "join": dict(role="execution", inputs=["two or more video assets"], outputs=["concatenated video artifact"],+ required=FF + [X264, AAC, "filter:xfade", "filter:acrossfade"], optional=[HDR_X265],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "color": dict(role="execution", inputs=["video asset", ".cube LUT (--lut)"], outputs=["video artifact with converted colour"],+ required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},+ {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"}],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],+ required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "any preset except gif"},+ {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},+ {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}],+ video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],+ required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default)"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"}],+ video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),+ "scenes": dict(role="analysis", inputs=["video asset"], outputs=["scene / audio-peak / highlight JSON on stdout", "EDL text (--edl)", "per-scene contact sheet PNG (--sheet)"],+ required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"}],+ video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),+ "look": dict(role="verification", inputs=["video artifact"], outputs=["PNG contact sheet / frames / side-by-side"],+ required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],+ video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),+ "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)"], outputs=["final video artifact", "work directory of stage outputs (--keep / --work)"],+ required=FF, optional=[{"capability": "delegated", "when": "each stage runs cut / join / fit / caption / overlay / audio / loudness / export / check with their capabilities"}],+ video_required=True, audio_only=False, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],+ required=FF, optional=[{"capability": "delegated", "when": "each recipe step runs the named script with its capabilities"}],+ video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="cached", deterministic=True),+ "verify": dict(role="verification", inputs=["media files and/or folders"], outputs=["PASS/FAIL JSON per step", "Markdown report (--report)", "step outputs (--out / --keep)"],+ required=FF, optional=[{"capability": "delegated", "when": "runs cut / fit / caption / export / loudness / color on each file"}],+ video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=True, idempotency="environment_dependent", deterministic=False),+ "report": dict(role="verification", inputs=["deliverable (--after)", "source (--before)", "commands / notes text"], outputs=["single-file HTML delivery report"],+ required=FF + ["filter:loudnorm"], optional=[{"capability": "delegated", "when": "runs look (sheets) and check (--platform)"}],+ video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+}++# Dry-run behaviour a parser cannot express (measured in tests/test_contract.py with a fake ffmpeg+# on PATH). "analysis_only": ffmpeg still decodes/measures the input under --dry-run, but nothing+# is encoded and no file is written. Every other tool with the flag runs no ffmpeg at all.+DRY_RUN_ANALYSIS = {+ "sync": "audio is decoded to find the offset; the aligned output is not written",+ "multicam": "audio is decoded to align the cameras; the switched output is not written",+ "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",+ "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",+}+DRY_RUN_NOTES = {+ "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",+ "check": "read-only tool; --dry-run skips the ffmpeg loudness measurement, so loudness rows are absent",+ "verify": "not supported: the flag is accepted but the steps run and outputs are written",+}++IDEMPOTENCY = {+ "bit_exact": "same inputs and flags give byte-identical output",+ "content_equivalent": "same inputs and flags give the same media content; bytes may differ between encoder builds",+ "cached": "re-runs skip inputs whose content hash and recipe are unchanged",+ "environment_dependent": "output includes timings or machine state and differs between runs",+}+++# ----------------------------------------------------------------------------- parsers+class _Captured(Exception):+ def __init__(self, parser: argparse.ArgumentParser) -> None:+ self.parser = parser+++def _capture_parser(script: Path) -> argparse.ArgumentParser:+ """Import the script and run main() until parse_args() to get its live parser."""+ original = argparse.ArgumentParser.parse_args++ def fake_parse(self: argparse.ArgumentParser, *a: Any, **k: Any) -> Any:+ raise _Captured(self)++ argparse.ArgumentParser.parse_args = fake_parse # type: ignore[assignment]+ sys_argv = sys.argv+ try:+ sys.argv = [str(script)]+ spec = importlib.util.spec_from_file_location("ffskill_tool_" + script.stem, script)+ module = importlib.util.module_from_spec(spec)+ assert spec.loader is not None+ spec.loader.exec_module(module)+ module.main()+ except _Captured as cap:+ return cap.parser+ finally:+ argparse.ArgumentParser.parse_args = original # type: ignore[assignment]+ sys.argv = sys_argv+ raise RuntimeError(f"{script.name}: main() returned before parse_args()")+++def _json_type(action: argparse.Action) -> Dict[str, Any]:+ if isinstance(action, argparse._StoreTrueAction):+ return {"type": "boolean"}+ if isinstance(action, argparse._AppendAction) or action.nargs in ("+", "*"):+ return {"type": "array", "items": {"type": "string"}}+ if action.type is int:+ return {"type": "integer"}+ if action.type is float:+ return {"type": "number"}+ return {"type": "string"}+++def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:+ props: Dict[str, Any] = {}+ required: List[str] = []+ positional: List[str] = []+ common = {"dry_run", "json", "progress", "fast"}+ for action in parser._actions:+ if isinstance(action, argparse._HelpAction):+ continue+ prop: Dict[str, Any] = _json_type(action)+ if action.help and action.help != argparse.SUPPRESS:+ prop["description"] = action.help % {"default": action.default} if "%(default)" in action.help else action.help+ if action.choices:+ prop["enum"] = list(action.choices)+ if action.default not in (None, False, argparse.SUPPRESS):+ prop["default"] = action.default+ if action.option_strings:+ prop["cli"] = list(action.option_strings)+ if action.required:+ required.append(action.dest)+ else:+ prop["cli"] = "positional"+ positional.append(action.dest)+ if action.nargs not in ("?", "*"):+ required.append(action.dest)+ if action.dest in common:+ prop["common"] = True+ props[action.dest] = prop+ groups = [g for g in getattr(parser, "_mutually_exclusive_groups", []) if g._group_actions]+ schema: Dict[str, Any] = {"type": "object", "properties": props, "required": required, "positional": positional, "additionalProperties": False}+ if groups:+ schema["mutually_exclusive"] = [[a.dest for a in g._group_actions] for g in groups]+ schema["one_of_required"] = [[a.dest for a in g._group_actions] for g in groups if g.required]+ return schema+++def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:+ """What the tool prints on stdout with --json (keys observed in the implementation)."""+ if name == "probe":+ return {"type": "object", "description": "one probe document, or an array of them for several inputs",+ "properties": {"file": {"type": "string"}, "format": {"type": "string"}, "duration": {"type": "number"}, "size_bytes": {"type": "integer"},+ "video": {"type": ["object", "null"]}, "audio": {"type": ["object", "null"]}}, "additionalProperties": True}+ base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},+ "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "every ffmpeg command line planned or run"},+ "probe": {"type": "object", "description": "probe of the output when a file was written"}}+ extra: Dict[str, Any] = {}+ if name == "check":+ extra = {"platform": {"type": "string"}, "ok": {"type": "boolean"}, "failed": {"type": "integer"}, "warnings": {"type": "integer"},+ "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}+ elif name == "scenes":+ extra = {"file": {"type": "string"}, "duration": {"type": "number"}, "scene_count": {"type": "integer"}, "scenes": {"type": "array"}, "audio_peaks": {"type": "array"}}+ elif name == "silence":+ extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"}}+ elif name == "sync":+ extra = {"reference": {"type": "string"}, "second": {"type": "string"}, "offset_seconds": {"type": "number"}, "confidence": {"type": "number"}, "meaning": {"type": "string"}, "drift": {"type": "object"}}+ elif name == "look":+ extra = {"outputs": {"type": "array", "items": {"type": "string"}}}+ elif name == "render":+ extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]}}+ elif name == "verify":+ extra = {"report": {"type": ["string", "null"]}, "files": {"type": "array"}, "failed": {"type": "integer"}, "total": {"type": "integer"}}+ elif name == "batch":+ extra = {"results": {"type": "array"}, "processed": {"type": "integer"}, "total": {"type": "integer"}}+ elif name == "report":+ extra = {"report": {"type": "string"}, "check": {"type": ["object", "null"]}}+ elif name == "loudness":+ extra = {"measured": {"type": "object", "description": "--measure-only prints the loudnorm measurement instead (input_i, input_tp, input_lra, input_thresh, target_offset)"}}+ props = dict(base)+ props.update(extra)+ required = ["status", "output", "dry_run", "commands"]+ return {"type": "object", "properties": props, "required": required, "additionalProperties": True}+++# ----------------------------------------------------------------------------- environment+def skill_version() -> str:+ for candidate in (ROOT / "package.json",):+ try:+ return str(json.loads(candidate.read_text(encoding="utf-8"))["version"])+ except (OSError, ValueError, KeyError):+ continue+ return "unknown"+++def skill_description() -> str:+ try:+ text = (ROOT / "SKILL.md").read_text(encoding="utf-8")+ m = re.search(r"^description:\s*(.+)$", text, re.M)+ return m.group(1).strip() if m else ""+ except OSError:+ return ""+++def public_tools() -> List[str]:+ return sorted(p.stem for p in HERE.glob("*.py") if not p.name.startswith("_"))+++def _ff_list(binary: str, flag: str) -> List[str]:+ """Names from `ffmpeg -encoders` / `-filters` / `-bsfs` (empty list when ffmpeg is missing)."""+ exe = shutil.which(binary)+ if not exe:+ return []+ proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ names: List[str] = []+ flags = {"-encoders": r"[VASFXBD.]{6}", "-filters": r"[TSC.]{3}"}.get(flag)+ for line in proc.stdout.splitlines():+ parts = line.split()+ if not parts:+ continue+ if flag == "-bsfs":+ if len(parts) == 1 and not parts[0].endswith(":"):+ names.append(parts[0])+ elif flags and len(parts) >= 2 and re.fullmatch(flags, parts[0]):+ names.append(parts[1])+ return names+++def _version_line(binary: str) -> Optional[str]:+ exe = shutil.which(binary)+ if not exe:+ return None+ proc = subprocess.run([exe, "-version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ first = (proc.stdout or proc.stderr).splitlines()[:1]+ m = re.match(rf"{binary} version (\S+)", first[0]) if first else None+ return m.group(1) if m else (first[0] if first else "unknown")+++def _whisper_available() -> bool:+ if shutil.which("whisper-cli") or shutil.which("whisper-cpp") or shutil.which("whisper"):+ return True+ return importlib.util.find_spec("faster_whisper") is not None or importlib.util.find_spec("whisper") is not None+++def required_capabilities() -> Dict[str, List[str]]:+ req: set = set()+ opt: set = set()+ for meta in TOOL_META.values():+ req.update(meta["required"])+ opt.update(o["capability"] for o in meta["optional"] if o["capability"] != "delegated")+ opt -= req+ return {"required": sorted(req), "optional": sorted(opt)}+++def doctor() -> Dict[str, Any]:+ """Detect which declared capabilities this machine has. No secrets, no environment variables."""+ encoders = set(_ff_list("ffmpeg", "-encoders"))+ filters = set(_ff_list("ffmpeg", "-filters"))+ bsfs = set(_ff_list("ffmpeg", "-bsfs"))+ have: Dict[str, bool] = {}+ wanted = required_capabilities()+ for cap in wanted["required"] + wanted["optional"]:+ if cap == "ffmpeg":+ have[cap] = shutil.which("ffmpeg") is not None+ elif cap == "ffprobe":+ have[cap] = shutil.which("ffprobe") is not None+ elif cap.startswith("encoder:"):+ have[cap] = cap[8:] in encoders+ elif cap.startswith("filter:"):+ have[cap] = cap[7:] in filters+ elif cap.startswith("bsf:"):+ have[cap] = cap[4:] in bsfs+ elif cap == "external:whisper":+ have[cap] = _whisper_available()+ else:+ have[cap] = False+ available = sorted(c for c, ok in have.items() if ok)+ missing_required = sorted(c for c in wanted["required"] if not have.get(c))+ missing_optional = sorted(c for c in wanted["optional"] if not have.get(c))+ return {+ "python": ".".join(str(x) for x in sys.version_info[:3]),+ "ffmpeg": _version_line("ffmpeg"),+ "ffprobe": _version_line("ffprobe"),+ "available": available,+ "missing": missing_required,+ "missing_optional": missing_optional,+ "ok": not missing_required,+ }+++# ----------------------------------------------------------------------------- contract+def tool_spec(name: str, version: str) -> Dict[str, Any]:+ meta = TOOL_META[name]+ parser = _capture_parser(HERE / f"{name}.py")+ schema = input_schema(parser)+ # structured key -> CLI flag where key.replace("_", "-") is not the long option (MCP uses the same table)+ exceptions: Dict[str, str] = {}+ for dest, prop in schema["properties"].items():+ if prop["cli"] == "positional":+ continue+ longs = [f for f in prop["cli"] if f.startswith("--")]+ if dest == "output":+ exceptions[dest] = "-o"+ elif name == "loudness" and dest == "lufs":+ exceptions[dest] = "-I"+ elif "--" + dest.replace("_", "-") not in longs:+ exceptions[dest] = longs[0] if longs else prop["cli"][0]+ supports_dry_run = "dry_run" in schema["properties"] and name != "verify"+ return {+ "id": f"{SKILL_ID}/{name}",+ "name": name,+ "version": version,+ "description": (parser.description or "").strip().splitlines()[0] if parser.description else "",+ "executable": f"scripts/{name}.py",+ "role": meta["role"],+ "capabilities": {"required": list(meta["required"]), "optional": list(meta["optional"])},+ "inputs": list(meta["inputs"]),+ "outputs": list(meta["outputs"]),+ "input_schema": schema,+ "output_schema": output_schema(name, meta),+ "supports_dry_run": supports_dry_run,+ "dry_run": {"supported": supports_dry_run,+ "ffmpeg_execution": "full" if not supports_dry_run else "analysis_only" if name in DRY_RUN_ANALYSIS else "none",+ "semantics": "prints the ffmpeg command lines that would run; no output file is written",+ **({"note": DRY_RUN_ANALYSIS.get(name) or DRY_RUN_NOTES[name]} if name in DRY_RUN_ANALYSIS or name in DRY_RUN_NOTES else {})},+ "supports_json": "json" in schema["properties"],+ "mutates_input": False,+ "produces_artifact": meta["produces_artifact"],+ "verification": {"required": bool(meta["verify"]), "tools": [f"{SKILL_ID}/{t}" for t in meta["verify"]]},+ "requires_visual_verification": meta["visual"],+ "audio_only": meta["audio_only"],+ "video_required": meta["video_required"],+ "deterministic_inputs": meta["deterministic"],+ "idempotency_hint": meta["idempotency"],+ "mcp": {"tool": name, "positional": schema["positional"], "argument_exceptions": exceptions},+ }+++def build(detect: bool = True) -> Dict[str, Any]:+ version = skill_version()+ tools = [tool_spec(n, version) for n in public_tools()]+ wanted = required_capabilities()+ caps: Dict[str, Any] = {"required": wanted["required"], "optional": wanted["optional"], "naming": "ffmpeg | ffprobe | encoder:<name> | filter:<name> | bsf:<name> | external:whisper"}+ if detect:+ d = doctor()+ caps.update({"available": d["available"], "missing": d["missing"], "missing_optional": d["missing_optional"], "detected_by": "doctor"})+ return {+ "contract_version": CONTRACT_VERSION,+ "skill": {+ "id": SKILL_ID,+ "version": version,+ "description": skill_description(),+ "execution_mode": "local",+ "kind": "execution",+ "entrypoints": {+ "cli": "python3 scripts/<tool>.py [args] [--json] [--dry-run]",+ "mcp": "python3 mcp/server.py (stdio JSON-RPC; tools/list == this tool list)",+ "contract": "python3 scripts/_contract.py --json | ffmpeg-skill contract --json",+ "doctor": "python3 scripts/_contract.py doctor --json | ffmpeg-skill doctor --json",+ },+ "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", "node": ">=16 (npx installer only)"},+ "execution": {+ "shell": False,+ "arbitrary_executables": False,+ "subprocess": "argv list only: [python3, scripts/<tool>.py, ...] and [ffmpeg|ffprobe, ...] resolved from PATH",+ "network": False,+ "input_mutation": False,+ },+ "invocation": {+ "structured": {+ "canonical": True,+ "transports": ["cli", "mcp"],+ "argument_mapping": {+ "positional": "listed in input_schema.positional, in order; array values expand to several arguments",+ "options": "key -> --key with '_' replaced by '-'; booleans are flags; arrays repeat the flag; input_schema.properties[key].cli lists the accepted spellings",+ "exceptions": "per tool in mcp.argument_exceptions (key -> flag), e.g. output -> -o, loudness.lufs -> -I, graphics.count_from -> --from",+ "json": "--json is appended for every tool except look and probe (probe prints JSON by default)",+ },+ },+ "raw_argv": {"canonical": False, "transports": ["mcp"], "note": "MCP tools also accept {\"argv\": [...]} for CLI compatibility; it is still bound to the named script, never a shell"},+ },+ "roles": ROLES,+ "idempotency_hints": IDEMPOTENCY,+ "verification_policy": {+ "probe_first": "run ffmpeg-skill/probe on every input before planning",+ "verify_last": "run the tools named in each ToolSpec.verification after it wrote an artifact",+ "visual": "when requires_visual_verification is true, run ffmpeg-skill/look on the output and inspect the PNG",+ "audio_only": "audio-only inputs and audio-only tools never need ffmpeg-skill/look",+ "check_rows": "ffmpeg-skill/check rows carry kind=format (fix) or kind=judgement (decide with the user)",+ },+ "json_output": {+ "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},+ "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"error\": {\"kind\": ..., \"message\": ...}} when --json was given", "stderr": "human-readable message"},+ "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error", "missing_tool": "ffmpeg or ffprobe not on PATH"},+ },+ "capabilities": caps,+ "tools": tools,+ }+++def main() -> int:+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("command", nargs="?", choices=["contract", "doctor"], default="contract")+ ap.add_argument("--json", action="store_true", help="JSON on stdout (the contract is always JSON)")+ ap.add_argument("--static", action="store_true", help="omit environment detection (available / missing capabilities)")+ args = ap.parse_args()+ if args.command == "doctor":+ d = doctor()+ if args.json:+ print(json.dumps(d, indent=2, sort_keys=True))+ else:+ print(f"python {d['python']}; ffmpeg {d['ffmpeg'] or 'MISSING'}; ffprobe {d['ffprobe'] or 'MISSING'}")+ print(f"available: {', '.join(d['available'])}")+ print(f"missing required: {', '.join(d['missing']) or 'none'}")+ print(f"missing optional: {', '.join(d['missing_optional']) or 'none'}")+ return 0 if d["ok"] else 1+ print(json.dumps(build(detect=not args.static), indent=2, sort_keys=True, ensure_ascii=False))+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/scripts/caption.py b/scripts/caption.pyindex b004fb0..3197615 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -23,7 +23,7 @@ import sysfrom pathlib import Pathfrom typing import List, Optional, Tuple-from _common import color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args+from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_argsALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}@@ -352,7 +352,8 @@ def main() -> int:srt_path = os.path.splitext(out_guess)[0] + ".srt"else:srt_path = os.path.splitext(args.text)[0] + ".srt"- write_srt(cues, srt_path)+ if not STATE.dry_run:+ write_srt(cues, srt_path)info(f"wrote {srt_path} ({len(cues)} cues)")if not args.input:print(srt_path)@@ -382,7 +383,7 @@ def main() -> int:if args.fonts_dir:vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"else:- if not srt_path or not os.path.exists(srt_path):+ if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):die(f"SRT file not found: {srt_path}")style = [f"FontName={args.font}",diff --git a/scripts/report.py b/scripts/report.pyindex f15e72e..509d298 100755--- a/scripts/report.py+++ b/scripts/report.py@@ -19,7 +19,7 @@ import tempfilefrom pathlib import Pathfrom 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, probeHERE = 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)diff --git a/tests/release_check.sh b/tests/release_check.shindex b8b682a..fd97e1e 100755--- a/tests/release_check.sh+++ b/tests/release_check.sh@@ -4,7 +4,10 @@# 2. the tarball installs via the real installer into a temp HOME# 3. every installed script answers --help# 4. the MCP server lists tools-# 5. (optional, --corpus) tests/corpus.py --expect --quick on downloaded real files+# 5. contract --json from the packed copy and the installed copy; every declared tool exists and answers --help+# 6. MCP tools/list == contract tools; doctor finds every required capability+# 7. test suites (tests/test_all.py, tests/test_contract.py) and the contract evals+# 8. (optional, --corpus) tests/corpus.py --expect --quick on downloaded real filesset -euo pipefailROOT="$(cd "$(dirname "$0")/.." && pwd)"cd "$ROOT"@@ -15,7 +18,7 @@ echo "== 1. pack contents"npm pack --pack-destination "$TMP" >/dev/null 2>&1TGZ="$(ls "$TMP"/*.tgz)"LIST="$(tar -tzf "$TGZ")"-for need in package/SKILL.md package/scripts/_common.py package/scripts/probe.py package/references/scripts.md package/references/devices.md package/mcp/server.py package/bin/install.js; do+for need in package/SKILL.md package/scripts/_common.py package/scripts/_contract.py package/scripts/probe.py package/references/scripts.md package/references/devices.md package/mcp/server.py package/bin/install.js; doecho "$LIST" | grep -qx "$need" || { echo "FAIL: $need missing from the package"; exit 1; }doneecho " ok ($(echo "$LIST" | wc -l | tr -d ' ') files)"@@ -24,7 +27,7 @@ echo "== 2. install from the tarball into a temp HOME"mkdir -p "$TMP/home" "$TMP/pkg"tar -xzf "$TGZ" -C "$TMP/pkg"HOME="$TMP/home" node "$TMP/pkg/package/bin/install.js" >/dev/null-for d in SKILL.md scripts references mcp; do+for d in SKILL.md scripts references mcp package.json; do[ -e "$TMP/home/.claude/skills/ffmpeg-skill/$d" ] || { echo "FAIL: $d not installed"; exit 1; }doneecho " ok"@@ -41,8 +44,43 @@ n="$(python3 "$TMP/home/.claude/skills/ffmpeg-skill/mcp/server.py" --list | wc -[ "$n" -ge 15 ] || { echo "FAIL: MCP server lists only $n tools"; exit 1; }echo " ok ($n tools)"+INST="$TMP/home/.claude/skills/ffmpeg-skill"+echo "== 5. contract from the packed and the installed copy"+node "$TMP/pkg/package/bin/install.js" contract --json --static > "$TMP/contract_pkg.json" || { echo "FAIL: contract --json (packed)"; exit 1; }+python3 "$INST/scripts/_contract.py" --json --static > "$TMP/contract_inst.json" || { echo "FAIL: contract --json (installed)"; exit 1; }+python3 - "$TMP/contract_pkg.json" "$TMP/contract_inst.json" "$INST" "$ROOT" <<'PY'+import json, subprocess, sys+pkg, inst, skill, root = json.load(open(sys.argv[1])), json.load(open(sys.argv[2])), sys.argv[3], sys.argv[4]+assert pkg["tools"] == inst["tools"], "packed and installed contracts differ"+assert pkg["skill"]["version"] == json.load(open(root + "/package.json"))["version"], "installed contract has the wrong version"+assert "contract_version" in pkg and pkg["contract_version"] != pkg["skill"]["version"]+for t in pkg["tools"]:+ path = skill + "/" + t["executable"]+ subprocess.run([sys.executable, path, "--help"], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)+print(f" ok ({len(pkg['tools'])} tools, contract {pkg['contract_version']}, skill {pkg['skill']['version']})")+PY++echo "== 6. MCP tools == contract tools; doctor"+python3 - "$TMP/contract_inst.json" "$INST" <<'PY'+import json, subprocess, sys+doc = json.load(open(sys.argv[1]))+listed = subprocess.run([sys.executable, sys.argv[2] + "/mcp/server.py", "--list"], stdout=subprocess.PIPE, text=True, check=True).stdout+names = {l.split()[0] for l in listed.splitlines() if l.strip()}+want = {t["name"] for t in doc["tools"]}+assert names == want, f"MCP {sorted(names ^ want)} differs from contract"+print(f" ok ({len(names)} tools)")+PY+python3 "$INST/scripts/_contract.py" doctor >/dev/null || { echo "FAIL: doctor reports missing required capabilities"; python3 "$INST/scripts/_contract.py" doctor; exit 1; }+echo " doctor ok"++echo "== 7. tests and contract evals"+python3 tests/test_all.py >"$TMP/test_all.log" 2>&1 || { tail -30 "$TMP/test_all.log"; echo "FAIL: tests/test_all.py"; exit 1; }+python3 tests/test_contract.py >"$TMP/test_contract.log" 2>&1 || { tail -30 "$TMP/test_contract.log"; echo "FAIL: tests/test_contract.py"; exit 1; }+python3 evals/contract/check.py >/dev/null || { echo "FAIL: evals/contract/check.py"; exit 1; }+echo " ok"+if [ "${1:-}" = "--corpus" ]; then- echo "== 5. real-device corpus (quick)"+ echo "== 8. real-device corpus (quick)"python3 tests/corpus.py --expect --verify --quickfiecho "release check passed: $(node -p "require('./package.json').version")"diff --git a/tests/test_contract.py b/tests/test_contract.pynew file mode 100644index 0000000..1310eb0--- /dev/null+++ b/tests/test_contract.py@@ -0,0 +1,460 @@+#!/usr/bin/env python3+"""Contract tests: the machine-readable execution contract matches the scripts, the MCP+server and the installer, and every ToolSpec claim (dry-run, JSON shape, input preservation,+verification policy) holds when the tool actually runs.++ python3 tests/test_contract.py+"""+import json+import os+import re+import shutil+import subprocess+import sys+import tempfile+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+SCRIPTS = ROOT / "scripts"+OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))+CORPUS = ROOT / "tests" / "corpus"+sys.path.insert(0, str(SCRIPTS))+sys.path.insert(0, str(ROOT / "mcp"))+import _contract # noqa: E402+import server as mcp_server # noqa: E402+++def sh(*cmd, check=True, env=None, cwd=None):+ proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env, cwd=cwd)+ if check and proc.returncode != 0:+ raise AssertionError(f"{cmd}\nSTDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}")+ return proc+++def ffmpeg(*args):+ return sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", *args)+++def tool(name, *args, **kw):+ return sh(sys.executable, SCRIPTS / f"{name}.py", *args, **kw)+++TONE = "0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.2)+0.3*sin(2*PI*660*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"+++class ContractTests(unittest.TestCase):+ @classmethod+ def setUpClass(cls):+ if not shutil.which("ffmpeg") or not shutil.which("ffprobe"):+ raise unittest.SkipTest("ffmpeg/ffprobe not on PATH")+ OUT.mkdir(parents=True, exist_ok=True)+ cls.contract = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "--json").stdout)+ cls.static = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "--json", "--static").stdout)+ cls.tools = {t["name"]: t for t in cls.contract["tools"]}+ # fixtures: normal MP4, VFR, HDR10, audio-only, 5.1, external audio, second camera+ cls.src = OUT / "c_source.mp4"+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONE}':s=48000",+ "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", "-c:a", "aac", cls.src)+ cls.wav = OUT / "c_tone.wav"+ ffmpeg("-i", cls.src, "-vn", "-c:a", "pcm_s16le", cls.wav)+ cls.mic = OUT / "c_mic.wav"+ ffmpeg("-ss", "1.5", "-i", cls.src, "-vn", "-c:a", "pcm_s16le", cls.mic)+ cls.camb = OUT / "c_camB.mp4"+ ffmpeg("-ss", "0.7", "-i", cls.src, "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", cls.camb)+ cls.vfr = OUT / "c_vfr.mp4"+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "4", "-vf", "select='not(mod(n\\,3))',setpts=N/20/TB",+ "-vsync", "vfr", "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", cls.vfr)+ cls.hdr = OUT / "c_hdr10.mp4"+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "2", "-c:v", "libx265", "-preset", "ultrafast", "-pix_fmt", "yuv420p10le",+ "-x265-params", "log-level=error:colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc", "-tag:v", "hvc1", cls.hdr)+ cls.surround = OUT / "c_surround.mov"+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-f", "lavfi", "-i", "aevalsrc='0.4*sin(2*PI*300*t)|0.4*sin(2*PI*400*t)|0.4*sin(2*PI*500*t)|0.1*sin(2*PI*60*t)|0.2*sin(2*PI*700*t)|0.2*sin(2*PI*800*t)':c=5.1:s=48000",+ "-t", "3", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", cls.surround)+ cls.logo = OUT / "c_logo.png"+ ffmpeg("-f", "lavfi", "-i", "[email protected]:s=120x40,format=rgba", "-frames:v", "1", cls.logo)+ cls.cues = OUT / "c_cues.txt"+ cls.cues.write_text("0:00-0:02 Hello\n0:02-0:04 World\n", encoding="utf-8")+ cls.work = Path(tempfile.mkdtemp(prefix="ffskill_contract_"))+ cls.input_hashes = {p: cls._sha(p) for p in (cls.src, cls.wav, cls.mic, cls.camb, cls.vfr, cls.hdr, cls.surround)}++ @staticmethod+ def _sha(path):+ import hashlib+ return hashlib.sha256(Path(path).read_bytes()).hexdigest()++ def out(self, name):+ return self.work / name++ # ------------------------------------------------------------------ unit: schema and metadata+ def test_contract_schema(self):+ c = self.contract+ for key in ("contract_version", "skill", "requirements", "execution", "invocation", "roles", "capabilities", "tools", "verification_policy", "json_output"):+ self.assertIn(key, c)+ self.assertEqual(c["skill"]["id"], "ffmpeg-skill")+ self.assertEqual(c["skill"]["execution_mode"], "local")+ self.assertFalse(c["execution"]["shell"])+ self.assertFalse(c["execution"]["arbitrary_executables"])+ self.assertTrue(c["invocation"]["structured"]["canonical"])+ self.assertFalse(c["invocation"]["raw_argv"]["canonical"])++ def test_skill_metadata_and_version_separation(self):+ pkg = json.loads((ROOT / "package.json").read_text())+ self.assertEqual(self.contract["skill"]["version"], pkg["version"])+ self.assertEqual(self.contract["contract_version"], _contract.CONTRACT_VERSION)+ self.assertNotEqual(self.contract["contract_version"], self.contract["skill"]["version"])+ self.assertTrue(re.fullmatch(r"\d+\.\d+", self.contract["contract_version"]))+ self.assertIn("Edit video and audio", self.contract["skill"]["description"])+ for t in self.contract["tools"]:+ self.assertEqual(t["version"], pkg["version"])++ def test_tool_ids_unique_and_canonical(self):+ ids = [t["id"] for t in self.contract["tools"]]+ self.assertEqual(len(ids), len(set(ids)))+ for t in self.contract["tools"]:+ self.assertEqual(t["id"], f"ffmpeg-skill/{t['name']}")+ self.assertTrue(re.fullmatch(r"[a-z]+", t["name"]), t["id"])+ self.assertEqual(ids, sorted(ids), "tools are listed in a stable, sorted order")++ def test_every_tool_executable_exists_and_internal_scripts_are_hidden(self):+ for t in self.contract["tools"]:+ self.assertTrue((ROOT / t["executable"]).is_file(), t["executable"])+ self.assertEqual(t["executable"], f"scripts/{t['name']}.py")+ names = {t["name"] for t in self.contract["tools"]}+ self.assertNotIn("_common", names)+ self.assertNotIn("_contract", names)+ public = {p.stem for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")}+ self.assertEqual(names, public, "contract tools == public scripts")++ def test_capabilities_declared_only_where_used(self):+ caps = self.contract["capabilities"]+ self.assertIn("ffmpeg", caps["required"])+ self.assertIn("ffprobe", caps["required"])+ for cap in caps["required"] + caps["optional"]:+ self.assertTrue(re.fullmatch(r"ffmpeg|ffprobe|encoder:\w+|filter:\w+|bsf:\w+|external:\w+", cap), cap)+ # every encoder / filter / bsf named in the contract is referenced by some script+ source = "\n".join(p.read_text(encoding="utf-8") for p in SCRIPTS.glob("*.py"))+ for cap in caps["required"] + caps["optional"]:+ if ":" in cap and not cap.startswith("external:"):+ self.assertIn(cap.split(":", 1)[1], source, f"{cap} declared but no script uses it")+ for t in self.contract["tools"]:+ for cap in t["capabilities"]["required"]:+ self.assertIn(cap, caps["required"])+ for o in t["capabilities"]["optional"]:+ self.assertIn("when", o)+ self.assertNotIn("available", self.static["capabilities"], "--static omits detection")+ self.assertIn("available", caps)+ self.assertEqual(sorted(caps["missing"]), sorted(set(caps["required"]) - set(caps["available"])))++ def test_request_schema_matches_argparse(self):+ for t in self.contract["tools"]:+ schema = t["input_schema"]+ self.assertEqual(schema["type"], "object")+ self.assertFalse(schema["additionalProperties"])+ help_text = tool(t["name"], "--help").stdout+ for dest, prop in schema["properties"].items():+ self.assertIn(prop["type"], ("string", "integer", "number", "boolean", "array"), f"{t['name']}.{dest}")+ if prop["cli"] != "positional":+ for flag in prop["cli"]:+ self.assertIn(flag, help_text, f"{t['name']}: {flag} not in --help")+ longs = [f for f in prop["cli"] if f.startswith("--")]+ exc = t["mcp"]["argument_exceptions"]+ if "--" + dest.replace("_", "-") not in longs:+ self.assertIn(dest, exc, f"{t['name']}: {dest} needs an argument exception")+ self.assertIn(exc[dest], prop["cli"])+ for pos in schema["positional"]:+ self.assertIn(pos, schema["properties"])+ for req in schema["required"]:+ self.assertIn(req, schema["properties"])+ cut = self.tools["cut"]["input_schema"]["properties"]+ self.assertEqual(cut["input"]["cli"], "positional")+ self.assertEqual(cut["accurate"]["type"], "boolean")+ self.assertEqual(cut["crf"]["type"], "integer")+ self.assertEqual(self.tools["export"]["input_schema"]["properties"]["preset"]["enum"], sorted(self.tools["export"]["input_schema"]["properties"]["preset"]["enum"]))++ def test_response_schema(self):+ for t in self.contract["tools"]:+ schema = t["output_schema"]+ self.assertEqual(schema["type"], "object")+ if t["name"] != "probe":+ for key in ("status", "output", "dry_run", "commands"):+ self.assertIn(key, schema["required"], t["name"])+ self.assertEqual(self.contract["json_output"]["success"]["status"], "completed")+ self.assertEqual(self.contract["json_output"]["failure"]["status"], "failed")++ def test_dry_run_metadata(self):+ for t in self.contract["tools"]:+ has_flag = "dry_run" in t["input_schema"]["properties"]+ self.assertEqual(t["supports_json"], "json" in t["input_schema"]["properties"])+ if t["name"] == "verify":+ self.assertFalse(t["supports_dry_run"], "verify runs its steps regardless of --dry-run")+ else:+ self.assertEqual(t["supports_dry_run"], has_flag, t["name"])+ self.assertEqual(t["dry_run"]["supported"], t["supports_dry_run"])++ def test_verification_metadata_matches_skill_workflow(self):+ for t in self.contract["tools"]:+ v = t["verification"]+ self.assertEqual(v["required"], bool(v["tools"]))+ for ref in v["tools"]:+ self.assertIn(ref.split("/")[1], self.tools, ref)+ self.assertIn(self.tools[ref.split("/")[1]]["role"], ("analysis", "verification"))+ if t["role"] in ("analysis", "verification"):+ self.assertFalse(v["required"], f"{t['name']} does not need post-verification")+ if t["produces_artifact"] and t["role"] == "execution":+ self.assertIn("ffmpeg-skill/probe", v["tools"], f"{t['name']}: probe first, verify last")+ self.assertEqual(self.tools["export"]["verification"]["tools"], ["ffmpeg-skill/probe", "ffmpeg-skill/check"])+ self.assertEqual(self.tools["cut"]["verification"]["tools"], ["ffmpeg-skill/probe"])++ def test_visual_verification_metadata(self):+ picture = {"fit", "caption", "overlay", "graphics", "color", "join", "multicam", "render"}+ for t in self.contract["tools"]:+ self.assertEqual(t["requires_visual_verification"], t["name"] in picture, t["name"])+ if t["requires_visual_verification"]:+ self.assertIn("ffmpeg-skill/look", t["verification"]["tools"])+ self.assertTrue(t["video_required"])+ self.assertFalse(t["audio_only"])+ if t["audio_only"]:+ self.assertFalse(t["requires_visual_verification"], f"{t['name']}: audio-only tools never need look.py")+ for name in ("loudness", "silence", "audio", "cut", "sync", "probe", "check"):+ self.assertTrue(self.tools[name]["audio_only"], name)+ # SKILL.md says the same thing+ skill = (ROOT / "SKILL.md").read_text(encoding="utf-8")+ self.assertIn("Look: not needed", skill)++ def test_original_preservation_and_roles(self):+ for t in self.contract["tools"]:+ self.assertFalse(t["mutates_input"], t["name"])+ self.assertIn(t["role"], self.contract["roles"])+ self.assertIn(t["idempotency_hint"], self.contract["idempotency_hints"])+ self.assertEqual(self.tools["probe"]["role"], "analysis")+ self.assertEqual(self.tools["silence"]["role"], "analysis_and_execution")+ self.assertEqual(self.tools["loudness"]["role"], "analysis_and_execution")+ self.assertEqual(self.tools["cut"]["role"], "execution")+ self.assertEqual(self.tools["export"]["role"], "execution")+ for name in ("check", "look", "verify"):+ self.assertEqual(self.tools[name]["role"], "verification")+ self.assertFalse(self.tools["verify"]["deterministic_inputs"])+ self.assertTrue(self.tools["probe"]["deterministic_inputs"])++ def test_json_determinism(self):+ a = sh(sys.executable, SCRIPTS / "_contract.py", "--json").stdout+ b = sh(sys.executable, SCRIPTS / "_contract.py", "--json").stdout+ self.assertEqual(a, b)+ doc = json.loads(a)+ self.assertEqual(json.dumps(doc, sort_keys=True), json.dumps(doc, sort_keys=True))+ self.assertEqual(list(json.loads(a).keys()), sorted(json.loads(a).keys()), "top-level keys sorted")++ # ------------------------------------------------------------------ consistency: MCP and installer+ def test_mcp_tools_match_contract(self):+ mcp_names = [t["name"] for t in mcp_server.tool_list()]+ self.assertEqual(sorted(mcp_names), sorted(self.tools), "MCP tools/list == contract tools")+ listed = [l.split()[0] for l in sh(sys.executable, ROOT / "mcp" / "server.py", "--list").stdout.splitlines() if l.strip()]+ self.assertEqual(sorted(listed), sorted(self.tools))+ for name, spec in self.tools.items():+ self.assertEqual(spec["mcp"]["tool"], name)+ self.assertEqual(spec["mcp"]["positional"], mcp_server.POSITIONAL.get(name, ["input"]) if spec["mcp"]["positional"] else spec["mcp"]["positional"])+ # a real JSON-RPC round trip+ req = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/list"}) + "\n"+ proc = subprocess.run([sys.executable, str(ROOT / "mcp" / "server.py")], input=req, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ resp = json.loads(proc.stdout.strip().splitlines()[0])+ self.assertEqual(sorted(t["name"] for t in resp["result"]["tools"]), sorted(self.tools))++ def test_installer_payload_matches_contract(self):+ js = (ROOT / "bin" / "install.js").read_text(encoding="utf-8")+ payload = re.search(r"const PAYLOAD = \[(.*?)\];", js).group(1)+ self.assertIn("'scripts'", payload)+ self.assertIn("'mcp'", payload)+ self.assertIn("'package.json'", payload, "installed skill needs package.json for the skill version")+ files = json.loads((ROOT / "package.json").read_text())["files"]+ self.assertIn("scripts/", files)+ self.assertIn("mcp/", files)+ self.assertIn("bin/", files)+ # the npm entry point answers `contract --json` and `doctor`+ doc = json.loads(sh("node", ROOT / "bin" / "install.js", "contract", "--json", "--static").stdout)+ self.assertEqual([t["id"] for t in doc["tools"]], [t["id"] for t in self.contract["tools"]])+ self.assertEqual(sh("node", ROOT / "bin" / "install.js", "doctor", "--json").returncode, 0)++ def test_contract_from_installed_copy(self):+ with tempfile.TemporaryDirectory() as tmp:+ env = dict(os.environ, HOME=tmp)+ sh("node", ROOT / "bin" / "install.js", env=env)+ installed = Path(tmp) / ".claude" / "skills" / "ffmpeg-skill"+ doc = json.loads(sh(sys.executable, installed / "scripts" / "_contract.py", "--json", "--static").stdout)+ self.assertEqual(doc["skill"]["version"], self.contract["skill"]["version"])+ self.assertEqual([t["id"] for t in doc["tools"]], [t["id"] for t in self.contract["tools"]])+ for t in doc["tools"]:+ self.assertTrue((installed / t["executable"]).is_file())++ # ------------------------------------------------------------------ integration: claims hold at run time+ def test_dry_run_never_runs_ffmpeg_and_writes_nothing(self):+ """A fake ffmpeg first on PATH records every invocation; ffprobe stays real."""+ shim = self.work / "shim"+ shim.mkdir(exist_ok=True)+ marker = self.work / "ffmpeg_was_called"+ (shim / "ffmpeg").write_text(f"#!/bin/sh\necho called >> {marker}\nexit 1\n")+ (shim / "ffmpeg").chmod(0o755)+ env = dict(os.environ, PATH=f"{shim}:{os.environ['PATH']}")+ outdir = self.work / "dry"+ outdir.mkdir(exist_ok=True)+ cases = {+ "cut": [self.src, "--start", "1", "--end", "3", "-o", outdir / "cut.mp4"],+ "fit": [self.src, "--duration", "3", "-o", outdir / "fit.mp4"],+ "caption": [self.src, "--text", self.cues, "-o", outdir / "cap.mp4"],+ "overlay": [self.src, "--image", self.logo, "-o", outdir / "ov.mp4"],+ "graphics": [self.src, "--template", "title", "--title", "T", "-o", outdir / "gfx.mp4"],+ "sync": [self.src, self.mic, "--replace-audio", "-o", outdir / "sync.mp4"],+ "multicam": [self.src, self.camb, "--switch", "0-2:0,2-4:1", "-o", outdir / "mc.mp4"],+ "audio": [self.src, "--voice", "-o", outdir / "au.mp4"],+ "loudness": [self.src, "-o", outdir / "ld.mp4"],+ "silence": [self.src, "-o", outdir / "sil.mp4"],+ "join": [self.src, self.camb, "-o", outdir / "join.mp4"],+ "color": [self.hdr, "--to-sdr", "-o", outdir / "col.mp4"],+ "export": [self.src, "--preset", "x", "-o", outdir / "exp.mp4"],+ "scenes": [self.src, "--sheet", outdir / "sc.png", "--edl", outdir / "sc.txt"],+ "look": [self.src, "-o", outdir / "look.png"],+ "report": ["--after", self.src, "-o", outdir / "rep.html"],+ }+ for name, args in cases.items():+ spec = self.tools[name]+ self.assertTrue(spec["supports_dry_run"], name)+ strict = spec["dry_run"]["ffmpeg_execution"] == "none"+ # tools whose measurement needs ffmpeg (sync, multicam, scenes, report) run with the real ffmpeg+ proc = tool(name, *args, "--dry-run", "--json", env=env if strict else None, check=False)+ self.assertEqual(proc.returncode, 0, f"{name} --dry-run failed:\n{proc.stderr}")+ doc = json.loads(proc.stdout)+ self.assertTrue(doc["dry_run"], name)+ self.assertNotIn("probe", doc, f"{name}: dry-run must not claim an output probe")+ self.assertNotIn("\nwrote ", proc.stderr, name)+ self.assertEqual(sorted(p.name for p in outdir.iterdir()), [], f"{name} --dry-run wrote files")+ if strict:+ self.assertFalse(marker.exists(), f"{name} --dry-run invoked ffmpeg")+ self.assertEqual({n for n, s in self.tools.items() if s["dry_run"]["ffmpeg_execution"] == "analysis_only"}, {"sync", "multicam", "scenes", "report"})+ # the read-only tools keep working under --dry-run (ffprobe still runs)+ self.assertEqual(tool("probe", self.src, "--dry-run", env=env).returncode, 0)+ self.assertEqual(tool("check", self.src, "--platform", "x", "--no-loudness", "--dry-run", env=env).returncode, 0)++ def test_json_success_and_failure_shapes_and_exit_codes(self):+ doc = json.loads(tool("cut", self.wav, "--start", "1", "--end", "3", "-o", self.out("shape.wav"), "--json").stdout)+ self.assertEqual(doc["status"], "completed")+ for key in self.tools["cut"]["output_schema"]["required"]:+ self.assertIn(key, doc)+ self.assertIn("probe", doc)+ proc = tool("cut", self.work / "missing.mp4", "--json", check=False)+ self.assertEqual(proc.returncode, 1)+ err = json.loads(proc.stdout)+ self.assertEqual(err["status"], "failed")+ self.assertEqual(err["error"]["kind"], "input")+ self.assertIn("not found", err["error"]["message"])+ self.assertIn("error:", proc.stderr, "stderr message kept for existing callers")+ # without --json the old behaviour is unchanged: empty stdout, message on stderr+ proc = tool("cut", self.work / "missing.mp4", check=False)+ self.assertEqual(proc.stdout, "")+ self.assertEqual(proc.returncode, 1)+ # missing ffmpeg -> exit 127, kind missing_tool+ env = dict(os.environ, PATH=str(self.work / "empty"))+ (self.work / "empty").mkdir(exist_ok=True)+ proc = tool("loudness", self.src, "--json", env=env, check=False)+ self.assertEqual(proc.returncode, 127)+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "missing_tool")++ def _run_structured(self, name, args):+ """Drive a tool the way an agent adapter would: structured args -> argv (same mapping as MCP)."""+ argv = mcp_server.build_argv(name, args)+ proc = tool(name, *argv, check=False)+ self.assertEqual(proc.returncode, 0, f"{name} {argv}\n{proc.stderr}")+ return json.loads(proc.stdout) if proc.stdout.strip().startswith(("{", "[")) else proc.stdout++ def _verify(self, name, output):+ """Apply the ToolSpec verification policy to an artifact."""+ for ref in self.tools[name]["verification"]["tools"]:+ vt = ref.split("/")[1]+ if vt == "probe":+ meta = self._run_structured("probe", {"inputs": [str(output)]})+ self.assertGreater(meta["duration"], 0)+ elif vt == "check":+ self._run_structured("check", {"input": str(output), "platform": "custom"})+ elif vt == "look":+ doc = self._run_structured("look", {"input": str(output), "output": str(self.out(f"{name}_look.png")), "json": True})+ self.assertTrue(Path(doc["output"]).exists())++ def test_probe_cut_silence_loudness_sync_audio_via_contract(self):+ meta = self._run_structured("probe", {"inputs": [str(self.src)]})+ self.assertEqual(meta["video"]["width"], 640)+ doc = self._run_structured("cut", {"input": str(self.src), "start": "1", "end": "3", "output": str(self.out("cut.mp4"))})+ self.assertAlmostEqual(doc["probe"]["duration"], 2.0, delta=0.6)+ self._verify("cut", doc["output"])+ doc = self._run_structured("silence", {"input": str(self.src), "output": str(self.out("silence.mp4"))})+ self.assertLessEqual(doc["probe"]["duration"], 6.1)+ self._verify("silence", doc["output"])+ doc = self._run_structured("loudness", {"input": str(self.wav), "lufs": -16, "tp": -1.5, "output": str(self.out("loud.m4a"))})+ self.assertEqual(doc["probe"]["audio"]["codec"], "aac")+ self._verify("loudness", doc["output"])+ doc = self._run_structured("sync", {"reference": str(self.src), "second": str(self.mic)})+ self.assertAlmostEqual(doc["offset_seconds"], 1.5, delta=0.05)+ doc = self._run_structured("sync", {"reference": str(self.src), "second": str(self.mic), "replace_audio": True, "output": str(self.out("synced.mp4"))})+ self._verify("sync", doc["output"])+ doc = self._run_structured("audio", {"input": str(self.surround), "downmix": True, "output": str(self.out("stereo.mov"))})+ self.assertEqual(doc["probe"]["audio"]["channels"], 2)+ self._verify("audio", doc["output"])++ def test_color_overlay_caption_export_check_look_render_via_contract(self):+ doc = self._run_structured("color", {"input": str(self.hdr), "to_sdr": True, "fast": True, "output": str(self.out("sdr.mp4"))})+ self.assertFalse(doc["probe"]["video"]["hdr"])+ self._verify("color", doc["output"])+ doc = self._run_structured("overlay", {"input": str(self.src), "image": str(self.logo), "position": "top-right", "fast": True, "output": str(self.out("ov.mp4"))})+ self._verify("overlay", doc["output"])+ doc = self._run_structured("caption", {"input": str(self.src), "text": str(self.cues), "fast": True, "output": str(self.out("cap.mp4"))})+ self._verify("caption", doc["output"])+ doc = self._run_structured("export", {"input": str(self.vfr), "preset": "x", "fast": True, "output": str(self.out("vfr_x.mp4"))})+ self.assertFalse(doc["probe"]["video"].get("variable_frame_rate_suspected"))+ self._verify("export", doc["output"])+ chk = self._run_structured("check", {"input": doc["output"], "platform": "x"})+ self.assertIn("checks", chk)+ look = self._run_structured("look", {"input": doc["output"], "output": str(self.out("sheet.png")), "json": True})+ self.assertTrue(Path(look["output"]).exists())+ project = self.out("project.json")+ project.write_text(json.dumps({"output": str(self.out("render.mp4")), "frame": {"aspect": "9:16", "width": 360, "fps": 30},+ "clips": [{"src": str(self.src), "in": 0, "out": 3}], "export": {"preset": "reels"}, "check": {"platform": "reels"}}), encoding="utf-8")+ doc = self._run_structured("render", {"project": str(project), "fast": True})+ self.assertEqual(doc["status"], "completed")+ self._verify("render", doc["output"])++ def test_mcp_tool_call_round_trip(self):+ req = json.dumps({"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "probe", "arguments": {"inputs": [str(self.wav)]}}}) + "\n"+ proc = subprocess.run([sys.executable, str(ROOT / "mcp" / "server.py")], input=req, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ resp = json.loads(proc.stdout.strip().splitlines()[0])+ self.assertIsNone(resp["result"]["structuredContent"]["video"])+ self.assertEqual(resp["result"]["structuredContent"]["audio"]["codec"], "pcm_s16le")++ def test_every_tool_help_and_no_shell_paths(self):+ for t in self.contract["tools"]:+ self.assertIn("usage:", tool(t["name"], "--help").stdout)+ for path in list(SCRIPTS.glob("*.py")) + [ROOT / "mcp" / "server.py"]:+ src = path.read_text(encoding="utf-8")+ for forbidden in ("shell=True", "os.system(", "eval(", "exec(", "os.popen("):+ self.assertNotIn(forbidden, src, f"{path.name} uses {forbidden}")++ def test_inputs_untouched_after_the_run(self):+ for path, digest in self.input_hashes.items():+ self.assertEqual(self._sha(path), digest, f"{path.name} was modified by a tool")++ def test_real_device_corpus_when_present(self):+ wanted = [CORPUS / n for n in ("iphone13pro_4K60p.mov", "android_screen_1.mp4", "dji_DJI_0038.MOV", "gopro_GX010743.MP4")]+ present = [p for p in wanted if p.exists()]+ if not present:+ self.skipTest("real-device corpus not downloaded (tests/corpus.py --fetch)")+ for p in present:+ meta = self._run_structured("probe", {"inputs": [str(p)]})+ before = self._sha(p) if p.stat().st_size < 50_000_000 else p.stat().st_size+ doc = self._run_structured("cut", {"input": str(p), "start": "0", "end": "2", "tolerance": -1, "output": str(self.out(p.stem + "_cut" + p.suffix))})+ self._verify("cut", doc["output"])+ self._run_structured("check", {"input": doc["output"], "platform": "custom", "no_loudness": True})+ if meta.get("video"):+ self._run_structured("look", {"input": doc["output"], "output": str(self.out(p.stem + "_look.png")), "json": True})+ after = self._sha(p) if p.stat().st_size < 50_000_000 else p.stat().st_size+ self.assertEqual(before, after, f"{p.name} modified")+++if __name__ == "__main__":+ unittest.main(verbosity=2)