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: @fps in caption cue files, one @ only, time_arg() in metadata/multicam/speedramp, render normalize default documented (#207)
claude[bot]b2dd9b9780ed
diff --git a/references/scripts.md b/references/scripts.mdindex 012c17f..b0bf3e9 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -400,7 +400,9 @@ for a `--platform` or a platform export preset), and reports `plan`, `tool`,`tool_result` and `check`. Show the plan to the user, get the yes, execute:one round trip instead of re-deriving the command.`"export": {"preset": "reels", "normalize": true}` forwards `export.py --normalize`-so the rendered file meets the platform's loudness without a separate pass.+so the rendered file meets the platform's loudness without a separate pass. Since+1.9.0 it is on by default when the preset is a platform (`youtube|youtube4k|reels|x`)+and the project has no `loudness` stage; `"normalize": false` opts out.Stages: clips (cut, optional speed) → join (transition) → silence → fit →captions → graphics → overlays → audio → loudness → export → check. Keys mirror thediff --git a/scripts/_common.py b/scripts/_common.pyindex 13925fc..582d6b3 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -1438,6 +1438,8 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:# time grammar); it overrides the source fps a tool passed in, and is meaningless without# the four-part formv, _, rate = v.rpartition("@")+ if "@" in v:+ raise ValueError(f"'{value}': only one @fps suffix is allowed")try:fps = float(rate)except ValueError:diff --git a/scripts/caption.py b/scripts/caption.pyindex cac1b23..024d76f 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -19,7 +19,7 @@ The subtitle codec is picked from the output container: mov_text forText-to-SRT input format (one cue per line, blank lines ignored):0:00-0:03 Hello and welcome00:00:03.500 --> 00:00:06 Second line | with a manual line break- 00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode (hh:mm:ss:ff, needs --fps)+ 00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode (hh:mm:ss:ff, needs --fps or an @fps suffix: 00:00:03:[email protected])Text without a time is auto-timed after the previous cue (--auto-seconds)Examples:@@ -41,7 +41,7 @@ from _common import STATE, color_hex, load_brand, video_args, add_common, apply_ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}TIME_RE = re.compile(- r"^\s*(?P<a>[\d:.,]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,]+)\s+(?P<text>.+)$"+ r"^\s*(?P<a>[\d:.,@]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$" # @ = the 1.9 @fps suffix)diff --git a/scripts/metadata.py b/scripts/metadata.pyindex ef3f3fc..12d7a35 100755--- a/scripts/metadata.py+++ b/scripts/metadata.py@@ -30,7 +30,7 @@ import tempfilefrom pathlib import Pathfrom typing import Any, Dict, List, Optional-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, STATE, read_text_or_die+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, STATE, read_text_or_dieCHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")@@ -46,10 +46,8 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:if not line or line.startswith("#"):continueparts = line.split(None, 1)- try:- start = parse_time(parts[0])- except ValueError: # MissingFpsError is a ValueError: chapter files carry no fps- die(f"{path}:{n}: cannot read the time in {line!r} (use seconds, mm:ss or hh:mm:ss.ms)")+ # chapter files carry no fps, so hh:mm:ss:ff needs its @fps suffix; time_arg() says so+ start = time_arg(parts[0], f"{path}:{n}")title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"if entries and start <= entries[-1]["start"]:die(f"{path}:{n}: chapter at {start:g}s does not come after the previous one at {entries[-1]['start']:g}s")diff --git a/scripts/multicam.py b/scripts/multicam.pyindex 4f8cbb6..2104abe 100755--- a/scripts/multicam.py+++ b/scripts/multicam.py@@ -29,7 +29,7 @@ import argparseimport sysfrom typing import List, Tuple-from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args, X264_PRESETS, fmt_secs+from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secsfrom sync import measure_offset@@ -42,9 +42,10 @@ def parse_switch(spec: str, n: int) -> List[Tuple[float, float, int]]:try:rng, cam = raw.rsplit(":", 1)a, b = rng.rsplit("-", 1)- s, e, c = parse_time(a), parse_time(b), int(cam)+ c = int(cam)except ValueError:die(f"bad switch entry '{raw}' (want START-END:CAM)")+ s, e = time_arg(a, f"--switch {raw!r} start"), time_arg(b, f"--switch {raw!r} end")if not 0 <= c < n:die(f"camera {c} does not exist (inputs are 0..{n - 1})")if e <= s:diff --git a/scripts/render.py b/scripts/render.pyindex 38df63b..dd36283 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -27,7 +27,7 @@ Project format (all keys optional except clips):"audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2},"loudness": {"lufs": -14, "tp": -1},"fit": {"duration": 60},- "export": {"preset": "reels", "normalize": true},+ "export": {"preset": "reels", "normalize": true}, (default for platform presets; false opts out)"check": {"platform": "reels"}}diff --git a/scripts/speedramp.py b/scripts/speedramp.pyindex aa72b5e..b4214ce 100644--- a/scripts/speedramp.py+++ b/scripts/speedramp.py@@ -19,7 +19,7 @@ import argparseimport sysfrom typing import List, Tuple-from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, parse_time+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, time_argMAX_SPEED = 20.0MIN_SPEED = 0.05@@ -43,9 +43,10 @@ def parse_segment(raw: str) -> Tuple[float, float, float]:try:span, factor_s = raw.rsplit(":", 1)start_s, end_s = span.rsplit("-", 1)- start, end, factor = parse_time(start_s), parse_time(end_s), float(factor_s)+ factor = float(factor_s)except ValueError:- die(f"--segment must look like START-END:FACTOR (times in seconds or mm:ss), got '{raw}'")+ die(f"--segment must look like START-END:FACTOR, got '{raw}'")+ start, end = time_arg(start_s, f"--segment {raw!r} start"), time_arg(end_s, f"--segment {raw!r} end")if end <= start:die(f"--segment {raw}: END must be after START")if not MIN_SPEED <= factor <= MAX_SPEED:diff --git a/tests/test_all.py b/tests/test_all.pyindex 894121f..9726363 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -1114,6 +1114,31 @@ class FFmpegSkillTests(unittest.TestCase):d = json.loads(script("broll.py", self.src, "--insert", self.src, "--at", "1:xx", "-o", OUT / "tc_broll.mp4", "--json", expect_fail=True).stdout)self.assertEqual(d["error"]["kind"], "input")self.assertIn("--at", d["error"]["message"])+ # 1.9.1 (audit 8): a cue file may carry the suffix too -- the timecodes must not become the caption text+ with self.assertRaises(ValueError) as cm:+ c.parse_time("00:00:01:15@30@30")+ self.assertIn("only one @fps", str(cm.exception), "no interpreter internals in the refusal")+ tc = OUT / "tc_at_cues.txt"+ tc.write_text("00:00:00:15@30 --> 00:00:02:00@30 Hello there\n", encoding="utf-8")+ srt = OUT / "tc_at.srt"+ script("caption.py", "--text", tc, "--write-srt", srt)+ text = srt.read_text(encoding="utf-8")+ self.assertIn("00:00:00,500 --> 00:00:02,000\nHello there", text)+ self.assertNotIn("@30", text)+ # metadata / multicam / speedramp refuse through the same parser and name the suffix+ ch = OUT / "tc_chapters.txt"+ ch.write_text("00:00:01:00 Intro\n", encoding="utf-8")+ d = json.loads(script("metadata.py", self.src, "--chapters", ch, "-o", OUT / "tc_md.mp4", "--json", "--dry-run", expect_fail=True).stdout)+ self.assertEqual(d["error"]["kind"], "input")+ self.assertIn("@fps", d["error"]["message"])+ ch.write_text("00:00:01:00@30 Intro\n", encoding="utf-8")+ script("metadata.py", self.src, "--chapters", ch, "-o", OUT / "tc_md.mp4", "--json", "--dry-run")+ d = json.loads(script("multicam.py", self.src, self.src, "--switch", "0-1:xx:0", "-o", OUT / "tc_mc.mp4", "--json", "--dry-run", expect_fail=True).stdout)+ self.assertEqual(d["error"]["kind"], "input")+ self.assertIn("@fps", d["error"]["message"])+ d = json.loads(script("speedramp.py", self.src, "--segment", "0-1:xx:2", "-o", OUT / "tc_sr.mp4", "--json", "--dry-run", expect_fail=True).stdout)+ self.assertEqual(d["error"]["kind"], "input")+ self.assertIn("@fps", d["error"]["message"])def test_probe_hdr_signal_is_the_transfer_not_the_primaries(self):"""1.9: hdr_signal is true for PQ / HLG / Dolby Vision only; hdr keeps its 1.x meaning."""