Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Add capability_map and proxy.py (abstract-capability resolution + low-bitrate analysis proxy) (#39)
Shogo Kajiyamad275e42019f3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 907a367..6a65c1b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@## Unreleased+- **`proxy.py`: low-bitrate proxy for downstream AI analysis, preview and editing decisions.** No tool here served a "cheap for a machine to decode" output distinct from `export.py`'s delivery presets, which all target near-visually-lossless platform delivery (CRF 18-24) rather than size/speed. `proxy.py` resizes to `--width` (default 640) or by `--scale` factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest x264/x265 preset, supports `--fps` and `--no-audio`, and keeps the source's own dynamic range (an HDR source proxies to HEVC10, same as every other re-encoding tool here — run `color.py --to-sdr` first if SDR is wanted). Pure mechanical resize+re-encode, same primitives `fit.py`/`export.py` already use: no new dependency, no GPU requirement, works identically regardless of source resolution (1080p/4K/6K/8K) or codec (H.264/H.265/ProRes, since ffmpeg's own decoders are already codec-agnostic everywhere in this repo). This tool only executes the spec it is given — it does not decide which asset should be proxied or what the proxy will be used for; that stays with the calling agent. `capability_map` gains `media.proxy` -> `proxy` (see below). Tests cover default width/CRF, `--scale`/`--no-audio`, forcing CFR on a VFR source, HDR passthrough, and dry-run.+- **`contract --json`: `capability_map`.** `provides` re-indexes each tool by an id shaped like its own name (`ffmpeg-skill.cut`); it doesn't let a planner that only knows an abstract goal ("I need to trim a video") find the right tool. `capability_map` is a new, small, hand-authored table: `[{"capability": "<domain>.<verb>", "tool_id": "ffmpeg-skill/<tool>", "params": {...}}, ...]`, covering `video.trim`, `video.reframe` (pins `fit` to `fit=crop`, since `fit.py` also duration-fits and pads), `audio.loudness`, `subtitle.burn`, `media.stream.inspect`, `media.frames.extract` and `media.proxy`. It is purely descriptive — a caller still builds and runs the named tool's own CLI/MCP call from its `input_schema`; this skill never picks a capability or executes on the caller's behalf. Deliberately excludes anything that would require judgment to resolve (no `video.highlight`, since `scenes.py --highlights` ranks by a measured proxy, not understood content). `docs/contract.md` documents the table and why it stays short; `tests/test_contract.py` verifies every entry resolves to a real tool and real params. Additive; no existing field changed.- **`doctor`: this installed copy's own `version`.** `doctor --json` and the human-readable `doctor` now report the version of the copy answering, read locally from its own `package.json` (same value `contract --json`'s `skill.version` reports) — never fetched from the network, never compared against the latest published release. A copy installed with `npx ffmpeg-skill` is not updated automatically; the human-readable output and the installer `--help`/README Quick start now say to re-run the installer to refresh it. Additive; every existing `doctor` key is unchanged.- **`doctor`: `ok` vs. per-tool `usable` clarified.** The human-readable `doctor` output now adds one line when `ok` is true but at least one tool's `usable` isn't `"yes"` (e.g. a plain Homebrew `ffmpeg` on macOS: overall `ok` since nothing required by *every* tool is missing, while `caption.py` specifically can't run). README Quick start says the same. No field changed, no behaviour changed — a caller reading `doctor` no longer has to already know to check `tools` separately from `ok`.- **`doctor`'s Windows fix hint for a missing subtitles/drawtext/zscale filter** now names the same remedy README documents for that platform (`winget install Gyan.FFmpeg`, since the gyan.dev full build carries them and a plain choco package can lack them) instead of falling through to a generic "install/build it" message — matching the existing macOS `brew install ffmpeg-full` hint. No change on any other platform.diff --git a/README.md b/README.mdindex a6240ff..1e7229d 100644--- a/README.md+++ b/README.md@@ -25,7 +25,7 @@ npx ffmpeg-skill-`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **27 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **28 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.@@ -131,7 +131,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth1. **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 27 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 27 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`.+4. **Machine-readable contract.** `contract --json` describes all 28 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 28 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.@@ -140,7 +140,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth## Tools-21 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.+22 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.**Analysis and inspection**@@ -187,6 +187,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth| Tool | What it does ||---|---|| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif`, all tagged BT.709 |+| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--crf`, `--fps`, `--no-audio`; not a delivery preset || `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, broadcast and podcast specs, with the fix for each failure and a `format` / `judgement` kind per row || `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run |@@ -222,7 +223,7 @@ npx ffmpeg-skill contract --json # or: python3 scripts/_contract.py -npx ffmpeg-skill contract --json --static # without environment detection```-The contract is generated from the code that runs, not maintained beside it. For each of the 27 tools (`ffmpeg-skill/<name>`) it states:+The contract is generated from the code that runs, not maintained beside it. For each of the 28 tools (`ffmpeg-skill/<name>`) it states:| Field | Meaning ||---|---|diff --git a/SKILL.md b/SKILL.mdindex 5da3c13..3971fb3 100644--- a/SKILL.md+++ b/SKILL.md@@ -80,7 +80,7 @@ This skill cuts, joins, measures, syncs, exports and checks files — it execute- **Thumbnail or cover-image composition** — that's a design decision, not a measurement; a thumbnail-generation skill or the user makes it.- **Understanding what a video is *about*** — this skill has no transcription or vision beyond `look.py`'s contact sheets, which exist for the calling agent's own eyes, not for this skill to interpret on its own.-If a request needs an FFmpeg feature none of the 27 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.+If a request needs an FFmpeg feature none of the 28 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.## Request → script@@ -110,6 +110,7 @@ If a request needs an FFmpeg feature none of the 27 scripts expose, say so and n| "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) || "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` || "make a GIF preview" | `export.py input.mp4 --preset gif` |+| "make a small/low-res proxy for an analysis pass", "a cheap preview file" | `proxy.py input.mp4 [--width 640 --no-audio]` — not a delivery preset, see `export.py` for those || "cut out the pauses / dead air", "tighten it up", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` || "stitch these clips together", "add a crossfade between them" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` || "show me what it looks like", "check the captions are readable" | `look.py output.mp4` then view the PNG |diff --git a/docs/contract.md b/docs/contract.mdindex 6c72602..f111516 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -122,7 +122,7 @@ gives you:## `provides`-`provides` lists these 27 tools by a cross-repository Capability id, for+`provides` lists these 28 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 inthat project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill's@@ -137,6 +137,38 @@ contract's own slash-shaped `id` (`ffmpeg-skill/cut`) unchanged. It ispurely additive: derived from `public_tools()`, saying nothing `tools[]`doesn't already say, only indexed by Capability id instead of tool name.+## `capability_map`++`provides` re-indexes each tool by an id shaped like the tool name+(`ffmpeg-skill.cut`); it doesn't tell a caller that "I need to trim a+video" resolves to `cut`. `capability_map` is the small, hand-authored+table that closes that gap: `[{"capability": "<domain>.<verb>", "tool_id":+"ffmpeg-skill/<tool>", "params": {...}}, ...]`. A planner that only knows+an abstract goal (`video.trim`, `audio.loudness`, `subtitle.burn`,+`media.stream.inspect`, `media.frames.extract`, `media.proxy`) looks it up here to find+the tool, then builds and runs that tool's own call from its+`input_schema` exactly as it would have if it already knew the tool name -+`capability_map` never executes anything itself, and this skill never+picks a capability on the caller's behalf.++Some entries also fix one or more `params` where the capability names a+*specific* behaviour narrower than the whole tool: `video.reframe` maps+to `fit` with `params: {"fit": "crop"}`, because `fit.py` also does+duration-fit and letterbox padding, and only the crop mode is a+"reframe". A caller resolving `video.reframe` should treat those params+as fixed inputs to that tool's own schema, not as optional defaults.++This list is deliberately short and will stay short: a capability is only+added when resolving it is a mechanical, no-judgment lookup. There is no+`video.highlight` entry, for instance, because `scenes.py --highlights`+ranks candidates by a measured proxy (audio energy or duration), never by+understood content - offering it as a blindly-delegable capability would+misrepresent what it does (see SKILL.md, "What this skill does and does+not decide"). `media.proxy` (a low-bitrate, fast-decode proxy for+downstream analysis/preview, distinct from `export.py`'s delivery+presets) resolves to `proxy` - itself a mechanical resize + re-encode+with no opinion on which asset should be proxied or what for.+## CapabilitiesNames: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,diff --git a/references/scripts.md b/references/scripts.mdindex a004378..2a15c41 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -33,6 +33,7 @@ Every script prints the same information with `--help`; this file exists so the- audio.py — clean-up, music, ducking, layout- loudness.py — EBU R128 normalisation- export.py — delivery presets+- proxy.py — low-bitrate proxy for analysis/preview## Scripts@@ -375,3 +376,13 @@ export.py --listScales into the preset frame (pad by default), tags BT.709, sets `+faststart`,trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.+### proxy.py — low-bitrate proxy for analysis/preview+```+proxy.py INPUT [--width W | --scale F] [--crf N] [--fps N] [--no-audio] [-o OUT]+```+Not a delivery preset: resizes to `--width` (default 640) or by `--scale`+factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest+x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;+run `color.py --to-sdr` first if SDR is wanted). Only executes the spec+given — does not decide which asset to proxy or what for.+diff --git a/scripts/_contract.py b/scripts/_contract.pyindex 1e96ef7..a70d807 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -128,6 +128,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {{"capability": "filter:exposure", "when": "--correct"}, {"capability": "filter:eq", "when": "--correct"},{"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"}],video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "proxy": dict(role="execution", inputs=["video asset"], outputs=["low-resolution, low-bitrate proxy artifact for downstream analysis, preview or editing decisions"],+ 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),"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"},@@ -199,6 +202,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {"silence": dict(video="always", audio="always", note="removing gaps requires cutting on non-keyframe boundaries"),"join": dict(video="always", audio="always"),"color": dict(video="always", audio="always"),+ "proxy": dict(video="always", audio="conditional", note="video is always re-encoded at proxy-grade quality; audio is re-encoded when present, dropped entirely with --no-audio or when the source has none"),"export": dict(video="conditional", audio="conditional", note="--preset copy is -c:v copy -c:a copy (no re-encode); every other preset re-encodes both"),"check": dict(video="never", audio="never", note="read-only, no artifact"),"scenes": dict(video="never", audio="never", note="analysis only; --sheet renders a new contact-sheet PNG, not a re-encode of the source"),@@ -584,6 +588,52 @@ 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()]+# Abstract, domain-shaped capability ids (`<domain>.<verb>`, matching the convention `provides`+# already documents for cross-repo Capability ids) that a planning agent can resolve without+# already knowing this skill's tool names. Unlike `provides` (one entry per tool, id derived+# from the tool name), this is a hand-authored, many-to-one table: several of these ids name a+# tool PLUS the fixed parameters that pin it to that specific behaviour (`video.reframe` is+# `fit.py` with `fit=crop` fixed, not bare `fit.py`, which also speed-ramps and pads). This is+# still purely descriptive -- a caller still builds and runs the named tool's own CLI/MCP call+# from its `input_schema`; nothing here executes or chooses on the caller's behalf. Deliberately+# excludes any capability that would require judgment to resolve (e.g. no `video.highlight`:+# `scenes.py --highlights` ranks by a measured proxy, never by understood content -- see+# SKILL.md "What this skill does and does not decide" -- so it is not offered as a capability+# a planner can blindly delegate to). `media.proxy` (a low-bitrate, fast-decode proxy, distinct+# from `export.py`'s delivery presets, which target visual quality over size/speed) resolves to+# `proxy.py` -- itself a purely mechanical resize+re-encode with no opinion on which asset should+# be proxied or what for.+CAPABILITY_MAP: List[Dict[str, Any]] = [+ {"capability": "video.trim", "tool_id": f"{SKILL_ID}/cut", "params": {}},+ {"capability": "video.reframe", "tool_id": f"{SKILL_ID}/fit", "params": {"fit": "crop"}},+ {"capability": "audio.loudness", "tool_id": f"{SKILL_ID}/loudness", "params": {}},+ {"capability": "subtitle.burn", "tool_id": f"{SKILL_ID}/caption", "params": {}},+ {"capability": "media.stream.inspect", "tool_id": f"{SKILL_ID}/probe", "params": {}},+ {"capability": "media.frames.extract", "tool_id": f"{SKILL_ID}/look", "params": {}},+ {"capability": "media.proxy", "tool_id": f"{SKILL_ID}/proxy", "params": {}},+]+++def capability_map(tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:+ """Validate CAPABILITY_MAP against the live tool specs before returning it. A fixed param+ that isn't a real input_schema property is drift, not a typo to ship silently (same "fail+ loudly" posture as tool_spec()'s missing-TOOL_META check). A tool_id that no longer exists+ is not drift in that sense -- a tool can legitimately be removed -- so that capability is+ dropped from the map rather than crashing the whole contract build."""+ by_id = {t["id"]: t for t in tools}+ result = []+ for entry in CAPABILITY_MAP:+ spec = by_id.get(entry["tool_id"])+ if spec is None:+ continue+ props = spec["input_schema"]["properties"]+ for key in entry["params"]:+ if key not in props:+ raise RuntimeError(f"capability {entry['capability']!r} sets param {key!r} which is not in {entry['tool_id']}'s input_schema")+ result.append(dict(entry))+ return result++# ----------------------------------------------------------------------------- contractdef tool_spec(name: str, version: str) -> Dict[str, Any]:if name not in TOOL_META:@@ -772,6 +822,7 @@ def build(detect: bool = True) -> Dict[str, Any]:"capabilities": caps,"tools": tools,"provides": capability_provides(),+ "capability_map": capability_map(tools),}diff --git a/scripts/proxy.py b/scripts/proxy.pynew file mode 100644index 0000000..7f66074--- /dev/null+++ b/scripts/proxy.py@@ -0,0 +1,82 @@+#!/usr/bin/env python3+"""Generate a small, low-bitrate proxy of a video: cheap for a machine to decode,+not meant for delivery. Intended for downstream AI analysis, preview or+editing-decision workflows that only need to look at (or feed a model) a+much smaller stand-in for the original.++Resizes to --width (default 640px, height follows the source aspect) or by+--scale factor, re-encodes at a proxy-grade --crf (default 30 - well above any+delivery preset's 18-24 in export.py, since a proxy trades visual quality for+size and speed), and always uses the fastest x264/x265 preset. Keeps the+source's own dynamic range (an HDR source proxies to HEVC10, same as every+other re-encoding tool here) rather than guessing whether SDR is wanted -+run color.py --to-sdr first if it is.++This tool only executes the spec it is given: it does not decide which asset+should be proxied, what resolution or bitrate is "right" for a given+downstream use, or what the proxy will be used for - those are the calling+agent's call.++Examples:+ python3 proxy.py input.mov # 640px wide, CRF 30, keeps audio+ python3 proxy.py input.mov --width 480 --no-audio # smaller, video-only+ python3 proxy.py input.mov --scale 0.25 --fps 10 # quarter-size, 10fps (e.g. for a vision model)+"""+import argparse+import sys++from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args+++def even(n: float) -> int:+ v = int(round(n))+ return v if v % 2 == 0 else v + 1+++def main() -> int:+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("input")+ ap.add_argument("-o", "--output", help="output file (default: <name>_proxy.<ext>)")+ ap.add_argument("--width", type=int, default=640, help="output width in px, height follows the source aspect (default 640)")+ ap.add_argument("--scale", type=float, help="scale factor applied to the source dimensions instead of --width (0 < scale <= 1)")+ ap.add_argument("--crf", type=int, default=30, help="proxy-grade CRF, higher = smaller/lower quality (default 30)")+ ap.add_argument("--fps", type=float, help="force a constant output frame rate")+ ap.add_argument("--no-audio", action="store_true", help="drop audio entirely (default: keep it)")+ add_common(ap)+ args = ap.parse_args()+ apply_common(args)++ if args.scale is not None and not 0.0 < args.scale <= 1.0:+ die(f"--scale must be > 0 and <= 1, got {args.scale}")+ if args.width <= 0:+ die(f"--width must be > 0, got {args.width}")+ if args.fps is not None and args.fps <= 0:+ die(f"--fps must be > 0, got {args.fps}")++ meta = probe(args.input)+ if not meta.get("video"):+ die("input has no video stream")+ sw, sh = meta["video"]["width"], meta["video"]["height"]+ if meta["video"].get("rotation") in (90, -90, 270, -270):+ sw = sh+ has_audio = bool(meta.get("audio")) and not args.no_audio++ out_w = even(sw * args.scale) if args.scale is not None else even(args.width)+ output = args.output or default_output(args.input, "proxy")++ cmd = ffmpeg_base() + ["-i", args.input, "-vf", f"scale={out_w}:-2"]+ cmd += video_args(meta, args.crf, "veryfast")+ cmd += cfr_args(meta, args.fps)+ cmd += ["-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"]+ cmd.append(output)+ run(cmd)++ result = probe(output)+ v = result["video"]+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']}, crf {args.crf})")+ emit(output)+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tests/test_all.py b/tests/test_all.pyindex 3ced1c2..35f7c16 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -610,6 +610,52 @@ class FFmpegSkillTests(unittest.TestCase):self.assertTrue(m["video"]["hdr"], "the source's real HDR tags must survive a stream copy")self.assertNotEqual(m["video"]["color_space"], "bt709", "copy must never relabel HDR content as bt709")+ def test_proxy_default_width_and_crf_keeps_audio(self):+ out = OUT / "proxy_default.mp4"+ script("proxy.py", self.src, "-o", out)+ m = probe(str(out))+ self.assertEqual(m["video"]["width"], 640)+ self.assertEqual(m["video"]["codec"], "h264")+ self.assertIsNotNone(m.get("audio"), "default keeps audio when the source has it")+ self.assertClose(m["duration"], 12.0, 0.2)++ def test_proxy_scale_and_no_audio(self):+ out = OUT / "proxy_scale.mp4"+ script("proxy.py", self.src, "--scale", "0.25", "--no-audio", "-o", out)+ src_w = probe(str(self.src))["video"]["width"]+ m = probe(str(out))+ self.assertEqual(m["video"]["width"], src_w // 4)+ self.assertIsNone(m.get("audio"), "--no-audio must drop the track, not just mute it")++ def test_proxy_forces_fps(self):+ out = OUT / "proxy_fps.mp4"+ script("proxy.py", self.vfr, "--fps", "10", "-o", out)+ m = probe(str(out))+ self.assertFalse(m["video"]["variable_frame_rate_suspected"], "an explicit --fps must conform a VFR source to CFR")+ self.assertClose(m["video"]["fps"], 10.0, 0.5)++ def test_proxy_keeps_hdr_dynamic_range_like_every_other_reencode(self):+ """A proxy meant for machine consumption still shouldn't silently wash out HDR to a+ mislabelled BT.709 file — same posture as fit.py/caption.py: keep HDR as HEVC10, and+ let color.py --to-sdr be the tool that makes the SDR-vs-HDR call, not this one."""+ out = OUT / "proxy_hdr.mp4"+ script("proxy.py", self.hdr, "-o", out)+ m = probe(str(out))+ self.assertTrue(m["video"]["hdr"])+ self.assertEqual(m["video"]["codec"], "hevc")++ def test_proxy_rejects_bad_scale_and_width(self):+ script("proxy.py", self.src, "--scale", "1.5", expect_fail=True)+ script("proxy.py", self.src, "--scale", "0", expect_fail=True)+ script("proxy.py", self.src, "--width", "0", expect_fail=True)++ def test_proxy_dry_run_writes_nothing(self):+ out = OUT / "proxy_dry_run_absent.mp4"+ proc = script("proxy.py", self.src, "-o", out, "--dry-run", "--json")+ doc = json.loads(proc.stdout)+ self.assertTrue(doc["dry_run"])+ self.assertFalse(out.exists())+# ---------------------------------------------------------------- real-world materialdef test_probe_detects_vfr_rotation_surround_hdr(self):self.assertTrue(probe(str(self.vfr))["video"]["variable_frame_rate_suspected"])diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 2d3c8c9..e9e0356 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -135,6 +135,28 @@ class ContractTests(unittest.TestCase):self.assertEqual(p["lifecycle"], "EXPERIMENTAL")self.assertEqual(set(p), {"id", "lifecycle", "tool_id"})+ def test_capability_map_resolves_to_real_tools_and_params(self):+ """capability_map is a hand-authored, descriptive lookup (abstract id -> tool + fixed+ params), not generated like `provides` -- so unlike that test, this doesn't check+ coverage of every tool. It checks the table can't silently drift: every tool_id must+ be a real tool, every fixed param a real input_schema property of that tool, and no+ capability id may collide or duplicate a tool_id 1:1 (this is many:one by design, e.g.+ video.reframe pins fit.py to fit=crop -- it never executes anything itself)."""+ cap_map = self.contract["capability_map"]+ ids = [c["capability"] for c in cap_map]+ self.assertEqual(len(ids), len(set(ids)), "capability ids are unique")+ specs_by_id = {t["id"]: t for t in self.contract["tools"]}+ for entry in cap_map:+ self.assertEqual(set(entry), {"capability", "tool_id", "params"})+ self.assertRegex(entry["capability"], r"^[a-z]+(\.[a-z]+)+$")+ spec = specs_by_id.get(entry["tool_id"])+ self.assertIsNotNone(spec, f"{entry['capability']} maps to unknown tool_id {entry['tool_id']!r}")+ props = spec["input_schema"]["properties"]+ for key, value in entry["params"].items():+ self.assertIn(key, props, f"{entry['capability']}: {key!r} is not a real param of {entry['tool_id']}")+ if "enum" in props[key]:+ self.assertIn(value, props[key]["enum"])+def test_docstring_examples_use_flags_that_actually_exist(self):"""A docstring's own runnable examples are the first thing a reader tries and trusts.scenes.py once claimed (in prose, not an example) that highlight ranking used motion --@@ -251,7 +273,7 @@ class ContractTests(unittest.TestCase):self.assertEqual(self.tools["cut"]["verification"]["tools"], ["ffmpeg-skill/probe"])def test_visual_verification_metadata(self):- picture = {"fit", "crop", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render"}+ picture = {"fit", "crop", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render", "proxy"}# join is the one picture tool that also accepts audio-only inputs (audio concat); look applies# to its video output only, which SKILL.md states next to "Look: not needed"both = {"join"}