Skip to content

Commit 5a164fb

Browse files
feat(cli): render --start and --end render only that span of the film as its own MP4 (#6834)
* feat(cli): render --start and --end render only that span of the film as its own MP4 The span reuses the chunked render path, so frames are captured at their absolute times and sub-composition timing matches a full render. * chore(producer): shorten the renderSpan comment * fix(producer): a cancelled span render stops, and its real-render test runs in the integration lane renderSpan checks the abort signal before each chunk part and before the stitch. The real-render tests move to their own file listed in the integration lane. * chore(producer): put the renderSpan doc comment back above renderSpan
1 parent b45e602 commit 5a164fb

11 files changed

Lines changed: 426 additions & 1 deletion

File tree

‎docs/packages/cli.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1674,6 +1674,7 @@ Quality and file size:
16741674
| `--crf` | from `--quality`| Override MP4/WebM encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`; rejected for MOV. |
16751675
| `--video-bitrate` | from `--quality`| Target MP4/WebM bitrate, e.g. `10M` or `5000k`. Not with `--crf`; rejected for MOV. |
16761676
| `--keyframe-interval` | encoder default | MP4 only. A keyframe at least every N seconds, e.g. `2`, so a player can seek or switch rendition at that spacing. |
1677+
| `--start`, `--end` | whole film | Render only the seconds between them, as an MP4 that starts at 0 with that span's audio. MP4 at 24, 25, 30 or 60 fps, SDR only. |
16771678
| `--max-bitrate` | uncapped | MP4 only. Peak video bitrate cap, e.g. `8M`, held alongside the `--crf` or `--quality` target rather than replacing it. |
16781679
| `--buffer-size` | 2 × `--max-bitrate` | MP4 only. Buffer the cap is measured over, e.g. `16M`. Needs `--max-bitrate`. |
16791680
| `--vp9-cpu-used` | encoder default | libvpx-vp9 speed/quality trade-off for WebM, -8 to 8. Env: `PRODUCER_VP9_CPU_USED`. |

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

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,12 @@ import { failCommand, requestCliExit, scheduleCliExit } from "../utils/commandRe
44
import { defineCommand } from "../utils/defineCommand.js";
55
import type { Example } from "./_examples.js";
66
import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
7-
import { createRenderPlan, resolveBrowserGpuForCli, type RenderFormat } from "./render/plan.js";
7+
import {
8+
createRenderPlan,
9+
resolveBrowserGpuForCli,
10+
type RenderFormat,
11+
type RenderRange,
12+
} from "./render/plan.js";
813
import { seedProjectAuthoringSkill } from "../utils/projectConfig.js";
914
import { deliveryFlagArgs } from "../utils/deliveryFlags.js";
1015
import type { CatalogUsage } from "../utils/catalogUsage.js";
@@ -263,6 +268,16 @@ export default defineCommand({
263268
description:
264269
"Override MP4/WebM encoder CRF. Mutually exclusive with --video-bitrate; unsupported for MOV.",
265270
},
271+
start: {
272+
type: "string",
273+
description:
274+
"Render from this second of the film (MP4). The clip starts at 0 and carries the audio of the span.",
275+
},
276+
end: {
277+
type: "string",
278+
description:
279+
"Render up to this second of the film (default: the end). Needs MP4, a whole frame rate of 24, 25, 30 or 60, and SDR.",
280+
},
266281
"video-bitrate": {
267282
type: "string",
268283
description:
@@ -526,6 +541,7 @@ export interface RenderOptions {
526541
vp9CpuUsed?: number;
527542
videoBitrate?: string;
528543
keyframeIntervalSeconds?: number;
544+
range?: RenderRange;
529545
proresProfile?: ProresProfile;
530546
maxBitrate?: string;
531547
bufferSize?: string;
@@ -861,6 +877,7 @@ async function renderDocker(
861877
vp9CpuUsed: options.vp9CpuUsed,
862878
videoBitrate: options.videoBitrate,
863879
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
880+
range: options.range,
864881
proresProfile: options.proresProfile,
865882
maxBitrate: options.maxBitrate,
866883
bufferSize: options.bufferSize,
@@ -1160,8 +1177,24 @@ async function executeLocalRender(
11601177
resumeSegments: options.resumeSegments,
11611178
keepSegments: options.keepSegments,
11621179
strictness: options.bestEffort === false ? "strict" : "best-effort",
1180+
// plan() takes the film's own size; these only satisfy the request shape.
1181+
distributed: options.range ? { width: 1920, height: 1080 } : undefined,
11631182
},
11641183
});
1184+
if (options.range) {
1185+
return renderRange({
1186+
producer,
1187+
request,
1188+
range: options.range,
1189+
projectDir,
1190+
outputPath,
1191+
options,
1192+
logger,
1193+
startTime,
1194+
cpu,
1195+
signal: cancellation.signal,
1196+
});
1197+
}
11651198
const job = producer.createRenderJob(producer.renderConfigFromRequest(request, { logger }));
11661199

11671200
const onProgress = options.quiet
@@ -1261,6 +1294,54 @@ async function executeLocalRender(
12611294
};
12621295
}
12631296

1297+
async function renderRange(input: {
1298+
producer: Awaited<ReturnType<typeof loadProducer>>;
1299+
request: ReturnType<Awaited<ReturnType<typeof loadProducer>>["createRenderRequest"]>;
1300+
range: RenderRange;
1301+
projectDir: string;
1302+
outputPath: string;
1303+
options: RenderOptions;
1304+
logger: ProducerLogger;
1305+
startTime: number;
1306+
cpu: RenderCpuSampler;
1307+
signal: AbortSignal;
1308+
}): Promise<SingleRenderResult> {
1309+
const { producer, options } = input;
1310+
let framesEncoded = 0;
1311+
try {
1312+
const config = producer.distributedConfigFromRequest(input.request, {
1313+
logger: input.logger,
1314+
abortSignal: input.signal,
1315+
});
1316+
({ framesEncoded } = await producer.renderSpan(
1317+
input.projectDir,
1318+
config,
1319+
input.range,
1320+
input.outputPath,
1321+
));
1322+
} catch (error: unknown) {
1323+
handleRenderError(error, options, input.startTime, input.cpu, false, "");
1324+
}
1325+
markRenderSucceeded();
1326+
const elapsed = Date.now() - input.startTime;
1327+
input.cpu.stop();
1328+
printRenderComplete({
1329+
outputPath: input.outputPath,
1330+
projectDir: input.projectDir,
1331+
desktopHint: wantsDesktopHint(options),
1332+
elapsedMs: elapsed,
1333+
quiet: options.quiet,
1334+
format: options.format,
1335+
});
1336+
if (options.exitAfterComplete) scheduleCliExit();
1337+
return {
1338+
renderTimeMs: elapsed,
1339+
durationMs: Math.round((framesEncoded / fpsToNumber(options.fps)) * 1000),
1340+
outcome: "completed",
1341+
warnings: [],
1342+
};
1343+
}
1344+
12641345
function getMemorySnapshot() {
12651346
return {
12661347
peakMemoryMb: bytesToMb(process.memoryUsage.rss()),

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,7 @@ export function renderOptionsFromPlan(
162162
vp9CpuUsed: plan.vp9CpuUsed,
163163
videoBitrate: plan.videoBitrate,
164164
keyframeIntervalSeconds: plan.keyframeIntervalSeconds,
165+
range: plan.range,
165166
proresProfile: plan.proresProfile,
166167
maxBitrate: plan.maxBitrate,
167168
bufferSize: plan.bufferSize,
@@ -376,6 +377,7 @@ export function batchRowRenderOptions(
376377
vp9CpuUsed: plan.vp9CpuUsed,
377378
videoBitrate: plan.videoBitrate,
378379
keyframeIntervalSeconds: plan.keyframeIntervalSeconds,
380+
range: plan.range,
379381
proresProfile: plan.proresProfile,
380382
maxBitrate: plan.maxBitrate,
381383
bufferSize: plan.bufferSize,

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,30 @@ describe("createRenderPlan", () => {
266266
}
267267
});
268268

269+
it("carries --start and --end into the plan, and refuses what a range cannot render", () => {
270+
expect(createRenderPlan({ dir: projectDir, start: "2.5", end: "6" }).range).toEqual({
271+
startSeconds: 2.5,
272+
endSeconds: 6,
273+
});
274+
expect(createRenderPlan({ dir: projectDir, end: "4" }).range).toEqual({
275+
startSeconds: 0,
276+
endSeconds: 4,
277+
});
278+
expect(createRenderPlan({ dir: projectDir }).range).toBeUndefined();
279+
const refused: Array<Record<string, string | boolean>> = [
280+
{ start: "-1" },
281+
{ start: "abc" },
282+
{ start: "5", end: "5" },
283+
{ start: "1", format: "webm" },
284+
{ start: "1", fps: "29.97" },
285+
{ start: "1", fps: "50" },
286+
{ start: "1", hdr: true },
287+
];
288+
for (const flags of refused) {
289+
expect(() => createRenderPlan({ dir: projectDir, ...flags })).toThrow(CliUsageError);
290+
}
291+
});
292+
269293
it("rejects batch and single-render variables before execution", () => {
270294
expect(() =>
271295
createRenderPlan({ dir: projectDir, batch: "rows.json", variables: '{"name":"Ada"}' }),

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
import { statSync } from "node:fs";
22
import { dirname, join, resolve } from "node:path";
33
import {
4+
DISTRIBUTED_FPS,
45
formatRenderOutputTimestamp,
56
fpsToNumber,
67
isAspectAgnosticResolutionAlias,
8+
isDistributedFps,
79
normalizeResolutionFlag,
810
parseFps,
911
type CanvasResolution,
@@ -84,6 +86,8 @@ export interface RenderCommandArgs {
8486
hdr?: boolean;
8587
sdr?: boolean;
8688
crf?: string;
89+
start?: string;
90+
end?: string;
8791
"video-bitrate"?: string;
8892
"keyframe-interval"?: string;
8993
"max-bitrate"?: string;
@@ -168,6 +172,7 @@ export interface RenderPlan {
168172
vp9CpuUsed?: number;
169173
videoBitrate?: string;
170174
keyframeIntervalSeconds?: number;
175+
range?: RenderRange;
171176
proresProfile?: ProresProfile;
172177
maxBitrate?: string;
173178
bufferSize?: string;
@@ -207,6 +212,53 @@ function parseRenderFormat(input: string): RenderFormat | undefined {
207212
return RENDER_FORMATS.find((format) => format === input);
208213
}
209214

215+
export interface RenderRange {
216+
startSeconds: number;
217+
endSeconds?: number;
218+
}
219+
220+
function parseRenderRange(
221+
args: Pick<RenderCommandArgs, "start" | "end">,
222+
format: RenderFormat,
223+
fps: Fps,
224+
hdr: boolean | undefined,
225+
): RenderRange | undefined {
226+
if (args.start === undefined && args.end === undefined) return undefined;
227+
const seconds = (flag: string, raw: string): number => {
228+
const parsed = raw.trim() === "" ? Number.NaN : Number(raw);
229+
if (!Number.isFinite(parsed) || parsed < 0) {
230+
errorBox(`Invalid ${flag}`, `Got "${raw}". Must be a number of seconds, 0 or more.`);
231+
failUsage();
232+
}
233+
return parsed;
234+
};
235+
const startSeconds = args.start === undefined ? 0 : seconds("--start", args.start);
236+
const endSeconds = args.end === undefined ? undefined : seconds("--end", args.end);
237+
if (endSeconds !== undefined && endSeconds <= startSeconds) {
238+
errorBox("Invalid range", `--end (${endSeconds}) must be after --start (${startSeconds}).`);
239+
failUsage();
240+
}
241+
const limit = rangeLimit(format, fps, hdr);
242+
if (limit) {
243+
errorBox(
244+
"A range renders what chunked renders can",
245+
limit,
246+
"Remove --start/--end to render the whole film.",
247+
);
248+
failUsage();
249+
}
250+
return { startSeconds, endSeconds };
251+
}
252+
253+
function rangeLimit(format: RenderFormat, fps: Fps, hdr: boolean | undefined): string | undefined {
254+
if (format !== "mp4") return `--start/--end render MP4 only, not ${format}.`;
255+
if (fps.den !== 1 || !isDistributedFps(fps.num)) {
256+
return `--start/--end need a whole frame rate in ${DISTRIBUTED_FPS.join(", ")}, not ${fps.num}/${fps.den}.`;
257+
}
258+
if (hdr) return "--start/--end render SDR only, not --hdr.";
259+
return undefined;
260+
}
261+
210262
function positiveInteger(raw: string, title: string, message: string, min = 1): number {
211263
const parsed = Number(raw);
212264
if (!Number.isInteger(parsed) || parsed < min) {
@@ -545,6 +597,7 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
545597
failUsage();
546598
}
547599

600+
const range = parseRenderRange(args, format, fps, args.hdr);
548601
const quiet = args.quiet ?? false;
549602
const batchJson = args.json ?? false;
550603
return Object.freeze({
@@ -592,6 +645,7 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
592645
vp9CpuUsed,
593646
videoBitrate,
594647
...delivery,
648+
range,
595649
hdrMode: args.sdr ? "force-sdr" : args.hdr ? "force-hdr" : "auto",
596650
pageSideCompositing: args["page-side-compositing"] !== false,
597651
experimentalFastCapture: args["experimental-fast-capture"] === true,

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

Lines changed: 8 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+
range?: { startSeconds: number; endSeconds?: number };
5455
proresProfile?: string;
5556
maxBitrate?: string;
5657
bufferSize?: string;
@@ -148,6 +149,13 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
148149
...(options.vp9CpuUsed != null ? ["--vp9-cpu-used", String(options.vp9CpuUsed)] : []),
149150
...(options.videoBitrate ? ["--video-bitrate", options.videoBitrate] : []),
150151
...(options.proresProfile ? ["--prores-profile", options.proresProfile] : []),
152+
...(options.range
153+
? [
154+
"--start",
155+
String(options.range.startSeconds),
156+
...(options.range.endSeconds != null ? ["--end", String(options.range.endSeconds)] : []),
157+
]
158+
: []),
151159
...(options.keyframeIntervalSeconds != null
152160
? ["--keyframe-interval", String(options.keyframeIntervalSeconds)]
153161
: []),

‎packages/producer/scripts/integration-tests.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
"src/services/distributed/planSizeCap.test.ts",
1717
"src/services/distributed/planV2RemoteFiles.test.ts",
1818
"src/services/distributed/renderChunk.test.ts",
19+
"src/services/distributed/renderSpan.integration.test.ts",
1920
"src/services/fileServer.test.ts",
2021
"src/services/fileServer.file-race.test.ts",
2122
"src/services/fileServer.listenError.test.ts",

‎packages/producer/src/index.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ export {
2424
type RenderPerfSummary,
2525
type ProgressCallback,
2626
} from "./services/renderOrchestrator.js";
27+
export {
28+
renderSpan,
29+
RenderSpanUnsupportedError,
30+
spanFrameRange,
31+
type RenderSpanResult,
32+
} from "./services/distributed/renderSpan.js";
2733
export { extractSafeRenderErrorCode } from "./services/safeRenderErrorCode.js";
2834
export {
2935
RENDER_JOB_DIR,

0 commit comments

Comments
 (0)