Skip to content

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.

Machine-readable execution contract: contract --json, doctor, ToolSpecs, contract tests (#18)

Shogo Kajiyamaa3882fd8cb68
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 (sl
python3 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.
## Requirements
diff --git a/bin/install.js b/bin/install.js
index 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.md
new file mode 100644
index 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 release
diff --git a/evals/contract/README.md b/evals/contract/README.md
new file mode 100644
index 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.py
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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 file
diff --git a/mcp/server.py b/mcp/server.py
index 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.json
index 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.py
index 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.py
new file mode 100644
index 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.py
index b004fb0..3197615 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -23,7 +23,7 @@ import sys
from pathlib import Path
from 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_args
ALIGN = {"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.py
index f15e72e..509d298 100755
--- a/scripts/report.py
+++ b/scripts/report.py
@@ -19,7 +19,7 @@ import tempfile
from pathlib import Path
from typing import Any, Dict, List, Optional
-from _common import add_common, apply_common, die, emit, info, probe
+from _common import STATE, add_common, apply_common, die, emit, info, probe
HERE = Path(__file__).resolve().parent
@@ -150,8 +150,11 @@ def main() -> int:
.foot{color:var(--ink2);font-size:12px;margin-top:36px;border-top:1px solid var(--line);padding-top:10px}
"""
doc = f"<!doctype html><html><head><meta charset='utf-8'><meta name='viewport' content='width=device-width,initial-scale=1'><title>{html.escape(title)}</title><style>{css}</style></head><body><div class='wrap'>{''.join(parts)}</div></body></html>"
- Path(output).write_text(doc, encoding="utf-8")
- info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
+ if STATE.dry_run:
+ info(f"wrote {output}") # printed as "[dry-run] would write"; nothing is written
+ else:
+ Path(output).write_text(doc, encoding="utf-8")
+ info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
emit(None, report=output, check=chk)
if not args.json:
print(output)
diff --git a/tests/release_check.sh b/tests/release_check.sh
index 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 files
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$ROOT"
@@ -15,7 +18,7 @@ echo "== 1. pack contents"
npm pack --pack-destination "$TMP" >/dev/null 2>&1
TGZ="$(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; do
echo "$LIST" | grep -qx "$need" || { echo "FAIL: $need missing from the package"; exit 1; }
done
echo " 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; }
done
echo " 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 --quick
fi
echo "release check passed: $(node -p "require('./package.json').version")"
diff --git a/tests/test_contract.py b/tests/test_contract.py
new file mode 100644
index 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)