ffmpeg-skill 2.15.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.15.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.15.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.15.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/scripts.md

@@ -717,15 +717,16 @@ 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 veryfast
+render.py project.json --intermediate-preset medium   # the stages' own encoder preset instead of superfast
 ```
-`--intermediate-preset` (2.15, default `veryfast`): when the project has an export stage that
+`--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). `medium` restores the stages' default; `--fast` still overrides
+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

package/scripts/render.py

@@ -640,7 +640,11 @@ CACHE: Dict[str, Any] = _fresh_cache()
 # 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. `--intermediate-preset medium` restores it.
+# 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}
 
@@ -1066,8 +1070,8 @@ 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="veryfast", choices=X264_PRESETS,
-                    help="x264/x265 preset of the stages before an encoding export (default veryfast: the export "
+    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)")