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.

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.md
index 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 the
duration, 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 assume
diff --git a/references/scripts.md b/references/scripts.md
index 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 — inspect
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 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"]