@hyperframes/producer 0.8.179 → 0.8.181

package/dist/distributed.d.ts

@@ -33,8 +33,8 @@ export { buildChunkSlices, measurePlanDirBytes, plan, rejectUnsupportedDistribut
 export { createPlanV2FromExecutionPlan, createPlanV2FromV1, getPlanV2ExecutionPlanHash, isPlanV2DeferredSourceArtifact, listPlanV2ArtifactsForTarget, materializePlanV2Target, planV2, planV2WithPublisher, publishPlanV2FromExecutionPlan, publishPlanV2FromV1, readPlanV2Manifest, validatePlanV2MaterializedTarget, PLAN_V2_INTEGRITY_UNRECOVERABLE, PLAN_V2_MATERIALIZATION_MARKER, PlanV2IntegrityError, type PlanV2Artifact, type PlanV2Limitations, type PlanV2Manifest, type PlanV2MaterializeOptions, type PlanV2MaterializationResult, type PlanV2MaterializationTarget, type PlanV2RemoteSources, type PlanV2Result, type PlanV2WithPublisherOptions, } from "./services/distributed/planV2.js";
 export { LocalPlanV2ArtifactPublisher, type LocalPlanV2ArtifactPublisherOptions, type PlanV2ArtifactPublisher, type PlanV2PublishBlob, } from "./services/distributed/planV2Publisher.js";
 export { assembleV2, renderChunkV2 } from "./services/distributed/planV2Execution.js";
-export { applyRuntimeEnvSnapshot, readWebGlVendorInfoFromCanvas, renderChunk, type ChunkRenderer, type ChunkResult, type EffectiveChunkResult, FFMPEG_VERSION_MISMATCH, INVALID_VIDEO_METADATA, PLAN_HASH_MISMATCH, RenderChunkValidationError, } from "./services/distributed/renderChunk.js";
-export { assemble, chunksAreStitchedMp4, type AssembleResult, } from "./services/distributed/assemble.js";
+export { applyRuntimeEnvSnapshot, readWebGlVendorInfoFromCanvas, renderChunk, type ChunkFrameRange, type ChunkRenderer, type ChunkResult, type EffectiveChunkResult, type RenderChunkOptions, CHUNK_FRAME_RANGE_INVALID, FFMPEG_VERSION_MISMATCH, INVALID_VIDEO_METADATA, PLAN_HASH_MISMATCH, RenderChunkValidationError, } from "./services/distributed/renderChunk.js";
+export { assemble, chunksAreStitchedMp4, type AssembleChunkPaths, type AssembleResult, } from "./services/distributed/assemble.js";
 export { muxChunkWithAudio } from "./services/distributed/chunkAudio.js";
 export { buildStitchedHeader, readMp4Layout, type Mp4Layout, type ReadRange, } from "./services/distributed/mp4Stitch.js";
 export { InvalidConfigError, type SerializableDistributedRenderConfig, validateDistributedRenderConfig, validateVariablesPayload, } from "./services/distributed/renderConfigValidation.js";

package/dist/distributed.js

@@ -5709,14 +5709,84 @@ import { mkdtempSync as mkdtempSync2, renameSync as renameSync2, rmSync as rmSyn
 import { dirname as dirname6, join as join13 } from "node:path";
 import {
   DEFAULT_CONFIG,
-  describeFfmpegFailure,
+  describeFfmpegFailure as describeFfmpegFailure2,
   extractAudioMetadata as extractAudioMetadata2,
   getFfprobeBinary,
   ManagedChildProcess,
-  runFfmpeg as runFfmpeg4,
+  runFfmpeg as runFfmpeg5,
   trackChildProcess
 } from "@hyperframes/engine";
 import { redactKnownPaths, redactTelemetryString as redactTelemetryString3 } from "@hyperframes/core";
+
+// src/services/render/audioTruePeak.ts
+import { aacSegmentCount, describeFfmpegFailure, runFfmpeg as runFfmpeg4 } from "@hyperframes/engine";
+var toDbfs = (token) => token.toLowerCase() === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
+function checkedDbfs(value) {
+  if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
+    throw new Error("[audioTruePeak] FFmpeg did not report AAC true peak");
+  }
+  return value;
+}
+async function scanTruePeak(audioPath, trim, timeoutMs, signal) {
+  let firstBlock;
+  let laterBlocks = Number.NEGATIVE_INFINITY;
+  let partialLine = "";
+  const readLines = (chunk) => {
+    const lines = (partialLine + chunk).split(/\r|\n/);
+    partialLine = lines.pop() ?? "";
+    for (const line of lines) {
+      const ftpk = /FTPK:([^d]*)dBFS/.exec(line)?.[1];
+      if (!ftpk) continue;
+      const block = Math.max(...ftpk.trim().split(/\s+/).map(toDbfs));
+      if (firstBlock === void 0) firstBlock = block;
+      else laterBlocks = Math.max(laterBlocks, block);
+    }
+  };
+  const result = await runFfmpeg4(
+    ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", `${trim}ebur128=peak=true`, "-f", "null", "-"],
+    { signal, timeout: timeoutMs, onStderr: readLines }
+  );
+  if (!result.success) {
+    throw new Error(`[audioTruePeak] ${describeFfmpegFailure(result, timeoutMs)}`);
+  }
+  const summary = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
+  return {
+    peak: checkedDbfs(toDbfs(summary.at(-1)?.[1] ?? "nan")),
+    firstBlock: checkedDbfs(firstBlock ?? Number.NEGATIVE_INFINITY),
+    laterBlocks: checkedDbfs(laterBlocks)
+  };
+}
+async function measureTruePeakDbfs(audioPath, options) {
+  const { timeoutMs, signal, segments } = options;
+  const wholeFile = async () => (await scanTruePeak(audioPath, "", timeoutMs, signal)).peak;
+  const block = 4800;
+  const count = segments?.sampleRate === 48e3 ? aacSegmentCount(segments.durationSeconds) : 1;
+  if (!segments || count === 1) return wholeFile();
+  const cut = (k) => k * Math.floor(segments.durationSeconds * 10 / count) * block;
+  const peers = new AbortController();
+  const segmentSignal = signal ? AbortSignal.any([signal, peers.signal]) : peers.signal;
+  const scans = await Promise.all(
+    Array.from({ length: count }, (_, k) => {
+      const start = k === 0 ? 0 : cut(k) - block;
+      const end = k === count - 1 ? "" : `:end_sample=${cut(k + 1)}`;
+      return scanTruePeak(
+        audioPath,
+        `atrim=start_sample=${start}${end},`,
+        timeoutMs,
+        segmentSignal
+      );
+    })
+  ).catch((error) => {
+    peers.abort();
+    throw error;
+  });
+  const last = scans[count - 1];
+  const counted = Math.max(scans[0].peak, ...scans.slice(1).map((scan) => scan.laterBlocks));
+  if (last.peak > last.firstBlock || last.peak <= counted) return Math.max(counted, last.peak);
+  return wholeFile();
+}
+
+// src/services/render/audioPadTrim.ts
 var AUDIO_DURATION_TOLERANCE_SECONDS = 1e-3;
 var AAC_DELIVERY_TRUE_PEAK_DBFS = -1;
 var AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB = 0.5;
@@ -5816,7 +5886,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   const probeAudio = input.probeAudioInfo ?? defaultProbeAudioInfo;
   const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
   const runner = input.runFfmpeg ?? ((args) => defaultRunFfmpeg(args, timeoutMs, input.signal));
-  const probeTruePeak = input.probeAudioTruePeakDbfs ?? (input.runFfmpeg ? void 0 : (audioPath, signal) => defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal));
+  const probeTruePeak = input.probeAudioTruePeakDbfs ?? (input.runFfmpeg ? void 0 : (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }));
   const [videoResult, audioResult] = await Promise.allSettled([
     probeVideo(input.videoPath),
     probeAudio(input.audioPath, input.signal)
@@ -5925,7 +5995,11 @@ async function constrainAacTruePeak(input) {
     audioPath: input.audioPath,
     targetDurationSeconds: input.targetDurationSeconds,
     signal: input.signal,
-    probeTruePeak: (audioPath, signal) => defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal),
+    probeTruePeak: async (audioPath, signal) => {
+      const { sampleRate } = await extractAudioMetadata2(audioPath, { signal });
+      const segments = { durationSeconds: input.targetDurationSeconds, sampleRate };
+      return measureTruePeakDbfs(audioPath, { timeoutMs, signal, segments });
+    },
     runner: (args) => defaultRunFfmpeg(args, timeoutMs, input.signal)
   });
 }
