ffmpeg-skill 1.9.0 → 1.9.1

package/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 (`1.9.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.9.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`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.9.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.9.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"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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",

package/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

package/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:

package/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:15@29.97)
   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
 )
 
 

package/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")

package/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:

package/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"}
 }
 

package/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: