Skip to content

Commit 2f7b7a9

Browse files
fix(render): reject unsupported ProRes rate controls (#3702)
1 parent e1ff7e6 commit 2f7b7a9

5 files changed

Lines changed: 49 additions & 6 deletions

File tree

‎docs/guides/rendering.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,9 @@ browser already supports the source or you are diagnosing the proxy itself.
9595
## Choose quality and frame rate
9696

9797
The default `standard` quality is the right choice for most finished work.
98+
MOV is an alpha-preserving editing intermediate and always uses the fixed
99+
ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
100+
and are rejected for MOV; choose MP4 or WebM when you need those controls.
98101

99102
```bash
100103
# Faster review version

‎docs/packages/cli.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -857,7 +857,7 @@ The flags that come up most:
857857
| `--composition, -c` | `index.html` | Render a different composition file. Sub-compositions using `<template>` wrappers must be referenced from `index.html` via `data-composition-src`. |
858858
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, or `png-sequence`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory. |
859859
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |
860-
| `--quality, -q` | `standard` | `draft`, `standard`, or `high`. Drives CRF and bitrate. |
860+
| `--quality, -q` | `standard` | `draft`, `standard`, or `high`. Drives MP4/WebM encoder settings; MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
861861
| `--resolution` | the composition's size | Supersample to a preset via Chrome's `deviceScaleFactor`. Aspect ratio must match and the scale must be a whole multiple. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). |
862862
| `--docker` | off | Render inside Docker for [deterministic output](/concepts/determinism) |
863863
| `--variables` | — | JSON object merged over the composition's `data-composition-variables` defaults |
@@ -869,8 +869,8 @@ Quality and file size:
869869

870870
| Flag | Default | Description |
871871
| ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
872-
| `--crf` | from `--quality`| Override encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`. |
873-
| `--video-bitrate` | from `--quality`| Target bitrate, e.g. `10M` or `5000k`. Not with `--crf`. |
872+
| `--crf` | from `--quality`| Override MP4/WebM encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`; rejected for MOV. |
873+
| `--video-bitrate` | from `--quality`| Target MP4/WebM bitrate, e.g. `10M` or `5000k`. Not with `--crf`; rejected for MOV. |
874874
| `--vp9-cpu-used` | encoder default | libvpx-vp9 speed/quality trade-off for WebM, -8 to 8. Env: `PRODUCER_VP9_CPU_USED`. |
875875
| `--gif-loop` | `0` | GIF loop count, `0` for forever. Range 0–65535, `--format gif` only. |
876876
| `--video-frame-format` | `auto` | How source video frames are extracted: `auto`, `jpg`, `png`. Use `png` for UI recordings, screen captures, and other colour-sensitive footage. |

‎packages/cli/src/commands/render.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,8 @@ export default defineCommand({
142142
quality: {
143143
type: "string",
144144
alias: "q",
145-
description: "Quality: draft, standard, high",
145+
description:
146+
"Quality: draft, standard, high. MOV always uses the fixed alpha-preserving ProRes 4444 profile.",
146147
default: "standard",
147148
},
148149
skill: {
@@ -195,11 +196,13 @@ export default defineCommand({
195196
},
196197
crf: {
197198
type: "string",
198-
description: "Override encoder CRF. Mutually exclusive with --video-bitrate.",
199+
description:
200+
"Override MP4/WebM encoder CRF. Mutually exclusive with --video-bitrate; unsupported for MOV.",
199201
},
200202
"video-bitrate": {
201203
type: "string",
202-
description: "Target video bitrate such as 10M. Mutually exclusive with --crf.",
204+
description:
205+
"Target MP4/WebM video bitrate such as 10M. Mutually exclusive with --crf; unsupported for MOV.",
203206
},
204207
"vp9-cpu-used": {
205208
type: "string",

‎packages/cli/src/commands/render/plan.test.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,34 @@ describe("createRenderPlan", () => {
8989
expect(() => createRenderPlan({ dir: projectDir, quality: "maximum" })).toThrow(CliUsageError);
9090
});
9191

92+
it.each([
93+
["--crf", { crf: "18" }],
94+
["--video-bitrate", { "video-bitrate": "78M" }],
95+
])("rejects unsupported %s rate control for ProRes MOV", (flag, encoderArgs) => {
96+
expect(() => createRenderPlan({ dir: projectDir, format: "mov", ...encoderArgs })).toThrow(
97+
CliUsageError,
98+
);
99+
expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(flag);
100+
expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(
101+
"fixed alpha-preserving ProRes 4444",
102+
);
103+
});
104+
105+
it("keeps MOV quality tiers on the fixed alpha-preserving profile", () => {
106+
const plan = createRenderPlan({ dir: projectDir, format: "mov", quality: "high" });
107+
108+
expect(plan).toMatchObject({ format: "mov", quality: "high" });
109+
expect(plan.crf).toBeUndefined();
110+
expect(plan.videoBitrate).toBeUndefined();
111+
});
112+
113+
it("keeps MP4 and WebM rate controls available", () => {
114+
expect(createRenderPlan({ dir: projectDir, format: "mp4", crf: "18" }).crf).toBe(18);
115+
expect(
116+
createRenderPlan({ dir: projectDir, format: "webm", "video-bitrate": "10M" }).videoBitrate,
117+
).toBe("10M");
118+
});
119+
92120
it("rejects batch and single-render variables before execution", () => {
93121
expect(() =>
94122
createRenderPlan({ dir: projectDir, batch: "rows.json", variables: '{"name":"Ada"}' }),

‎packages/cli/src/commands/render/plan.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -408,6 +408,15 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
408408
);
409409
failUsage();
410410
}
411+
if (format === "mov" && (crf !== undefined || videoBitrate !== undefined)) {
412+
const flag = crf !== undefined ? "--crf" : "--video-bitrate";
413+
errorBox(
414+
"Unsupported ProRes rate control",
415+
`${flag} does not apply to MOV. MOV uses a fixed alpha-preserving ProRes 4444 profile.`,
416+
`Remove ${flag}, or choose MP4/WebM when you need CRF or target-bitrate control.`,
417+
);
418+
failUsage();
419+
}
411420

412421
const quiet = args.quiet ?? false;
413422
const batchJson = args.json ?? false;

0 commit comments

Comments
 (0)