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: @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.md
index 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 the
diff --git a/scripts/_common.py b/scripts/_common.py
index 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 form
v, _, 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.py
index 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 for
Text-to-SRT input format (one cue per line, blank lines ignored):
0:00-0:03 Hello and welcome
00: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.py
index ef3f3fc..12d7a35 100755
--- a/scripts/metadata.py
+++ b/scripts/metadata.py
@@ -30,7 +30,7 @@ import tempfile
from pathlib import Path
from 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_die
CHAPTER_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("#"):
continue
parts = 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.py
index 4f8cbb6..2104abe 100755
--- a/scripts/multicam.py
+++ b/scripts/multicam.py
@@ -29,7 +29,7 @@ import argparse
import sys
from 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_secs
from 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.py
index 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.py
index aa72b5e..b4214ce 100644
--- a/scripts/speedramp.py
+++ b/scripts/speedramp.py
@@ -19,7 +19,7 @@ import argparse
import sys
from 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_arg
MAX_SPEED = 20.0
MIN_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.py
index 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."""