Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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> {