@@ -6062,28 +6136,12 @@ async function defaultProbeAudioInfo(audioPath, signal) {
     audioCodec: metadata.audioCodec
   };
 }
-async function defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal) {
-  const result = await runFfmpeg4(
-    ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"],
-    { signal, timeout: timeoutMs }
-  );
-  if (!result.success) {
-    throw new Error(`[audioPadTrim] ${describeFfmpegFailure(result, timeoutMs)}`);
-  }
-  const matches = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
-  const token = matches.at(-1)?.[1]?.toLowerCase();
-  const value = token === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
-  if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
-    throw new Error("[audioPadTrim] FFmpeg did not report AAC true peak");
-  }
-  return value;
-}
 async function defaultRunFfmpeg(args, timeoutMs, signal) {
-  const result = await runFfmpeg4(args, { signal, timeout: timeoutMs });
+  const result = await runFfmpeg5(args, { signal, timeout: timeoutMs });
   if (result.success) return { success: true };
   return {
     success: false,
-    error: `[audioPadTrim] ${describeFfmpegFailure(result, timeoutMs)}`,
+    error: `[audioPadTrim] ${describeFfmpegFailure2(result, timeoutMs)}`,
     failureReason: result.failureReason
   };
 }
@@ -6773,6 +6831,7 @@ var FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
 var PLAN_HASH_MISMATCH = "PLAN_HASH_MISMATCH";
 var MISSING_PLAN_ARTIFACT = "MISSING_PLAN_ARTIFACT";
 var CHUNK_INDEX_OUT_OF_RANGE = "CHUNK_INDEX_OUT_OF_RANGE";
