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.

render.py: --intermediate-preset defaults to superfast (#356)

Shogo Kajiyamabe785f83856e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9dbd4af..45664d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@
## Unreleased
-(nothing yet)
+### Changed
+
+- **`render.py --intermediate-preset` defaults to `superfast`** (was `veryfast` in 2.15). On FFmpeg 8.0.1 a 30 s 1080p reels render took 30 s instead of 33 s, with SSIM against a lossless reference of 0.9868 vs 0.9863; on 6.1 the two took the same time. `ultrafast` was measured too: 26 s, but SSIM 0.9814, so it is not the default. `--intermediate-preset veryfast` restores 2.15's choice.
## 2.15.0
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index c088aa5..6f9a414 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -45,6 +45,7 @@ exists. When a decision changes, edit the entry in the same PR.
- [2.11.0–2.12.0 — nothing happens silently](#21102120--nothing-happens-silently)
- [2.14.0 — the FFmpeg 5.x deprecation](#2140--the-ffmpeg-5x-deprecation)
- [2.15.0 — render.py's intermediate stages encode with veryfast](#2150--renderpys-intermediate-stages-encode-with-veryfast)
+- [2.16.0 — intermediates at superfast, not ultrafast](#2160--intermediates-at-superfast-not-ultrafast)
<!-- contents:end -->
## Time limits
@@ -2082,3 +2083,13 @@ What was decided there:
preset is part of each stage's arguments, so a `--cache` entry made at `medium` is not reused
for a `veryfast` run. Code: `render.sh()`, `INTERMEDIATE`. Test:
`test_render_intermediate_stages_use_veryfast_only_before_an_encoding_export`.
+
+## 2.16.0 — intermediates at superfast, not ultrafast
+
+- **`superfast` is the default intermediate preset; `ultrafast` is not.** Measured on a 30 s
+ 1080p reels render, with SSIM against a lossless reference of the same frame and captions:
+ veryfast 33 s / 0.9863, superfast 30 s / 0.9868, ultrafast 26 s / 0.9814 (FFmpeg 8.0.1; on 6.1
+ veryfast and superfast took the same time). superfast loses nothing the export keeps.
+ ultrafast's last 4 s cost a visible step in quality, which the export cannot win back.
+ Test: `test_render_intermediate_stages_use_veryfast_only_before_an_encoding_export` (its name
+ is from 2.15; it asserts the current default).
diff --git a/references/scripts.md b/references/scripts.md
index ee21a7a..d53a93a 100644
--- a/references/scripts.md
+++ b/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
diff --git a/scripts/render.py b/scripts/render.py
index 04487e6..3da286f 100755
--- a/scripts/render.py
+++ b/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)")
diff --git a/tests/test_orchestration.py b/tests/test_orchestration.py
index 870d669..e082cde 100644
--- a/tests/test_orchestration.py
+++ b/tests/test_orchestration.py
@@ -1013,7 +1013,7 @@ class OrchestrationTests(MediaFixtures):
def test_render_intermediate_stages_use_veryfast_only_before_an_encoding_export(self):
"""2.15: the x264 stages before an encoding export run at --intermediate-preset (default
- veryfast): export.py re-encodes them and its own preset sets the delivered quality. Kept
+ superfast since 2.16): export.py re-encodes them and its own preset sets the delivered quality. Kept
at the stages' medium when nothing re-encodes after them: --stop-after before the
export, a copy export, or --intermediate-preset medium. --fast still wins."""
proj = OUT / "ip_project.json"
@@ -1026,9 +1026,9 @@ class OrchestrationTests(MediaFixtures):
return doc.get("intermediate_preset"), x264
used, x264 = presets(proj)
- self.assertEqual(used, "veryfast")
+ self.assertEqual(used, "superfast")
self.assertEqual(x264[-1], "medium", "the export keeps its preset")
- self.assertTrue(x264[:-1] and set(x264[:-1]) == {"veryfast"}, x264)
+ self.assertTrue(x264[:-1] and set(x264[:-1]) == {"superfast"}, x264)
self.assertEqual(presets(proj, "--intermediate-preset", "medium"), (None, ["medium"] * len(x264)))
used, x264_fast = presets(proj, "--fast")
self.assertIsNone(used, "--fast decides every stage's preset, not --intermediate-preset")