Skip to content

Commit 957df5c

Browse files
feat(cli): render --prores-profile picks ProRes 4444, hq, 422, lt or proxy for MOV (#6581)
* feat(cli): render --prores-profile picks ProRes 4444, hq, 422, lt or proxy for MOV * fix(cli): drop a comment line that raised the comment share * fix(cli): the render plan args type carries --prores-profile
1 parent e21fd12 commit 957df5c

23 files changed

Lines changed: 273 additions & 21 deletions

‎docs/guides/rendering.mdx‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,9 +139,15 @@ browser already supports the source or you are diagnosing the proxy itself.
139139
## Choose quality and frame rate
140140

141141
The default `looks` quality (CRF 16) is the right choice for most finished work.
142-
MOV is an alpha-preserving editing intermediate and always uses the fixed
143-
ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
144-
and are rejected for MOV; choose MP4 or WebM when you need those controls.
142+
MOV is an editing intermediate. It uses ProRes 4444 with alpha unless
143+
`--prores-profile` picks a smaller 4:2:2 profile (`hq`, `422`, `lt` or `proxy`),
144+
which has no alpha: transparent areas render black. `--crf` and `--video-bitrate`
145+
do not map to ProRes and are rejected for MOV; choose MP4 or WebM when you need
146+
those controls.
147+
148+
```bash
149+
npx hyperframes render --format mov --prores-profile hq --output edit.mov
150+
```
145151

146152
For delivery to a player or platform, an MP4 render can also set how often a
147153
keyframe lands and how high the bitrate may peak. `--keyframe-interval 2` puts a

‎packages/cli/src/commands/lambda/render-batch.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -363,6 +363,7 @@ export function buildLambdaBatchRenderConfig(
363363
maxParallelChunks: args.maxParallelChunks,
364364
targetChunkFrames: args.targetChunkFrames,
365365
keyframeIntervalSeconds: args.keyframeIntervalSeconds,
366+
proresProfile: args.proresProfile,
366367
maxBitrate: args.maxBitrate,
367368
bufferSize: args.bufferSize,
368369
workerConcurrency,

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,7 @@ export function buildLambdaRenderConfig(
257257
maxParallelChunks: args.maxParallelChunks,
258258
targetChunkFrames: args.targetChunkFrames,
259259
keyframeIntervalSeconds: args.keyframeIntervalSeconds,
260+
proresProfile: args.proresProfile,
260261
maxBitrate: args.maxBitrate,
261262
bufferSize: args.bufferSize,
262263
workerConcurrency,

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ import type { ProducerLogger, RenderJob, RenderPerfSummary } from "@hyperframes/
139139
import {
140140
EXTRACT_CACHE_DIR_DISABLED_ALIASES,
141141
sandboxDeniedRemediation,
142+
type ProresProfile,
142143
type VideoFrameFormat,
143144
} from "@hyperframes/engine";
144145
import {
@@ -191,7 +192,7 @@ export default defineCommand({
191192
type: "string",
192193
alias: "q",
193194
description:
194-
"Quality: draft, looks, delivery, or standard/high. looks is the default (CRF 16). delivery is high. MOV always uses the fixed alpha-preserving ProRes 4444 profile.",
195+
"Quality: draft, looks, delivery, or standard/high. looks is the default (CRF 16). delivery is high. MOV uses ProRes 4444 with alpha unless --prores-profile picks a 422 profile.",
195196
default: "looks",
196197
},
197198
skill: {
@@ -522,6 +523,7 @@ export interface RenderOptions {
522523
vp9CpuUsed?: number;
523524
videoBitrate?: string;
524525
keyframeIntervalSeconds?: number;
526+
proresProfile?: ProresProfile;
525527
maxBitrate?: string;
526528
bufferSize?: string;
527529
videoFrameFormat?: VideoFrameFormat;
@@ -855,6 +857,7 @@ async function renderDocker(
855857
vp9CpuUsed: options.vp9CpuUsed,
856858
videoBitrate: options.videoBitrate,
857859
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
860+
proresProfile: options.proresProfile,
858861
maxBitrate: options.maxBitrate,
859862
bufferSize: options.bufferSize,
860863
videoFrameFormat: options.videoFrameFormat,
@@ -1137,6 +1140,7 @@ async function executeLocalRender(
11371140
crf: options.crf,
11381141
videoBitrate: options.videoBitrate,
11391142
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
1143+
proresProfile: options.proresProfile,
11401144
maxBitrate: options.maxBitrate,
11411145
bufferSize: options.bufferSize,
11421146
videoFrameFormat: options.videoFrameFormat,

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
import { mkdirSync, readFileSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import type { CanvasResolution, OutputResolutionIssueKind } from "@hyperframes/core";
5+
import { PRORES_PROFILES } from "@hyperframes/engine";
56
import { c } from "../../ui/colors.js";
67
import { errorBox, formatBytes } from "../../ui/format.js";
78
import { formatLintStartupMessage } from "../../utils/lintFormat.js";
@@ -118,6 +119,12 @@ export async function executeRenderPlan(
118119
reportVariableIssues(issues, { strict: plan.strictVariables, quiet: plan.quiet });
119120
}
120121

122+
if (plan.proresProfile && !PRORES_PROFILES[plan.proresProfile].alpha && !plan.quiet) {
123+
console.log(
124+
c.dim(`ProRes ${plan.proresProfile} has no alpha channel: transparent areas render black.`),
125+
);
126+
}
127+
121128
const options = renderOptionsFromPlan(plan, browserPath, variables);
122129
const execute = plan.useDocker ? dependencies.renderDocker : dependencies.renderLocal;
123130
await execute(plan.project.dir, plan.outputPath, options, cancellation);
@@ -153,6 +160,7 @@ export function renderOptionsFromPlan(
153160
vp9CpuUsed: plan.vp9CpuUsed,
154161
videoBitrate: plan.videoBitrate,
155162
keyframeIntervalSeconds: plan.keyframeIntervalSeconds,
163+
proresProfile: plan.proresProfile,
156164
maxBitrate: plan.maxBitrate,
157165
bufferSize: plan.bufferSize,
158166
videoFrameFormat: plan.videoFrameFormat,
@@ -361,6 +369,7 @@ export function batchRowRenderOptions(
361369
vp9CpuUsed: plan.vp9CpuUsed,
362370
videoBitrate: plan.videoBitrate,
363371
keyframeIntervalSeconds: plan.keyframeIntervalSeconds,
372+
proresProfile: plan.proresProfile,
364373
maxBitrate: plan.maxBitrate,
365374
bufferSize: plan.bufferSize,
366375
videoFrameFormat: plan.videoFrameFormat,

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,19 @@ describe("createRenderPlan", () => {
166166
);
167167
expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(flag);
168168
expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(
169-
"fixed alpha-preserving ProRes 4444",
169+
"MOV rate is set by the ProRes profile",
170+
);
171+
});
172+
173+
it("takes --prores-profile on MOV only", () => {
174+
expect(
175+
createRenderPlan({ dir: projectDir, format: "mov", "prores-profile": "hq" }).proresProfile,
176+
).toBe("hq");
177+
expect(() =>
178+
createRenderPlan({ dir: projectDir, format: "mp4", "prores-profile": "hq" }),
179+
).toThrow(CliUsageError);
180+
expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(
181+
"ProRes profile applies to MOV",
170182
);
171183
});
172184

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

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import {
1515
MAX_VP9_CPU_USED,
1616
MIN_VP9_CPU_USED,
1717
isVideoFrameFormat,
18+
type ProresProfile,
1819
type VideoFrameFormat,
1920
} from "@hyperframes/engine";
2021
import { errorBox } from "../../ui/format.js";
@@ -87,6 +88,7 @@ export interface RenderCommandArgs {
8788
"keyframe-interval"?: string;
8889
"max-bitrate"?: string;
8990
"buffer-size"?: string;
91+
"prores-profile"?: string;
9092
"vp9-cpu-used"?: string;
9193
gpu?: boolean;
9294
"browser-gpu"?: boolean;
@@ -166,6 +168,7 @@ export interface RenderPlan {
166168
vp9CpuUsed?: number;
167169
videoBitrate?: string;
168170
keyframeIntervalSeconds?: number;
171+
proresProfile?: ProresProfile;
169172
maxBitrate?: string;
170173
bufferSize?: string;
171174
hdrMode: HdrMode;
@@ -517,14 +520,23 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
517520
const flag = crf !== undefined ? "--crf" : "--video-bitrate";
518521
errorBox(
519522
"Unsupported ProRes rate control",
520-
`${flag} does not apply to MOV. MOV uses a fixed alpha-preserving ProRes 4444 profile.`,
523+
`${flag} does not apply to MOV. MOV rate is set by the ProRes profile; see --prores-profile.`,
521524
`Remove ${flag}, or choose MP4/WebM when you need CRF or target-bitrate control.`,
522525
);
523526
failUsage();
524527
}
525528

526529
const delivery = parseDeliveryFlags(args);
527-
if (Object.keys(delivery).length > 0 && format !== "mp4") {
530+
const { proresProfile, ...mp4Delivery } = delivery;
531+
if (proresProfile !== undefined && format !== "mov") {
532+
errorBox(
533+
"ProRes profile applies to MOV",
534+
`--prores-profile sets the ProRes profile of a MOV file, not ${format}.`,
535+
"Remove it, or render --format mov.",
536+
);
537+
failUsage();
538+
}
539+
if (Object.keys(mp4Delivery).length > 0 && format !== "mp4") {
528540
errorBox(
529541
"Delivery options apply to MP4",
530542
"--keyframe-interval, --max-bitrate and --buffer-size set how the MP4 encoder delivers the file.",

‎packages/cli/src/utils/deliveryFlags.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@ describe("parseDeliveryFlags", () => {
2222
).toEqual({ keyframeIntervalSeconds: 2.5, maxBitrate: "8M", bufferSize: "12M" });
2323
});
2424

25+
it("reads the ProRes profile and rejects an unknown name before any render starts", () => {
26+
expect(parseDeliveryFlags({ "prores-profile": " hq " })).toEqual({ proresProfile: "hq" });
27+
expect(() => parseDeliveryFlags({ "prores-profile": "422hq" })).toThrow(CliUsageError);
28+
});
29+
2530
it.each([["0"], ["-1"], ["abc"], [""]])("rejects keyframe interval %j", (value) => {
2631
expect(() => parseDeliveryFlags({ "keyframe-interval": value })).toThrow(CliUsageError);
2732
});

‎packages/cli/src/utils/deliveryFlags.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import { appendRateCapArgs } from "@hyperframes/engine";
1+
import { PRORES_PROFILE_NAMES, appendRateCapArgs, isProresProfile } from "@hyperframes/engine";
2+
import type { ProresProfile } from "@hyperframes/engine";
23
import { errorBox } from "../ui/format.js";
34
import { failUsage } from "./commandResult.js";
45

@@ -18,18 +19,24 @@ export const deliveryFlagArgs = {
1819
type: "string",
1920
description: "Buffer for --max-bitrate, such as 16M (default: twice --max-bitrate).",
2021
},
22+
"prores-profile": {
23+
type: "string",
24+
description: `MOV ProRes profile: ${PRORES_PROFILE_NAMES.join(", ")} (default 4444, keeps alpha; the others drop it).`,
25+
},
2126
} as const;
2227

2328
export interface DeliveryFlagValues {
2429
keyframeIntervalSeconds?: number;
2530
maxBitrate?: string;
2631
bufferSize?: string;
32+
proresProfile?: ProresProfile;
2733
}
2834

2935
interface DeliveryFlagArgs {
3036
"keyframe-interval"?: string;
3137
"max-bitrate"?: string;
3238
"buffer-size"?: string;
39+
"prores-profile"?: string;
3340
}
3441

3542
/** Parse the delivery flags, exiting with a usage error on a value the encoder would refuse. */
@@ -49,6 +56,17 @@ export function parseDeliveryFlags(args: DeliveryFlagArgs): DeliveryFlagValues {
4956
}
5057
values.keyframeIntervalSeconds = seconds;
5158
}
59+
const profile = args["prores-profile"]?.trim();
60+
if (profile !== undefined) {
61+
if (!isProresProfile(profile)) {
62+
errorBox(
63+
"Invalid prores-profile",
64+
`Got "${profile}". Must be one of ${PRORES_PROFILE_NAMES.join(", ")}.`,
65+
);
66+
failUsage();
67+
}
68+
values.proresProfile = profile;
69+
}
5270
if (maxBitrate !== undefined) values.maxBitrate = maxBitrate;
5371
if (bufferSize !== undefined) values.bufferSize = bufferSize;
5472
try {

‎packages/cli/src/utils/dockerRunArgs.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ export interface DockerRenderOptions {
5151
vp9CpuUsed?: number;
5252
videoBitrate?: string;
5353
keyframeIntervalSeconds?: number;
54+
proresProfile?: string;
5455
maxBitrate?: string;
5556
bufferSize?: string;
5657
videoFrameFormat?: "auto" | "jpg" | "png";
@@ -146,6 +147,7 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
146147
...(options.crf != null ? ["--crf", String(options.crf)] : []),
147148
...(options.vp9CpuUsed != null ? ["--vp9-cpu-used", String(options.vp9CpuUsed)] : []),
148149
...(options.videoBitrate ? ["--video-bitrate", options.videoBitrate] : []),
150+
...(options.proresProfile ? ["--prores-profile", options.proresProfile] : []),
149151
...(options.keyframeIntervalSeconds != null
150152
? ["--keyframe-interval", String(options.keyframeIntervalSeconds)]
151153
: []),

0 commit comments

Comments
 (0)