@hyperframes/producer 0.8.169 → 0.8.171

package/dist/index.js

@@ -13969,6 +13969,13 @@ var PLAN_AUDIO_LEGACY_RELATIVE_PATH = "audio.aac";
 function isPlanAudioArtifactPath(path) {
   return path === PLAN_AUDIO_RELATIVE_PATH || path === PLAN_AUDIO_LEGACY_RELATIVE_PATH;
 }
+function resolvePlanAudioPath(planDir) {
+  for (const name of [PLAN_AUDIO_RELATIVE_PATH, PLAN_AUDIO_LEGACY_RELATIVE_PATH]) {
+    const candidate = join28(planDir, name);
+    if (existsSync18(candidate)) return candidate;
+  }
+  return null;
+}
 var INVALID_VIDEO_METADATA = "INVALID_VIDEO_METADATA";
 var PlanVideosMetadataError = class extends Error {
   // Read by cloud adapters across the package boundary to classify retries.
@@ -14621,9 +14628,28 @@ function buildLockedRenderConfig(input) {
     chunkSize: input.effectiveChunkSize,
     chunkCount: input.chunkCount,
     runtimeEnv: input.runtimeEnv,
-    variables: config.variables
+    variables: config.variables,
+    ...input.chunksCarryAudio ? { chunksCarryAudio: true } : {}
   };
 }
