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 escape_drawtext() semicolon/quote gaps, and grid.py --pad's audio (#113)
Shogo Kajiyamae0ef0ec0206a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.pyNew tool: composite `--cols`x`--rows` clips into one grid (e.g. a 4x2 walldiff --git a/docs/contract.md b/docs/contract.mdindex 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 theToolSpec 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.jsonindex 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.pyindex 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.pyindex 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 unlessaudio together is rarely what a comparison grid is for, so this tool neverdoes 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.gaplayout = "|".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.pyindex 4bbc19a..04afec3 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -17,7 +17,7 @@ ROOT = Path(__file__).resolve().parent.parentSCRIPTS = 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: E402TONES = ("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 callerdoes 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