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 two more caption.py delimiter bugs: ASS override injection, SRT blank-line split (#116)

Shogo Kajiyama3c55b57c59c4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa8edc1..7610974 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,28 @@
(nothing yet)
+## 0.16.3 — fix two more caption.py delimiter bugs: ASS override injection, SRT blank-line split
+
+Following on from 0.16.2's `--font` fix, a closer look at `caption.py` found
+two more places where user-controlled cue text (from `--text`, an SRT
+file, or ASR transcription) flows raw into a delimited text format:
+
+- ASS `Dialogue:` text treats a literal `{...}` as an override block --
+ real style/animation commands (`\pos`, `\fscx`, `\t`, ...), not literal
+ characters. Cue text containing braces was interpreted as those
+ commands instead of read out, letting a caption reposition, rescale,
+ or recolor itself or later text. Fixed by dropping `{`/`}` from cue
+ text before writing the ASS `Dialogue:` line (also closes the same gap
+ in the karaoke word-by-word path, which built its `{\kf..}` tags from
+ the same unsanitised text).
+- `write_srt()` wrote cue text raw. `parse_text_cues()` turns a bare `|`
+ into a newline (the documented two-line-caption syntax), so two
+ adjacent pipes (`a||b`) produced cue text containing a blank line --
+ and a blank line is SRT's own block separator. Writing it raw split
+ one cue into two malformed half-blocks, silently dropping the text
+ after the fake boundary when re-parsed. Fixed by collapsing any run of
+ blank lines within a cue's text to a single newline before writing.
+
## 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
diff --git a/docs/contract.md b/docs/contract.md
index 126c13f..9d96577 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.2`) | any release |
+| `skill.version` | the npm / package.json version (`0.16.3`) | 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.2", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.16.3", "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 5d8918f..fbf6379 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.16.2",
+ "version": "0.16.3",
"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 66efc75..cfb3685 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -165,6 +165,13 @@ def parse_srt(path: str) -> List[Tuple[float, float, str]]:
def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
with open(path, "w", encoding="utf-8") as fh:
for i, (s, e, t) in enumerate(cues, 1):
+ # A blank line is SRT's own block separator (index/timecode/text, blank, next block).
+ # Cue text can contain one -- parse_text_cues() turns a bare "|" into "\n", so a source
+ # line with two adjacent pipes ("a||b") becomes "a\n\nb" -- and writing that blank line
+ # raw would split one cue into two malformed half-blocks (the second missing its own
+ # index/timecode). Collapse any run of blank lines within the cue text to a single
+ # newline so the cue's own text can never fake the format's block boundary.
+ t = re.sub(r"\n{2,}", "\n", t).strip("\n")
fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
@@ -253,6 +260,14 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
lines = []
for start, end, text in cues:
text = text.replace("\n", "\\N")
+ # ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
+ # commands, not literal characters. Cue text (from --text, an SRT, or ASR transcription --
+ # all effectively user-controlled) that happens to contain braces would otherwise be
+ # interpreted as those commands (\pos, \t, \fscx, ...), letting caption content reposition,
+ # rescale, or recolor itself or later text instead of just being read out. No caption needs
+ # a literal curly brace, so they're dropped outright, matching the "unneeded delimiter
+ # character -> drop it" call already made for font names (see ass_font_name()).
+ text = text.replace("{", "").replace("}", "")
fx = ""
if args.animate == "fade":
fx = "{\\fad(200,200)}"
diff --git a/tests/test_all.py b/tests/test_all.py
index f0f096d..e17dd4f 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -1711,6 +1711,40 @@ class FFmpegSkillTests(unittest.TestCase):
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_caption_ass_dialogue_text_cannot_forge_override_blocks(self):
+ """ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
+ commands (\\pos, \\fscx, \\t, ...), not literal characters. Cue text is effectively user-
+ controlled (--text cues, an SRT file, or ASR transcription), so cue content containing
+ braces used to be interpreted as those commands instead of being read out literally,
+ letting a caption reposition/rescale/recolor itself or later text. Verify a hostile cue
+ survives as inert text with the override syntax neutralised."""
+ hostile_cues = OUT / "brace_inject_cues.txt"
+ hostile_cues.write_text("00:00:00 --> 00:00:03 hi {\\pos(0,0)\\fscx500}INJECTED\n", encoding="utf-8")
+ ass_out = OUT / "brace_inject.ass"
+ script("caption.py", self.src, "--text", hostile_cues, "--animate", "fade", "--write-ass", ass_out, "--dry-run")
+ dialogue = next(l for l in ass_out.read_text(encoding="utf-8").splitlines() if l.startswith("Dialogue: "))
+ # --animate fade legitimately prepends its own "{\fad(200,200)}" override block; only the
+ # cue-text-derived braces from the hostile payload must be gone.
+ self.assertNotIn("{\\pos(0,0)\\fscx500}", dialogue, "cue text must not be able to open a real ASS override block")
+ self.assertIn("\\pos(0,0)\\fscx500INJECTED", dialogue, "the rest of the cue text still renders, just as literal (now brace-free) text")
+
+ def test_caption_srt_blank_line_in_cue_text_does_not_split_the_block(self):
+ """parse_text_cues() turns a bare '|' into a newline (a documented way to write a two-line
+ caption), so a source line with two adjacent pipes ("a||b") produces cue text containing a
+ blank line ("a\\n\\nb"). A blank line is SRT's own block separator (index / timecode / text
+ / blank / next block) -- writing it raw used to split one cue into two malformed half-
+ blocks, the second missing its own index and timecode. Verify the generated SRT still
+ parses back as exactly the cues that were written, not more."""
+ hostile_cues = OUT / "blank_line_cues.txt"
+ hostile_cues.write_text("00:00:00 --> 00:00:03 a||b\n00:00:03 --> 00:00:06 second cue\n", encoding="utf-8")
+ srt_out = OUT / "blank_line.srt"
+ script("caption.py", "--text", hostile_cues, "--write-srt", srt_out)
+ from caption import parse_srt
+ cues = parse_srt(str(srt_out))
+ self.assertEqual(len(cues), 2, "the blank line inside cue text must not fake a third block boundary")
+ self.assertEqual(cues[0][2], "a\nb", "text after the fake blank-line boundary must not be silently dropped")
+ self.assertEqual(cues[1][2], "second cue", "the second cue must still have its own timecode/index, not be swallowed as stray text")
+
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/