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.

Add provides: publish Capability ids for cross-repository discovery

Claude08bd18c8486d
diff --git a/README.md b/README.md
index 119d4fe..1da5703 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
-4. **Machine-readable contract.** `contract --json` describes all 21 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`.
+4. **Machine-readable contract.** `contract --json` describes all 21 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 21 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.
diff --git a/docs/contract.md b/docs/contract.md
index d54ca1f..fe068b5 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -119,6 +119,23 @@ gives you:
| `cached` | batch (content-hash cache, re-runs skip unchanged inputs) |
| `environment_dependent` | verify |
+## `provides`
+
+`provides` lists these 21 tools by a cross-repository Capability id, for
+`kajisho5/AI-video-production-OS`'s `CapabilityContract.provides`
+(`docs/SPEC.md` there), matching the ids already assigned to this Skill in
+that project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill's
+21 raw tools ... are Capabilities in their own right, independent of the
+higher-level Skills that delegate to them"): `[{"id": "ffmpeg-skill.<tool>",
+"lifecycle": "EXPERIMENTAL", "tool_id": "ffmpeg-skill/<tool>"}, ...]`, one
+entry per tool, sorted by id. The Capability id uses a dot
+(`ffmpeg-skill.cut`) - the `<domain>.<verb>` shape every other Skill's
+Capability ids use elsewhere in that project (`video.trim`, `audio.gain`,
+...), with `ffmpeg-skill` as the domain - while `tool_id` carries this
+contract's own slash-shaped `id` (`ffmpeg-skill/cut`) unchanged. It is
+purely additive: derived from `public_tools()`, saying nothing `tools[]`
+doesn't already say, only indexed by Capability id instead of tool name.
+
## Capabilities
Names: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,
diff --git a/scripts/_contract.py b/scripts/_contract.py
index e7f0b33..50a1d08 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -450,6 +450,18 @@ def doctor() -> Dict[str, Any]:
}
+# Cross-repository Capability ids (kajisho5/AI-video-production-OS docs/SPEC.md
+# `CapabilityContract.provides`), matching the ids already assigned to these 21 tools in
+# that project's own docs/CAPABILITY_MATRIX.md section 9: "ffmpeg-skill's 21 raw tools ...
+# are Capabilities in their own right, independent of the higher-level Skills that
+# delegate to them". Each tool's own id is `ffmpeg-skill/<tool>` (a slash, matching every
+# ToolSpec.id here); the Capability id uses a dot - `ffmpeg-skill.<tool>` - the same
+# `<domain>.<verb>`-shaped convention every other Skill's Capability ids use elsewhere in
+# that project (`video.trim`, `audio.gain`, ...), with "ffmpeg-skill" as the domain.
+def capability_provides() -> List[Dict[str, str]]:
+ return [{"id": f"{SKILL_ID}.{name}", "lifecycle": "EXPERIMENTAL", "tool_id": f"{SKILL_ID}/{name}"} for name in public_tools()]
+
+
# ----------------------------------------------------------------------------- contract
def tool_spec(name: str, version: str) -> Dict[str, Any]:
if name not in TOOL_META:
@@ -631,6 +643,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
},
"capabilities": caps,
"tools": tools,
+ "provides": capability_provides(),
}
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 2b7e5db..adf82dc 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -116,6 +116,18 @@ class ContractTests(unittest.TestCase):
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_provides_covers_every_tool_with_the_dotted_capability_id(self):
+ provides = self.contract["provides"]
+ ids = [p["id"] for p in provides]
+ self.assertEqual(len(ids), len(set(ids)))
+ self.assertEqual(ids, sorted(ids), "provides is listed in a stable, sorted order")
+ tool_ids = {t["id"] for t in self.contract["tools"]}
+ self.assertEqual({p["tool_id"] for p in provides}, tool_ids, "provides covers exactly the tools this build has")
+ for p in provides:
+ self.assertEqual(p["id"], p["tool_id"].replace("/", ".", 1))
+ self.assertEqual(p["lifecycle"], "EXPERIMENTAL")
+ self.assertEqual(set(p), {"id", "lifecycle", "tool_id"})
+
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"])