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: fourth-review P3 batch -- render speed 1.0, brand animation over mux, newline-safe command log, reverse warning, 16-bit levels, analyze-seconds ceiling, shorter common help (#188)
claude[bot]a57a3d39fb54
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 8f61212..400b307 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -128,15 +128,36 @@ jobs:- uses: actions/setup-python@v7with:python-version: "3.9"+ # The tarball is pinned by version and never changes, so one download per runner image+ # is enough: cache it, and only fetch when the cache is cold.+ - name: Cache the ffmpeg 5.1.1 static tarball+ id: ffcache+ uses: actions/cache@v4+ with:+ path: ffmpeg.tar.xz+ key: ffmpeg-5.1.1-amd64-static-tar-xz- name: Install ffmpeg 5.1.1 (static) and fontsrun: |sudo apt-get update && sudo apt-get install -y fonts-dejavu-core- # johnvansickle.com is a single small host; a connect timeout there took the whole- # job with it once (2026-09-12, "Failed to connect ... after 132939 ms"). Retry the- # download for a few minutes before giving up, and fail loudly if it still cannot.- curl -sSL --retry 6 --retry-all-errors --retry-delay 15 --connect-timeout 30 \- -o ffmpeg.tar.xz https://johnvansickle.com/ffmpeg/old-releases/ffmpeg-5.1.1-amd64-static.tar.xz- test -s ffmpeg.tar.xz || { echo "::error::ffmpeg 5.1.1 static download failed"; exit 1; }+ # johnvansickle.com is a single small host. Seen on 2026-09-12: a connect timeout+ # ("Failed to connect ... after 132939 ms") and, an hour later, an HTTP 200 whose body+ # was not an xz archive ("xz: (stdin): File format not recognized"). curl's --retry+ # covers only the first, so verify the archive and retry the whole download until it+ # is one, then fail loudly.+ if [ "${{ steps.ffcache.outputs.cache-hit }}" != "true" ] || ! xz -t ffmpeg.tar.xz 2>/dev/null; then+ ok=0+ for attempt in 1 2 3 4 5 6; do+ rm -f ffmpeg.tar.xz+ curl -sSL --connect-timeout 30 --max-time 600 \+ -o ffmpeg.tar.xz https://johnvansickle.com/ffmpeg/old-releases/ffmpeg-5.1.1-amd64-static.tar.xz || true+ if [ -s ffmpeg.tar.xz ] && xz -t ffmpeg.tar.xz 2>/dev/null; then ok=1; break; fi+ echo "attempt $attempt: not a valid xz archive ($(stat -c %s ffmpeg.tar.xz 2>/dev/null || echo 0) bytes; $(head -c 120 ffmpeg.tar.xz 2>/dev/null | tr -d '\0' | tr '\n' ' ' | cut -c1-120)); retrying in 20 s"+ sleep 20+ done+ [ "$ok" = 1 ] || { echo "::error::ffmpeg 5.1.1 static download failed after 6 attempts"; exit 1; }+ else+ echo "ffmpeg.tar.xz restored from cache"+ fimkdir -p "$HOME/ffmpeg5" && tar -xJf ffmpeg.tar.xz -C "$HOME/ffmpeg5" --strip-components=1echo "$HOME/ffmpeg5" >> "$GITHUB_PATH"- name: ffmpeg version, listings and doctordiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1f81267..cf3312d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@## Unreleased-(nothing yet)+- Fourth review, P3: `render.py` no longer re-encodes a clip whose `speed` is 1.0; a brand's `caption.animate` default is ignored over `--mode mux` instead of making it fail; `shell_quote` quotes newlines so the `commands` log stays copy-pasteable; `reverse.py` warns that a clip over 60 s is buffered whole in memory; `analyze_levels` scales 16-bit sources correctly (10 / 12 / 16-bit tiers); `sync.py`/`multicam.py --analyze-seconds` is capped at 900 s; the shared `--timeout`/`--overwrite` help is shorter, which trims every tool's MCP `inputSchema` (118 KB → 112 KB for `tools/list`); SKILL.md warns against burning captions at an intermediate size that `export.py` then upscales.## 1.4.12diff --git a/SKILL.md b/SKILL.mdindex 603b365..13eb029 100644--- a/SKILL.md+++ b/SKILL.md@@ -278,6 +278,7 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out-40 LUFS or below is room tone, wind or nothing; raising it 25 dB raises thenoise, not the content. Leave the level, say so, and offer music or narration.- Captions burned before a crop/resize: text lands off-frame. Frame changes first, then text.+- Captions burned at an intermediate size and then upscaled by `export.py` come out soft (a 1280x720 source fit to 9:16 is 406x720 until export scales it to 1080x1920). Fit to the delivery size first (`fit.py --width 1080 --height 1920`), then caption, then export.- Anything chained by hand through three re-encodes: use `render.py` so the plan is one file and the user can change one number.- `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot loses people at the edges. Check the sheet; pad (bars), `--crop-x`/`--crop-y` toward the subject, or a reframe is often the honest answer — a silent centre crop is a guess, not a decision.- Conforming 60 fps to 30 halves the motion samples: fine for a talking head, visibly choppy for sports, gaming, drone pans. Keep 60 when the platform allows it.diff --git a/scripts/_common.py b/scripts/_common.pyindex 5ef97d4..f6ae1ab 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -258,9 +258,9 @@ def add_common(ap: "argparse.ArgumentParser") -> None:g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")if "--timeout" not in ap._option_string_actions: # verify.py defines its own per-step --timeout; apply_common reads eitherg.add_argument("--timeout", type=float, default=None, metavar="SECONDS",- help=f"kill any single ffmpeg run that exceeds this many seconds and report kind=timeout (default {DEFAULT_TIMEOUT:.0f}, or FFMPEG_SKILL_TIMEOUT; 0 = no limit)")+ help=f"kill an ffmpeg run past this many seconds, kind=timeout (default {DEFAULT_TIMEOUT:.0f}; 0 = no limit)")g.add_argument("--overwrite", action="store_true",- help="allow replacing an output file that already exists (without it a warning is printed today; from 2.0 an existing output is refused, and FFMPEG_SKILL_NO_OVERWRITE=1 opts into that now)")+ help="allow replacing an existing output (warned today, refused from 2.0)")def apply_common(args: "argparse.Namespace") -> None:@@ -840,7 +840,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcedef shell_quote(s: str) -> str:- if not s or any(ch in s for ch in " \t\\\"';|&<>()[]{}$*?"):+ if not s or any(ch in s for ch in " \t\n\r\\\"';|&<>()[]{}$*?"):return "'" + s.replace("'", "'\\''") + "'"return s@@ -1466,7 +1466,7 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:# signalstats reports in the source bit depth; normalise everything to an 8-bit scalescale = 1.0if ymax > 255 or yavg > 255:- scale = 1 / 4.0 if ymax <= 1023 else 1 / 16.0+ scale = 1 / 4.0 if ymax <= 1023 else (1 / 16.0 if ymax <= 4095 else 1 / 256.0) # 10 / 12 / 16-bitymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale# 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/maxlows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))diff --git a/scripts/caption.py b/scripts/caption.pyindex 565a55e..af28996 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -450,7 +450,9 @@ def main() -> int:args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))args.outline = args.outline if args.outline is not None else (float(bcap.get("outline", 2)) if args.brand else 2.0)args.position = args.position or (bcap.get("position", "bottom") if args.brand else "bottom")- args.animate = args.animate or (bcap.get("animate", "none") if args.brand else "none")+ # a brand's caption.animate is a burn-in default; over --mode mux (soft subtitles) it used+ # to be applied anyway and then refused as "animation is burn only" -- ignore it there+ args.animate = args.animate or (bcap.get("animate", "none") if args.brand and args.mode != "mux" else "none")args.highlight_color = color_hex(args.highlight_color or bc.get("primary", "FFD200"))if args.brand and bcap.get("bold") and not args.bold:args.bold = Truediff --git a/scripts/multicam.py b/scripts/multicam.pyindex f7e9432..a89b0f2 100755--- a/scripts/multicam.py+++ b/scripts/multicam.py@@ -73,6 +73,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.analyze_seconds > 900:+ die(f"--analyze-seconds {args.analyze_seconds:g}: the window is decoded into memory; 900 s is the ceiling")if args.fps is not None and args.fps <= 0:die(f"--fps must be positive, got {args.fps:g}")diff --git a/scripts/render.py b/scripts/render.pyindex 55301a2..3050b5a 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -168,10 +168,11 @@ def main() -> int:spd = float(c["speed"])if not (spd > 0) or spd != spd or spd == float("inf"):die(f"clip {i}: speed must be a positive number, got {c['speed']!r}")- dur = (probe(part).get("duration") or 0.0) if not STATE.dry_run else 10.0- fitted = str(work / f"clip{i:02d}_speed.mp4")- sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)- part = fitted+ if abs(spd - 1.0) > 1e-6: # speed 1.0 used to cost a full re-encode for nothing+ dur = (probe(part).get("duration") or 0.0) if not STATE.dry_run else 10.0+ fitted = str(work / f"clip{i:02d}_speed.mp4")+ sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)+ part = fittedparts.append(part)stages_done.append("clips")current = parts[0]diff --git a/scripts/reverse.py b/scripts/reverse.pyindex 4e0169d..e1c5061 100644--- a/scripts/reverse.py+++ b/scripts/reverse.py@@ -34,6 +34,9 @@ def main() -> int:has_audio = bool(meta.get("audio")) and not args.no_audiooutput = args.output or default_output(args.input, "reverse")+ if (meta.get("duration") or 0) > 60:+ info(f"warning: reverse buffers every decoded frame in memory; {meta['duration']:.0f}s of "+ f"{meta['video']['width']}x{meta['video']['height']} can exhaust RAM -- cut the part to reverse first (cut.py)")cmd = ffmpeg_base() + ["-i", args.input, "-vf", "reverse"]if has_audio:cmd += ["-af", "areverse"]diff --git a/scripts/sync.py b/scripts/sync.pyindex 98c320f..6023e16 100755--- a/scripts/sync.py+++ b/scripts/sync.py@@ -213,6 +213,8 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ if args.analyze_seconds > 900:+ die(f"--analyze-seconds {args.analyze_seconds:g}: the window is decoded into memory; 900 s is the ceiling")for p in (args.reference, args.second):if not probe(p).get("audio"):diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 9da4970..389cde5 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -1606,6 +1606,22 @@ class ContractTests(unittest.TestCase):out = subprocess.run([sys.executable, "-c", code], env=env, stdout=subprocess.PIPE, text=True, check=True).stdoutself.assertEqual(out.strip(), "(7, 0)")+ def test_fourth_review_p3_regressions(self):+ """Fourth review P3 items: render re-encoded a clip at speed 1.0 (#47); a brand's default+ caption.animate made --mode mux fail (#32); shell_quote left a newline bare (#54);+ --analyze-seconds had no ceiling for the in-memory PCM window (#65)."""+ self.assertEqual(_common.shell_quote("a\nb"), "'a\nb'")+ proj = self.out("speed1.json")+ proj.write_text(json.dumps({"output": str(self.out("speed1.mp4")), "clips": [{"src": str(self.src), "speed": 1.0}]}))+ doc = json.loads(tool("render", proj, "--dry-run", "--json").stdout)+ self.assertNotIn("fit.py", " ".join(map(str, doc["commands"])) + json.dumps(doc.get("stages", [])))+ brand = self.out("brand_anim.json"); brand.write_text(json.dumps({"caption": {"animate": "pop"}}))+ srt = self.out("mux.srt"); srt.write_text("1\n00:00:00,000 --> 00:00:01,000\nhi\n\n", encoding="utf-8")+ doc = json.loads(tool("caption", self.src, "--srt", srt, "--brand", brand, "--mode", "mux", "--dry-run", "--json", "-o", self.out("mux_out.mkv")).stdout)+ self.assertEqual(doc["status"], "completed")+ proc = tool("sync", self.src, self.src, "--analyze-seconds", "5000", "--json", check=False)+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")+def test_cut_segments_refuses_output_equal_to_input(self):"""Fourth review, P0: `cut.py in.mp4 --segments 0-1,2-3 -o in.mp4` replaced the sourcewith the 2 s join. The run() guard compares the ffmpeg command's -i paths with its output,