Skip to content

Write HTML. Render video. Built for agents.

perf(producer): assemble in one pass and keep its disk use under one output copy (#5768)

Miguel Ángela498cf2032c6
diff --git a/packages/aws-lambda/src/handler.ts b/packages/aws-lambda/src/handler.ts
index d0af408879..a3456ea2fc 100644
--- a/packages/aws-lambda/src/handler.ts
+++ b/packages/aws-lambda/src/handler.ts
@@ -677,7 +677,9 @@ async function handleAssembleV2(
// `downloadAndMaterializePlanV2` materializes atomically. Audio is
// assembler-only and lives at the familiar v1-compatible location.
const audioPath = resolvePlanAudioPath(planDir);
+ const chunksStarted = Date.now();
const chunkPaths = await downloadChunkObjects(s3, event.ChunkS3Uris, work, event.Format);
+ const chunksMs = Date.now() - chunksStarted;
const finalOutput =
event.Format === "png-sequence"
? join(work, "output-frames")
@@ -685,6 +687,7 @@ async function handleAssembleV2(
const result = await primitive(planDir, chunkPaths, audioPath, finalOutput, {
cfr: event.Cfr === true,
});
+ const uploadStarted = Date.now();
if (event.Format === "png-sequence") {
const tarball = `${finalOutput}.tar.gz`;
await tarDirectory(finalOutput, tarball);
@@ -692,6 +695,13 @@ async function handleAssembleV2(
} else {
await uploadFileToS3(s3, finalOutput, event.OutputS3Uri);
}
+ logEvent({
+ event: "assemble_stages",
+ planMs: chunksStarted - started,
+ chunksMs,
+ assembleMs: result.durationMs,
+ uploadMs: Date.now() - uploadStarted,
+ });
return {
Action: "assemble",
OutputS3Uri: event.OutputS3Uri,
diff --git a/packages/engine/src/services/chunkEncoder.ts b/packages/engine/src/services/chunkEncoder.ts
index e733eb7d26..98cd10aa08 100644
--- a/packages/engine/src/services/chunkEncoder.ts
+++ b/packages/engine/src/services/chunkEncoder.ts
@@ -102,6 +102,8 @@ export interface MuxVideoWithAudioOptions extends Partial<
* depend on the file extension alone.
*/
audioCodec?: "aac";
+ /** Replaces `-i <videoPath>` (which is then unused), e.g. with a concat-demuxer input. */
+ videoInputArgs?: readonly string[];
/**
* @deprecated No longer used. `-avoid_negative_ts` is never passed for
* mp4/mov muxing (ffmpeg's `auto` default already resolves to `disabled`
@@ -110,7 +112,6 @@ export interface MuxVideoWithAudioOptions extends Partial<
* source compatibility; it will be removed in a future major.
*/
preserveAudioPrimingEditList?: boolean;
- /** Hard cap copied audio to the already-encoded video's exact duration. */
}
async function shouldCopyAacSidecar(
@@ -785,7 +786,7 @@ export async function muxVideoWithAudio(
const isWebm = outputPath.endsWith(".webm");
const isMov = outputPath.endsWith(".mov");
const shouldCopyAudio = isWebm ? false : await shouldCopyAacSidecar(audioPath, config);
- const args = ["-i", videoPath, "-i", audioPath, "-c:v", "copy"];
+ const args = [...(config?.videoInputArgs ?? ["-i", videoPath]), "-i", audioPath, "-c:v", "copy"];
if (isWebm) {
args.push("-c:a", "libopus", "-b:a", "128k");
diff --git a/packages/producer/src/services/distributed/assemble.test.ts b/packages/producer/src/services/distributed/assemble.test.ts
index 58c6d96104..65711d2946 100644
--- a/packages/producer/src/services/distributed/assemble.test.ts
+++ b/packages/producer/src/services/distributed/assemble.test.ts
@@ -29,11 +29,14 @@ import {
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
+ applyFaststart,
+ muxVideoWithAudio,
PROVENANCE_RENDERER_NAME,
PROVENANCE_VERSION,
readRenderProvenance,
renderProvenanceArgs,
} from "@hyperframes/engine";
+import { padOrTrimAudioToVideoFrameCount } from "../render/audioPadTrim.js";
import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
import { assemble, cfrRateControlArgs } from "./assemble.js";
import type { DistributedFormat } from "./shared.js";
@@ -91,14 +94,14 @@ function buildPlanDir(
* independently concatenable because GOP === frame count and the first
* frame is forced as a keyframe.
*/
-function makeMp4Chunk(outputPath: string, frameCount: number): void {
+function makeMp4Chunk(outputPath: string, frameCount: number, size = "160x120"): void {
const args = [
"-v",
"error",
"-f",
"lavfi",
"-i",
- `testsrc=size=160x120:rate=30:duration=${frameCount / 30}`,
+ `testsrc=size=${size}:rate=30:duration=${frameCount / 30}`,
"-c:v",
"libx264",
"-preset",
@@ -229,6 +232,36 @@ function probeStream(
return parsed.streams?.[0] ?? null;
}
+/** Per-packet pts, dts, duration, size and payload hash of one stream. */
+function streamPackets(path: string, stream: "v" | "a"): string {
+ const result = spawnSync(
+ "ffmpeg",
+ ["-v", "error", "-i", path, "-map", `0:${stream}:0`, "-c", "copy", "-f", "framemd5", "-"],
+ { stdio: "pipe" },
+ );
+ if (result.status !== 0) throw new Error(result.stderr.toString().slice(-400));
+ return result.stdout.toString();
+}
+
+/** Three 1 s chunks plus audio 0.5 s too long, so the trim branch runs. */
+function buildAudioFixture(): { planDir: string; chunkPaths: string[]; audioPath: string } {
+ const chunks: ChunkSliceJson[] = [0, 1, 2].map((index) => ({
+ index,
+ startFrame: index * 30,
+ endFrame: (index + 1) * 30,
+ }));
+ const planDir = buildPlanDir("mp4", chunks, 90, true);
+ const chunkPaths = chunks.map(({ index }) => join(planDir, `chunk-${index}.mp4`));
+ for (const chunkPath of chunkPaths) makeMp4Chunk(chunkPath, 30, "640x360");
+ const audioPath = join(planDir, "audio.m4a");
+ makeAacAudio(audioPath, 3.5);
+ return { planDir, chunkPaths, audioPath };
+}
+
+function diskKb(path: string): number {
+ return Number(spawnSync("du", ["-sk", path]).stdout.toString().split("\t")[0]);
+}
+
describe("assemble()", () => {
const TIMEOUT_MS = 30_000;
@@ -484,6 +517,86 @@ describe("assemble()", () => {
TIMEOUT_MS,
);
+ it(
+ "keeps local disk under the chunks plus one copy of the output",
+ async () => {
+ if (!hasFfmpeg || process.platform === "win32") return;
+ const { planDir, chunkPaths, audioPath } = buildAudioFixture();
+ const outputPath = join(planDir, "output.mp4");
+ // Every intermediate is complete when its ffmpeg exits, so the disk
+ // total at each exit bounds the peak.
+ const diskLog = join(planDir, "disk.log");
+ const wrapper = join(runRoot, `ffmpeg-disk-${Date.now()}.sh`);
+ const realFfmpeg = process.env.HYPERFRAMES_FFMPEG_PATH?.trim() || "ffmpeg";
+ writeFileSync(
+ wrapper,
+ `#!/bin/sh\n"${realFfmpeg}" "$@"\nstatus=$?\ndu -sk '${planDir}' | cut -f1 >> '${diskLog}'\nexit $status\n`,
+ { mode: 0o755 },
+ );
+ const baselineKb = diskKb(planDir);
+ const previous = process.env.HYPERFRAMES_FFMPEG_PATH;
+ process.env.HYPERFRAMES_FFMPEG_PATH = wrapper;
+ try {
+ await assemble(planDir, chunkPaths, audioPath, outputPath);
+ } finally {
+ if (previous === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
+ else process.env.HYPERFRAMES_FFMPEG_PATH = previous;
+ }
+ const peakKb = Math.max(...readFileSync(diskLog, "utf8").trim().split("\n").map(Number));
+ const outputKb = statSync(outputPath).size / 1024;
+ expect(peakKb - baselineKb).toBeLessThan(outputKb * 1.5);
+ },
+ TIMEOUT_MS,
+ );
+
+ it(
+ "writes the same video and audio packets as separate concat, mux and faststart passes",
+ async () => {
+ if (!hasFfmpeg) return;
+ const { planDir, chunkPaths, audioPath } = buildAudioFixture();
+ const outputPath = join(planDir, "output.mp4");
+ await assemble(planDir, chunkPaths, audioPath, outputPath);
+
+ const concatList = join(planDir, "legacy-list.txt");
+ writeFileSync(concatList, chunkPaths.map((path) => `file '${path}'`).join("\n"));
+ const concatPath = join(planDir, "legacy-concat.mp4");
+ const concat = spawnSync("ffmpeg", [
+ ...["-v", "error", "-r", "30", "-f", "concat", "-safe", "0", "-i", concatList],
+ ...["-c", "copy", ...renderProvenanceArgs(concatPath), "-y", concatPath],
+ ]);
+ expect(concat.status).toBe(0);
+ const paddedPath = join(planDir, "legacy-audio.m4a");
+ expect(
+ (
+ await padOrTrimAudioToVideoFrameCount({
+ videoPath: concatPath,
+ audioPath,
+ outputPath: paddedPath,
+ })
+ ).success,
+ ).toBe(true);
+ const fps = { num: 30, den: 1 };
+ const muxPath = join(planDir, "legacy-mux.mp4");
+ const mux = await muxVideoWithAudio(
+ concatPath,
+ paddedPath,
+ muxPath,
+ undefined,
+ { audioCodec: "aac" },
+ fps,
+ );
+ expect(mux.success).toBe(true);
+ const legacyPath = join(planDir, "legacy.mp4");
+ expect((await applyFaststart(muxPath, legacyPath, undefined, undefined, fps)).success).toBe(
+ true,
+ );
+
+ expect(streamPackets(outputPath, "v")).toBe(streamPackets(legacyPath, "v"));
+ expect(streamPackets(outputPath, "a")).toBe(streamPackets(legacyPath, "a"));
+ },
+ TIMEOUT_MS,
+ );
+
it(
"cfr:true re-encodes for exact avg_frame_rate matching r_frame_rate",
async () => {
diff --git a/packages/producer/src/services/distributed/assemble.ts b/packages/producer/src/services/distributed/assemble.ts
index 4780915436..5647c3eb55 100644
--- a/packages/producer/src/services/distributed/assemble.ts
+++ b/packages/producer/src/services/distributed/assemble.ts
@@ -10,14 +10,10 @@
* decodable). For png-sequence chunks (each chunk is a directory of
* frames) this is a straight directory merge with global re-numbering.
*
- * Mux + faststart for mp4 / mov / webm go through the engine's
- * `muxVideoWithAudio` + `applyFaststart` helpers — same path the
- * in-process renderer uses; we just feed concat output rather than
- * streaming-encoder output. (Faststart is a no-op for webm and mov —
- * applyFaststart copies the input verbatim.) Audio length is
- * pad-or-trimmed to `frameCount / fps` via
- * `padOrTrimAudioToVideoFrameCount` so the mux step doesn't introduce
- * sub-millisecond drift at the end of long renders.
+ * Join, audio mux and mp4 faststart run as one ffmpeg pass over the concat
+ * demuxer, so disk holds the chunks plus one output copy. Audio is first
+ * pad-or-trimmed to `frameCount / fps` (frames summed over the chunks) so
+ * the mux adds no drift at the end of long renders.
*
* Pure function over local paths. No networking. The caller is responsible
* for moving `outputPath` to its orchestration-level storage.
@@ -30,6 +26,7 @@ import {
mkdtempSync,
readFileSync,
readdirSync,
+ renameSync,
rmSync,
statSync,
writeFileSync,
@@ -37,7 +34,6 @@ import {
import { dirname, join } from "node:path";
import {
appendRenderProvenanceArgs,
- applyFaststart,
describeFfmpegFailure,
getEncoderPreset,
MIXED_AUDIO_FILENAME,
@@ -48,7 +44,11 @@ import {
import { fpsToFfmpegArg } from "@hyperframes/core";
import { defaultLogger, type ProducerLogger } from "../../logger.js";
import { formatExportFrameName } from "../../utils/paths.js";
-import { padOrTrimAudioToVideoFrameCount } from "../render/audioPadTrim.js";
+import {
+ defaultProbeVideoFrameInfo,
+ padOrTrimAudioToVideoFrameCount,
+ type ProbeVideoFrameInfo,
+} from "../render/audioPadTrim.js";
import { encoderFailureError } from "../render/encoderInterruption.js";
import type { ChunkSliceJson, LockedRenderConfig } from "../render/stages/freezePlan.js";
import { DISTRIBUTED_RENDER_CAPABILITIES, readPlanProtocolV1 } from "./planProtocol.js";
@@ -133,10 +133,71 @@ export async function assemble(
): Promise<AssembleResult> {
const start = Date.now();
const log = options?.logger ?? defaultLogger;
- const abortSignal = options?.abortSignal;
const cfr = options?.cfr === true;
- const { ffmpegProcessTimeout } = resolveConfig();
+ const plan = readAssemblePlan(planDir, chunkPaths);
+ if (plan.dimensions.format === "png-sequence") {
+ // ── 2a. png-sequence: merge frame directories with global re-numbering
+ return mergePngFrameDirs(chunkPaths, outputPath, plan.totalFrames, audioPath, start);
+ }
+
+ // ── 2b. mp4 / mov / webm: join + audio mux + faststart in one pass ─────
+ const format = plan.dimensions.format;
+ const cfrEncoder = cfr ? readCfrEncoder(planDir, format) : null;
+ if (!existsSync(dirname(outputPath))) {
+ mkdirSync(dirname(outputPath), { recursive: true });
+ }
+ const workDir = mkdtempSync(`${outputPath}.assemble-work-`);
+ const fps = { num: plan.dimensions.fpsNum, den: plan.dimensions.fpsDen };
+ const stageMs: Record<string, number> = {};
+ const ctx: JoinContext = {
+ workDir,
+ format,
+ fps,
+ fpsArg: fpsToFfmpegArg(fps),
+ signal: options?.abortSignal,
+ timeout: resolveConfig().ffmpegProcessTimeout,
+ log,
+ timed: async (stage, run) => {
+ const stageStart = Date.now();
+ const result = await run();
+ stageMs[stage] = Date.now() - stageStart;
+ return result;
+ },
+ };
+
+ try {
+ const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
+ const finalPath = join(workDir, `output.${format}`);
+ const audio = audioPath !== null && existsSync(audioPath) ? audioPath : null;
+ await writeJoined(ctx, videoSources, audio, finalPath);
+ renameSync(finalPath, outputPath);
+ log.info("[assemble] stage timings", {
+ ...stageMs,
+ chunks: chunkPaths.length,
+ totalMs: Date.now() - start,
+ });
+ } finally {
+ try {
+ rmSync(workDir, { recursive: true, force: true });
+ } catch (err) {
+ log.warn("[assemble] failed to remove work dir", {
+ workDir,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+
+ const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
+ return {
+ outputPath,
+ durationMs: Date.now() - start,
+ framesEncoded: plan.totalFrames,
+ fileSize,
+ };
+}
+
+function readAssemblePlan(planDir: string, chunkPaths: readonly string[]): PlanJsonForAssemble {
// ── 1. Validate planDir manifest matches chunkPaths shape ──────────────
const planJsonPath = join(planDir, "plan.json");
const chunksJsonPath = join(planDir, "meta", "chunks.json");
@@ -163,241 +224,188 @@ export async function assemble(
}
}
- if (plan.dimensions.format === "png-sequence") {
- // ── 2a. png-sequence: merge frame directories with global re-numbering
- return mergePngFrameDirs(chunkPaths, outputPath, plan.totalFrames, audioPath, start);
- }
+ return plan;
+}
- // ── 2b. mp4 / mov / webm: concat-copy then mux + faststart ────────────
- if (!existsSync(dirname(outputPath))) {
- mkdirSync(dirname(outputPath), { recursive: true });
- }
- const workDir = mkdtempSync(`${outputPath}.assemble-work-`);
+interface JoinContext {
+ workDir: string;
+ format: DistributedFormat;
+ fps: { num: number; den: number };
+ fpsArg: string;
+ signal: AbortSignal | undefined;
+ timeout: number;
+ log: ProducerLogger;
+ timed: <T>(stage: string, run: () => Promise<T>) => Promise<T>;
+}
- try {
- const concatOutputPath = join(workDir, `concat.${plan.dimensions.format}`);
- const fpsArg = fpsToFfmpegArg({
- num: plan.dimensions.fpsNum,
- den: plan.dimensions.fpsDen,
- });
+// A one-entry concat list ignores the input-side `-r` (observed `359/12` in the
+// container), so a single file is read directly; every write also sets output `-r`.
+function videoInputArgs(ctx: JoinContext, videoSources: readonly string[]): string[] {
+ return videoSources.length === 1
+ ? ["-i", videoSources[0]!]
+ : concatDemuxerInput(videoSources, ctx.workDir, ctx.fpsArg);
+}
- // Single-chunk renders bypass the concat demuxer entirely. ffmpeg's
- // concat demuxer with a one-entry list re-runs as a straight remux of
- // the single source, and in that path the input-side `-r` flag does
- // not consistently override the source's PTS-derived r_frame_rate
- // (observed: `359/12` carrying through to the output container while
- // the equivalent multi-chunk path produces `30/1` exact). Running a
- // direct `-c copy` remux with `-r <fps>` as an output flag gives the
- // muxer the authoritative rate to stamp into the container without
- // touching the encoded stream. Multi-chunk renders continue through
- // the concat demuxer where the existing `-r` input flag works.
- if (chunkPaths.length === 1) {
- const remuxArgs = ["-i", chunkPaths[0]!, "-c", "copy", "-r", fpsArg];
- appendRenderProvenanceArgs(remuxArgs, concatOutputPath);
- remuxArgs.push("-y", concatOutputPath);
- const remuxResult = await runFfmpeg(remuxArgs, {
- signal: abortSignal,
- timeout: ffmpegProcessTimeout,
- });
- if (!remuxResult.success) {
- throw encoderFailureError("[assemble] ffmpeg single-chunk remux failed", {
- error: describeFfmpegFailure(remuxResult, ffmpegProcessTimeout),
- failureReason: remuxResult.failureReason,
- });
- }
- } else {
- // Concat list file — one `file '<path>'` per chunk, in order. ffmpeg's
- // concat demuxer escapes single quotes via `'\''`; we replicate that
- // here so chunk paths containing quotes don't break the parser.
- const concatListPath = join(workDir, "concat-list.txt");
- const concatBody = chunkPaths
- .map((path) => `file '${path.replace(/'/g, "'\\''")}'`)
- .join("\n");
- writeFileSync(concatListPath, `${concatBody}\n`, "utf-8");
+// ── 2c. Optional exact-CFR re-encode ──────────────────────────────────
+// Lands the stream-level `avg_frame_rate` (PTS-derived under stream copy)
+// on the requested rational, for consumers that strict-check it.
+async function reencodeCfr(
+ ctx: JoinContext,
+ chunkPaths: readonly string[],
+ encoder: CfrRateControlSource,
+): Promise<string> {
+ const cfrOutputPath = join(ctx.workDir, `cfr.${ctx.format}`);
+ const cfrArgs = [
+ ...videoInputArgs(ctx, chunkPaths),
+ "-c:v",
+ "libx264",
+ ...cfrRateControlArgs(encoder),
+ "-pix_fmt",
+ "yuv420p",
+ "-fps_mode",
+ "cfr",
+ "-r",
+ ctx.fpsArg,
+ ];
+ appendRenderProvenanceArgs(cfrArgs, cfrOutputPath);
+ cfrArgs.push("-y", cfrOutputPath);
+ await ctx.timed("cfrMs", () =>
+ runAssembleFfmpeg(cfrArgs, "cfr re-encode", ctx.signal, ctx.timeout),
+ );
+ ctx.log.info("[assemble] cfr re-encode applied", {
+ format: ctx.format,
+ fpsNum: ctx.fps.num,
+ fpsDen: ctx.fps.den,
+ });
+ return cfrOutputPath;
+}
- // Set the exact input framerate so the concat demuxer doesn't
- // PTS-average a fractional rational like `360000/12001` instead
- // of `30/1` into the output container metadata. `-c copy` is
- // retained; no re-encode.
- const concatArgs = [
- "-r",
- fpsArg,
- "-f",
- "concat",
- "-safe",
- "0",
- "-i",
- concatListPath,
- "-c",
- "copy",
- ];
- appendRenderProvenanceArgs(concatArgs, concatOutputPath);
- concatArgs.push("-y", concatOutputPath);
- const concatResult = await runFfmpeg(concatArgs, {
- signal: abortSignal,
- timeout: ffmpegProcessTimeout,
- });
- if (!concatResult.success) {
- throw encoderFailureError("[assemble] ffmpeg concat-copy failed", {
- error: describeFfmpegFailure(concatResult, ffmpegProcessTimeout),
- failureReason: concatResult.failureReason,
- });
- }
- }
+// ── 3. Audio pad-or-trim, then one write of the deliverable ──────────
+async function writeJoined(
+ ctx: JoinContext,
+ videoSources: readonly string[],
+ audioPath: string | null,
+ finalPath: string,
+): Promise<void> {
+ if (audioPath === null) {
+ const joinArgs = [...videoInputArgs(ctx, videoSources), "-c", "copy"];
+ if (ctx.format === "mp4") joinArgs.push("-movflags", "+faststart");
+ appendRenderProvenanceArgs(joinArgs, finalPath);
+ joinArgs.push("-r", ctx.fpsArg, "-y", finalPath);
+ await ctx.timed("joinMs", () =>
+ runAssembleFfmpeg(joinArgs, "concat-copy", ctx.signal, ctx.timeout),
+ );
+ return;
+ }
+ const paddedAudioPath = join(ctx.workDir, "audio-padded.m4a");
+ const padTrimResult = await ctx.timed("audioMs", () =>
+ padOrTrimAudioToVideoFrameCount({
+ videoPath: videoSources[0]!,
+ probeVideoFrameInfo: () => probeJoinedFrameInfo(videoSources, ctx.fps, ctx.signal),
+ audioPath,
+ outputPath: paddedAudioPath,
+ signal: ctx.signal,
+ timeoutMs: ctx.timeout,
+ }),
+ );
+ if (!padTrimResult.success) {
+ throw encoderFailureError("[assemble] audio pad/trim failed", padTrimResult);
+ }
+ ctx.log.info("[assemble] audio normalized for mux", {
+ operation: padTrimResult.operation,
+ targetDurationSeconds: padTrimResult.targetDurationSeconds,
+ sourceDurationSeconds: padTrimResult.sourceDurationSeconds,
+ });
+ const muxResult = await ctx.timed("joinMs", () =>
+ muxVideoWithAudio(
+ videoSources[0]!,
+ paddedAudioPath,
+ finalPath,
+ ctx.signal,
+ {
+ audioCodec: "aac",
+ ffmpegProcessTimeout: ctx.timeout,
+ videoInputArgs: videoInputArgs(ctx, videoSources),
+ },
+ ctx.fps,
+ ),
+ );
+ if (!muxResult.success) {
+ throw encoderFailureError("[assemble] audio mux failed", muxResult);
+ }
+}
- // ── 2c. Optional exact-CFR re-encode ──────────────────────────────────
- // The concat / single-chunk step produces a stream-copy intermediate
- // whose container `r_frame_rate` is exact but whose stream-level
- // `avg_frame_rate` stays PTS-derived (concat-copy carries each chunk's
- // original PTS unmodified). For consumers that strict-check
- // `avg_frame_rate` or ms-precision duration (broadcast workflows,
- // frame-accurate compositors, some third-party transcoders), an
- // opt-in re-encode with `-fps_mode cfr -r <fps>` lands the stream's
- // avg-frame-rate on the requested rational exactly. Restricted to
- // mp4 / libx264 — webm and mov go through their own stream-copy
- // paths that don't exhibit the same avg-frame-rate drift, and h265
- // mp4 would silently transcode to h264 under the hardcoded
- // `-c:v libx264` re-encode (a typed throw is preferable to silent
- // codec loss).
- let postConcatPath = concatOutputPath;
- if (cfr) {
- if (plan.dimensions.format !== "mp4") {
- throw new Error(
- `[assemble] cfr=true is only supported for format="mp4" (got ` +
- `"${plan.dimensions.format}"). Stream-copy paths for webm and mov ` +
- `already produce exact avg_frame_rate; cfr re-encode is not needed.`,
- );
- }
- // Read `meta/encoder.json` to detect the chunk encoder. The cfr
- // re-encode hardcodes `-c:v libx264`; pairing it with h265 chunks
- // would silently transcode them to h264. Throw a typed error so the
- // caller surfaces the conflict instead of producing a wrong-codec
- // deliverable.
- const encoderJsonPath = join(planDir, "meta", "encoder.json");
- if (!existsSync(encoderJsonPath)) {
- throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
- }
- const encoderJson = JSON.parse(
- readFileSync(encoderJsonPath, "utf-8"),
- ) as CfrRateControlSource & { encoder?: string };
- if (encoderJson.encoder === "libx265-software") {
- throw new Error(
- `[assemble] cfr=true is not yet supported with codec: "h265". The ` +
- `cfr re-encode pass uses libx264 and would silently transcode the ` +
- `h265 chunks. Either disable cfr or render with codec: "h264".`,
- );
- }
- const cfrOutputPath = join(workDir, `cfr.${plan.dimensions.format}`);
- const cfrArgs = [
- "-i",
- concatOutputPath,
- "-c:v",
- "libx264",
- ...cfrRateControlArgs(encoderJson),
- "-pix_fmt",
- "yuv420p",
- "-fps_mode",
- "cfr",
- "-r",
- fpsArg,
- ];
- appendRenderProvenanceArgs(cfrArgs, cfrOutputPath);
- cfrArgs.push("-y", cfrOutputPath);
- const cfrResult = await runFfmpeg(cfrArgs, {
- signal: abortSignal,
- timeout: ffmpegProcessTimeout,
- });
- if (!cfrResult.success) {
- throw encoderFailureError("[assemble] ffmpeg cfr re-encode failed", {
- error: describeFfmpegFailure(cfrResult, ffmpegProcessTimeout),
- failureReason: cfrResult.failureReason,
- });
- }
- postConcatPath = cfrOutputPath;
- log.info("[assemble] cfr re-encode applied", {
- format: plan.dimensions.format,
- fpsNum: plan.dimensions.fpsNum,
- fpsDen: plan.dimensions.fpsDen,
- });
- }
+/** Concat-demuxer input args; `-r` keeps the demuxer from PTS-averaging the rate. */
+function concatDemuxerInput(
+ chunkPaths: readonly string[],
+ workDir: string,
+ fpsArg: string,
+): string[] {
+ // ffmpeg's concat list escapes a single quote as `'\''`.
+ const listPath = join(workDir, "concat-list.txt");
+ const body = chunkPaths.map((path) => `file '${path.replace(/'/g, "'\\''")}'`).join("\n");
+ writeFileSync(listPath, `${body}\n`, "utf-8");
+ return ["-r", fpsArg, "-f", "concat", "-safe", "0", "-i", listPath];
+}
- // ── 3. Audio: pad-or-trim then mux ────────────────────────────────────
- let normalizedAudioPath: string | null = null;
- if (audioPath !== null && existsSync(audioPath)) {
- const paddedAudioPath = join(workDir, "audio-padded.m4a");
- const padTrimResult = await padOrTrimAudioToVideoFrameCount({
- videoPath: postConcatPath,
- audioPath,
- outputPath: paddedAudioPath,
- signal: abortSignal,
- timeoutMs: ffmpegProcessTimeout,
- });
- if (!padTrimResult.success) {
- throw encoderFailureError("[assemble] audio pad/trim failed", padTrimResult);
- }
- normalizedAudioPath = paddedAudioPath;
- log.info("[assemble] audio normalized for mux", {
- operation: padTrimResult.operation,
- targetDurationSeconds: padTrimResult.targetDurationSeconds,
- sourceDurationSeconds: padTrimResult.sourceDurationSeconds,
- });
- }
+/** What a probe of the joined file would report: the chunks' frames at the plan's rate. */
+async function probeJoinedFrameInfo(
+ videoPaths: readonly string[],
+ fps: { num: number; den: number },
+ signal: AbortSignal | undefined,
+): Promise<ProbeVideoFrameInfo> {
+ const infos = await Promise.all(
+ videoPaths.map((path) => defaultProbeVideoFrameInfo(path, signal)),
+ );
+ return {
+ frameCount: infos.reduce((sum, info) => sum + info.frameCount, 0),
+ fpsNum: fps.num,
+ fpsDen: fps.den,
+ };
+}
- // mux + faststart paths mirror `runAssembleStage` for in-process renders
- // (`render/stages/assembleStage.ts`). We can't call that stage directly
- // because it operates on a `RenderJob` and emits `updateJobStatus`
- // payloads — the distributed activity has no job to thread through.
- const muxOutputPath =
- normalizedAudioPath !== null
- ? join(workDir, `mux.${plan.dimensions.format}`)
- : postConcatPath;
- if (normalizedAudioPath !== null) {
- const muxResult = await muxVideoWithAudio(
- postConcatPath,
- normalizedAudioPath,
- muxOutputPath,
- abortSignal,
- { audioCodec: "aac", ffmpegProcessTimeout },
- { num: plan.dimensions.fpsNum, den: plan.dimensions.fpsDen },
- );
- if (!muxResult.success) {
- throw encoderFailureError("[assemble] audio mux failed", muxResult);
- }
- }
+async function runAssembleFfmpeg(
+ args: string[],
+ step: string,
+ signal: AbortSignal | undefined,
+ timeout: number,
+): Promise<void> {
+ const result = await runFfmpeg(args, { signal, timeout });
+ if (!result.success) {
+ throw encoderFailureError(`[assemble] ffmpeg ${step} failed`, {
+ error: describeFfmpegFailure(result, timeout),
+ failureReason: result.failureReason,
+ });
+ }
+}
- // applyFaststart is a no-op for `.mov` (it copies the input to output);
- // we still call it so the success path produces `outputPath` regardless.
- const faststartResult = await applyFaststart(
- muxOutputPath,
- outputPath,
- abortSignal,
- { ffmpegProcessTimeout },
- {
- num: plan.dimensions.fpsNum,
- den: plan.dimensions.fpsDen,
- },
+/**
+ * The cfr re-encode hardcodes `-c:v libx264`: reject non-mp4 formats and h265
+ * chunks (which it would silently transcode) before any ffmpeg runs.
+ */
+function readCfrEncoder(planDir: string, format: DistributedFormat): CfrRateControlSource {
+ if (format !== "mp4") {
+ throw new Error(
+ `[assemble] cfr=true is only supported for format="mp4" (got ` +
+ `"${format}"). Stream-copy paths for webm and mov ` +
+ `already produce exact avg_frame_rate; cfr re-encode is not needed.`,
);
- if (!faststartResult.success) {
- throw encoderFailureError("[assemble] faststart failed", faststartResult);
- }
- } finally {
- try {
- rmSync(workDir, { recursive: true, force: true });
- } catch (err) {
- log.warn("[assemble] failed to remove work dir", {
- workDir,
- error: err instanceof Error ? err.message : String(err),
- });
- }
}
-
- const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
- return {
- outputPath,
- durationMs: Date.now() - start,
- framesEncoded: plan.totalFrames,
- fileSize,
+ const encoderJsonPath = join(planDir, "meta", "encoder.json");
+ if (!existsSync(encoderJsonPath)) {
+ throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
+ }
+ const encoderJson = JSON.parse(readFileSync(encoderJsonPath, "utf-8")) as CfrRateControlSource & {
+ encoder?: string;
};
+ if (encoderJson.encoder === "libx265-software") {
+ throw new Error(
+ `[assemble] cfr=true is not yet supported with codec: "h265". The ` +
+ `cfr re-encode pass uses libx264 and would silently transcode the ` +
+ `h265 chunks. Either disable cfr or render with codec: "h264".`,
+ );
+ }
+ return encoderJson;
}
/**
diff --git a/packages/producer/src/services/render/audioPadTrim.ts b/packages/producer/src/services/render/audioPadTrim.ts
index 7ad0309a76..c897dd60bb 100644
--- a/packages/producer/src/services/render/audioPadTrim.ts
+++ b/packages/producer/src/services/render/audioPadTrim.ts
@@ -77,8 +77,8 @@ export interface PadTrimAudioInput {
/** Deadline for each ffmpeg process; defaults to the engine's `ffmpegProcessTimeout`. */
timeoutMs?: number;
/**
- * Optional injectables for unit tests. Production callers omit them and
- * get the real `ffprobe`/`ffmpeg`-backed implementations.
+ * Optional injectables. Tests stub them; the distributed assembler supplies
+ * the frame probe because its video is still separate chunks.
*/
probeVideoFrameInfo?: (videoPath: string) => Promise<ProbeVideoFrameInfo>;
probeAudioInfo?: (audioPath: string, signal?: AbortSignal) => Promise<AudioProbeInfo>;
@@ -537,7 +537,7 @@ interface FfprobeOutput {
streams?: FfprobeStreamInfo[];
}
-async function defaultProbeVideoFrameInfo(
+export async function defaultProbeVideoFrameInfo(
videoPath: string,
signal?: AbortSignal,
): Promise<ProbeVideoFrameInfo> {