+function carriesChunkAudio(config, options) {
+  return options.chunksCarryAudio === true && config.format === "mp4" && config.cfr !== true;
+}
+async function fitPlanAudioToFrames(audioPath, workDir, totalFrames, fps, run) {
+  const fittedPath = join30(workDir, "audio-fitted.m4a");
+  const result = await padOrTrimAudioToVideoFrameCount({
+    videoPath: audioPath,
+    probeVideoFrameInfo: async () => ({ frameCount: totalFrames, fpsNum: fps, fpsDen: 1 }),
+    audioPath,
+    outputPath: fittedPath,
+    signal: run.signal,
+    timeoutMs: run.timeoutMs
+  });
+  if (!result.success) {
+    throw encoderFailureError("[plan] audio pad/trim failed", result);
+  }
+  renameSync5(fittedPath, audioPath);
+}
 function resolveEncoderTriple(config) {
   if (config.format === "mp4") {
     return resolveMp4EncoderTriple(config.codec);
@@ -14677,6 +14703,13 @@ function pathInside(root, path) {
   const rel = relative5(root, path);
   return rel === "" || rel.startsWith("..") || isAbsolute3(rel) ? null : rel;
 }
+function stableSourcePath(roots, srcPath) {
+  for (const [root, prefix] of roots) {
+    const rel = pathInside(root, srcPath);
+    if (rel !== null) return [prefix, ...rel.split(sep2)].filter(Boolean).join("/");
+  }
+  return srcPath;
+}
 function createVideoSourceShipper(input) {
   const shipped = /* @__PURE__ */ new Map();
   return (srcPath) => {
@@ -14889,12 +14922,17 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     workCompiledDir: compiledDir,
     workVideoFramesDir: stagedVideoFrames
   });
+  const sourceRoots = [
+    [stagedVideoFrames, "video-frames"],
+    [compiledDir, "compiled"],
+    [projectDir, ""]
+  ];
   const planVideosJson = buildPlanVideosJson({
     videos: composition.videos,
     compositionEnd: job.duration ?? Number.NaN,
     extracted: (extractResult.extractionResult?.extracted ?? []).map((ext) => ({
       videoId: ext.videoId,
-      srcPath: ext.srcPath,
+      srcPath: stableSourcePath(sourceRoots, ext.srcPath),
       framePattern: ext.framePattern,
       fps: ext.fps,
       totalFrames: ext.totalFrames,
@@ -14945,6 +14983,13 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   if (audioResult.hasAudio && existsSync19(audioResult.audioOutputPath)) {
     renameSync5(audioResult.audioOutputPath, planAudioPath);
   }
+  const chunksCarryAudio2 = carriesChunkAudio(config, options);
+  if (chunksCarryAudio2 && existsSync19(planAudioPath)) {
+    await fitPlanAudioToFrames(planAudioPath, workDir, totalFrames, config.fps, {
+      signal: abortSignal,
+      timeoutMs: cfg.ffmpegProcessTimeout
+    });
+  }
   const ffmpegVersion = await readFfmpegVersion();
   const producerVersion = readProducerVersion();
   const fontSnapshotSha = await readFontSnapshotSha();
@@ -14957,7 +15002,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     engineConfig: cfg,
     effectiveChunkSize,
     chunkCount,
-    runtimeEnv
+    runtimeEnv,
+    chunksCarryAudio: chunksCarryAudio2
   });
   const compositionJson = {
     durationSeconds: job.duration ?? 0,
@@ -16656,8 +16702,10 @@ function resolveExtractedVideoOutputDir(planDir, videoId) {
   }
   return outputDir;
 }
-function artifactTargets(path, videoDependencies) {
-  if (isPlanAudioArtifactPath(path)) return { chunks: [], assembler: true };
+function artifactTargets(path, videoDependencies, chunksCarryAudio2) {
+  if (isPlanAudioArtifactPath(path)) {
+    return { chunks: chunksCarryAudio2 ? "all" : [], assembler: true };
+  }
   if (path === "plan.json" || path === "meta/chunks.json" || path === "meta/encoder.json") {
     return { chunks: "all", assembler: true };
   }
@@ -16879,9 +16927,11 @@ function buildPlanV2Publication(executionPlanDir, digests) {
   }
   validateExtractionCacheCompleteSentinels(executionPlanDir);
   const videoDependencyPlan = buildVideoChunkDependencies(executionPlanDir, dimensions);
+  const encoder = readJsonFile(join36(executionPlanDir, "meta", "encoder.json"), "meta/encoder.json");
+  const chunksCarryAudio2 = isRecord3(encoder) && encoder.chunksCarryAudio === true;
   for (const file of listFiles(executionPlanDir)) {
     if (isExtractionCacheCompleteSentinelPath(file.path)) continue;
-    const targets = artifactTargets(file.path, videoDependencyPlan.dependencies);
+    const targets = artifactTargets(file.path, videoDependencyPlan.dependencies, chunksCarryAudio2);
     if ((file.path.startsWith("video-frames/") || file.path.startsWith("video-sources/")) && targets.chunks !== "all" && targets.chunks.length === 0 && !targets.assembler) {
       continue;
     }
@@ -16984,7 +17034,8 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
         listFiles(join36(stagingRoot, "compiled")).map(
           (file) => publishBlobFor(file.absolutePath, digests)
         )
-      )
+      ),
+      chunksCarryAudio: options.chunksCarryAudio
     });
     return await publishExecutionPlan(stagingRoot, publisher, { digests, log: config.logger });
   } catch (error) {
@@ -17307,6 +17358,7 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
     format,
     fps,
     fpsArg: fpsToFfmpegArg3(fps),
+    chunkSeconds: chunksCarryAudio(planDir) ? plan2.chunks.map((chunk) => (chunk.endFrame - chunk.startFrame) * fps.den / fps.num) : null,
     signal: options?.abortSignal,
     timeout: resolveConfig6().ffmpegProcessTimeout,
     log,
@@ -17369,10 +17421,10 @@ function readAssemblePlan(planDir, chunkPaths) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
   }
-  return plan2;
+  return { ...plan2, chunks };
 }
 function videoInputArgs(ctx, videoSources) {
-  return videoSources.length === 1 ? ["-i", videoSources[0]] : concatDemuxerInput(videoSources, ctx.workDir, ctx.fpsArg);
+  return videoSources.length === 1 ? ["-i", videoSources[0]] : concatDemuxerInput(videoSources, ctx.workDir, ctx.fpsArg, ctx.chunkSeconds);
 }
 async function reencodeCfr(ctx, chunkPaths, encoder) {
   const cfrOutputPath = join37(ctx.workDir, `cfr.${ctx.format}`);
@@ -17452,10 +17504,15 @@ async function writeJoined(ctx, videoSources, audioPath, finalPath) {
     throw encoderFailureError("[assemble] audio mux failed", muxResult);
   }
 }
-function concatDemuxerInput(chunkPaths, workDir, fpsArg) {
+function concatDemuxerInput(chunkPaths, workDir, fpsArg, chunkSeconds) {
   const listPath = join37(workDir, "concat-list.txt");
-  const body = chunkPaths.map((path) => `file '${path.replace(/'/g, "'\\''")}'`).join("\n");
-  writeFileSync11(listPath, `${body}
+  const head = chunkSeconds ? ["stream", "exact_stream_id 1"] : [];
+  const body = chunkPaths.map((path, i) => {
+    const line = `file '${path.replace(/'/g, "'\\''")}'`;
+    return chunkSeconds ? `${line}
+duration ${chunkSeconds[i].toFixed(6)}` : line;
+  });
+  writeFileSync11(listPath, `${[...head, ...body].join("\n")}
 `, "utf-8");
   return ["-r", fpsArg, "-f", "concat", "-safe", "0", "-i", listPath];
 }
