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 escape_drawtext() semicolon/quote gaps, and grid.py --pad's audio (#113)

Shogo Kajiyamae0ef0ec0206a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 299c81b..8730e09 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,46 @@
(nothing yet)
+## 0.16.1 — fix two more escape_drawtext() gaps, and grid.py --pad's audio
+
+Adversarial testing (deliberately hostile filenames -- very long, Unicode,
+shell metacharacters, quotes, semicolons, `%` specifiers, literal filter-
+graph syntax) found two more gaps in `escape_drawtext()`, the shared helper
+every `drawtext=text=...` call site uses (`overlay.py --text`, the
+`--font`/brand-font fallback, and 0.16.0's `grid.py` labels):
+
+- An unescaped `;` split a filterchain exactly like an unescaped `,` does --
+ minimal repro: `overlay.py clip.mp4 --text "a'b;c"` crashed real ffmpeg
+ with `No such filter: 'c...'`. Fixed by adding `;` to the backslash-escape
+ set.
+- The quote character itself had no backslash escape that survives every
+ call shape this codebase uses it in: both the existing `\'`-style escape
+ and a POSIX-shell `'\''` close-insert-reopen escape parse fine in a
+ simple `-vf` chain, but corrupt a `-filter_complex` chain with explicit
+ `[label]` pads (grid.py's shape) -- confirmed by rendering the result:
+ the text value doesn't end where the quote closes it, and trailing
+ option text (`fontfile=...`, `fontsize=...`) leaks into the picture as
+ literal burnt-in text. Fixed by dropping the quote character outright
+ instead of escaping it -- losing one apostrophe from a label is a fair
+ trade for the filter graph parsing correctly everywhere.
+- `%` had the same problem the quote character did: the existing `\%`
+ escape is not a real escape as far as drawtext's own text-expansion
+ scanner (on by default, for `%{pts}`/`%{localtime}`/etc., a separate
+ pass from the graph-level backslash escaping) is concerned -- a bare
+ backslash-escaped `%` always logs "Stray % near ...", which is merely
+ noisy on one ffmpeg build but a hard filtering failure that writes no
+ output at all on another. No caller ever wants `%{...}` expansion, so
+ `%` (and control characters, same underlying cause) are dropped outright
+ instead of chasing a per-build-safe escape.
+
+Also fixed a real bug CodeRabbit's review of 0.16.0 caught before it was
+acted on: `grid.py --pad` held each shorter cell's video on its last frame
+out to the longest clip, but a `--audio-from` track shorter than that was
+mapped straight through with no padding at all -- the release note's "with
+silence" claim wasn't true. Now `--pad` pads the selected audio track with
+`apad`/`atrim` to match, and the docstring/help text describe what `--pad`
+actually does (holds the last frame; does not add black video).
+
## 0.16.0 — add grid.py
New tool: composite `--cols`x`--rows` clips into one grid (e.g. a 4x2 wall
diff --git a/docs/contract.md b/docs/contract.md
index 4162f88..4196412 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.0`) | any release |
+| `skill.version` | the npm / package.json version (`0.16.1`) | 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.0", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.16.1", "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 dc67c13..1e5f683 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.16.0",
+ "version": "0.16.1",
"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/_common.py b/scripts/_common.py
index 4572def..8ca2d0f 100755
--- a/scripts/_common.py
+++ b/scripts/_common.py
@@ -641,14 +641,46 @@ def default_font_file(font_name: str) -> Optional[str]:
def escape_drawtext(text: str) -> str:
+ """Escape `text` for use as a single-quoted drawtext option value (`text='<this>'`).
+
+ Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash
+ escape regardless of the surrounding quotes -- the graph parser still splits on an
+ unescaped `,`/`;` or ends an option list on an unescaped `:`/`[`/`]` even while
+ "inside" a quoted value. The quote character itself has no reliable backslash
+ escape at all: `\\'` and the POSIX shell `'\\''` close-insert-reopen trick both
+ parse fine in a simple `-vf` chain, but silently corrupt a `-filter_complex` chain
+ that uses explicit `[label]` pads -- confirmed by rendering the result: the text
+ value doesn't end where the quote closes it, and trailing option names/values
+ (fontfile=..., fontsize=...) leak into the rendered picture as literal text
+ instead of being parsed as options. A quote is therefore dropped outright rather
+ than escaped -- losing one apostrophe from a label is a fine trade for "the
+ filter graph parses the way the code intends, on every call shape this codebase
+ uses it in".
+
+ `%` has the same problem the quote character did: `\%` is not a real escape as
+ far as drawtext's own text-expansion scanner (on by default, `expansion=normal`,
+ for `%{pts}`/`%{localtime}`/etc.) is concerned -- a bare backslash-escaped `%`
+ always logs "Stray % near ..." (confirmed with the minimal case
+ `text='100\%done'`), which is merely noisy on one ffmpeg
+ build (the warning is printed, the file still gets written) but a hard filtering
+ failure that writes no output at all on another. Every caller of this function
+ only ever wants a literal label, never `%{...}` expansion, so `%` is dropped
+ outright rather than chasing a per-build-safe escape (`expansion=none` on the
+ filter would also fix it, but needs touching every drawtext= call site instead
+ of the one shared helper). Control characters (newline, tab, ...) are dropped
+ for the same reason: none are meaningful in a one-line burnt-in label, and
+ unlike the graph-special characters above, ffmpeg's own text-expansion scanner
+ -- not just the graph parser -- is involved in whether they're actually safe."""
+ text = re.sub(r"[\x00-\x1f\x7f]", "", text)
return (
- text.replace("\\", "\\\\")
+ text.replace("'", "")
+ .replace("%", "")
+ .replace("\\", "\\\\")
.replace(":", "\\:")
- .replace("'", "\\\\\\'")
- .replace("%", "\\%")
.replace(",", "\\,")
.replace("[", "\\[")
.replace("]", "\\]")
+ .replace(";", "\\;")
)
diff --git a/scripts/grid.py b/scripts/grid.py
index 6a3216b..677126a 100644
--- a/scripts/grid.py
+++ b/scripts/grid.py
@@ -10,9 +10,11 @@ right corner -- --label none turns that off. The grid has no audio unless
audio together is rarely what a comparison grid is for, so this tool never
does it silently.
-The grid runs only as long as its shortest clip (--shortest, the default) or
-is padded to the longest with black+silence (--pad); a mismatched frame rate
-across sources is conformed to --fps first so cells stay in sync.
+The grid runs only as long as its shortest clip by default, or is padded to
+the longest clip's duration with --pad (each shorter cell holds its last
+frame, and --audio-from's track is padded with silence, out to that length);
+a mismatched frame rate across sources is conformed to --fps first so cells
+stay in sync.
Examples:
python3 grid.py take1.mp4 take2.mp4 take3.mp4 take4.mp4 take5.mp4 take6.mp4 take7.mp4 take8.mp4 --cols 4 --rows 2
@@ -43,7 +45,7 @@ def main() -> int:
ap.add_argument("--font", default="DejaVu Sans", help="label font (fontconfig family name, default DejaVu Sans)")
ap.add_argument("--font-size", type=int, default=16, help="label font size (default 16)")
ap.add_argument("--font-color", default="white", help="label text colour (default white)")
- ap.add_argument("--pad", action="store_true", help="pad every cell to the longest clip's duration with black+silence instead of stopping at the shortest")
+ ap.add_argument("--pad", action="store_true", help="hold each shorter cell's last frame (and pad --audio-from's track with silence) out to the longest clip's duration, instead of stopping at the shortest")
ap.add_argument("--audio-from", type=int, help="0-based index into inputs to take audio from (default: no audio)")
ap.add_argument("--gap", type=int, default=0, help="gap between cells in px, must be even (default 0, cells touch)")
ap.add_argument("--background", default="black", help="colour of the gap/pad borders (default black)")
@@ -112,10 +114,13 @@ def main() -> int:
cw, ch = args.cell_width + args.gap, args.cell_height + args.gap
layout = "|".join(f"{c * cw}_{r * ch}" for r in range(args.rows) for c in range(args.cols))
parts.append("".join(f"[v{i}]" for i in range(n)) + f"xstack=inputs={n}:layout={layout}:fill={args.background}[out]")
+ if args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
+ parts.append(f"[{args.audio_from}:a:0]apad,atrim=duration={target_duration:.3f}[aout]")
cmd += ["-filter_complex", ";".join(parts), "-map", "[out]"]
if args.audio_from is not None:
- cmd += ["-map", f"{args.audio_from}:a:0"]
+ audio_source = "[aout]" if (args.pad and durations[args.audio_from] < target_duration) else f"{args.audio_from}:a:0"
+ cmd += ["-map", audio_source]
cmd += video_args(None, args.crf, args.preset)
cmd += cfr_args(None, args.fps)
if args.audio_from is not None:
diff --git a/tests/test_all.py b/tests/test_all.py
index 4bbc19a..04afec3 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -17,7 +17,7 @@ ROOT = Path(__file__).resolve().parent.parent
SCRIPTS = ROOT / "scripts"
OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))
sys.path.insert(0, str(SCRIPTS))
-from _common import default_font_file, escape_filter_path, probe, shell_quote # noqa: E402
+from _common import default_font_file, escape_drawtext, escape_filter_path, probe, shell_quote # noqa: E402
TONES = ("0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.3)+0.4*sin(2*PI*880*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"
"+0.3*sin(2*PI*220*t)*gt(sin(2*PI*0.21*t+2)\\,0.7)")
@@ -534,6 +534,20 @@ class FFmpegSkillTests(unittest.TestCase):
m = probe(str(out))
self.assertClose(m["duration"], probe(str(self.src))["duration"], 0.5)
+ def test_grid_pad_also_pads_the_selected_audio_track_with_silence(self):
+ """--pad holds a shorter cell's video on its last frame out to the longest clip -- but
+ --audio-from's track was, until fixed, mapped straight through with no padding at all, so
+ a grid with --pad and a short --audio-from track silently lost audio for the padded tail.
+ The audio stream must actually span the full padded duration, not just the video."""
+ short = OUT / "grid_pad_audio_short.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", short)
+ out = OUT / "grid6.mp4"
+ script("grid.py", short, self.src, "--cols", "2", "--rows", "1", "--audio-from", "0", "--pad", "-o", out)
+ full_duration = probe(str(self.src))["duration"]
+ audio_duration = float(sh("ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
+ "stream=duration", "-of", "default=nw=1:nk=1", out).stdout.strip())
+ self.assertClose(audio_duration, full_duration, 0.5, "audio must be padded with silence to match the padded video, not stop at 2s")
+
def test_grid_filename_derived_label_refuses_filter_graph_injection(self):
"""The per-cell label is the clip's own filename (extension stripped), which the caller
does not choose through a flag -- but on a filesystem where filenames can contain a comma
@@ -1675,6 +1689,29 @@ class FFmpegSkillTests(unittest.TestCase):
sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-ss", "1", "-vframes", "1", frame)
self.assertTrue(frame.exists())
+ 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/
+ bracket class fixed in 0.15.2/0.15.3: (1) an unescaped ';' -- ffmpeg's graph parser splits
+ a filterchain there exactly like an unescaped ',' does, confirmed with the minimal repro
+ `--text "a'b;c"` crashing real ffmpeg with "No such filter: 'c...'" on the unpatched code;
+ (2) the quote character itself has no backslash escape that survives every call shape --
+ both `\\'` and the POSIX `'\\''` close-insert-reopen trick corrupt a -filter_complex chain
+ that uses explicit [label] pads (confirmed by rendering: trailing option text like
+ "fontfile=...:fontsize=..." leaks into the picture as literal burnt-in text instead of
+ being parsed as options), even though the same escape works fine in a simple -vf chain.
+ Render a text containing both a quote and a semicolon and confirm it appears verbatim
+ (minus the dropped quote) with nothing named after it leaking into the frame."""
+ out = OUT / "semicolon_quote.mp4"
+ proc = script("overlay.py", self.src, "--text", "a'b;c", "-o", out)
+ # The quote is dropped (a'b -> ab) and the semicolon escaped, then the value must close
+ # cleanly right where the template's own quote closes it -- ":fontsize=" must follow
+ # immediately, not somewhere downstream after leaked option text.
+ self.assertIn("ab\\;c'\\'':fontsize", proc.stderr, "value must render as 'ab;c' and close cleanly into :fontsize=, no leakage")
+ frame = OUT / "semicolon_quote_frame.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-vframes", "1", frame)
+ self.assertTrue(frame.exists())
+
# ---------------------------------------------------------------- real iPhone regressions (Dolby Vision 8.4 / HLG, VFR, extra tracks)
def test_hdr_source_stays_hdr_through_reencodes(self):
# HLG 10-bit HEVC with audio AND a timecode data track, like an iPhone .mov