@hyperframes/producer 0.8.179 → 0.8.181

package/dist/index.js

@@ -10373,14 +10373,84 @@ import { mkdtempSync as mkdtempSync3, renameSync as renameSync4, rmSync as rmSyn
 import { dirname as dirname9, join as join25 } 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;
@@ -10480,7 +10550,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)
@@ -10589,7 +10659,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)
   });
 }
@@ -10726,28 +10800,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
   };
 }
@@ -13927,6 +13985,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;
@@ -14178,7 +14237,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;
@@ -14527,7 +14587,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 import { closeSync as closeSync6, existsSync as existsSync20, ftruncateSync, mkdirSync as mkdirSync12, openSync as openSync5, readFileSync as readFileSync11 } from "node:fs";
 import { writeFileSync as writeFileSync7, writeSync } from "node:fs";
 import { join as join32 } 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 {
@@ -14893,6 +14953,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",
@@ -15005,10 +15077,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];
@@ -18219,12 +18291,12 @@ import {
 import { dirname as dirname17, join as join41 } 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 resolveConfig6,
-  runFfmpeg as runFfmpeg6
+  runFfmpeg as runFfmpeg7
 } from "@hyperframes/engine";
 import { fpsToFfmpegArg as fpsToFfmpegArg3 } from "@hyperframes/core";
 function cfrRateControlArgs(locked) {
@@ -18234,11 +18306,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);
   }
@@ -18321,7 +18394,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 (!existsSync27(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
@@ -18427,10 +18505,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
     });
   }
@@ -18540,6 +18618,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: createCaptureSession10,
   assertSwiftShader,
@@ -18610,7 +18699,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 = join42(planDir, "plan.json");
@@ -18664,13 +18753,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 = join42(planDir, "compiled");
   if (!existsSync28(compiledDir)) {
     throw new RenderChunkValidationError(
@@ -18735,10 +18826,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,
@@ -18894,7 +18982,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)) {
@@ -18988,12 +19076,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
         });
@@ -19022,8 +19111,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,
@@ -19052,6 +19141,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       outputPath: outputChunkPath,
       outputKind,
       framesEncoded,
+      frameRange: range,
       sha256,
       durationMs,
       planHashMs,
@@ -19068,12 +19158,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 = mkdtempSync9(join43(tmpdir5(), "hf-plan-v2-chunk-"));
   const materializedPlanDir = join43(workRoot, "plan");
   try {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
-    return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath);
+    return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath, options);
   } finally {
     rmSync17(workRoot, { recursive: true, force: true });
   }

package/dist/public-server.js

@@ -10356,14 +10356,84 @@ import { mkdtempSync as mkdtempSync3, renameSync as renameSync4, rmSync as rmSyn
 import { dirname as dirname9, join as join25 } 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;
@@ -10463,7 +10533,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)
@@ -10699,28 +10769,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
   };
 }
@@ -13845,14 +13899,15 @@ var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
       accepts: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2]),
       acceptsLegacyV1WithoutDescriptor: true
     })
-  })
+  }),
+  chunkFrameRange: true
 });
 
 // src/services/render/stages/planHash.ts
 var FIELD_DELIMITER = Buffer.from([0]);
 
 // src/services/distributed/chunkAudio.ts
-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
 var SCAN_BYTES = 64 * 1024;

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

@@ -31,6 +31,7 @@ export interface AssembleResult {
     framesEncoded: number;
     fileSize: number;
 }
+export type AssembleChunkPaths = readonly (string | readonly string[])[];
 type CfrRateControlSource = Partial<Pick<LockedRenderConfig, "quality" | "crf" | "bitrate">>;
 export declare function cfrRateControlArgs(locked: CfrRateControlSource): string[];
 /**
@@ -39,7 +40,8 @@ export declare function cfrRateControlArgs(locked: CfrRateControlSource): string
  * @param planDir — absolute path to the planDir produced by `plan()`.
  * @param chunkPaths — ordered chunk outputs, length === `chunks.json` length.
  *   For mp4/mov each entry is a path to an encoded chunk file; for
- *   png-sequence each entry is a path to a directory of frames.
+ *   png-sequence each entry is a path to a directory of frames. An entry
+ *   may instead be the ordered parts of that chunk (see {@link AssembleChunkPaths}).
  * @param audioPath — `<planDir>/<MIXED_AUDIO_FILENAME>` for mux'd formats. Pass `null`
  *   when the composition has no audio (or `assemble` is being called for a
  *   format whose audio is muxed elsewhere). `assemble` always normalizes
@@ -48,7 +50,7 @@ export declare function cfrRateControlArgs(locked: CfrRateControlSource): string
  * @param outputPath — final on-disk output (file for mp4/mov; directory
  *   for png-sequence — created if missing).
  */