@@ -17478,6 +17535,11 @@ async function runAssembleFfmpeg(args, step, signal, timeout) {
     });
   }
 }
+function chunksCarryAudio(planDir) {
+  const encoderJsonPath = join37(planDir, "meta", "encoder.json");
+  if (!existsSync25(encoderJsonPath)) return false;
+  return JSON.parse(readFileSync13(encoderJsonPath, "utf-8")).chunksCarryAudio === true;
+}
 function readCfrEncoder(planDir, format) {
   if (format !== "mp4") {
     throw new Error(
@@ -17562,6 +17624,104 @@ import {
   readWebGlVendorInfoFromCanvas,
   resolveConfig as resolveConfig7
 } from "@hyperframes/engine";
+
+// src/services/distributed/chunkAudio.ts
+import { appendRenderProvenanceArgs as appendRenderProvenanceArgs2, describeFfmpegFailure as describeFfmpegFailure3, runFfmpeg as runFfmpeg6 } from "@hyperframes/engine";
+function audioCutForChunk(grid, chunks, index, fps) {
+  const firstPacketAt = (frame) => Math.min(
+    grid.packetCount,
+    Math.max(
+      0,
+      Math.ceil(
+        (frame * fps.den * grid.sampleRate - grid.firstStart * fps.num) / (grid.packetSamples * fps.num)
+      )
+    )
+  );
+  const first = index === 0 ? 0 : firstPacketAt(chunks[index].startFrame);
+  const end = index === chunks.length - 1 ? grid.packetCount : firstPacketAt(chunks[index + 1].startFrame);
+  if (end <= first) return null;
+  const cutSeconds = (packet) => (grid.firstStart + packet * grid.packetSamples - grid.packetSamples / 2) / grid.sampleRate;
+  const seekSeconds = index === 0 ? null : cutSeconds(first);
+  const durationSeconds = end === grid.packetCount ? null : cutSeconds(end) - (seekSeconds ?? 0);
+  return { seekSeconds, durationSeconds, firstPacket: first, packetCount: end - first };
+}
+async function probeAacPacketGrid(audioPath) {
+  const probe = await runFfprobeJson([
+    "-v",
+    "error",
+    "-select_streams",
+    "a:0",
+    "-show_entries",
+    "stream=sample_rate,time_base,nb_frames:packet=pts,duration",
+    "-read_intervals",
+    "%+#1",
+    "-of",
+    "json",
+    "--",
+    audioPath
+  ]);
+  const stream = probe.streams?.[0] ?? {};
+  const packet = probe.packets?.[0] ?? {};
+  const sampleRate = Number(stream.sample_rate);
+  const [tbNum = NaN, tbDen = NaN] = String(stream.time_base).split("/").map(Number);
+  const toSamples = (ticks) => Number(ticks) * sampleRate * tbNum / tbDen;
+  const grid = {
+    sampleRate,
+    firstStart: toSamples(packet.pts),
+    packetSamples: toSamples(packet.duration),
+    packetCount: Number(stream.nb_frames)
+  };
+  const counts = [grid.sampleRate, grid.packetSamples, grid.packetCount];
+  if (!Number.isFinite(grid.firstStart) || !counts.every((n) => Number.isFinite(n) && n > 0)) {
+    throw new Error(`[chunkAudio] could not read the AAC packet grid: ${JSON.stringify(probe)}`);
+  }
+  return grid;
+}
+function chunkMuxArgs(input, cut) {
+  if (!cut) return ["-i", input.videoPath, "-map", "0:v:0"];
+  const seek = cut.seekSeconds === null ? [] : ["-ss", cut.seekSeconds.toFixed(6)];
+  const length = cut.durationSeconds === null ? [] : ["-t", cut.durationSeconds.toFixed(6)];
+  const exact = seek.length ? ["-copypriorss", "0"] : [];
+  return [
+    ...["-i", input.videoPath, ...seek, ...length, "-i", input.audioPath],
+    ...["-map", "0:v:0", "-map", "1:a:0", ...exact]
+  ];
+}
+async function muxChunkWithAudio(input) {
+  const grid = input.audioPath ? await probeAacPacketGrid(input.audioPath) : null;
+  const cut = grid ? audioCutForChunk(grid, input.chunks, input.chunkIndex, input.fps) : null;
+  const args = [...chunkMuxArgs(input, cut), "-c", "copy"];
+  appendRenderProvenanceArgs2(args, input.outputPath);
+  args.push("-y", input.outputPath);
+  const result = await runFfmpeg6(args, { signal: input.signal, timeout: input.timeoutMs });
+  if (!result.success) {
+    throw new Error(
+      `[chunkAudio] chunk mux failed: ${describeFfmpegFailure3(result, input.timeoutMs)}`
+    );
+  }
+  const slice = input.chunks[input.chunkIndex];
+  const expected = { video: slice.endFrame - slice.startFrame };
+  if (cut) expected.audio = cut.packetCount;
+  const probe = await runFfprobeJson([
+    "-v",
+    "error",
+    "-count_packets",
+    "-show_entries",
+    "stream=codec_type,nb_read_packets",
+    "-of",
+    "json",
+    "--",
+    input.outputPath
+  ]);
+  for (const [type, count] of Object.entries(expected)) {
+    const packets = Number(probe.streams?.find((s) => s.codec_type === type)?.nb_read_packets ?? 0);
+    if (packets !== count) {
+      throw new Error(`[chunkAudio] ${type} packets in chunk ${packets}, expected ${count}`);
+    }
+  }
+}
+
+// src/services/distributed/renderChunk.ts
 import { readWebGlVendorInfoFromCanvas as readWebGlVendorInfoFromCanvas2 } from "@hyperframes/engine";
 var FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
 var PLAN_HASH_MISMATCH = "PLAN_HASH_MISMATCH";
@@ -18111,7 +18271,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       const preset = resolvePresetForLockedEncoder(basePreset, encoder.encoder);
       const effectiveQuality = encoder.crf ?? preset.quality;
       const effectiveBitrate = encoder.crf != null ? void 0 : encoder.bitrate;
-      const videoOnlyPath = outputChunkPath;
+      const videoOnlyPath = encoder.chunksCarryAudio ? `${outputChunkPath}.video.mp4` : outputChunkPath;
       if (isPngSequence) {
         if (!existsSync26(outputChunkPath)) mkdirSync16(outputChunkPath, { recursive: true });
       } else {
@@ -18122,16 +18282,16 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       await runEncodeStage({
         job,
         log,
-        outputPath: outputChunkPath,
+        outputPath: videoOnlyPath,
         framesDir,
         videoOnlyPath,
         width: Math.round(plan2.dimensions.width * encoder.deviceScaleFactor),
         height: Math.round(plan2.dimensions.height * encoder.deviceScaleFactor),
         needsAlpha: plan2.dimensions.format !== "mp4",
         captureImageFormat: captureOptions.format ?? "jpeg",
-        // Each chunk produces video only — audio is muxed once at assemble
-        // time. Suppressing `hasAudio` skips the png-sequence audio sidecar
-        // AND the mp4 audio mux.
+        // The encoder writes video only; audio joins at assemble time or in the
+        // chunk that carries audio. Suppressing `hasAudio` skips the png-sequence audio
+        // sidecar AND the mp4 audio mux.
         hasAudio: false,
         isPngSequence,
         // `DistributedFormat` has no "gif" member — distributed chunks are
@@ -18158,6 +18318,18 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
         lockGopForChunkConcat: !isPngSequence,
         gopSize: framesInChunk
       });
+      if (encoder.chunksCarryAudio) {
+        await muxChunkWithAudio({
+          videoPath: videoOnlyPath,
+          audioPath: resolvePlanAudioPath(planDir),
+          outputPath: outputChunkPath,
+          chunks,
+          chunkIndex,
+          fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
+          timeoutMs: cfg.ffmpegProcessTimeout
+        });
+        rmSync15(videoOnlyPath, { force: true });
+      }
       encodeStageMs = Date.now() - encodeStarted;
     } finally {
       if (session) {

package/dist/services/distributed/chunkAudio.d.ts

@@ -0,0 +1,30 @@
+import type { Fps } from "@hyperframes/core";
+import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
+/** Where AAC packet `j` of the plan audio starts: `firstStart + j * packetSamples`, in samples. */
+interface AacPacketGrid {
+    sampleRate: number;
+    firstStart: number;
+    packetSamples: number;
+    packetCount: number;
+}
+/** Input-side `-ss` / `-t` that select exactly packets `[first, end)` for one chunk. */
+interface AudioCut {
+    seekSeconds: number | null;
+    durationSeconds: number | null;
+    firstPacket: number;
+    packetCount: number;
+}
+export declare function audioCutForChunk(grid: AacPacketGrid, chunks: readonly ChunkSliceJson[], index: number, fps: Fps): AudioCut | null;
+interface MuxInput {
+    videoPath: string;
+    audioPath: string | null;
+    outputPath: string;
+    chunks: readonly ChunkSliceJson[];
+    chunkIndex: number;
+    fps: Fps;
+    signal?: AbortSignal;
+    timeoutMs: number;
+}
+/** Mux one encoded chunk with the plan audio packets it owns into a regular mp4 at `outputPath`. */
+export declare function muxChunkWithAudio(input: MuxInput): Promise<void>;
+export {};

package/dist/services/distributed/plan.d.ts

@@ -205,6 +205,11 @@ export interface BuildLocalExecutionPlanOptions {
     readonly digests?: PlanFileDigests;
     /** Runs while the audio mixes, once `compiled/` and the video trees are final. */
     readonly whileAudioMixes?: () => Promise<void>;
+    /**
+     * mp4 chunks carry their own slice of the plan audio (renderChunk muxes it). Ignored for other
+     * formats and with `cfr`, which re-encodes.
+     */
+    readonly chunksCarryAudio?: boolean;
 }
 export declare function logPlanStage(log: ProducerLogger, stage: string, startedAt: number): void;
 /**

package/dist/services/distributed/planV2.d.ts

@@ -88,6 +88,7 @@ export interface PlanV2WithPublisherOptions {
      * can avoid a second set of data blocks.
      */
     readonly stagingParentDir?: string;
+    readonly chunksCarryAudio?: boolean;
 }
 export interface PlanV2MaterializationResult {
     readonly planDir: string;

package/dist/services/render/audioPadTrim.d.ts

@@ -112,3 +112,4 @@ export declare function buildPadTrimAudioArgs(audioPath: string, outputPath: str
  */
 export declare function padOrTrimAudioToVideoFrameCount(input: PadTrimAudioInput): Promise<PadTrimAudioResult>;
 export declare function defaultProbeVideoFrameInfo(videoPath: string, signal?: AbortSignal): Promise<ProbeVideoFrameInfo>;
+export declare function runFfprobeJson<T>(args: string[], signal?: AbortSignal): Promise<T>;

package/dist/services/render/stages/freezePlan.d.ts

@@ -69,6 +69,7 @@ export interface LockedRenderConfig {
      * before this field existed.
      */
     variables?: Record<string, unknown>;
+    chunksCarryAudio?: true;
 }
 export interface CompositionMetadataJson {
     durationSeconds: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.169",
+  "version": "0.8.171",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "0.8.169",
-    "@hyperframes/engine": "0.8.169",
-    "@hyperframes/lint": "0.8.169",
-    "@hyperframes/parsers": "0.8.169",
-    "@hyperframes/studio-server": "0.8.169"
+    "@hyperframes/core": "0.8.171",
+    "@hyperframes/lint": "0.8.171",
+    "@hyperframes/engine": "0.8.171",
+    "@hyperframes/studio-server": "0.8.171",
+    "@hyperframes/parsers": "0.8.171"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.8.169"
+    "@hyperframes/aws-lambda": "0.8.171"
   },
   "engines": {
     "node": ">=22"