ffmpeg-skill 2.14.0 → 2.16.0

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 (`2.14.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.16.0`) | 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`
@@ -131,7 +131,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"},
                  {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.14.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.16.0", "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; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "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/gotchas.md

@@ -301,7 +301,8 @@ the contact sheet (`--sheet`) before treating the picks as final.
 Anything chained by hand through three re-encodes should be one `render.py`
 project instead, so the plan is one file and the user can change one number.
 Re-encodes use x264 `medium`; for long files add `--preset veryfast` to
-intermediates and keep the default for the final export. On Apple Silicon,
+intermediates and keep the default for the final export. `render.py` does that by itself since
+2.15 when its project ends in an encoding export (`--intermediate-preset medium` turns it off). On Apple Silicon,
 `--hw` (or `FFMPEG_SKILL_HW=1` for the machine) moves h264/hevc/prores encodes to
 VideoToolbox: 2–7× faster, 1.1–2.9× the bytes at the same quality (1.9–3.5× on HDR). The variable
 leaves `export.py`'s delivery presets on the CPU, which is the usual split (GPU

package/references/scripts.md

@@ -717,7 +717,18 @@ render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --k
 render.py project.json --cache DIR [--from STAGE]    # reuse identical stages from a previous run
 render.py plan.json [--audit-log FILE]       # execute a plan written by <tool> --plan plan.json
 render.py project.json --export-timeline edit.fcpxml|edit.edl|edit.otio   # the cut for an editor, nothing rendered
-```
+render.py project.json --intermediate-preset medium   # the stages' own encoder preset instead of superfast
+```
+`--intermediate-preset` (2.15; default `superfast` since 2.16, `veryfast` in 2.15): when the project has an export stage that
+re-encodes (any preset but `copy`) and the run goes that far (no `--stop-after` before it), the
+stages before it that encode with x264 or x265 (clips, fit, join, silence, captions, graphics,
+overlays, audiogram; x265 on the HDR path) encode with this preset instead of `medium`. export.py re-encodes their output and its own
+preset sets the delivered quality, so the earlier `medium` passes cost time the file does not
+keep: a 30 s 1080p reels render took 41.7 s instead of 51.8 s on FFmpeg 8.0.1 (SSIM 0.997
+between the two deliveries); `superfast` (2.16) took it to 30 s from veryfast's 33 s on 8.0.1, the
+same time on 6.1, at the same quality. `medium` restores the stages' default; `--fast` still overrides
+everything; a stage given its own `--preset` keeps it. The result names it as
+`intermediate_preset` (`null` when not applied).
 `--export-timeline FILE` (2.1) writes the project's cut as an editor timeline instead of
 rendering it: `.fcpxml` (FCPXML 1.10: Final Cut Pro, DaVinci Resolve), `.edl` (CMX 3600:
 Premiere, Resolve, Avid) or `.otio` (OpenTimelineIO JSON: Resolve natively, others through

package/scripts/render.py

@@ -74,7 +74,7 @@ from typing import Any, Dict, List, Optional, Sequence
 
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, ffmpeg_exe
+from _common import STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, ffmpeg_exe, X264_PRESETS
 from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 import subprocess
@@ -353,7 +353,8 @@ def render_pack(names: List[str], args) -> int:
         argv = [str(HERE / "render.py"), args.input, "--template", name, "-o", dest_out]
         for flag, value in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
                             ("--title", args.title), ("--brand", args.brand), ("--fit", args.fit),
-                            ("--chapters", args.chapters), ("--image", args.image)):
+                            ("--chapters", args.chapters), ("--image", args.image),
+                            ("--intermediate-preset", args.intermediate_preset)):
             if value:
                 argv += [flag, str(value)]
         info(f"→ pack: {name}")
@@ -545,6 +546,13 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
     cache instead of re-encoded. `stages_done` is unchanged either way: a cached stage is still
     a stage that happened.
     """
+    if (INTERMEDIATE["preset"] and script in _X264_STAGES
+            and "--preset" not in [str(a) for a in argv] + (extra or [])):
+        extra = (extra or []) + ["--preset", INTERMEDIATE["preset"]]
+        if not INTERMEDIATE["applied"]:
+            info(f"intermediate stages: preset {INTERMEDIATE['preset']} (the export re-encodes them; "
+                 "--intermediate-preset medium for the stages' own default)")
+        INTERMEDIATE["applied"] = True
     full = [str(a) for a in argv] + (extra or [])
     dest = full[full.index("-o") + 1] if "-o" in full[:-1] else None
     key = None
@@ -627,6 +635,25 @@ def _fresh_cache() -> "Dict[str, Any]":
 # inherit each other's hit/miss lists.
 CACHE: Dict[str, Any] = _fresh_cache()
 
+# The stages whose x264 encode (x265 on the HDR path, which takes the same --preset) is an
+# intermediate when an encoding export follows: export.py
+# re-encodes their output, so their own `medium` pass bought nothing the delivery keeps. Measured
+# on a 30 s 1080p reels render (4 cores): fit 18 s and captions 27 s of a 70 s run at `medium`;
+# `veryfast` at the same CRF encodes in about half the time (SSIM 0.997 against `medium`) and
+# the export, still `medium`, sets the delivered quality. 2.16: `superfast` (the default since): on
+# FFmpeg 8.0.1 the same render took 30 s instead of 33 s with veryfast, SSIM against a lossless
+# reference 0.9868 vs 0.9863 (the export decides what is kept); on 6.1 the two took the same time.
+# `ultrafast` was faster still (26 s) but measurably worse (0.9814). `--intermediate-preset medium`
+# restores the stages' own default.
+_X264_STAGES = frozenset({"cut.py", "fit.py", "join.py", "silence.py", "caption.py", "graphics.py", "overlay.py", "waveform.py"})
+INTERMEDIATE: Dict[str, Any] = {"preset": None, "applied": False}
+
+
+def _intermediate_used() -> Optional[str]:
+    """The preset `intermediate_preset` reports: only once a stage actually received it (a project
+    whose only encode is the export reports null)."""
+    return INTERMEDIATE["preset"] if INTERMEDIATE["applied"] else None
+
 
 def _content_hash(path: str) -> str:
     """The same cheap content fingerprint batch.py caches on: name, size, mtime, first and last
@@ -1043,6 +1070,10 @@ def main() -> int:
                     help="append the audit records of this run (a refused plan, a lock taken over, ...) to FILE as JSON lines; "
                          "default for a refused plan: <plan>.audit.jsonl next to it. A record that cannot be written is a "
                          "warning, never a failure")
+    ap.add_argument("--intermediate-preset", default="superfast", choices=X264_PRESETS,
+                    help="x264/x265 preset of the stages before an encoding export (default superfast: the export "
+                         "re-encodes them, and its own preset sets the delivered quality); medium = the stages' own default. "
+                         "Not used without an export stage, with --stop-after before it, with --fast, or for a copy export")
     ap.add_argument("--stop-after", choices=["clips", "join", "silence", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export"], help="stop after this stage (for iterating)")
     tpl = ap.add_argument_group("delivery templates (one command per destination)")
     tpl.add_argument("--template", metavar="NAME", help="render INPUT with a shipped template: " + ", ".join(template_names())
@@ -1175,6 +1206,13 @@ def main() -> int:
     # unchanged -- it never gets a --platform it did not ask for.
     dest = str(((proj.get("check") or {}).get("platform") or "")) if proj.get("template") else ""
     platform_args: List[str] = ["--platform", dest] if dest in PLATFORMS and PLATFORMS[dest].get("frame") else []
+    ex_cfg = proj.get("export")
+    # a malformed "export" is refused by the export stage with its own message; here it only means
+    # "no encoding export", never a traceback before that refusal
+    ex_preset = str(ex_cfg.get("preset") or "") if isinstance(ex_cfg, dict) else ""
+    if (ex_preset and "copy" not in PRESETS.get(ex_preset, {}).get("video", [])
+            and args.stop_after in (None, "export") and args.intermediate_preset != "medium" and not STATE.fast):
+        INTERMEDIATE["preset"] = args.intermediate_preset
     stages_done: List[str] = []
     # what the caption stage reported (wrapped/split counts and the fit-size keys), so a caller
     # reading render.py's JSON can see whether the type was shrunk to fit or a cue was split.
@@ -1306,7 +1344,7 @@ def main() -> int:
         stages_done.append("audiogram")
 
     if args.stop_after == "clips":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- join
@@ -1322,7 +1360,7 @@ def main() -> int:
         sh("join.py", *argv, stage="join")
         stages_done.append("join")
     if args.stop_after == "join":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- silence
@@ -1337,7 +1375,7 @@ def main() -> int:
         current = nxt
         stages_done.append("silence")
     if args.stop_after == "silence":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- fit (duration and/or frame)
@@ -1374,7 +1412,7 @@ def main() -> int:
         current = nxt
         stages_done.append("fit")
     if args.stop_after == "fit":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- captions
@@ -1403,7 +1441,7 @@ def main() -> int:
         current = nxt
         stages_done.append("captions")
     if args.stop_after == "captions":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- graphics
@@ -1422,7 +1460,7 @@ def main() -> int:
         if "graphics" not in stages_done:
             stages_done.append("graphics")
     if args.stop_after == "graphics":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- overlays
@@ -1453,7 +1491,7 @@ def main() -> int:
         if "overlays" not in stages_done:
             stages_done.append("overlays")
     if args.stop_after == "overlays":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- audio
@@ -1490,7 +1528,7 @@ def main() -> int:
         current = nxt
         stages_done.append("audio")
     if args.stop_after == "audio":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- loudness
@@ -1506,7 +1544,7 @@ def main() -> int:
         current = nxt
         stages_done.append("loudness")
     if args.stop_after == "loudness":
-        emit(current, stages=stages_done)
+        emit(current, stages=stages_done, intermediate_preset=_intermediate_used())
         return 0
 
     # ---- export
@@ -1612,7 +1650,7 @@ def main() -> int:
         snap_report = dict(snap_reports[0])
         snap_report["clips"] = snap_reports
     emit(output, stages=stages_done, check=check_result, snap=snap_report, cache=cache_report,
-         caption=caption_report,
+         caption=caption_report, intermediate_preset=_intermediate_used(),
          verification=[{"step": "check", "ok": True, "platform": ck.get("platform")}] if check_result else [])
     return 0