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 capability_map and proxy.py (abstract-capability resolution + low-bitrate analysis proxy) (#39)

Shogo Kajiyamad275e42019f3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index a6240ff..1e7229d 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ npx ffmpeg-skill
![before / after demo](assets/demo.gif)
-`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. 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 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.md
index 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.md
index 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 in
that 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 is
purely 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.
+
## Capabilities
Names: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,
diff --git a/references/scripts.md b/references/scripts.md
index 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 --list
Scales 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.py
index 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
+
+
# ----------------------------------------------------------------------------- contract
def 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.py
new file mode 100644
index 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.py
index 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 material
def 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.py
index 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"}