ffmpeg-skill 1.4.12 → 1.4.13

package/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 the
   noise, 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.

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.4.12`) | any release |
+| `skill.version` | the npm / package.json version (`1.4.13`) | 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.4.12", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.4.13", "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.4.12",
+  "version": "1.4.13",
   "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/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 either
         g.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.CompletedProce
 
 
 def 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 scale
     scale = 1.0
     if 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-bit
     ymin, 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/max
     lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))

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

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

package/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 = fitted
         parts.append(part)
     stages_done.append("clips")
     current = parts[0]

package/scripts/reverse.py

@@ -34,6 +34,9 @@ def main() -> int:
     has_audio = bool(meta.get("audio")) and not args.no_audio
 
     output = 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"]

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