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.

fix: doctor probes drawtext with the tools' fontfile=; raw docstrings for invalid escapes (#299)

Shogo Kajiyama0682a836e6dc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.1
diff --git a/docs/contract.md b/docs/contract.md
index 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 exi
non-zero), and it is never folded into `missing`, so an installed filter is not reported
absent, nor into `available`, so a failed detection is not a pass. `detection` gives the
status (`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 for
both live in `tests/fixtures/`.
diff --git a/scripts/_ass_overlay.py b/scripts/_ass_overlay.py
index 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: its
advance 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.py
index 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 for
every character on every build shape this repo uses.
The filter-graph parser never sees the text at all: only the PATH is parsed, and
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 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 actually
used 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 = probe
if probe["status"] == "missing":
drawtext_probe = probe
state[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.py
index fcb0cca..6ab9fc3 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -15,6 +15,7 @@ import sys
import tempfile
import time
import unittest
+import warnings
from pathlib import Path
ROOT = 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: yuv410p
read as 10-bit (#2); audio --mono halved an already-mono track (#3); sync --replace-audio
cut the reference to the shorter second (#4); 25+ tools raised TypeError formatting a
None 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 either
way, so it must leave a listed-available drawtext alone rather than reporting it missing.