@hyperframes/producer 0.8.206 → 0.8.208

package/dist/distributed.js

@@ -6,16 +6,17 @@ import {
   existsSync as existsSync15,
   linkSync,
   mkdirSync as mkdirSync10,
-  rmSync as rmSync9,
+  rmSync as rmSync7,
   writeFileSync as writeFileSync7
 } from "node:fs";
 import { extname as extname4, isAbsolute as isAbsolute3, join as join22, relative as relative5, sep as sep2 } from "node:path";
 import {
-  fpsToNumber as fpsToNumber10,
+  fpsToNumber as fpsToNumber9,
   HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
 } from "@hyperframes/core";
 import {
   getEncoderPreset as getEncoderPreset4,
+  keyframeIntervalToGopSize as keyframeIntervalToGopSize3,
   normalizeVp9CpuUsed,
   resolveConfig as resolveConfig3,
   declareContentAddressedUrl,
@@ -69,7 +70,7 @@ import {
   mkdirSync as mkdirSync6,
   readFileSync as readFileSync6,
   readdirSync as readdirSync3,
-  rmSync as rmSync7,
+  rmSync as rmSync5,
   statSync as statSync5,
   writeFileSync as writeFileSync4,
   copyFileSync as copyFileSync5,
@@ -77,7 +78,7 @@ import {
 } from "fs";
 import {
   chainCapture,
-  fpsToNumber as fpsToNumber9,
+  fpsToNumber as fpsToNumber8,
   HF_COLOR_GRADING_ATTR,
   HF_VFX_ATTR,
   parseVfxChain,
@@ -822,7 +823,34 @@ function outputNeedsAlpha(format) {
 }
 
 // src/services/render/hlsConfig.ts
-import { fpsToNumber as fpsToNumber2 } from "@hyperframes/core";
+import { keyframeIntervalToGopSize } from "@hyperframes/engine";
+
+// src/services/render/deliveryEncoder.ts
+import { appendRateCapArgs, keyframeIntervalToGopSize as keyframeIntervalToGopSize2 } from "@hyperframes/engine";
+function validateDeliveryEncoderConfig(config) {
+  const { keyframeIntervalSeconds, maxBitrate, bufferSize, format } = config;
+  if (keyframeIntervalSeconds === void 0 && maxBitrate === void 0 && bufferSize === void 0)
+    return;
+  if (keyframeIntervalSeconds !== void 0) {
+    if (!Number.isFinite(keyframeIntervalSeconds) || keyframeIntervalSeconds <= 0) {
+      throw new Error(
+        `keyframeIntervalSeconds must be a positive number of seconds; got ${keyframeIntervalSeconds}`
+      );
+    }
+    if (format === "hls") {
+      throw new Error(
+        "keyframeIntervalSeconds does not apply to hls; hlsSegmentSeconds sets its keyframes"
+      );
+    }
+  }
+  if (format !== void 0 && format !== "mp4") {
+    throw new Error(`keyframeIntervalSeconds and maxBitrate apply to mp4 renders, not ${format}`);
+  }
+  appendRateCapArgs([], { maxBitrate, bufferSize });
+}
+function chunkGopFrames(framesInChunk, intervalFrames) {
+  return Math.min(framesInChunk, intervalFrames ?? framesInChunk);
+}
 
 // src/services/render/shared.ts
 import {
@@ -1245,7 +1273,7 @@ import {
 import { CaptureFailure, classifyCaptureFailure } from "@hyperframes/engine";
 
 // src/services/render/perfSummary.ts
-import { fpsToNumber as fpsToNumber3 } from "@hyperframes/core";
+import { fpsToNumber as fpsToNumber2 } from "@hyperframes/core";
 function pushWorkerDedupPerfs(results, sink) {
   for (const r of results) {
     if (r.perf) sink.push(r.perf);
@@ -1324,7 +1352,7 @@ import {
   resolveVideoExtractionWindow,
   runFfmpeg
 } from "@hyperframes/engine";
-import { fpsToFfmpegArg, fpsToNumber as fpsToNumber4 } from "@hyperframes/core";
+import { fpsToFfmpegArg, fpsToNumber as fpsToNumber3 } from "@hyperframes/core";
 var BYTES_PER_MIB = 1024 * 1024;
 var DEFAULT_HDR_WINDOW_BYTES = 512 * BYTES_PER_MIB;
 
@@ -1375,7 +1403,7 @@ function resolveVideoCaptureBeyondViewport(videoCount) {
 }
 
 // src/services/render/captureCost.ts
-import { fpsToNumber as fpsToNumber5 } from "@hyperframes/core";
+import { fpsToNumber as fpsToNumber4 } from "@hyperframes/core";
 import {
   calculateOptimalWorkers,
   captureFrameToBuffer as captureFrameToBuffer3,
@@ -1785,7 +1813,7 @@ async function observeRenderStage(recorder, phase, data, fn, options = {}) {
 // src/services/render/videoFrameCoverage.ts
 import { parseHTML } from "linkedom";
 import {
-  fpsToNumber as fpsToNumber6,
+  fpsToNumber as fpsToNumber5,
   normalizeRateSpec,
   sourceTimeAt,
   toFps
@@ -2993,7 +3021,7 @@ function detectShaderTransitionUsage(html) {
   }
   return false;
 }
-async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath) {
+async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath, probes) {
   let filePath = src;
   if (isHttpUrl(src)) {
     if (!existsSync6(downloadDir)) mkdirSync4(downloadDir, { recursive: true });
@@ -3020,45 +3048,52 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
     if (error instanceof Error && error.stack) wrapped.stack = error.stack;
     return wrapped;
   };
-  return withMediaProbeSlot(async () => {
-    let profile;
+  const probe = () => withMediaProbeSlot(async () => {
     try {
       await assertMediaPayload(filePath, elementIdentity);
-      profile = await probeMediaProfile2(filePath);
-    } catch (error) {
-      if (tagName !== "video") {
-        if (error instanceof NotMediaPayloadError2) {
-          log?.warn(
-            `[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media file, so the element is dropped from the render. Point it at a rendered media file.`
-          );
-        }
-        return { duration: null, resolvedPath: filePath };
+      const profile = await probeMediaProfile2(filePath);
+      if (tagName === "video") {
+        return { profile, fileDuration: (await extractMediaMetadata(filePath)).durationSeconds };
       }
-      throw withSrcContext(error);
-    }
-    assertAssetMediaTypeProfile(tagName === "video" ? "video" : "audio", profile, elementIdentity);
-    let metadata;
-    if (tagName === "video") {
-      try {
-        metadata = await extractMediaMetadata(filePath);
-      } catch (error) {
-        throw withSrcContext(error);
-      }
-    } else {
       try {
-        metadata = await extractAudioMetadata(filePath);
+        return { profile, fileDuration: (await extractAudioMetadata(filePath)).durationSeconds };
       } catch {
-        return { duration: null, resolvedPath: filePath };
+        return { profile, fileDuration: null };
       }
+    } catch (error) {
+      return { error };
     }
-    const fileDuration = metadata.durationSeconds;
-    const duration = resolveNaturalMediaTimelineDurationFromValues(
-      fileDuration,
-      mediaStart,
-      playbackRate
-    );
-    return { duration, resolvedPath: filePath };
   });
+  const key = `${tagName}\0${filePath}`;
+  let probed = probes?.get(key);
+  if (!probed) {
+    probed = probe();
+    probes?.set(key, probed);
+  }
+  const outcome = await probed;
+  if ("error" in outcome) {
+    if (tagName !== "video") {
+      if (outcome.error instanceof NotMediaPayloadError2) {
+        log?.warn(
+          `[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media file, so the element is dropped from the render. Point it at a rendered media file.`
+        );
+      }
+      return { duration: null, resolvedPath: filePath };
+    }
+    throw withSrcContext(outcome.error);
+  }
+  assertAssetMediaTypeProfile(
+    tagName === "video" ? "video" : "audio",
+    outcome.profile,
+    elementIdentity
+  );
+  if (outcome.fileDuration === null) return { duration: null, resolvedPath: filePath };
+  const duration = resolveNaturalMediaTimelineDurationFromValues(
+    outcome.fileDuration,
+    mediaStart,
+    playbackRate
+  );
+  return { duration, resolvedPath: filePath };
 }
 function markInferredVariableMediaDurations(html, unresolvedMedia) {
   const unresolvedIds = new Set(unresolvedMedia.map((element) => element.id));
@@ -3072,7 +3107,7 @@ function markInferredVariableMediaDurations(html, unresolvedMedia) {
   }
   return changed ? document2.toString() : html;
 }
-async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath) {
+async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath, probes) {
   const { html: staticCompiled, unresolved } = compileTimingAttrs(html);
   const mediaUnresolved = unresolved.filter(
     (el) => (el.tagName === "video" || el.tagName === "audio") && el.src
@@ -3089,7 +3124,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
         el.tagName,
         el.id,
         log,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -3110,7 +3146,9 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        void 0,
+        probes
       );
       return { id: el.id, tagName: el.tagName, duration: el.duration, maxDuration, src: el.src };
     })
@@ -3132,7 +3170,7 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
   compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
-async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath) {
+async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath, probes) {
   const subCompositions = /* @__PURE__ */ new Map();
   const { document: document2 } = parseHTML5(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -3160,14 +3198,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
         dirname5(item.filePath),
         downloadDir,
         void 0,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
         item.nestedVisited,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       );
       return {
         srcPath: item.srcPath,
@@ -3937,19 +3977,22 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   );
   const rawHtml = rewriteUnresolvableGsapToCdn(entryHtml, projectDir);
   assertSubCompositionsUsable(rawHtml, projectDir);
+  const probes = /* @__PURE__ */ new Map();
   const { html: compiledHtml, unresolvedCompositions } = await compileHtmlFile(
     rawHtml,
     projectDir,
     downloadDir,
     options.log,
-    options.urlByAbsentLocalPath
+    options.urlByAbsentLocalPath,
+    probes
   );
   const { subCompositions } = await parseSubCompositions(
     compiledHtml,
     projectDir,
     downloadDir,
     void 0,
-    options.urlByAbsentLocalPath
+    options.urlByAbsentLocalPath,
+    probes
   );
   const fullHtml = ensureFullDocument(compiledHtml);
   const inlinedHtml = inlineSubCompositions(
@@ -4052,9 +4095,12 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   }
   const { videos, audios, images, droppedMediaIds } = collectRenderMedia(html);
   const masterFxChain = parseMasterFxChain(html);
+  const advised = /* @__PURE__ */ new Set();
   for (const video of videos) {
     if (isHttpUrl(video.src)) continue;
     const videoPath = resolve6(projectDir, video.src);
+    if (advised.has(videoPath)) continue;
+    advised.add(videoPath);
     const reencode = `ffmpeg -i "${video.src}" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4`;
     (async () => {
       const metadata = await withMediaProbeSlot(() => extractMediaMetadata(videoPath));
@@ -4605,13 +4651,14 @@ import {
 } from "@hyperframes/engine";
 import {
   MEDIA_RENDER_ID_ATTR as MEDIA_RENDER_ID_ATTR2,
-  fpsToNumber as fpsToNumber7,
+  fpsToNumber as fpsToNumber6,
   normalizeRateSpec as normalizeRateSpec3,
   readMediaStart as readMediaStart2,
   shiftRateLane as shiftRateLane2,
   sourceTimeAt as sourceTimeAt3,
   timeAtSourceTime
 } from "@hyperframes/core";
+import { parseHostVariableValues as parseHostVariableValues2, readDeclaredDefaults as readDeclaredDefaults2 } from "@hyperframes/core/compiler";
 import { extractMediaSrcMutations } from "@hyperframes/parsers";
 
 // src/services/render/stages/probeFailures.ts
@@ -4649,8 +4696,15 @@ function hasAutoStartVideos(html) {
   const { document: document2 } = parseHTML6(html);
   return document2.querySelector("video[data-hf-auto-start]") !== null;
 }
+function variableHasValue(element, variableId, variables) {
+  if (variables && Object.hasOwn(variables, variableId)) return true;
+  for (let scope = element.parentElement; scope; scope = scope.parentElement) {
+    if (Object.hasOwn(parseHostVariableValues2(scope), variableId)) return true;
+    if (Object.hasOwn(readDeclaredDefaults2(scope), variableId)) return true;
+  }
+  return Object.hasOwn(readDeclaredDefaults2(element.ownerDocument.documentElement), variableId);
+}
 function hasVariableBoundMedia(html, variables) {
-  if (!variables || Object.keys(variables).length === 0) return false;
   const { document: document2 } = parseHTML6(html);
   return Array.from(
     document2.querySelectorAll(
@@ -4658,7 +4712,7 @@ function hasVariableBoundMedia(html, variables) {
     )
   ).some((element) => {
     const variableId = element.getAttribute("data-var-src")?.trim();
-    return Boolean(variableId && Object.hasOwn(variables, variableId));
+    return Boolean(variableId && variableHasValue(element, variableId, variables));
   });
 }
 function authoredMediaStarts(html) {
@@ -5084,7 +5138,7 @@ async function runProbeStage(input) {
           session.page,
           composition.audios.map((audio) => audio.id),
           composition.duration,
-          fpsToNumber7(job.config.fps)
+          fpsToNumber6(job.config.fps)
         );
         assertNotAborted();
         if (automation.length > 0) {
@@ -5147,7 +5201,7 @@ async function runProbeStage(input) {
   }
   const browserProbeMs = Date.now() - probeStart;
   const duration = composition.duration;
-  const totalFrames = durationToFrameCount(duration, fpsToNumber7(job.config.fps));
+  const totalFrames = durationToFrameCount(duration, fpsToNumber6(job.config.fps));
   if (duration <= 0) {
     const diagnostics = [];
     try {
@@ -5392,10 +5446,11 @@ var VideoExtractionStageError = class extends Error {
       kind: failure.kind,
       affectedElementCount: failure.count
     }))
-  )) {
+  ), ffmpegReason) {
     const total = failures.reduce((sum2, failure) => sum2 + failure.count, 0);
     const breakdown = failures.map((failure) => `${failure.kind}=${failure.count}`).join(",");
-    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]`);
+    const reason = ffmpegReason ? `: ffmpeg said: ${ffmpegReason}` : "";
+    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]${reason}`);
     this.code = code;
     this.retryable = retryable;
     this.failures = failures;
@@ -5442,7 +5497,8 @@ function buildVideoExtractionStageError(result) {
     retryable ? "VIDEO_EXTRACTION_FAILED" : "VIDEO_SOURCE_UNRENDERABLE",
     retryable,
     failures,
-    extractionFailureMetadataFromResult(result)
+    extractionFailureMetadataFromResult(result),
+    result.errors.find((failure) => failure.ffmpegReason)?.ffmpegReason
   );
 }
 function buildHdrProbeStageError(failures) {
@@ -5710,16 +5766,17 @@ async function appendVideoAudioFromProbe(input) {
 
 // src/services/render/stages/audioStage.ts
 import { join as join11 } from "node:path";
-import { rmSync as rmSync5 } from "node:fs";
 import {
   MIXED_AUDIO_FILENAME,
   audioFailureDiagnostics,
-  processCompositionAudio
+  processCompositionAudio,
+  removeScratch as removeScratch2,
+  collectScratchLeftovers
 } from "@hyperframes/engine";
 
 // src/services/render/audioPadTrim.ts
 import { spawn } from "node:child_process";
-import { mkdtempSync, rmSync as rmSync4 } from "node:fs";
+import { mkdtempSync } from "node:fs";
 import { dirname as dirname6, join as join10 } from "node:path";
 import {
   DEFAULT_CONFIG,
@@ -5728,6 +5785,7 @@ import {
   extractAudioMetadata as extractAudioMetadata3,
   getFfprobeBinary,
   ManagedChildProcess,
+  removeScratch,
   renameWithRetry as renameWithRetry5,
   runFfmpeg as runFfmpeg5,
   trackChildProcess
@@ -5923,7 +5981,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
       error: `audioPadTrim: failed to materialize ${plan2.operation}: ${err instanceof Error ? err.message : String(err)}`
     };
   } finally {
-    for (const path of plan2.cleanupPaths) rmSync4(path, { force: true });
+    for (const path of plan2.cleanupPaths) removeScratch(path);
   }
   let loweredDb = 0;
   if (probeTruePeak) {
@@ -5986,7 +6044,7 @@ async function enforceAacTruePeak(input) {
       }
       if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
         if (measuredPath !== correctedPath) return { success: true };
-        renameWithRetry5(correctedPath, input.audioPath);
+        renameWithRetry5(correctedPath, input.audioPath, { copyFallback: true });
         return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
@@ -6027,7 +6085,7 @@ async function enforceAacTruePeak(input) {
       )}`
     };
   } finally {
-    if (scratchDir) rmSync4(scratchDir, { recursive: true, force: true });
+    if (scratchDir) removeScratch(scratchDir);
   }
 }
 function failResult(outputPath, target, source, error) {
@@ -6172,7 +6230,15 @@ function assertAudioNotInterrupted(failures) {
     ])
   });
 }
-async function runAudioStage(input) {
+function runAudioStage(input) {
+  return collectScratchLeftovers(
+    () => runAudioStageScoped(input),
+    (left) => {
+      if (left.length > 0) input.log?.warn("[audio] scratch left behind", { count: left.length });
+    }
+  );
+}
+async function runAudioStageScoped(input) {
   const stageStart = Date.now();
   const pcmSourcePath = join11(input.workDir, "audio-source.wav");
   const duration = input.totalFrames * input.fps.den / input.fps.num;
@@ -6194,7 +6260,7 @@ async function runAudioStage(input) {
     }
     return { ...result, audioLoweredDb, audioProcessMs: Date.now() - stageStart };
   } finally {
-    rmSync5(pcmSourcePath, { force: true });
+    removeScratch2(pcmSourcePath);
   }
 }
 async function mixAudioForDelivery(input, duration, pcmSourcePath) {
@@ -6437,6 +6503,7 @@ async function runCaptureStage(input) {
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       openAttempt: input.openAttempt,
+      verifyFirstSession: input.verifyFirstSession,
       onProgress: (progress) => {
         if (progress.latestWorkerPhase) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
@@ -6653,7 +6720,7 @@ import {
   initializeSession as initializeSession7,
   spawnStreamingEncoder as spawnStreamingEncoder3
 } from "@hyperframes/engine";
-import { fpsToNumber as fpsToNumber8 } from "@hyperframes/core";
+import { fpsToNumber as fpsToNumber7 } from "@hyperframes/core";
 
 // src/services/hdrImageTransferCache.ts
 import { convertTransfer as convertTransfer2 } from "@hyperframes/engine";
@@ -6683,7 +6750,7 @@ import {
   mkdirSync as mkdirSync5,
   readdirSync as readdirSync2,
   readFileSync as readFileSync5,
-  rmSync as rmSync6,
+  rmSync as rmSync4,
   statSync as statSync4,
   writeFileSync as writeFileSync3
 } from "node:fs";
@@ -6822,7 +6889,7 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
       fileSize
     };
   } finally {
-    rmSync6(input.palettePath, { force: true });
+    rmSync4(input.palettePath, { force: true });
   }
 }
 function startEncodeProgress(job, stage, onProgress) {
@@ -6846,6 +6913,8 @@ function videoEncoderOptions(input, engineCfg) {
     preset: preset.preset,
     quality: input.effectiveQuality,
     bitrate: input.effectiveBitrate,
+    maxBitrate: input.maxBitrate,
+    bufferSize: input.bufferSize,
     pixelFormat: preset.pixelFormat,
     vp9CpuUsed: engineCfg.vp9CpuUsed,
     useGpu: job.config.useGpu,
@@ -7305,7 +7374,8 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
               });
             } : void 0,
             void 0,
-            options.cfg
+            options.cfg,
+            { verifyFirstSession: options.verifyFirstSession }
           );
           pushWorkerDedupPerfs(workerResults, options.dedupPerfs);
           if (options.pageErrorLines) pushWorkerPageErrors(workerResults, options.pageErrorLines);
@@ -8468,7 +8538,7 @@ import { join as join20 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure3, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
 
 // src/services/distributed/mp4Stitch.ts
-import { createReadStream as createReadStream4, createWriteStream, mkdirSync as mkdirSync8, mkdtempSync as mkdtempSync2, rmSync as rmSync8 } from "node:fs";
+import { createReadStream as createReadStream4, createWriteStream, mkdirSync as mkdirSync8, mkdtempSync as mkdtempSync2, rmSync as rmSync6 } from "node:fs";
 import { open } from "node:fs/promises";
 import { renameWithRetry as renameWithRetry6 } from "@hyperframes/engine";
 import { dirname as dirname10, join as join19 } from "node:path";
@@ -8846,7 +8916,7 @@ async function writeStitchedMp4(chunkPaths, outputPath, audioPath) {
     renameWithRetry6(join19(workDir, "out.mp4"), outputPath);
   } finally {
     out.destroy();
-    rmSync8(workDir, { recursive: true, force: true });
+    rmSync6(workDir, { recursive: true, force: true });
   }
 }
 
@@ -9358,7 +9428,7 @@ var FREEZE_OWNED_PLAN_FILES = [
 ];
 function removeFreezeOwnedPlanFiles(planDir) {
   for (const relativePath of FREEZE_OWNED_PLAN_FILES) {
-    rmSync9(join22(planDir, relativePath), { force: true });
+    rmSync7(join22(planDir, relativePath), { force: true });
   }
 }
 function buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize) {
@@ -9418,6 +9488,9 @@ function buildLockedRenderConfig(input) {
     preset,
     crf: config.crf,
     bitrate: config.bitrate,
+    maxBitrate: config.maxBitrate,
+    bufferSize: config.bufferSize,
+    keyframeIntervalFrames: config.keyframeIntervalSeconds === void 0 ? void 0 : keyframeIntervalToGopSize3({ num: config.fps, den: 1 }, config.keyframeIntervalSeconds),
     ...locksVp9CpuUsed,
     // GOP === chunkSize so every chunk's first frame is an IDR keyframe and
     // ffmpeg concat-copy round-trips losslessly.
@@ -9569,7 +9642,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
   const workDir = join22(planDir, ".plan-work");
-  rmSync9(workDir, { recursive: true, force: true });
+  rmSync7(workDir, { recursive: true, force: true });
   mkdirSync10(workDir, { recursive: true });
   const compiledDir = join22(workDir, "compiled");
   mkdirSync10(compiledDir, { recursive: true });
@@ -9662,7 +9735,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   validateDistributedDuration({
     duration: probeResult.duration,
     totalFrames,
-    fps: fpsToNumber10(job.config.fps)
+    fps: fpsToNumber9(job.config.fps)
   });
   if (probeResult.fileServer) closeFileServerSafely(probeResult.fileServer, "plan", log);
   if (probeResult.probeSession) {
@@ -9776,15 +9849,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "extract", stageStarted);
   const stagedVideoFrames = join22(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join22(planDir, "video-frames");
-  if (existsSync15(videoFramesDst)) rmSync9(videoFramesDst, { recursive: true, force: true });
+  if (existsSync15(videoFramesDst)) rmSync7(videoFramesDst, { recursive: true, force: true });
   const videoSourcesDir = join22(planDir, "video-sources");
-  rmSync9(videoSourcesDir, { recursive: true, force: true });
+  rmSync7(videoSourcesDir, { recursive: true, force: true });
   if (existsSync15(stagedVideoFrames)) {
     renameWithRetry7(stagedVideoFrames, videoFramesDst);
   } else {
     mkdirSync10(videoFramesDst, { recursive: true });
   }
-  if (existsSync15(finalCompiledDir)) rmSync9(finalCompiledDir, { recursive: true, force: true });
+  if (existsSync15(finalCompiledDir)) rmSync7(finalCompiledDir, { recursive: true, force: true });
   renameWithRetry7(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
@@ -9952,7 +10025,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     format: config.format
   };
   try {
-    rmSync9(workDir, { recursive: true, force: true });
+    rmSync7(workDir, { recursive: true, force: true });
   } catch (err) {
     log.warn("[plan] failed to remove temp work dir", {
       workDir,
@@ -10022,7 +10095,7 @@ async function buildPlanAudio(projectDir, config, workRoot, outputPath, options
     renameWithRetry7(mixed.audioOutputPath, outputPath);
     return { hasAudio: true };
   } finally {
-    rmSync9(c.workDir, { recursive: true, force: true });
+    rmSync7(c.workDir, { recursive: true, force: true });
   }
 }
 async function plan(projectDir, config, planDir, options = {}) {
@@ -10051,7 +10124,7 @@ import {
   mkdtempSync as mkdtempSync4,
   readFileSync as readFileSync10,
   readdirSync as readdirSync7,
-  rmSync as rmSync11,
+  rmSync as rmSync9,
   statSync as statSync7,
   writeFileSync as writeFileSync9
 } from "node:fs";
@@ -10067,7 +10140,7 @@ import {
   linkSync as linkSync2,
   mkdirSync as mkdirSync11,
   mkdtempSync as mkdtempSync3,
-  rmSync as rmSync10,
+  rmSync as rmSync8,
   statSync as statSync6,
   writeFileSync as writeFileSync8
 } from "node:fs";
@@ -10162,7 +10235,7 @@ var LocalPlanV2ArtifactPublisher = class {
       }
       renameWithRetry8(temporaryPath, destinationPath);
     } finally {
-      rmSync10(stagingDir, { recursive: true, force: true });
+      rmSync8(stagingDir, { recursive: true, force: true });
     }
   }
   async commitManifest(manifestBytes) {
@@ -10179,7 +10252,7 @@ var LocalPlanV2ArtifactPublisher = class {
   }
   async abort() {
     if (!this.#committed) {
-      rmSync10(this.temporaryDir, { recursive: true, force: true });
+      rmSync8(this.temporaryDir, { recursive: true, force: true });
     }
   }
 };
@@ -10448,7 +10521,7 @@ function writeBlob(sourcePath, destinationPath) {
     copyFileSync8(sourcePath, temporaryPath);
     renameWithRetry9(temporaryPath, destinationPath);
   } finally {
-    rmSync11(temporaryDir, { recursive: true, force: true });
+    rmSync9(temporaryDir, { recursive: true, force: true });
   }
 }
 function publishBlobFor(absolutePath, digests) {
@@ -10581,7 +10654,7 @@ function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
     renameWithRetry9(tempDir, planV2Dir);
     return resultFromManifest(planV2Dir, publication.manifest);
   } catch (error) {
-    rmSync11(tempDir, { recursive: true, force: true });
+    rmSync9(tempDir, { recursive: true, force: true });
     throw error;
   }
 }
@@ -10648,7 +10721,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
     }
     throw error;
   } finally {
-    rmSync11(stagingRoot, { recursive: true, force: true });
+    rmSync9(stagingRoot, { recursive: true, force: true });
   }
 }
 async function planV2(projectDir, config, planV2Dir) {
@@ -10865,7 +10938,7 @@ function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}
     );
     renameWithRetry9(tempDir, destinationDir);
   } catch (error) {
-    rmSync11(tempDir, { recursive: true, force: true });
+    rmSync9(tempDir, { recursive: true, force: true });
     throw error;
   }
   return {
@@ -10929,7 +11002,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
 }
 
 // src/services/distributed/planV2Execution.ts
-import { mkdtempSync as mkdtempSync6, rmSync as rmSync14 } from "node:fs";
+import { mkdtempSync as mkdtempSync6, rmSync as rmSync12 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { join as join28 } from "node:path";
 
@@ -10941,12 +11014,13 @@ import {
   mkdtempSync as mkdtempSync5,
   readFileSync as readFileSync11,
   readdirSync as readdirSync8,
-  rmSync as rmSync12,
+  rmSync as rmSync10,
   statSync as statSync8,
   writeFileSync as writeFileSync10
 } from "node:fs";
 import { dirname as dirname13, join as join26 } from "node:path";
 import {
+  appendRateCapArgs as appendRateCapArgs2,
   appendRenderProvenanceArgs as appendRenderProvenanceArgs2,
   describeFfmpegFailure as describeFfmpegFailure4,
   getEncoderPreset as getEncoderPreset5,
@@ -11020,7 +11094,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
     });
   } finally {
     try {
-      rmSync12(workDir, { recursive: true, force: true });
+      rmSync10(workDir, { recursive: true, force: true });
     } catch (err) {
       log.warn("[assemble] failed to remove work dir", {
         workDir,
@@ -11082,6 +11156,9 @@ function cfrEncodeArgs(inputArgs, encoder, fpsArg) {
     "-r",
     fpsArg
   ];
+  if (encoder.keyframeIntervalFrames !== void 0)
+    args.push("-g", String(encoder.keyframeIntervalFrames));
+  appendRateCapArgs2(args, encoder);
   appendSoftwareEncoderThreadsArg(args, "libx264");
   return args;
 }
@@ -11218,7 +11295,7 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync18(outputPath)) rmSync12(outputPath, { recursive: true, force: true });
+  if (existsSync18(outputPath)) rmSync10(outputPath, { recursive: true, force: true });
   mkdirSync13(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
@@ -11263,7 +11340,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync19, mkdirSync as mkdirSync14, readFileSync as readFileSync12, readdirSync as readdirSync9, rmSync as rmSync13, writeFileSync as writeFileSync11 } from "node:fs";
+import { existsSync as existsSync19, mkdirSync as mkdirSync14, readFileSync as readFileSync12, readdirSync as readdirSync9, rmSync as rmSync11, writeFileSync as writeFileSync11 } from "node:fs";
 import { cpus } from "node:os";
 import { join as join27 } from "node:path";
 import {
@@ -11359,16 +11436,18 @@ function observedChunkCaptureMode(perfs) {
   }
   return mode;
 }
+var PROBE_SELECTED_SCREENSHOT = "[renderChunk] probe selected screenshot capture";
 function shouldRetryChunkCaptureWithScreenshot(error) {
   const failure = classifyCaptureFailure4(error);
   if (failure.kind === "cancelled" || failure.kind === "memory_exhaustion") return false;
-  return /HeadlessExperimental\.beginFrame/i.test(failure.message) || /beginFrame probe timeout/i.test(failure.message) || /Another frame is pending|Frame still pending/i.test(failure.message);
+  return /HeadlessExperimental\.beginFrame/i.test(failure.message) || /beginFrame probe timeout/i.test(failure.message) || failure.message.includes(PROBE_SELECTED_SCREENSHOT) || /Another frame is pending|Frame still pending/i.test(failure.message);
 }
 async function runCaptureWithScreenshotFallback(input) {
   try {
     return await input.run(input.forceScreenshot);
   } catch (error) {
-    if (input.forceScreenshot || !shouldRetryChunkCaptureWithScreenshot(error)) throw error;
+    if (input.forceScreenshot || await input.canRetry?.() === false) throw error;
+    if (!shouldRetryChunkCaptureWithScreenshot(error)) throw error;
     input.onFallback?.(error);
     await input.resetForScreenshotRetry();
     return await input.run(true);
@@ -11577,7 +11656,24 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     let extraction;
     const overlap = { current: null };
     try {
-      if (chunkWorkerCount === 1 || !forceScreenshotForChunk) {
+      const verifyInWorker = chunkWorkerCount > 1 && !forceScreenshotForChunk;
+      let boxesMeasured;
+      let boxesFailed;
+      const boxesReady = new Promise((resolve10, reject) => {
+        boxesMeasured = resolve10;
+        boxesFailed = reject;
+      });
+      boxesReady.catch(() => {
+      });
+      const measureBoxes = async (page) => {
+        shownBoxes = await measureVideoShownBoxes(
+          page,
+          [...shownFrames.keys()],
+          chunkFrameNumbers.map((frame) => frame * chunkFps.den / chunkFps.num)
+        );
+        boxesMeasured();
+      };
+      if (chunkWorkerCount === 1) {
         const bootStarted = Date.now();
         session = await createVerifiedDistributedCaptureSession(
           fileServer.url,
@@ -11586,11 +11682,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           cfg
         );
         sessionBootMs = Date.now() - bootStarted;
-        shownBoxes = await measureVideoShownBoxes(
-          session.page,
-          [...shownFrames.keys()],
-          chunkFrameNumbers.map((frame) => frame * chunkFps.den / chunkFps.num)
-        );
+        await measureBoxes(session.page);
         const browserSelectedScreenshot = session.launchCaptureMode === "screenshot";
         const beginFrameStalled = !browserSelectedScreenshot && await beginFrameSessionNeedsScreenshotFallback(session);
         if (browserSelectedScreenshot) {
@@ -11599,10 +11691,6 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
             "[renderChunk] Browser capability probe selected screenshot capture for the entire chunk",
             { chunkIndex }
           );
-          if (chunkWorkerCount > 1) {
-            await closeCaptureSession10(session);
-            session = null;
-          }
         } else if (beginFrameStalled) {
           forceScreenshotForChunk = true;
           log.warn(
@@ -11612,41 +11700,66 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           await closeCaptureSession10(session).catch(() => {
           });
           session = null;
-          if (chunkWorkerCount === 1) {
-            const screenshotBootStarted = Date.now();
-            const screenshotCfg = {
-              ...cfg,
-              forceScreenshot: true,
-              forceScreenshotExplicitlyOptedOut: false
-            };
-            session = await createVerifiedDistributedCaptureSession(
-              fileServer.url,
-              framesDir,
-              captureOptions,
-              screenshotCfg
+          const screenshotBootStarted = Date.now();
+          const screenshotCfg = {
+            ...cfg,
+            forceScreenshot: true,
+            forceScreenshotExplicitlyOptedOut: false
+          };
+          session = await createVerifiedDistributedCaptureSession(
+            fileServer.url,
+            framesDir,
+            captureOptions,
+            screenshotCfg
+          );
+          sessionBootMs += Date.now() - screenshotBootStarted;
+        }
+      } else if (!verifyInWorker) {
+        boxesMeasured();
+      }
+      let verification;
+      const verifyFirstWorker = (first) => verification ??= (async () => {
+        sessionBootMs = Date.now() - verifyStarted;
+        try {
+          await measureBoxes(first.page);
+          const selectedScreenshot = first.launchCaptureMode === "screenshot";
+          if (selectedScreenshot || await beginFrameSessionNeedsScreenshotFallback(first)) {
+            forceScreenshotForChunk = true;
+            log.warn(
+              selectedScreenshot ? "[renderChunk] Browser capability probe selected screenshot capture for the entire chunk" : "[renderChunk] BeginFrame liveness probe failed; using screenshot capture for the entire chunk",
+              { chunkIndex }
             );
-            sessionBootMs += Date.now() - screenshotBootStarted;
+            throw new Error(PROBE_SELECTED_SCREENSHOT);
           }
-        } else if (chunkWorkerCount > 1) {
-          await closeCaptureSession10(session);
-          session = null;
+        } catch (error) {
+          if (!forceScreenshotForChunk) {
+            verifyFailure = error;
+            boxesFailed(error);
+          }
+          throw error;
         }
-      }
-      const extractStarted = Date.now();
-      const deferredVideoFrames = planVideos ? extractDeferredVideoFramesForChunk({
-        planDir,
-        planVideos,
-        frames: chunkFrameNumbers,
-        fps: chunkFps,
-        outputRoot: videoFramesDir,
-        cfg,
-        remoteSources,
-        shownBoxes
-      }).then((frames) => {
-        videoExtractMs = Date.now() - extractStarted;
-        return frames;
-      }) : Promise.resolve([]);
+      })();
+      let verifyStarted = 0;
+      let verifyFailure;
+      const deferredVideoFrames = planVideos ? boxesReady.then(() => {
+        const extractStarted = Date.now();
+        return extractDeferredVideoFramesForChunk({
+          planDir,
+          planVideos,
+          frames: chunkFrameNumbers,
+          fps: chunkFps,
+          outputRoot: videoFramesDir,
+          cfg,
+          remoteSources,
+          shownBoxes
+        }).then((frames) => {
+          videoExtractMs = Date.now() - extractStarted;
+          return frames;
+        });
+      }) : boxesReady.then(() => []);
       extraction = deferredVideoFrames;
+      deferredVideoFrames.catch(() => {
+      });
       const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? deferredVideoFrames.then(
         (deferred) => createFrameLookupTable5(
           planVideos.videos,
@@ -11718,11 +11831,14 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         // first frame is an IDR keyframe and concat-copy at assemble time
         // round-trips losslessly.
         lockGopForChunkConcat: !isPngSequence,
-        gopSize: framesInChunk
+        gopSize: chunkGopFrames(framesInChunk, encoder.keyframeIntervalFrames),
+        maxBitrate: encoder.maxBitrate,
+        bufferSize: encoder.bufferSize
       };
       const captureStarted = Date.now();
       captureMode = await runCaptureWithScreenshotFallback({
         forceScreenshot: forceScreenshotForChunk,
+        canRetry: () => verifyFailure === void 0,
         // fallow-ignore-next-line complexity
         run: async (forceScreenshot) => {
           const captureCfg = cfg.forceScreenshot === forceScreenshot ? cfg : {
@@ -11752,6 +11868,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           }
           const captureSession = session;
           session = null;
+          verifyStarted = Date.now();
           overlap.current = canEncodeWhileCapturing(encodeInput, chunkWorkerCount, cpus().length) ? encodeWhileCapturing(encodeInput, framesInChunk) : null;
           await observeRenderStage(
             new RenderObservabilityRecorder({ pipelineStartMs: start, log }),
@@ -11779,7 +11896,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
               frameRange: range,
               onFrameLanded: (frame) => overlap.current?.onFrameLanded(frame),
               interleaveFrames: interleavesCapture(overlap.current !== null, options),
-              openAttempt
+              openAttempt,
+              verifyFirstSession: forceScreenshot || !verifyInWorker ? void 0 : verifyFirstWorker
             }),
             { stall: frameStallRule(job) }
           ).catch(async (captureError) => {
@@ -11790,7 +11908,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           return observedChunkCaptureMode(capturePerfs);
         },
         resetForScreenshotRetry: () => {
-          rmSync13(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+          rmSync11(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+          boxesMeasured();
           mkdirSync14(framesDir, { recursive: true });
           capturePerfs.length = 0;
           captureAttempts.length = 0;
@@ -11806,6 +11925,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           );
         }
       }).catch(async (captureError) => {
+        if (verifyFailure !== void 0) throw verifyFailure;
+        boxesFailed(captureError);
         await deferredVideoFrames;
         throw captureError;
       });
@@ -11833,8 +11954,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
           timeoutMs: cfg.ffmpegProcessTimeout
         });
-        rmSync13(videoOnlyPath, { force: true });
-        rmSync13(audioScratchPath, { force: true });
+        rmSync11(videoOnlyPath, { force: true });
+        rmSync11(audioScratchPath, { force: true });
       }
       encodeStageMs = Date.now() - encodeStarted;
     } finally {
@@ -11884,8 +12005,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     writeFileSync11(perfPath, `${JSON.stringify(perfPayload, null, 2)}
 `, "utf-8");
     try {
-      rmSync13(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
-      rmSync13(videoFramesDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      rmSync11(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      rmSync11(videoFramesDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     } catch (err) {
       log.warn("[renderChunk] failed to remove work dir", {
         workDir,
@@ -11920,7 +12041,7 @@ async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath, options) {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
     return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath, options);
   } finally {
-    rmSync14(workRoot, { recursive: true, force: true });
+    rmSync12(workRoot, { recursive: true, force: true });
   }
 }
 async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
@@ -11940,7 +12061,7 @@ async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
       options
     );
   } finally {
-    rmSync14(workRoot, { recursive: true, force: true });
+    rmSync12(workRoot, { recursive: true, force: true });
   }
 }
 
@@ -12033,6 +12154,20 @@ function validateDistributedRenderConfig(config) {
       `must look like "10M" or "5000k"; got ${JSON.stringify(config.bitrate)}`
     );
   }
+  try {
+    validateDeliveryEncoderConfig({
+      format: config.format,
+      fps: { num: config.fps, den: 1 },
+      keyframeIntervalSeconds: config.keyframeIntervalSeconds,
+      maxBitrate: config.maxBitrate,
+      bufferSize: config.bufferSize
+    });
+  } catch (error) {
+    throw new InvalidConfigError(
+      "config.maxBitrate",
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   if (config.chunkSize !== void 0) {
     if (!Number.isInteger(config.chunkSize) || config.chunkSize < 1) {
       throw new InvalidConfigError(