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
docs(SKILL): fix dry-run overclaim, add doctor/contract to workflow, split Look into mechanical/judgement (#84)
Shogo Kajiyamae7affa0560da
diff --git a/SKILL.md b/SKILL.mdindex 8591544..f2aaef1 100644--- a/SKILL.md+++ b/SKILL.md@@ -5,10 +5,20 @@ description: Edit video and audio with local FFmpeg from natural-language reques# ffmpeg-skill-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run` (print the ffmpeg commands, run nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.## Workflow (always follow this order)+0. **Check the environment once per session, if unfamiliar.** On a machine+ you haven't confirmed capability on this session, run `doctor --json`+ once: check `ok` and the target tool's `usable` before relying on it. If+ `usable` isn't `yes`, don't run that tool — report the missing capability+ instead of discovering it via a runtime failure (a missing `libass`,+ `zscale`, or encoder is the common case, e.g. `caption.py`). Don't re-run+ `doctor` per job — it queries `ffmpeg -filters`/`-encoders`, not free, and+ once per session/unfamiliar machine is enough. `contract --json`'s full+ tool schema is for a *planning* agent deciding which tool/params to use+ from an abstract goal — not part of this per-job workflow.1. **Probe first.** Run `probe.py` on every input before touching it. Read theduration, fps, resolution, codecs, audio channels and the`variable_frame_rate_suspected` flag. Plan the edit from real numbers, never@@ -18,10 +28,13 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>`cut.py` and `loudness.py` stream-copy video by default; only pass`--accurate` to `cut.py` when the user needs frame-exact cuts.3. **Plan with `--dry-run --json`, then execute.** Every script accepts- `--dry-run` (prints the ffmpeg commands, runs nothing) and `--json`- (structured result: output path, probe of the output, commands run). Use- them to confirm a plan before long encodes and to report exact facts.- `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`+ `--dry-run` (prints the ffmpeg commands that would run) and `--json`+ (structured result: output path, probe of the output, commands run). For+ writing tools this means nothing is written; a few tools (`sync`,+ `multicam`, `scenes`, `report`) still run ffmpeg/ffprobe to measure or+ analyse under `--dry-run` — see `contract --json`'s `dry_run` field per+ tool. Use them to confirm a plan before long encodes and to report exact+ facts. `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`prints percent and ETA on stderr for long encodes.4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →join → silence → fit → caption/overlay → sync → audio → loudness → export.@@ -48,13 +61,28 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>files next to the input or where the user asked.8. **Look at the picture.** Whenever the picture changed (captions, overlays,graphics, crop/pad, resize, colour, transitions) run `look.py OUTPUT`- (contact sheet) or `look.py OUTPUT --at T`, view the PNG, and judge it like- an editor: text inside the frame and not over faces, logos where asked,- crops keeping the subject, colours not washed out, transitions landing- where intended. The job is not finished until the report's `Look:` line- names that PNG; a probe alone cannot see a caption sitting on someone's- face. Audio-only jobs (sync, loudness, silence, or any job whose input is- an audio file) write `Look: not needed`; there is no picture to inspect.+ (contact sheet) or `look.py OUTPUT --at T`, view the PNG. The job is not+ finished until the report's `Look:` line names that PNG; a probe alone+ cannot see a caption sitting on someone's face. Audio-only jobs (sync,+ loudness, silence, or any job whose input is an audio file) write+ `Look: not needed`; there is no picture to inspect. What to look for+ splits the same way `check.py`'s rows do in step 5:+ - **Mechanical (verify and report as this skill's own job):** the+ specified text/logo is present at the specified position, subtitles/text+ appear at the specified timestamps, resolution has even dimensions.+ Letterboxing/pillarboxing from `fit.py --fit pad` is the *correct*+ result of that mode, not a defect — never flag it.+ - **Judgement (report to the calling agent/user, don't silently pass or+ fail):** whether a subject or face is cut off, whether text sits over a+ face, whether colours look washed out, whether a transition "lands"+ well or the edit feels cinematic. These require deciding what the+ subject *is*, which belongs to the calling agent (see "What this skill+ does and does not decide") — state what you see in one line and let the+ calling agent or user judge it, don't decide it here.+ If the execution environment cannot actually view images (no vision+ capability), write `Look: PATH (pixels not inspected; agent has no image+ view)` — never claim a picture was inspected when it wasn't, and don't+ stall indefinitely waiting for a capability that isn't there.## Before you run anything: what to ask, what to assumediff --git a/references/scripts.md b/references/scripts.mdindex 5db083c..f37a5ca 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -1,6 +1,6 @@# Script reference-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT`.+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).## Contents- probe.py — inspectdiff --git a/tests/test_contract.py b/tests/test_contract.pyindex af9e3e8..dfe96a8 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -343,6 +343,36 @@ class ContractTests(unittest.TestCase):self.assertEqual(t["supports_dry_run"], has_flag, t["name"])self.assertEqual(t["dry_run"]["supported"], t["supports_dry_run"])+ def test_skill_and_scripts_docs_name_the_real_dry_run_exceptions(self):+ """SKILL.md and references/scripts.md used to claim "every script accepts --dry-run+ (runs nothing)" unconditionally, in three places, which was false for sync/multicam/+ scenes/report (they still run ffmpeg/ffprobe to measure/analyze under --dry-run --+ see _contract.py's DRY_RUN_ANALYSIS) and for verify (accepts the flag but ignores it).+ Pin the doc text naming those exact tools against the real exception set so a future+ tool gaining/losing an analysis-only dry-run mode is caught here instead of the docs+ silently drifting out of sync with _contract.py again (issue #82)."""+ analysis_tools = set(_contract.DRY_RUN_ANALYSIS.keys())+ self.assertEqual(analysis_tools, {"sync", "multicam", "scenes", "report"},+ "the analysis-only dry-run tool set changed -- update SKILL.md/references/scripts.md's exception list to match")+ skill = (ROOT / "SKILL.md").read_text(encoding="utf-8")+ scripts_ref = (ROOT / "references" / "scripts.md").read_text(encoding="utf-8")+ for name in analysis_tools:+ self.assertIn(name, skill, f"SKILL.md's dry-run exception note is missing {name!r}")+ self.assertIn(name, scripts_ref, f"references/scripts.md's dry-run exception note is missing {name!r}")+ self.assertIn("verify", skill)+ self.assertIn("verify", scripts_ref)++ def test_skill_workflow_mentions_doctor_and_contract(self):+ """SKILL.md's Workflow section (the first thing an agent reads) used to never mention+ `doctor`/`contract` at all -- an agent on an unfamiliar machine had no documented step to+ check capability before running a tool that depends on an optional filter/encoder,+ discovering it only via a runtime failure (issue #81). Pin their presence in the workflow+ section specifically, not just anywhere in the file."""+ skill = (ROOT / "SKILL.md").read_text(encoding="utf-8")+ workflow = skill.split("## Workflow", 1)[1].split("\n## ", 1)[0]+ self.assertIn("doctor", workflow)+ self.assertIn("contract", workflow)+def test_verification_metadata_matches_skill_workflow(self):for t in self.contract["tools"]:v = t["verification"]