+var CHUNK_FRAME_RANGE_INVALID = "CHUNK_FRAME_RANGE_INVALID";
 var MISSING_RUNTIME_ENV_SNAPSHOT = "MISSING_RUNTIME_ENV_SNAPSHOT";
 var RenderChunkValidationError = class extends Error {
   code;
@@ -7024,7 +7083,8 @@ var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
       accepts: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2]),
       acceptsLegacyV1WithoutDescriptor: true
     })
-  })
+  }),
+  chunkFrameRange: true
 });
 function getDistributedRenderCapabilities() {
   return DISTRIBUTED_RENDER_CAPABILITIES;
@@ -7373,7 +7433,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 import { closeSync as closeSync4, existsSync as existsSync14, ftruncateSync, mkdirSync as mkdirSync9, openSync as openSync4, readFileSync as readFileSync9 } from "node:fs";
 import { writeFileSync as writeFileSync5, writeSync } from "node:fs";
 import { join as join20 } from "node:path";
-import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure2, runFfmpeg as runFfmpeg5 } from "@hyperframes/engine";
+import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure3, runFfmpeg as runFfmpeg6 } from "@hyperframes/engine";
 
 // src/services/distributed/mp4Stitch.ts
 import {
@@ -7739,6 +7799,18 @@ function audioCutForChunk(grid, chunks, index, fps) {
   const durationSeconds = end === grid.packetCount ? null : cutSeconds(end) - (seekSeconds ?? 0);
   return { seekSeconds, durationSeconds, firstPacket: first, packetCount: end - first };
 }
+function chunksWithSubRange(chunks, index, range) {
+  const slice = chunks[index];
+  const parts = [
+    { startFrame: slice.startFrame, endFrame: range.startFrame },
+    range,
+    { startFrame: range.endFrame, endFrame: slice.endFrame }
+  ].filter((part) => part.endFrame > part.startFrame);
+  const split = [...chunks.slice(0, index), ...parts, ...chunks.slice(index + 1)].map(
+    (chunk, i) => ({ index: i, startFrame: chunk.startFrame, endFrame: chunk.endFrame })
+  );
+  return { chunks: split, index: range.startFrame > slice.startFrame ? index + 1 : index };
+}
 async function probeAacPacketGrid(audioPath) {
   const probe = await runFfprobeJson([
     "-v",
@@ -7851,10 +7923,10 @@ async function muxChunkWithAudio(input) {
   const args = [...chunkMuxArgs(input, cut), "-c", "copy"];
   appendRenderProvenanceArgs(args, input.outputPath);
   args.push("-y", input.outputPath);
-  const result = await runFfmpeg5(args, { signal: input.signal, timeout: input.timeoutMs });
+  const result = await runFfmpeg6(args, { signal: input.signal, timeout: input.timeoutMs });
   if (!result.success) {
     throw new Error(
-      `[chunkAudio] chunk mux failed: ${describeFfmpegFailure2(result, input.timeoutMs)}`
+      `[chunkAudio] chunk mux failed: ${describeFfmpegFailure3(result, input.timeoutMs)}`
     );
   }
   const slice = input.chunks[input.chunkIndex];
@@ -9684,12 +9756,12 @@ import {
 import { dirname as dirname12, join as join26 } from "node:path";
 import {
   appendRenderProvenanceArgs as appendRenderProvenanceArgs2,
-  describeFfmpegFailure as describeFfmpegFailure3,
+  describeFfmpegFailure as describeFfmpegFailure4,
   getEncoderPreset as getEncoderPreset5,
   MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME4,
   muxVideoWithAudio as muxVideoWithAudio2,
   resolveConfig as resolveConfig4,
-  runFfmpeg as runFfmpeg6
+  runFfmpeg as runFfmpeg7
 } from "@hyperframes/engine";
 import { fpsToFfmpegArg as fpsToFfmpegArg3 } from "@hyperframes/core";
 function cfrRateControlArgs(locked) {
@@ -9699,11 +9771,12 @@ function cfrRateControlArgs(locked) {
   }
   return ["-preset", preset.preset, "-crf", String(locked.crf ?? preset.quality)];
 }
-async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
+async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   const start = Date.now();
   const log = options?.logger ?? defaultLogger;
   const cfr = options?.cfr === true;
-  const plan2 = readAssemblePlan(planDir, chunkPaths);
+  const plan2 = readAssemblePlan(planDir, chunkOutputs);
+  const chunkPaths = chunkOutputs.flat();
   if (plan2.dimensions.format === "png-sequence") {
     return mergePngFrameDirs(chunkPaths, outputPath, plan2.totalFrames, audioPath, start);
   }
@@ -9786,7 +9859,12 @@ function readAssemblePlan(planDir, chunkPaths) {
       `[assemble] chunkPaths length (${chunkPaths.length}) does not match chunks.json length (${chunks.length}). Adapters must pass one path per chunk, ordered by index.`
     );
   }
-  for (const path of chunkPaths) {
+  for (const [index, entry] of chunkPaths.entries()) {
+    if (typeof entry !== "string" && entry.length === 0) {
+      throw new Error(`[assemble] chunk ${index} has an empty list of parts`);
+    }
+  }
+  for (const path of chunkPaths.flat()) {
     if (!existsSync18(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
@@ -9892,10 +9970,10 @@ async function probeJoinedFrameInfo(videoPaths, fps, signal) {
   };
 }
 async function runAssembleFfmpeg(args, step, signal, timeout) {
-  const result = await runFfmpeg6(args, { signal, timeout });
+  const result = await runFfmpeg7(args, { signal, timeout });
   if (!result.success) {
     throw encoderFailureError(`[assemble] ffmpeg ${step} failed`, {
-      error: describeFfmpegFailure3(result, timeout),
+      error: describeFfmpegFailure4(result, timeout),
       failureReason: result.failureReason
     });
   }
@@ -10005,6 +10083,17 @@ function validatePlanVideosForChunk(value) {
     );
   }
 }
+function resolveChunkFrameRange(slice, chunkIndex, frameRange) {
+  if (frameRange === void 0) return { startFrame: slice.startFrame, endFrame: slice.endFrame };
+  const { startFrame, endFrame } = frameRange;
+  if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrame) || startFrame < slice.startFrame || endFrame > slice.endFrame || endFrame <= startFrame) {
+    throw new RenderChunkValidationError(
+      CHUNK_FRAME_RANGE_INVALID,
+      `[renderChunk] frameRange ${JSON.stringify(frameRange)} must be a non-empty integer range inside chunk ${chunkIndex}'s slice [${slice.startFrame}, ${slice.endFrame})`
+    );
+  }
+  return { startFrame, endFrame };
+}
 var distributedCaptureSessionDependencies = {
   createCaptureSession: createCaptureSession9,
   assertSwiftShader,
@@ -10075,7 +10164,7 @@ function resolveLockedVp9CpuUsed(lockedEncoder) {
   if (lockedEncoder.encoder !== "libvpx-vp9-software") return void 0;
   return lockedEncoder.vp9CpuUsed ?? LEGACY_DISTRIBUTED_VP9_CPU_USED;
 }
-async function renderChunk(planDir, chunkIndex, outputChunkPath) {
+async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const start = Date.now();
   const log = defaultLogger;
   const planJsonPath = join27(planDir, "plan.json");
@@ -10129,13 +10218,15 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
   if (slice === void 0) {
     throw new RenderChunkValidationError(CHUNK_INDEX_OUT_OF_RANGE, "[renderChunk] missing slice");
   }
-  const framesInChunk = slice.endFrame - slice.startFrame;
-  if (framesInChunk <= 0) {
+  const sliceFrames = slice.endFrame - slice.startFrame;
+  if (sliceFrames <= 0) {
     throw new RenderChunkValidationError(
       CHUNK_INDEX_OUT_OF_RANGE,
-      `[renderChunk] chunk ${chunkIndex} has non-positive frame count: ${framesInChunk}`
+      `[renderChunk] chunk ${chunkIndex} has non-positive frame count: ${sliceFrames}`
     );
   }
+  const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
+  const framesInChunk = range.endFrame - range.startFrame;
   const compiledDir = join27(planDir, "compiled");
   if (!existsSync19(compiledDir)) {
     throw new RenderChunkValidationError(
@@ -10200,10 +10291,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
       planDir,
       planVideos,
-      frames: Array.from(
-        { length: slice.endFrame - slice.startFrame },
-        (_, i) => slice.startFrame + i
-      ),
+      frames: Array.from({ length: framesInChunk }, (_, i) => range.startFrame + i),
       fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
       outputRoot: videoFramesDir,
       cfg,
@@ -10359,7 +10447,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
             abortSignal: void 0,
             assertNotAborted: () => {
             },
-            frameRange: { startFrame: slice.startFrame, endFrame: slice.endFrame }
+            frameRange: range
           });
           const observedModes = new Set(capturePerfs.map((perf) => perf.captureMode));
           if (observedModes.size !== 1 || ![...observedModes].every(isCaptureMode)) {
@@ -10453,12 +10541,13 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       });
       if (encoder.chunksCarryAudio) {
         const audioScratchPath = `${outputChunkPath}.audio.m4a`;
+        const audioChunks = options?.frameRange ? chunksWithSubRange(chunks, chunkIndex, range) : { chunks, index: chunkIndex };
         await muxChunkWithAudio({
           videoPath: videoOnlyPath,
           audioPath: chunkAudioSource(planDir, chunkIndex, audioScratchPath),
           outputPath: outputChunkPath,
-          chunks,
-          chunkIndex,
+          chunks: audioChunks.chunks,
+          chunkIndex: audioChunks.index,
           fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
           timeoutMs: cfg.ffmpegProcessTimeout
         });
@@ -10487,8 +10576,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const perfPayload = {
       planHash: plan2.planHash,
       chunkIndex,
-      startFrame: slice.startFrame,
-      endFrame: slice.endFrame,
+      startFrame: range.startFrame,
+      endFrame: range.endFrame,
       framesEncoded,
       durationMs,
       planHashMs,
@@ -10517,6 +10606,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       outputPath: outputChunkPath,
       outputKind,
       framesEncoded,
+      frameRange: range,
       sha256,
       durationMs,
       planHashMs,
@@ -10533,12 +10623,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
 }
 
 // src/services/distributed/planV2Execution.ts
-async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath) {
+async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath, options) {
   const workRoot = mkdtempSync7(join28(tmpdir2(), "hf-plan-v2-chunk-"));
   const materializedPlanDir = join28(workRoot, "plan");
   try {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
-    return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath);
+    return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath, options);
   } finally {
     rmSync13(workRoot, { recursive: true, force: true });
   }
@@ -10852,6 +10942,7 @@ function hashProjectDir(projectDir, files = listSiteFiles(projectDir)) {
 }
 export {
   CHUNK_EXCEEDS_WORKER_TIMEOUT,
+  CHUNK_FRAME_RANGE_INVALID,
   CURRENT_PLAN_PROTOCOL,
   ChunkExceedsWorkerTimeoutError,
   DEFAULT_CHUNK_SIZE,

package/dist/hyperframe.manifest.json

@@ -1,7 +1,7 @@
 {
   "version": "0.1.0",
   "buildId": "dev",
-  "sha256": "5da92c0e03e3d47df672f23707742908357e94fb7b39ed0f518d4c37400f433d",
+  "sha256": "2ae4b2eb24c5dea85f83bd9af6c14abc153ad59fc3f338d1ca9142d9df0c662e",
   "artifacts": {
     "iife": "hyperframe.runtime.iife.js",
     "esm": "hyperframe.runtime.mjs"