-export declare function assemble(planDir: string, chunkPaths: readonly string[], audioPath: string | null, outputPath: string, options?: {
+export declare function assemble(planDir: string, chunkOutputs: AssembleChunkPaths, audioPath: string | null, outputPath: string, options?: {
     logger?: ProducerLogger;
     abortSignal?: AbortSignal;
     /**

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

@@ -15,6 +15,14 @@ interface AudioCut {
     packetCount: number;
 }
 export declare function audioCutForChunk(grid: AacPacketGrid, chunks: readonly ChunkSliceJson[], index: number, fps: Fps): AudioCut | null;
+/** Chunk `index` split around `range`, so `audioCutForChunk` treats `range` as a chunk. */
+export declare function chunksWithSubRange(chunks: readonly ChunkSliceJson[], index: number, range: {
+    startFrame: number;
+    endFrame: number;
+}): {
+    chunks: ChunkSliceJson[];
+    index: number;
+};
 export declare function chunkAudioSlicePath(index: number): string;
 /** Which chunks need a sliced-audio file: `"all"`, one index, or `null` if it is not one. */
 export declare function chunkAudioSliceTarget(path: string): "all" | number | null;

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

@@ -7,9 +7,10 @@ export declare const FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
 export declare const PLAN_HASH_MISMATCH = "PLAN_HASH_MISMATCH";
 export declare const MISSING_PLAN_ARTIFACT = "MISSING_PLAN_ARTIFACT";
 export declare const CHUNK_INDEX_OUT_OF_RANGE = "CHUNK_INDEX_OUT_OF_RANGE";
+export declare const CHUNK_FRAME_RANGE_INVALID = "CHUNK_FRAME_RANGE_INVALID";
 export declare const MISSING_RUNTIME_ENV_SNAPSHOT = "MISSING_RUNTIME_ENV_SNAPSHOT";
 export { INVALID_VIDEO_METADATA };
-export type RenderChunkValidationCode = typeof FFMPEG_VERSION_MISMATCH | typeof PLAN_HASH_MISMATCH | typeof MISSING_PLAN_ARTIFACT | typeof CHUNK_INDEX_OUT_OF_RANGE | typeof MISSING_RUNTIME_ENV_SNAPSHOT | typeof INVALID_VIDEO_METADATA | typeof BROWSER_GPU_NOT_SOFTWARE;
+export type RenderChunkValidationCode = typeof FFMPEG_VERSION_MISMATCH | typeof PLAN_HASH_MISMATCH | typeof MISSING_PLAN_ARTIFACT | typeof CHUNK_INDEX_OUT_OF_RANGE | typeof CHUNK_FRAME_RANGE_INVALID | typeof MISSING_RUNTIME_ENV_SNAPSHOT | typeof INVALID_VIDEO_METADATA | typeof BROWSER_GPU_NOT_SOFTWARE;
 /** A malformed planDir or a worker that does not match the plan's fingerprint; adapters key retries off `code`. */
 export declare class RenderChunkValidationError extends Error {
     readonly code: RenderChunkValidationCode;

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

@@ -53,6 +53,7 @@ export interface DistributedRenderCapabilities {
         chunk: Readonly<PlanProtocolConsumerCapabilities>;
         assembler: Readonly<PlanProtocolConsumerCapabilities>;
     }>;
+    readonly chunkFrameRange?: boolean;
 }
 /** Serializable capability payload for fleet rollout and worker handshakes. */
 export declare const DISTRIBUTED_RENDER_CAPABILITIES: Readonly<DistributedRenderCapabilities>;

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

@@ -1,12 +1,12 @@
-import { assemble, type AssembleResult } from "./assemble.js";
-import { type EffectiveChunkResult } from "./renderChunk.js";
+import { assemble, type AssembleChunkPaths, type AssembleResult } from "./assemble.js";
+import { type EffectiveChunkResult, type RenderChunkOptions } from "./renderChunk.js";
 /**
  * Direct v2 chunk-role entry point. Storage adapters may instead download the
  * selected blobs themselves and call `materializePlanV2Target` + `renderChunk`.
  */
-export declare function renderChunkV2(planV2Dir: string, chunkIndex: number, outputChunkPath: string): Promise<EffectiveChunkResult>;
+export declare function renderChunkV2(planV2Dir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions): Promise<EffectiveChunkResult>;
 /**
  * Direct v2 assembler-role entry point. Audio is resolved exclusively from
  * the assembler dependency set and never materialized by chunk workers.
  */
-export declare function assembleV2(planV2Dir: string, chunkPaths: readonly string[], outputPath: string, options?: Parameters<typeof assemble>[4]): Promise<AssembleResult>;
+export declare function assembleV2(planV2Dir: string, chunkPaths: AssembleChunkPaths, outputPath: string, options?: Parameters<typeof assemble>[4]): Promise<AssembleResult>;

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

@@ -34,9 +34,9 @@
  * In-process renders (`executeRenderJob`) leave them off.
  */
 import { assertSwiftShader, type CaptureOptions, type CaptureMode, type CaptureSession, closeCaptureSession, createCaptureSession, type EngineConfig, initializeSession, probeBeginFrameLiveness, readWebGlVendorInfoFromCanvas } from "@hyperframes/engine";
-import { type LockedRenderConfig } from "../render/stages/freezePlan.js";
+import { type ChunkSliceJson, type LockedRenderConfig } from "../render/stages/freezePlan.js";
 import { type PlanVideosJson } from "./shared.js";
-export { CHUNK_INDEX_OUT_OF_RANGE, createChunkVideoFrameInjectorFactory, extractDeferredVideoFramesForChunk, FFMPEG_VERSION_MISMATCH, INVALID_VIDEO_METADATA, MISSING_PLAN_ARTIFACT, MISSING_RUNTIME_ENV_SNAPSHOT, PLAN_HASH_MISMATCH, rebuildExtractedFramesFromPlanDir, RenderChunkValidationError, } from "./chunkFrames.js";
+export { CHUNK_FRAME_RANGE_INVALID, CHUNK_INDEX_OUT_OF_RANGE, createChunkVideoFrameInjectorFactory, extractDeferredVideoFramesForChunk, FFMPEG_VERSION_MISMATCH, INVALID_VIDEO_METADATA, MISSING_PLAN_ARTIFACT, MISSING_RUNTIME_ENV_SNAPSHOT, PLAN_HASH_MISMATCH, rebuildExtractedFramesFromPlanDir, RenderChunkValidationError, } from "./chunkFrames.js";
 /** Validate the shared video contract before any v1 chunk can inject frames. */
 export declare function validatePlanVideosForChunk(value: unknown): PlanVideosJson;
 /**
@@ -51,6 +51,7 @@ export interface ChunkResult {
     /** `"file"` for mp4/mov; `"frame-dir"` for png-sequence. */
     outputKind: "file" | "frame-dir";
     framesEncoded: number;
+    frameRange?: ChunkFrameRange;
     sha256: string;
     durationMs: number;
     /**
@@ -92,7 +93,26 @@ export interface ChunkResult {
 /** Result returned by the built-in renderer, which always observes its mode. */
 export interface EffectiveChunkResult extends ChunkResult {
     captureMode: CaptureMode;
+    frameRange: ChunkFrameRange;
 }
+/** Absolute composition frame indices, end exclusive, like a chunk's slice. */
+export interface ChunkFrameRange {
+    startFrame: number;
+    endFrame: number;
+}
+export interface RenderChunkOptions {
+    /**
+     * Render only these frames of the chunk, e.g. to retry a slow chunk as
+     * parts rendered in parallel. Must be a non-empty range inside the chunk's
+     * slice. Each part is a self-contained output (its own IDR keyframe, frame
+     * names from zero, the audio packets it owns); pass the parts of a chunk,
+     * in order, as one `chunkPaths` entry to `assemble`. Omitted renders the
+     * whole slice.
+     */
+    frameRange?: ChunkFrameRange;
+}
+/** The frames a chunk renders: its slice, or a validated sub-range of it. */
+export declare function resolveChunkFrameRange(slice: ChunkSliceJson, chunkIndex: number, frameRange: ChunkFrameRange | undefined): ChunkFrameRange;
 /** Compatibility-safe adapter seam for built-in or injected chunk renderers. */
 export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string) => Promise<ChunkResult>;
 interface DistributedCaptureSessionDependencies {
@@ -159,4 +179,4 @@ export declare function resolveLockedVp9CpuUsed(lockedEncoder: Pick<LockedRender
  * outputs — the caller picks the right shape based on `meta/encoder.json`.
  * `renderChunk` enforces the same choice via `outputKind` on the result.
  */
-export declare function renderChunk(planDir: string, chunkIndex: number, outputChunkPath: string): Promise<EffectiveChunkResult>;
+export declare function renderChunk(planDir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions): Promise<EffectiveChunkResult>;

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

@@ -0,0 +1,12 @@
+/**
+ * The true peak one `ebur128=peak=true` pass over the whole file reports, measured in parallel
+ * segments when the length is known and the rate is 48 kHz: the same digit, not an estimate.
+ */
+export declare function measureTruePeakDbfs(audioPath: string, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    segments?: {
+        durationSeconds: number;
+        sampleRate: number;
+    };
+}): Promise<number>;