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 caption.py's --font not sanitised for ASS Style/force_style (#115)

Shogo Kajiyama1f9d23583045
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8730e09..fa8edc1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,27 @@
(nothing yet)
+## 0.16.2 — fix caption.py's --font not sanitised for ASS Style/force_style
+
+An attack-surface audit of every call site that embeds user-controlled text
+into a filter/subtitle construct found that `caption.py` was the one script
+that never routed `--font` through a sanitiser before using it, unlike
+`overlay.py`/`graphics.py`/`grid.py`/`look.py`, which all call
+`escape_drawtext()` first. `caption.py` doesn't build a `drawtext=` filter,
+though -- it embeds `--font` into two different ASS constructs
+`escape_drawtext()` was never designed for: the comma-delimited
+`[V4+ Styles]` `Style:` line, and the comma-separated `Key=Value` list
+inside a `-vf subtitles=...:force_style='...'` option. A font name
+containing a comma shifted every field after it in the `Style:` line
+(size, colours, bold flag, alignment, margins); a comma or colon inside
+`force_style`'s `FontName=` broke the option-list/`-vf` parsing the same
+way.
+
+Fixed with a new `ass_font_name()` helper in `caption.py` that drops
+`, : \ '` and control characters from the font name outright -- the same
+"no real font name needs this character, so don't chase a per-context
+escape" call this codebase already made for `escape_drawtext()`'s `'`/`%`.
+
## 0.16.1 — fix two more escape_drawtext() gaps, and grid.py --pad's audio
Adversarial testing (deliberately hostile filenames -- very long, Unicode,
diff --git a/docs/contract.md b/docs/contract.md
index 4196412..126c13f 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
| Field | Meaning | Changes when |
|---|---|---|
| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`0.16.1`) | any release |
+| `skill.version` | the npm / package.json version (`0.16.2`) | any release |
A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -39,7 +39,7 @@ drifting silently.
```json
{
"contract_version": "1.0",
- "skill": {"id": "ffmpeg-skill", "version": "0.16.1", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.16.2", "execution_mode": "local", "kind": "execution",
"entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
diff --git a/package.json b/package.json
index 1e5f683..5d8918f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.16.1",
+ "version": "0.16.2",
"description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 40 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
"keywords": [
"ffmpeg",
diff --git a/scripts/caption.py b/scripts/caption.py
index b0583e1..66efc75 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -247,7 +247,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
"[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}", "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
"[V4+ Styles]",
"Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
- f"Style: Default,{args.font},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin},{margin},{margin},1",
+ f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin},{margin},{margin},1",
"", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
]
lines = []
@@ -302,6 +302,20 @@ def ass_color(hex_rgb: str, alpha: int = 0) -> str:
return f"&H{alpha:02X}{b}{g}{r}".upper()
+def ass_font_name(name: str) -> str:
+ """Sanitise a font name for embedding in an ASS [V4+ Styles] Style line (comma-delimited
+ fields, no quoting mechanism) and in a `force_style='...'` option list (comma-separated
+ Key=Value pairs, colon-separated from the rest of the -vf filter). No real font name uses
+ `, : \\ '`, so rather than chase a per-context escape (a Style line and a force_style list
+ have different delimiter rules), those characters -- and control characters, which are never
+ meaningful in a font name either -- are dropped outright, the same "no escape proven safe
+ everywhere it's used" call this codebase already makes for escape_drawtext()'s `'`/`%`."""
+ name = re.sub(r"[\x00-\x1f\x7f]", "", name)
+ for ch in ",:\\'":
+ name = name.replace(ch, "")
+ return name
+
+
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("input", nargs="?", help="video to burn captions into (omit with --write-srt to only generate)")
@@ -471,7 +485,7 @@ def main() -> int:
if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
die(f"SRT file not found: {srt_path}")
style = [
- f"FontName={args.font}",
+ f"FontName={ass_font_name(args.font)}",
f"FontSize={args.size}",
f"PrimaryColour={ass_color(args.color)}",
f"OutlineColour={ass_color(args.outline_color)}",
diff --git a/tests/test_all.py b/tests/test_all.py
index 04afec3..f0f096d 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -1689,6 +1689,28 @@ class FFmpegSkillTests(unittest.TestCase):
sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-ss", "1", "-vframes", "1", frame)
self.assertTrue(frame.exists())
+ def test_caption_font_with_comma_and_colon_does_not_corrupt_ass_style(self):
+ """caption.py's --font flows into two ASS constructs escape_drawtext() was never meant to
+ cover: the comma-delimited [V4+ Styles] Style: line (write_ass()), and the comma-separated
+ Key=Value list inside a -vf subtitles=...:force_style='...' option. Neither is a drawtext
+ filter, so unlike overlay.py/graphics.py this call site used to embed args.font completely
+ raw. A font name containing a comma shifts every field after it (size, colours, bold flag,
+ alignment, margins) in the Style: line, and a comma or colon inside force_style's FontName=
+ breaks the option-list/-vf parsing the same way. Verify a hostile font name survives as an
+ inert, field-count-preserving value in both the --write-ass path and the plain SRT-burn
+ (force_style) path."""
+ hostile_font = "Arial,Bold:evil"
+ ass_out = OUT / "font_inject.ass"
+ script("caption.py", self.src, "--text", self.cues, "--font", hostile_font, "--animate", "fade", "--write-ass", ass_out, "--dry-run")
+ style_line = next(l for l in ass_out.read_text(encoding="utf-8").splitlines() if l.startswith("Style: Default,"))
+ self.assertNotIn(",Arial,Bold:evil,", style_line, "raw hostile font must not appear -- it would shift every later field")
+ fields = style_line.split(",")
+ self.assertEqual(len(fields), 23, "Style: line must keep its full field count (Format: line lists 23 columns)")
+
+ out = OUT / "font_inject_caption.mp4"
+ proc = sh(sys.executable, SCRIPTS / "caption.py", self.src, "--text", self.cues, "--font", hostile_font, "-o", out, "--dry-run")
+ self.assertNotIn("Arial,Bold:evil", proc.stderr, "hostile font must not reach force_style unsanitised")
+
def test_drawtext_semicolon_and_quote_render_as_inert_literal_text(self):
"""escape_drawtext() (shared by overlay.py --text, graphics.py/overlay.py's --font
fallback, and grid.py's filename-derived labels) had two more gaps beyond the comma/colon/