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: doctor probes drawtext with the tools' fontfile=; raw docstrings for invalid escapes (#299)
Shogo Kajiyama0682a836e6dc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8cecfb0..f7efe9b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@## Unreleased+- fix(doctor): `filter:drawtext` is probed with the `fontfile=` the tools pass by default, so a build whose fontconfig lookup crashes (winget's gyan.dev 9.x) is no longer reported as missing a required capability while every drawtext tool renders; the fontconfig-only crash is a `notes` entry instead (#298).+- fix: docstrings in `_common/drawtext.py` and `_ass_overlay.py` are raw strings, so Python 3.12+ no longer prints `SyntaxWarning: invalid escape sequence` on import, and `-W error` no longer fails it (#297). A test compiles every tracked `.py` with warnings as errors.- docs(SKILL.md): MCP line said "the other 42" stay callable (it is the other 30, as `mcp/server.py` and the tests say); `--fit-size off` described by what it does rather than "1.16 behaviour" (also in `caption.py --help`); workflow heading drops "always" (steps 0 and 8 are conditional). From a prompt audit.## 2.3.1diff --git a/docs/contract.md b/docs/contract.mdindex d4a09b8..e63ac62 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -353,7 +353,10 @@ read (`ffmpeg -filters` in a layout the parser does not recognise, or ffmpeg exinon-zero), and it is never folded into `missing`, so an installed filter is not reportedabsent, nor into `available`, so a failed detection is not a pass. `detection` gives thestatus (`parsed`, `unparsed`, `failed`, `missing`), row count and detail of each listing;-`errors` lists the unreadable ones. The filter parser recognises the FFmpeg 6/7 layout+`errors` lists the unreadable ones. `filter:drawtext` is also rendered once, with the+`fontfile=` the tools pass by default: a crash there makes it `missing`; a crash only on a+bare fontconfig lookup leaves it `available` and adds a `notes` entry (`--font-file`, not a+bare `--font <family>`, on that machine). The filter parser recognises the FFmpeg 6/7 layout(three flag characters, `..C acompressor A->A`) and the FFmpeg 8 layout (two, `T.acompressor A->A`) by the io-spec token, so the flag width does not matter; fixtures forboth live in `tests/fixtures/`.diff --git a/scripts/_ass_overlay.py b/scripts/_ass_overlay.pyindex b52a4d1..fa4ae9e 100644--- a/scripts/_ass_overlay.py+++ b/scripts/_ass_overlay.py@@ -29,7 +29,7 @@ EMOJI_SENTINEL = "\ue000"def emoji_placeholder(box_px: float) -> str:- """The ASS override that reserves exactly `box_px` of advance and draws nothing.+ r"""The ASS override that reserves exactly `box_px` of advance and draws nothing.Measured, not assumed (1.15 spec, open question 2). U+2588 FULL BLOCK is NOT 1.0 em: itsadvance measured 0.83 em in FreeSans, 0.79 in WenQuanYi Zen Hei and 0.66 in DejaVu Sans,diff --git a/scripts/_common/drawtext.py b/scripts/_common/drawtext.pyindex e7c23a9..f9dbca6 100644--- a/scripts/_common/drawtext.py+++ b/scripts/_common/drawtext.py@@ -98,7 +98,7 @@ def escape_drawtext(text: str) -> str:def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:- """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for+ r"""`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe forevery character on every build shape this repo uses.The filter-graph parser never sees the text at all: only the PATH is parsed, anddiff --git a/scripts/_contract.py b/scripts/_contract.pyindex bfa070f..c9e973c 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -668,22 +668,42 @@ def _drawtext_probe() -> Dict[str, Any]:present and doctor used to report the capability `available` anyway; every tool that actuallyused it (look, scenes --sheet, overlay --text, graphics) then crashed on first real use (#100).- This runs the cheapest real drawtext render there is: a one-frame synthetic clip, no font=- given at all (ffmpeg's own default resolution -- the same path that crashed). A clean exit- means drawtext genuinely works here. Anything that could not prove either way (no ffmpeg,- timeout, an ordinary nonzero exit with a real ffmpeg error) is `unknown`, same "unknown is not- missing" principle as every other capability here. A crash specifically -- killed by signal on- POSIX, or an unhandled access violation surfacing as a huge unsigned exit code on Windows -- is- the one case this function exists to catch, and folds into `missing`: the filter is present in- the build but cannot actually be used as ffmpeg's own default would use it.+ This runs the cheapest real drawtext render there is: a one-frame synthetic clip, with the+ fontfile= the tools themselves pass by default (_common.fonts.default_font_file), or no font+ at all where none resolves. A clean exit means drawtext genuinely works for the tools here.+ Anything that could not prove either way (no ffmpeg, timeout, an ordinary nonzero exit with a+ real ffmpeg error) is `unknown`, same "unknown is not missing" principle as every other+ capability here. A crash specifically -- killed by signal on POSIX, or an unhandled access+ violation surfacing as a huge unsigned exit code on Windows -- folds into `missing`. When the+ fontfile= render works but a bare one crashes, drawtext stays available and the result+ carries a `note`: only a fontconfig lookup (`--font <family>` with no file) would crash."""exe = shutil.which("ffmpeg")if not exe:return {"status": "unknown", "detail": "ffmpeg not on PATH"}+ # Probe the way the tools call drawtext: with the fontfile= they pick by default (#298). On a+ # build whose fontconfig lookup crashes (#100) the tools still render, because they never ask+ # fontconfig; probing only the bare `drawtext=text=x` reported such a machine as missing+ # drawtext altogether. The bare render still runs, and its crash is reported as a note: it is+ # the path `--font <family>` without a file would take.+ from _common.fonts import default_font_file+ from _common.decision import escape_filter_path+ font_file = default_font_file(_default_font())+ result = _drawtext_render(exe, f"drawtext=fontfile={escape_filter_path(font_file)}:text=x" if font_file else "drawtext=text=x")+ if font_file and result["status"] == "available":+ bare = _drawtext_render(exe, "drawtext=text=x")+ if bare["status"] == "missing":+ result["note"] = ("drawtext renders with fontfile= (what every drawtext tool passes by default) but crashes "+ "when it has to resolve a font through fontconfig: pass --font-file, not a bare --font "+ "<family>, on this machine (https://github.com/kajisho5/ffmpeg-skill/issues/100)")+ return result+++def _drawtext_render(exe: str, vf: str) -> Dict[str, Any]:try:proc = subprocess.run([exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=black:s=64x64:d=1",- "-vf", "drawtext=text=x", "-frames:v", "1", "-f", "null", "-"],+ "-vf", vf, "-frames:v", "1", "-f", "null", "-"],stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=_DETECT_TIMEOUT,)except subprocess.TimeoutExpired:@@ -695,9 +715,8 @@ def _drawtext_probe() -> Dict[str, Any]:if proc.returncode < 0 or proc.returncode >= 0x80000000:return {"status": "missing","detail": f"drawtext render crashed (exit {proc.returncode}) instead of failing cleanly -- "- "the filter is present in this build but cannot be used as-is, likely a fontconfig "- "resolution crash (see https://github.com/kajisho5/ffmpeg-skill/issues/100); "- "pass an explicit --font-file to every drawtext tool as a workaround"}+ "the filter is present in this build but cannot render even with the fontfile= the "+ "tools pass (see https://github.com/kajisho5/ffmpeg-skill/issues/100)"}tail = " ".join(proc.stderr.strip().splitlines()[-2:])return {"status": "unknown", "detail": f"drawtext probe exited {proc.returncode}: {tail}"}@@ -809,6 +828,8 @@ def doctor() -> Dict[str, Any]:# than downgrading it; see _drawtext_probe()'s own docstring for why a crash alone# is the one case this exists to catch.probe = _drawtext_probe()+ if probe.get("note"):+ drawtext_probe = probeif probe["status"] == "missing":drawtext_probe = probestate[cap] = "missing"@@ -832,6 +853,7 @@ def doctor() -> Dict[str, Any]:errors = [f"{k}: {v['detail']}" for k, v in listings.items() if v["status"] in ("unparsed", "failed")]if drawtext_probe is not None and drawtext_probe["status"] != "available":errors.append(f"filter:drawtext: {drawtext_probe['detail']}")+ notes = [f"filter:drawtext: {drawtext_probe['note']}"] if drawtext_probe and drawtext_probe.get("note") else []return {"version": skill_version(),"python": ".".join(str(x) for x in sys.version_info[:3]),@@ -843,6 +865,7 @@ def doctor() -> Dict[str, Any]:"unknown": unknown,"detection": {k: {"status": v["status"], "count": len(v["names"]), "detail": v["detail"]} for k, v in listings.items()},"errors": errors,+ **({"notes": notes} if notes else {}),"ok": not missing_required and not unknown_required,"tools": _tool_usability(state),"gpu_encoders": _gpu_encoders(listings["encoders"]),diff --git a/tests/test_contract.py b/tests/test_contract.pyindex fcb0cca..6ab9fc3 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -15,6 +15,7 @@ import sysimport tempfileimport timeimport unittest+import warningsfrom pathlib import PathROOT = Path(__file__).resolve().parent.parent@@ -1905,7 +1906,7 @@ class ContractTests(unittest.TestCase):self.assertTrue((bdir / "out").is_dir(), "default outdir is <folder>/out")def test_fifth_audit_regressions(self):- """Pins from the fifth audit (100 items, 2026-09-12). Confirmed and fixed here: yuv410p+ r"""Pins from the fifth audit (100 items, 2026-09-12). Confirmed and fixed here: yuv410pread as 10-bit (#2); audio --mono halved an already-mono track (#3); sync --replace-audiocut the reference to the shorter second (#4); 25+ tools raised TypeError formatting aNone duration after a successful encode (#5); energy karaoke gave the last word a@@ -2785,7 +2786,7 @@ class DoctorDetectionTests(unittest.TestCase):# simulate the real Windows crash: killed by a signal, so subprocess.run reports a negative# returncode (the only portable way to reproduce "crashed" from a POSIX shell shim -- the# real bug is a huge positive exit code on Windows, but this class only runs on POSIX)- script += "case \"$*\" in *drawtext=text=x*) kill -s SEGV $$;; esac\nexit 1\n"+ script += "case \"$*\" in *drawtext=*) kill -s SEGV $$;; esac\nexit 1\n"(shim / "ffmpeg").write_text(script)(shim / "ffmpeg").chmod(0o755)env = dict(os.environ, PATH=f"{shim}:{os.environ['PATH']}")@@ -2797,6 +2798,42 @@ class DoctorDetectionTests(unittest.TestCase):self.assertFalse(d["ok"])self.assertEqual(proc.returncode, 1)+ def test_drawtext_fontconfig_crash_alone_keeps_drawtext_available(self):+ """#298: on gyan.dev 9.x only a fontconfig lookup crashes; the fontfile= the tools pass+ renders. doctor probes the way the tools call drawtext, so drawtext stays available and+ the fontconfig crash is a note, not a missing required capability."""+ if not shutil.which("fc-match"):+ self.skipTest("default_font_file() resolves no fontfile= without fc-match off Windows")+ shim = self.work / "shim_fc"+ shim.mkdir(exist_ok=True)+ script = "#!/bin/sh\ncase \"$2\" in\n"+ for flag, name in (("-filters", "ffmpeg_filters_6.1.txt"), ("-encoders", "ffmpeg_encoders_6.1.txt"), ("-bsfs", "ffmpeg_bsfs_6.1.txt")):+ script += f" {flag}) cat '{self.FIX / name}'; exit 0;;\n"+ script += "esac\ncase \"$1\" in -version) echo 'ffmpeg version 8.0-fixture'; exit 0;; esac\n"+ script += "case \"$*\" in *drawtext=fontfile=*) exit 0;; *drawtext=text=x*) kill -s SEGV $$;; esac\nexit 1\n"+ (shim / "ffmpeg").write_text(script)+ (shim / "ffmpeg").chmod(0o755)+ env = dict(os.environ, PATH=f"{shim}:{os.environ['PATH']}")+ d = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "doctor", "--json", env=env, check=False).stdout)+ self.assertIn("filter:drawtext", d["available"])+ self.assertNotIn("filter:drawtext", d["missing"])+ self.assertFalse(any("drawtext" in e for e in d["errors"]), d["errors"])+ self.assertTrue(any("fontconfig" in n and "--font-file" in n for n in d.get("notes", [])), d.get("notes"))++ def test_python_sources_have_no_invalid_escapes(self):+ """#297: an invalid escape in a docstring (`\\%`) is a SyntaxWarning on Python 3.12+ and+ an import failure under -W error; every tracked .py must compile clean."""+ root = SCRIPTS.parent+ bad = []+ for path in sorted(list(root.glob("scripts/**/*.py")) + list(root.glob("mcp/*.py")) + list(root.glob("tests/*.py"))):+ with warnings.catch_warnings():+ warnings.simplefilter("error")+ try:+ compile(path.read_text(encoding="utf-8"), str(path), "exec")+ except (SyntaxError, SyntaxWarning, DeprecationWarning) as exc:+ bad.append(f"{path.relative_to(root)}: {exc}")+ self.assertEqual(bad, [])+def test_drawtext_ordinary_failure_does_not_downgrade_a_listed_filter(self):"""An ordinary nonzero exit from the drawtext probe -- not a crash -- proves nothing eitherway, so it must leave a listed-available drawtext alone rather than reporting it missing.