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
Fix the Codex install path, a stale SKILL.md tool count, and two silent CI holes (#136)
Shogo Kajiyama7ab7f4bc5539
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex e1e8f17..27288c7 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -53,13 +53,23 @@ jobs:# instead of failing the whole job on what's usually a transient upstream blip.shell: pwshrun: |+ # A zero exit from choco is not proof ffmpeg is usable: seen once returning 0 after+ # ~6 s with nothing on PATH (the next step's `ffmpeg -version` then failed). So the+ # success condition is "ffmpeg actually runs", and a phantom install is retried with+ # --force rather than trusted.$attempts = 5for ($i = 1; $i -le $attempts; $i++) {- choco install ffmpeg -y --no-progress- if ($LASTEXITCODE -eq 0) { break }- if ($i -eq $attempts) { exit $LASTEXITCODE }+ $force = if ($i -gt 1) { '--force' } else { '' }+ choco install ffmpeg -y --no-progress $force+ $code = $LASTEXITCODE+ if ($code -eq 0 -and (Get-Command ffmpeg -ErrorAction SilentlyContinue) -and (Get-Command ffprobe -ErrorAction SilentlyContinue)) {+ ffmpeg -version | Select-Object -First 1+ break+ }+ if ($code -eq 0) { Write-Host "choco reported success but ffmpeg/ffprobe are not on PATH (attempt $i/$attempts)"; $code = 1 }+ if ($i -eq $attempts) { exit $code }$delay = 15 * $i- Write-Host "choco install ffmpeg failed (attempt $i/$attempts, exit $LASTEXITCODE) -- retrying in ${delay}s"+ Write-Host "choco install ffmpeg failed (attempt $i/$attempts, exit $code) -- retrying in ${delay}s"Start-Sleep -Seconds $delay}- name: ffmpeg version, listings and doctordiff --git a/CRITICAL_ISSUES.md b/CRITICAL_ISSUES.mddeleted file mode 100644index 9514712..0000000--- a/CRITICAL_ISSUES.md+++ /dev/null@@ -1,34 +0,0 @@-# Identified Issues for ffmpeg-skill--## Summary-Found 5 issues during code review, overlapping with #100 (Windows drawtext crash). All five are now addressed.--## Issues--### Issue 1: Python 3.14+ SyntaxWarning on invalid escape sequence — Fixed-- **File**: `_common.py:342`-- **Problem**: `" \t\\"'\\;|&<>()[]{}$*?"` contains invalid escape sequence `\;`-- **Severity**: Medium (will become error in Python 3.14+)-- **Fix**: dropped the stray backslash before `;` (it was already a plain, unescaped character everywhere else in that string)--### Issue 2: Windows Python documentation gap — Fixed-- **Location**: README examples-- **Problem**: Examples show `python3` but Windows Git Bash only recognizes `python`-- **Fix**: added a note next to the Quick Start script examples pointing Windows/Git Bash users at `python` instead; `bin/install.js` and `doctor`/`contract` already handled this, only the raw script-example block needed it spelled out--### Issue 3: FFmpeg capability detection incomplete for drawtext — Fixed-- **Problem**: `doctor` reported `missing required: none` but `drawtext` crashes at runtime on Windows-- **Fix**: `doctor` now actually renders one frame through `drawtext` (`_drawtext_probe()` in `scripts/_contract.py`) instead of trusting the `-filters` listing alone. A crash (killed by signal on POSIX, an access-violation-style exit on Windows) downgrades `filter:drawtext` from "listed" to `missing`, with the crash detail surfaced in `errors[]`; an ordinary nonzero exit (including every existing fixture-driven test's fake ffmpeg) leaves the listing-based result standing, since that proves nothing either way--### Issue 4: Font error messages lack context — Mitigated, not directly fixed-- **Problem**: Fontconfig errors don't indicate actual cause (missing fontfile, invalid fonts.conf)-- **Impact**: All drawtext tools (look.py, scenes.py, overlay.py, graphics.py)-- **What changed**: all four tools now resolve a concrete `--font-file` by default (`default_font_file()` in `_common.py`) and emit `fontfile=` instead of `font=` whenever one can be found — this is the root-cause fix for #100 (fontconfig's own resolution is what crashes; `fontfile=` skips it entirely), so in practice the fontconfig error path this issue describes should rarely be hit anymore. The underlying ffmpeg/fontconfig error text itself is unchanged when it does still occur.--### Issue 5: SKILL.md missing Windows drawtext limitations — Fixed-- **Location**: SKILL.md Gotchas section-- **Problem**: No mention of Windows-specific `drawtext` + fontconfig issues-- **Fix**: added a Gotchas entry describing the crash, the automatic `fontfile=` default that now covers it, and the `--font-file` / `doctor` escape hatches if it still happens--## Related-- Issue #100: "drawtext access-violates on Windows" — the root-cause fix (fontfile= by default across look/scenes/overlay/graphics, plus doctor's real drawtext probe) closes this.diff --git a/README.md b/README.mdindex 9eb9a8d..09fb321 100644--- a/README.md+++ b/README.md@@ -349,11 +349,11 @@ Benchmarks live in `tests/bench_*.py`, agent evals in [evals/](evals/), results```bashnpx ffmpeg-skill # Claude Code → ~/.claude/skills/ffmpeg-skillnpx ffmpeg-skill --cursor # Cursor → ~/.cursor/skills/ffmpeg-skill-npx ffmpeg-skill --codex # Codex → ~/.codex/skills/ffmpeg-skill+npx ffmpeg-skill --codex # Codex → ~/.agents/skills/ffmpeg-skill (Cursor reads this location too)npx ffmpeg-skill --all # all threenpx ffmpeg-skill --project # this project → ./.claude/skills/ffmpeg-skillnpx ffmpeg-skill --dir ./my-skills-npx ffmpeg-skill --uninstall # remove from the selected targets+npx ffmpeg-skill --uninstall # remove from the selected targets (--codex also clears the older ~/.codex/skills location)```Without Node: clone this repository and copy `SKILL.md`, `scripts/`, `references/` and `mcp/` into your agent's skills directory.diff --git a/SKILL.md b/SKILL.mdindex 5b55e5c..c957814 100644--- a/SKILL.md+++ b/SKILL.md@@ -118,7 +118,7 @@ This skill cuts, joins, measures, syncs, exports and checks files — it executeThe line in general: if the same input and the same explicit parameters always produce the same, verifiable output, it belongs here. If the "right" answer depends on taste, content understanding, or what looks or sounds good, it belongs to whichever skill or agent makes that judgement — this skill only ever executes parameters it's given, never infers them from what something looks or sounds like.-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.+If a request needs an FFmpeg feature none of the 40 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 → scriptdiff --git a/bin/install.js b/bin/install.jsindex 7944afb..a0304c2 100755--- a/bin/install.js+++ b/bin/install.js@@ -7,7 +7,7 @@** npx ffmpeg-skill # Claude Code* npx ffmpeg-skill --cursor # Cursor (~/.cursor/skills/ffmpeg-skill)- * npx ffmpeg-skill --codex # Codex (~/.codex/skills/ffmpeg-skill)+ * npx ffmpeg-skill --codex # Codex (~/.agents/skills/ffmpeg-skill)* npx ffmpeg-skill --all # all of the above* npx ffmpeg-skill --dir ./skills # custom parent directory* npx ffmpeg-skill --project # ./.claude/skills/ffmpeg-skill in the current project@@ -69,7 +69,10 @@ if (!want.claude && !want.cursor && !want.codex && !customDir && !project) want.if (want.claude) targets.push({ label: 'Claude Code', dir: path.join(home, '.claude', 'skills', SKILL_NAME) });if (want.cursor) targets.push({ label: 'Cursor', dir: path.join(home, '.cursor', 'skills', SKILL_NAME) });-if (want.codex) targets.push({ label: 'Codex', dir: path.join(home, '.codex', 'skills', SKILL_NAME) });+// Codex reads user-level skills from ~/.agents/skills (its docs list $HOME/.agents/skills,+// .agents/skills up the repo tree, and /etc/codex/skills), not ~/.codex/skills -- the+// latter was this installer's original guess and is not a location current Codex scans.+if (want.codex) targets.push({ label: 'Codex', dir: path.join(home, '.agents', 'skills', SKILL_NAME), legacy: path.join(home, '.codex', 'skills', SKILL_NAME) });if (project) targets.push({ label: 'project (.claude/skills)', dir: path.join(process.cwd(), '.claude', 'skills', SKILL_NAME) });if (customDir) targets.push({ label: 'custom', dir: path.join(path.resolve(customDir), SKILL_NAME) });@@ -106,6 +109,12 @@ for (const t of targets) {if (has('--uninstall')) {fs.rmSync(t.dir, { recursive: true, force: true });console.log(`removed ${t.label}: ${t.dir}`);+ // A copy left by the installer's earlier, wrong guess at this agent's directory (see the+ // Codex target above) would otherwise survive every uninstall from here on.+ if (t.legacy && fs.existsSync(t.legacy)) {+ fs.rmSync(t.legacy, { recursive: true, force: true });+ console.log(`removed ${t.label} (older install location): ${t.legacy}`);+ }continue;}// Copy into a scratch directory next to the real target first, then swap it into placediff --git a/docs/contract.md b/docs/contract.mdindex 2c03130..1e378a0 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -28,11 +28,12 @@ ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.verfor provenance. Consumers should also pin `ffmpeg-skill` itself by npm version or gittag, not by tracking `main` — see README, "Development", "Releasing".-The prose tool count in this file, README and `package.json`'s description is not-generated (it reads naturally in a sentence), so `tests/test_contract.py`'s-`test_docs_tool_count_matches_the_real_tool_list` checks all three against the real-count from `scripts/` on every CI run instead — a stale count fails a test rather than-drifting silently.+The prose tool count in this file, README, `SKILL.md` and `package.json`'s description is+not generated (it reads naturally in a sentence), so `tests/test_contract.py`'s+`test_docs_tool_count_matches_the_real_tool_list` checks all four against the real count+from `scripts/` on every CI run instead — a stale count fails a test rather than drifting+silently. (`SKILL.md` was added to that check after its "the 28 scripts" sat stale through+twelve tool additions while the other three files were correct.)## Skilldiff --git a/references/process-pitfalls.md b/references/process-pitfalls.mdindex e01479a..158a08b 100644--- a/references/process-pitfalls.md+++ b/references/process-pitfalls.md@@ -30,23 +30,43 @@ Caught twice while adding capability metadata for new flags (`caption.py --modeafter a test failure revealed it. Do that grep first, every time `required`/`optional`changes.-## Git tag push and GitHub Release creation are not reachable from this environment+## Git tag push and GitHub Release creation are not reachable from this environment — so they are not done from itThe git credentials available here can push to `refs/heads/*` (branches) but not`refs/tags/*` — confirmed by a 403 straight from the git-receive-pack endpoint, not anauth failure, meaning it's a deliberate scope restriction, not a bug to route around.-The GitHub MCP tool surface has no `create_release`/`create_tag` equivalent either-(`create_branch`, `create_pull_request`, `create_or_update_file` exist; nothing for-releases). A direct call to the GitHub REST API's `/releases` endpoint with a raw token-is also blocked by the outbound proxy itself (its own 403, pointing at Anthropic's docs,-not GitHub's).+The GitHub MCP tool surface has no `create_release`/`create_tag` equivalent either, and a+direct call to the GitHub REST API's `/releases` endpoint with a raw token is blocked by+the outbound proxy itself.Confirmed once (retried the tag push a second time "just in case" before accepting it).-Don't retry either path a second time — if `git push origin <tag>` 403s, or no-release-creation tool is found in one `ToolSearch` pass, say so once and hand the user-the two-minute browser-only path instead (open the repo's `/releases/new`, type the new-tag name in the tag field — GitHub creates it from the target branch on publish, no git-command needed).+Don't retry either path a second time. Since 0.16.11 this is moot for releases:+`.github/workflows/release.yml` creates the tag, the GitHub Release and the npm publish+from GitHub Actions on every push to `main` (README, "Development" → "Releasing"), so a+session never needs to push a tag at all — merging the PR is the release. The one thing+still worth knowing: that workflow's own `git push origin HEAD:main` (the automatic+version-bump commit) and its tag run under the built-in `GITHUB_TOKEN`, which by design+triggers no further workflow runs, so a red `tests` run for that bump commit is not+"missing" — it is never scheduled; the PR run before the merge is the one that counted.++## A throwaway probe must be pointed at a copy in a directory you have just verified with `pwd`, never at "the repo, probably"++While validating the auto-bump script for `release.yml`, a scratch run was meant to+execute against a temporary copy of the repo. It ran with the real checkout as its+working directory instead — a `cd` into the scratch path happened in a shell whose+working directory was reset between commands — and its `git add -A && git commit`,+`git tag v0.16.12` and two empty commits landed on the real branch and moved the real+local `v0.16.12` tag. Nothing was pushed, and `git reflog` plus a `git fetch --force` of+the tag from `origin` restored everything, but it was only noticed because `git status`+showed files the session had not edited.++Rule: a probe that runs `git commit`, `git tag`, `rm -rf`, or writes into the tree goes+in a directory created *and* verified in the same command (`cd "$DIR" && pwd && ...`),+not one assumed from an earlier `cd`; prefer a fixture built from a few `printf` lines+over a copy of the whole checkout (the copy carries the real `.git`, so a mistake there+is a mistake in the real history); and run `git status` on the real repo before+committing anything afterwards. `.claude/skills/destructive-operations/SKILL.md` says the+same thing for the tools themselves — it applies to the person testing them too.## A quantitative test failing three different ways across fixture redesigns means the platform, not the fixture, is the problemdiff --git a/tests/test_all.py b/tests/test_all.pyindex 07b1394..7ab4b31 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -46,6 +46,11 @@ class FFmpegSkillTests(unittest.TestCase):@classmethoddef setUpClass(cls):if not shutil.which("ffmpeg"):+ # Locally a skip; in CI (GitHub sets CI=true) a missing ffmpeg is a broken install+ # step and must fail, or a job with zero real tests reports green -- see+ # test_contract.py's require_ffmpeg_or_skip for the incident this guards against.+ if os.environ.get("CI"):+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step, not a reason to skip")raise unittest.SkipTest("ffmpeg not on PATH")OUT.mkdir(parents=True, exist_ok=True)cls.src = OUT / "source.mp4"@@ -2141,6 +2146,11 @@ class FFmpegSkillTests(unittest.TestCase):mid-run. Verify the auto-derived work dir name includes this process's own PID."""proj = OUT / "project_workdir.json"proj.write_text(json.dumps({"output": "render_workdir_check.mp4", "clips": [{"src": "source.mp4", "in": 0, "out": 2}]}), encoding="utf-8")+ # --keep leaves the PID-suffixed dir behind, so a second run of this suite in the same+ # OUT (a local re-run, or a coverage pass) would count the previous run's dir too.+ for stale in OUT.glob("render_workdir_check_work*"):+ if stale.is_dir():+ shutil.rmtree(stale)out = json.loads(script("render.py", proj, "--fast", "--stop-after", "clips", "--keep", "--json").stdout)self.assertEqual(out["stages"], ["clips"])work_dirs = [p for p in OUT.glob("render_workdir_check_work*") if p.is_dir()]diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 30cb7e2..583aead 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -44,8 +44,25 @@ def tool(name, *args, **kw):TONE = "0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.2)+0.3*sin(2*PI*660*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"[email protected](shutil.which("ffprobe"), "ffprobe not on PATH")+def require_ffmpeg_or_skip(*binaries):+ """Locally, a machine without ffmpeg just skips these suites. In CI that same skip would+ make a job whose ffmpeg install silently failed report green with zero tests run (seen for+ real: a Chocolatey install that returned 0 in 6 s and left nothing on PATH -- 14 tests+ ran, 15 skipped, job "OK"). GitHub sets CI=true on every runner, so there it's a failure."""+ missing = [b for b in binaries if not shutil.which(b)]+ if not missing:+ return+ msg = f"{'/'.join(missing)} not on PATH"+ if os.environ.get("CI"):+ raise AssertionError(f"{msg} -- in CI this is a broken install step, not a reason to skip")+ raise unittest.SkipTest(msg)++class ProbeInputPreservationTests(unittest.TestCase):+ @classmethod+ def setUpClass(cls):+ require_ffmpeg_or_skip("ffprobe")+def test_failed_probe_preserves_input(self):# Use real ffprobe and independent fixtures: every failure mode must leave# even an unreadable original byte-for-byte intact.@@ -65,8 +82,7 @@ class ProbeInputPreservationTests(unittest.TestCase):class ContractTests(unittest.TestCase):@classmethoddef setUpClass(cls):- if not shutil.which("ffmpeg") or not shutil.which("ffprobe"):- raise unittest.SkipTest("ffmpeg/ffprobe not on PATH")+ require_ffmpeg_or_skip("ffmpeg", "ffprobe")OUT.mkdir(parents=True, exist_ok=True)cls.contract = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "--json").stdout)cls.static = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "--json", "--static").stdout)@@ -147,6 +163,10 @@ class ContractTests(unittest.TestCase):(ROOT / "README.md", re.compile(r"\b(\d+)\s+(?:public )?tools\b")),(ROOT / "docs" / "contract.md", re.compile(r"\b(\d+)\s+tools\b")),(ROOT / "package.json", re.compile(r"(\d+)\s+FFmpeg tools\b")),+ # SKILL.md is the one file the agent actually reads, and it phrases the count as+ # "the N scripts" -- it sat at a stale 28 for weeks while the three above were+ # correct, precisely because this check didn't look at it or at that wording.+ (ROOT / "SKILL.md", re.compile(r"\b(\d+)\s+(?:public )?(?:tools|scripts)\b")),]for path, pattern in checks:text = path.read_text(encoding="utf-8")@@ -774,6 +794,46 @@ class ContractTests(unittest.TestCase):self.assertEqual([t["id"] for t in doc["tools"]], [t["id"] for t in self.contract["tools"]])self.assertEqual(sh("node", ROOT / "bin" / "install.js", "doctor", "--json").returncode, 0)+ def test_installer_agent_targets_are_the_directories_those_agents_actually_read(self):+ """`--codex` installed into ~/.codex/skills for weeks -- a location Codex's own docs never+ list (they name $HOME/.agents/skills, .agents/skills up the repo tree, /etc/codex/skills).+ Nothing pinned the target dirs, so the wrong guess shipped in 23 releases. Pin each+ agent flag to the directory that agent documents, and make `--uninstall --codex` also+ clear the old, wrong location so an upgrade doesn't leave a stale orphan copy behind."""+ with tempfile.TemporaryDirectory() as tmp:+ env = dict(os.environ, HOME=tmp, USERPROFILE=tmp)+ home = Path(tmp)+ legacy_codex = home / ".codex" / "skills" / "ffmpeg-skill"+ legacy_codex.mkdir(parents=True)+ (legacy_codex / "SKILL.md").write_text("stale copy from an older installer", encoding="utf-8")+ sh("node", ROOT / "bin" / "install.js", "--codex", "--cursor", env=env)+ self.assertTrue((home / ".agents" / "skills" / "ffmpeg-skill" / "SKILL.md").is_file(),+ "--codex must install where Codex reads user-level skills: ~/.agents/skills")+ self.assertTrue((home / ".cursor" / "skills" / "ffmpeg-skill" / "SKILL.md").is_file())+ self.assertFalse((home / ".claude").exists(), "an explicit agent flag must not also install the default target")+ sh("node", ROOT / "bin" / "install.js", "--codex", "--uninstall", env=env)+ self.assertFalse((home / ".agents" / "skills" / "ffmpeg-skill").exists())+ self.assertFalse(legacy_codex.exists(), "--uninstall --codex must also remove the pre-fix ~/.codex/skills copy")+ self.assertTrue((home / ".cursor" / "skills" / "ffmpeg-skill").exists(), "uninstall is scoped to the selected targets")++ def test_missing_ffmpeg_skips_locally_but_fails_in_ci(self):+ """A job whose ffmpeg install silently failed once reported green: 14 tests ran, 15 were+ skipped with 'ffmpeg not on PATH', job OK. GitHub sets CI=true on every runner, so the+ same condition there must be a failure -- while a contributor's laptop without ffmpeg+ still gets a plain skip, not a red suite."""+ from unittest import mock+ with mock.patch("shutil.which", return_value=None):+ with mock.patch.dict(os.environ, {"CI": "true"}):+ with self.assertRaises(AssertionError):+ require_ffmpeg_or_skip("ffmpeg")+ with mock.patch.dict(os.environ, {}, clear=False):+ os.environ.pop("CI", None)+ with self.assertRaises(unittest.SkipTest):+ require_ffmpeg_or_skip("ffmpeg", "ffprobe")+ with mock.patch("shutil.which", return_value="/usr/bin/ffmpeg"):+ with mock.patch.dict(os.environ, {"CI": "true"}):+ require_ffmpeg_or_skip("ffmpeg") # present: no skip, no failure+def test_contract_from_installed_copy(self):with tempfile.TemporaryDirectory() as tmp:# Node's os.homedir() reads HOME on POSIX but USERPROFILE on Windows (falling back to