@hyperframes/engine 0.8.206 → 0.8.207

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type Cap
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, capturesAlpha, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.js";
-export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
+export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
 export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
@@ -55,7 +55,7 @@ export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCo
 export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
-export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, } from "./services/parallelCoordinator.js";
+export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, type ParallelWorkerPhaseDiagnostic, } from "./services/parallelCoordinator.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
@@ -74,6 +74,7 @@ export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChild
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
 export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
+export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
 export { decodePng, decodePngToRgb48le, blitRgba8OverRgb48le, blitRgb48leRegion, blitRgb48leAffine, parseTransformMatrix, roundedRectAlpha, resampleRgb48leObjectFit, normalizeObjectFit, type ObjectFit, } from "./utils/alphaBlit.js";
 export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";

package/dist/index.js

@@ -47,7 +47,7 @@ export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, capturesAlpha, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, } from "./services/screenshotService.js";
 // ── Encoding ───────────────────────────────────────────────────────────────────
-export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
+export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
 export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
@@ -78,6 +78,7 @@ export { ManagedChildProcess, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
 export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
+export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
 // drawElement self-verify comparison — shared by the streaming drain
 // (producer) and the parallel disk-path verify (parallelCoordinator).
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";

package/dist/services/aacEncode.js

@@ -3,7 +3,8 @@
  * so long audio is encoded as frame-aligned segments in parallel and their frames joined.
  */
 import { execFile } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { removeScratch } from "../utils/removeScratch.js";
 import { dirname, join } from "node:path";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
@@ -133,6 +134,6 @@ export async function encodeAac(input, outputPath, totalDuration, { signal, time
         return { ...muxed, durationMs: slowest + muxed.durationMs };
     }
     finally {
-        rmSync(dir, { recursive: true, force: true });
+        removeScratch(dir);
     }
 }

package/dist/services/audioFxRender.js

@@ -11,13 +11,14 @@
  * dynamics processors and the modulated delays) have no filter that behaves the
  * same way, so preview would quietly stop predicting the render.
  */
-import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, statSync, writeFileSync, writeSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { getAudioFxRuntimeScript } from "@hyperframes/core/audio-fx-runtime";
 import { enabledAudioFxNodes } from "@hyperframes/core/audio-fx";
 import { serializeAutomation } from "@hyperframes/core/audio-automation";
+import { removeScratch } from "../utils/removeScratch.js";
 import { acquireBrowser } from "./browserManager.js";
 import { createEnvelopeWalker } from "./audioVolumeEnvelope.js";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
@@ -460,7 +461,7 @@ async function withFxBrowser(options, body) {
         throw new AudioFxRenderError(`Audio FX failed for track ${options.trackId}: ${err.message}`);
     }
     finally {
-        rmSync(hostDir, { recursive: true, force: true });
+        removeScratch(hostDir);
         await lease?.release().catch(() => undefined);
     }
 }

package/dist/services/audioMixer.js

@@ -2,6 +2,7 @@
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
 import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
 import { renameWithRetry } from "../utils/renameWithRetry.js";
+import { removeScratch } from "../utils/removeScratch.js";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
@@ -575,7 +576,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             };
         }
         finally {
-            rmSync(cycleDir, { recursive: true, force: true });
+            removeScratch(cycleDir);
         }
     }
     const inputSeek = mediaStart >= (metadata?.latestStreamLeadSeconds ?? 0);
@@ -773,7 +774,7 @@ async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, con
             return await runFfmpeg(currentArgs, { signal, timeout: ffmpegProcessTimeout });
         }
         finally {
-            rmSync(scriptDir, { recursive: true, force: true });
+            removeScratch(scriptDir);
         }
     };
     let useNormalize = true;
@@ -934,7 +935,7 @@ async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, sign
             return await runFfmpeg(currentArgs, { signal, timeout: ffmpegProcessTimeout });
         }
         finally {
-            rmSync(scriptDir, { recursive: true, force: true });
+            removeScratch(scriptDir);
         }
     };
     let useNormalize = true;
@@ -991,8 +992,8 @@ async function sumInSlices(tracks, scratchDir, totalDuration, signal, config) {
         }
         const foldedPath = join(scratchDir, `${id}.wav`);
         const folded = await mixGroupMembersFlat([running, wavTrack(`${id}-slice`, slicePath)], foldedPath, totalDuration, signal, config);
-        rmSync(running.srcPath, { force: true });
-        rmSync(slicePath, { force: true });
+        removeScratch(running.srcPath);
+        removeScratch(slicePath);
         if (!folded.success)
             return folded;
         running = wavTrack(id, foldedPath);
@@ -1011,11 +1012,11 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         const summed = await sumInSlices(memberTracks, scratchDir, totalDuration, signal, config);
         if (!summed.success)
             return summed;
-        renameWithRetry(summed.track.srcPath, outputPath);
+        renameWithRetry(summed.track.srcPath, outputPath, { copyFallback: true });
         return { success: true, degradedAutomation: summed.degradedAutomation };
     }
     finally {
-        rmSync(scratchDir, { recursive: true, force: true });
+        removeScratch(scratchDir);
     }
 }
 async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config) {
@@ -1048,7 +1049,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
             : mixed;
     }
     finally {
-        rmSync(scratchDir, { recursive: true, force: true });
+        removeScratch(scratchDir);
     }
 }
 /**
@@ -1085,7 +1086,7 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
         };
     }
     if (config?.keepEncoderInputAt)
-        renameWithRetry(encoderInput, config.keepEncoderInputAt);
+        renameWithRetry(encoderInput, config.keepEncoderInputAt, { copyFallback: true });
     return {
         ...sum,
         outputPath,

package/dist/services/browserManager.js

@@ -706,6 +706,8 @@ async function launchBrowser(fingerprint) {
 }
 function forceCloseBrowserProcess(browser) {
     const proc = browser.process?.();
+    for (const stream of proc?.stdio ?? [])
+        stream?.on("error", () => { });
     if (proc && !proc.killed) {
         try {
             proc.kill("SIGKILL");

package/dist/services/chunkEncoder.d.ts

@@ -87,6 +87,14 @@ export declare function appendLockedGopArgs(args: string[], gopSize: number): vo
  * open-GOP references. `repeat-headers=1` keeps each boundary self-contained.
  */
 export declare function lockedGopCodecParams(codec: "h264" | "h265", gopSize: number): string;
+/** Frames per keyframe interval: the nearest whole frame, never below one. */
+export declare function keyframeIntervalToGopSize(fps: Fps, seconds: number): number;
+/** `-maxrate` / `-bufsize` for the VBV cap, written once for both arg builders. Buffer defaults to 2x. */
+export declare function appendRateCapArgs(args: string[], options: {
+    codec?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
+}): void;
 export declare function buildEncoderArgs(options: EncoderOptions, inputArgs: string[], outputPath: string, gpuEncoder?: GpuEncoder): string[];
 export declare function encodeFramesFromDir(framesDir: string, framePattern: string, outputPath: string, options: EncoderOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegEncodeTimeout">>, onFramesEncoded?: (frames: number) => void): Promise<EncodeResult>;
 export declare function buildConcatArgs(concatListPath: string, outputPath: string): string[];

package/dist/services/chunkEncoder.js

@@ -128,6 +128,38 @@ export function lockedGopCodecParams(codec, gopSize) {
     const shared = "scenecut=0:open-gop=0:repeat-headers=1";
     return codec === "h264" ? shared : `keyint=${gopSize}:min-keyint=${gopSize}:${shared}`;
 }
+/** Frames per keyframe interval: the nearest whole frame, never below one. */
+export function keyframeIntervalToGopSize(fps, seconds) {
+    return Math.max(1, Math.round(fpsToNumber(fps) * seconds));
+}
+const BITRATE_PATTERN = /^(\d+(?:\.\d+)?)([kKmMgG]?)$/;
+function bitrateToBitsPerSecond(value) {
+    const match = BITRATE_PATTERN.exec(value);
+    if (!match)
+        throw new Error(`[chunkEncoder] invalid bitrate ${JSON.stringify(value)}`);
+    const unit = match[2].toLowerCase();
+    const scale = { g: 1_000_000_000, m: 1_000_000, k: 1_000 }[unit] ?? 1;
+    return Number(match[1]) * scale;
+}
+/** `-maxrate` / `-bufsize` for the VBV cap, written once for both arg builders. Buffer defaults to 2x. */
+export function appendRateCapArgs(args, options) {
+    const { maxBitrate, bufferSize } = options;
+    if (maxBitrate === undefined) {
+        if (bufferSize !== undefined)
+            throw new Error("[chunkEncoder] bufferSize requires maxBitrate");
+        return;
+    }
+    const codec = options.codec ?? "h264";
+    if (codec !== "h264" && codec !== "h265") {
+        throw new Error(`[chunkEncoder] maxBitrate is not supported for codec ${codec}`);
+    }
+    const cap = bitrateToBitsPerSecond(maxBitrate);
+    const buffer = bufferSize !== undefined ? bitrateToBitsPerSecond(bufferSize) : cap * 2;
+    if (cap <= 0 || buffer <= 0) {
+        throw new Error("[chunkEncoder] maxBitrate and bufferSize must be positive");
+    }
+    args.push("-maxrate", String(Math.round(cap)), "-bufsize", String(Math.round(buffer)));
+}
 export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = null) {
     const { fps, codec = "h264", preset = "medium", quality = 23, bitrate, pixelFormat = "yuv420p", vp9CpuUsed, useGpu = false, } = options;
     // libx264 cannot encode HDR. If a caller passes hdr with codec=h264 we'd
@@ -142,6 +174,7 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
     // Without -xerror, ffmpeg ends the video at the first frame file it cannot read and still exits 0.
     const args = ["-xerror", ...inputArgs, "-r", fpsToFfmpegArg(fps)];
     const shouldUseGpu = useGpu && gpuEncoder !== null;
+    appendRateCapArgs(args, options);
     if (codec === "h264" || codec === "h265") {
         if (shouldUseGpu) {
             const encoderName = getGpuEncoderName(gpuEncoder, codec);

package/dist/services/chunkEncoder.types.d.ts

@@ -9,6 +9,8 @@ export interface EncoderOptions {
     preset?: string;
     quality?: number;
     bitrate?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
     pixelFormat?: string;
     /** libvpx-vp9 -cpu-used value. Defaults to the engine VP9 setting. */
     vp9CpuUsed?: number;

package/dist/services/drawElementCaptureError.d.ts

@@ -3,5 +3,6 @@ export declare class DrawElementCaptureError extends Error {
     readonly frameIndex: number;
     constructor(frameIndex: number, reason: string, cause?: unknown);
 }
+export declare function asDrawElementCaptureFailure(frameIndex: number, encodeResult: Promise<Buffer>): Promise<Buffer>;
 /** Structural matching survives engine/producer copies and worker error wrappers. */
 export declare function isDrawElementCaptureError(error: unknown): boolean;

package/dist/services/drawElementCaptureError.js

@@ -9,6 +9,19 @@ export class DrawElementCaptureError extends Error {
         this.frameIndex = frameIndex;
     }
 }
+function markRejectionHandled(promise) {
+    promise.catch(() => { });
+}
+export function asDrawElementCaptureFailure(frameIndex, encodeResult) {
+    const wrapped = encodeResult.catch((cause) => {
+        if (isDrawElementCaptureError(cause))
+            throw cause;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new DrawElementCaptureError(frameIndex, reason, cause);
+    });
+    markRejectionHandled(wrapped);
+    return wrapped;
+}
 /** Structural matching survives engine/producer copies and worker error wrappers. */
 export function isDrawElementCaptureError(error) {
     let current = error;

package/dist/services/frameCapture.js

@@ -11,7 +11,7 @@ import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END, RUNTIME_BOOTSTRAP_ATTR, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
 import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
-import { DrawElementCaptureError } from "./drawElementCaptureError.js";
+import { asDrawElementCaptureFailure, DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
 import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
@@ -3648,7 +3648,8 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
         // syncToPaintEvent = true); see initDrawElementOrTransparentBackground. The
         // BeginFrame branch present in the synchronous captureFrameCore is therefore
         // unreachable here and intentionally omitted.
-        const { encodeResult } = await produceDrawElementFrame(page, options.width, options.height, options.quality ?? 80, true);
+        const produced = await produceDrawElementFrame(page, options.width, options.height, options.quality ?? 80, true);
+        const encodeResult = asDrawElementCaptureFailure(frameIndex, produced.encodeResult);
         const captureTimeMs = Date.now() - startTime;
         session.capturePerf.frames += 1;
         session.capturePerf.seekMs += seekMs;
@@ -3763,7 +3764,10 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
         const encodeResult = encodeResults[i];
         if (frameIndex === undefined || !encodeResult)
             break;
-        results.push({ frameIndex, encodeResult });
+        results.push({
+            frameIndex,
+            encodeResult: asDrawElementCaptureFailure(frameIndex, encodeResult),
+        });
     }
     if (failedAt !== null) {
         // `error` is a plain string here (produceDrawElementFrameBatch returns it

package/dist/services/parallelCoordinator.d.ts

@@ -74,6 +74,7 @@ export interface ParallelWorkerPhaseDiagnostic {
     browserVersion: string;
     canvasDrawElement: boolean | "unknown";
     gpuBackend: string;
+    readStep?: () => string | undefined;
 }
 export interface WorkerSizingConfig extends Partial<Pick<EngineConfig, "concurrency" | "coresPerWorker" | "minParallelFrames" | "largeRenderThreshold">> {
     /**
@@ -237,6 +238,7 @@ export interface ParallelCaptureHooks {
      * frame (the ordered writer) with the original error, not a stall.
      */
     onWorkerFailure?: (failure: CaptureFailure) => void;
+    onWorkerOperation?: (diagnostic: ParallelWorkerPhaseDiagnostic) => void;
 }
 /**
  * The pool's single failure gate. Both halves of the contract the streaming

package/dist/services/parallelCoordinator.js

@@ -320,20 +320,22 @@ function resolveParallelWorkerTimeoutMs(enabled) {
     return Number.isFinite(parsed) && parsed > 0 ? parsed : 30_000;
 }
 // fallow-ignore-next-line complexity
-async function captureFrameRange(session, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase) {
+async function captureFrameRange(session, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase, onWorkerOperation) {
     let framesCaptured = 0;
     const outputOffset = task.outputFrameOffset ?? 0;
     const stride = task.frameStride ?? 1;
     const runCaptureOperation = (phase, frameIndex, operation) => {
-        const diagnostic = diagnosticFor(phase, frameIndex);
+        const diagnostic = { ...diagnosticFor(phase, frameIndex), readStep: () => session.captureStep };
         if (framesCaptured === 0)
             onWorkerPhase?.(diagnostic);
+        onWorkerOperation?.(diagnostic);
         return withParallelWorkerDeadline(operation(), diagnostic, phaseTimeoutMs, signal);
     };
     const awaitEncode = (frameIndex, encodeResult) => {
         const diagnostic = diagnosticFor("frame_encode", frameIndex);
         if (framesCaptured === 0)
             onWorkerPhase?.(diagnostic);
+        onWorkerOperation?.(diagnostic);
         return withParallelWorkerDeadline(encodeResult, diagnostic, phaseTimeoutMs, signal);
     };
     // Depth-2 pipelined drawElement produce (HF_DE_PARALLEL_STREAM spike): frame
@@ -550,7 +552,7 @@ export async function verifyDiskDrawElementSamples(session, task, streaming) {
 // flagged only because the disk self-verify call shifted its line range into
 // the changed-code audit. Not restructured by this PR.
 // fallow-ignore-next-line complexity
-async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase) {
+async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, onWorkerOperation) {
     const startTime = Date.now();
     let framesCaptured = 0;
     if (!existsSync(task.outputDir))
@@ -605,7 +607,7 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         canvasDrawElement = activeSession.captureMode === "drawelement";
         gpuBackend = activeSession.gpuRenderer ?? "unknown";
         logParDebug(() => `[par:w${task.workerId}] init done (mode=${session?.captureMode} workerEncode=${session?.workerEncodeEnabled === true})`);
-        framesCaptured = await captureFrameRange(activeSession, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase);
+        framesCaptured = await captureFrameRange(activeSession, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase, onWorkerOperation);
         await verifyDiskDrawElementSamples(activeSession, task, Boolean(onFrameBuffer));
         perf = getCapturePerfSummary(activeSession);
         return {
@@ -775,7 +777,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
         hooks,
     });
     const onFailure = failureHandler.onFailure;
-    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase)));
+    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation)));
     flagSilentWorkerExits(results);
     const errors = results.filter((r) => r.failure || r.error);
     if (errors.length > 0) {

package/dist/services/streamingEncoder.d.ts

@@ -38,6 +38,8 @@ export interface StreamingEncoderOptions {
     preset?: string;
     quality?: number;
     bitrate?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
     pixelFormat?: string;
     /** libvpx-vp9 -cpu-used value. Defaults to the engine VP9 setting. */
     vp9CpuUsed?: number;

package/dist/services/streamingEncoder.js

@@ -30,7 +30,7 @@ import { fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
 import { appendVp9CpuUsedArg } from "./vp9Options.js";
 import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js";
 import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
-import { appendLockedGopArgs, lockedGopCodecParams, resolveLockedGopSize } from "./chunkEncoder.js";
+import { appendLockedGopArgs, appendRateCapArgs, lockedGopCodecParams, resolveLockedGopSize, } from "./chunkEncoder.js";
 export function createFrameReorderBuffer(startFrame, endFrame) {
     let cursor = startFrame;
     let aborted = null;
@@ -121,6 +121,7 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
     }
     args.push("-r", fpsToFfmpegArg(fps));
     const shouldUseGpu = useGpu && gpuEncoder !== null;
+    appendRateCapArgs(args, options);
     if (codec === "h264" || codec === "h265") {
         if (shouldUseGpu) {
             const encoderName = getGpuEncoderName(gpuEncoder, codec);

package/dist/services/videoFrameExtractor.js

@@ -623,9 +623,6 @@ outputDirOverride) {
         throw new Error("frameRanges extraction needs a constant-frame-rate source");
     }
     const args = urlInputArgs(videoPath);
-    if (decodeWithVideoToolbox) {
-        args.push("-hwaccel", "videotoolbox");
-    }
     // Always force the alpha-aware decoder on codecs that can carry alpha. The
     // alternative — gating on `metadata.hasAlpha` — relies on tag detection that
     // has at least three known failure modes: case-sensitivity across ffmpeg
@@ -708,9 +705,9 @@ outputDirOverride) {
     // emits that last slot: the fps filter ends a `-t` window at the nearest slot. A
     // decimal rate counts zero frames here and keeps the `-t` window.
     const boundVfrFrameCount = metadata.isVFR && totalFrames > 0;
-    const processResult = sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
-        ? await runSegmentedExtraction({
-            decodeArgs,
+    const extract = (hwaccel) => sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
+        ? runSegmentedExtraction({
+            decodeArgs: [...hwaccel, ...decodeArgs],
             filterAndEncodeArgs: (seek) => [...filterArgsFor(seek), ...encodeArgs],
             videoPath,
             startTime,
@@ -719,7 +716,14 @@ outputDirOverride) {
             segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
             runOptions,
         })
-        : await inExtractionSlot(() => runFfmpeg([...args, ...filterArgsFor(startTime), ...encodeArgs], runOptions), signal);
+        : inExtractionSlot(() => runFfmpeg([...hwaccel, ...args, ...filterArgsFor(startTime), ...encodeArgs], runOptions), signal);
+    let processResult = await extract(decodeWithVideoToolbox ? ["-hwaccel", "videotoolbox"] : []);
+    const ffmpegExitedFailing = processResult.terminationReason === "exit" &&
+        !processResult.success &&
+        !processResult.failureReason;
+    const videoToolboxWasOptional = decodeWithVideoToolbox && !keepsHdrForChrome;
+    if (ffmpegExitedFailing && videoToolboxWasOptional)
+        processResult = await extract([]);
     if (processResult.failureReason === "external_interruption") {
         throw new VideoSourceExtractionError("external_interruption", true, "Video frame extraction interrupted by host lifecycle", `FFmpeg exited with code ${processResult.exitCode}: ${processResult.stderr.slice(-500)}`);
     }

package/dist/utils/removeScratch.d.ts

@@ -0,0 +1,5 @@
+/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
+ * delete) leaves it for the render's own cleanup and never fails the audio it served. */
+export declare function removeScratch(path: string): void;
+/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
+export declare function collectScratchLeftovers<T>(run: () => Promise<T>, report: (left: string[]) => void): Promise<T>;

package/dist/utils/removeScratch.js

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { rmSync } from "node:fs";
+const collecting = new AsyncLocalStorage();
+/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
+ * delete) leaves it for the render's own cleanup and never fails the audio it served. */
+export function removeScratch(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        collecting.getStore()?.push(path);
+    }
+}
+/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
+export async function collectScratchLeftovers(run, report) {
+    const left = [];
+    try {
+        return await collecting.run(left, run);
+    }
+    finally {
+        report(left);
+    }
+}

package/dist/utils/renameWithRetry.d.ts

@@ -1,12 +1,16 @@
 interface Options {
     platform?: NodeJS.Platform;
+    /** Copy the bytes when Windows keeps refusing (a TEMP that denies delete). Not atomic: scratch files only. */
+    copyFallback?: boolean;
 }
 /** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
 export declare function renameWithRetry(from: string, to: string, options?: Options & {
     rename?: (from: string, to: string) => void;
+    copy?: (from: string, to: string) => void;
 }): void;
 /** Async twin of {@link renameWithRetry}. */
 export declare function renameWithRetryAsync(from: string, to: string, options?: Options & {
     rename?: (from: string, to: string) => Promise<void>;
+    copy?: (from: string, to: string) => Promise<void>;
 }): Promise<void>;
 export {};

package/dist/utils/renameWithRetry.js

@@ -1,5 +1,6 @@
-import { renameSync } from "node:fs";
-import { rename } from "node:fs/promises";
+import { copyFileSync, renameSync } from "node:fs";
+import { copyFile, rename } from "node:fs/promises";
+import { removeScratch } from "./removeScratch.js";
 // Windows reports EPERM/EACCES/EBUSY while antivirus or a just-exited process still holds the
 // file; the hold clears within milliseconds. Total wait before giving up: about 1.3 s.
 const RETRYABLE = new Set(["EPERM", "EACCES", "EBUSY"]);
@@ -9,12 +10,21 @@ function isRetryable(error, platform) {
         return false;
     return RETRYABLE.has(error?.code ?? "");
 }
+/** What a refused rename does next: wait and try again, fall back to a copy, or give up with the error. */
+function nextStep(error, attempt, options, platform) {
+    if (!isRetryable(error, platform))
+        return "throw";
+    if (attempt < BACKOFF_MS.length)
+        return "wait";
+    return options.copyFallback ? "copy" : "throw";
+}
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 /** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
 export function renameWithRetry(from, to, options = {}) {
     const doRename = options.rename ?? renameSync;
+    const doCopy = options.copy ?? copyFileSync;
     const platform = options.platform ?? process.platform;
     for (let attempt = 0;; attempt++) {
         try {
@@ -22,15 +32,28 @@ export function renameWithRetry(from, to, options = {}) {
             return;
         }
         catch (error) {
-            if (attempt >= BACKOFF_MS.length || !isRetryable(error, platform))
+            const step = nextStep(error, attempt, options, platform);
+            if (step === "throw")
+                throw error;
+            if (step === "wait") {
+                sleepSync(BACKOFF_MS[attempt]);
+                continue;
+            }
+            try {
+                doCopy(from, to);
+            }
+            catch {
                 throw error;
-            sleepSync(BACKOFF_MS[attempt]);
+            }
+            removeScratch(from);
+            return;
         }
     }
 }
 /** Async twin of {@link renameWithRetry}. */
 export async function renameWithRetryAsync(from, to, options = {}) {
     const doRename = options.rename ?? rename;
+    const doCopy = options.copy ?? copyFile;
     const platform = options.platform ?? process.platform;
     for (let attempt = 0;; attempt++) {
         try {
@@ -38,9 +61,21 @@ export async function renameWithRetryAsync(from, to, options = {}) {
             return;
         }
         catch (error) {
-            if (attempt >= BACKOFF_MS.length || !isRetryable(error, platform))
+            const step = nextStep(error, attempt, options, platform);
+            if (step === "throw")
                 throw error;
-            await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
+            if (step === "wait") {
+                await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
+                continue;
+            }
+            try {
+                await doCopy(from, to);
+            }
+            catch {
+                throw error;
+            }
+            removeScratch(from);
+            return;
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.206",
+  "version": "0.8.207",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.206",
-    "@hyperframes/parsers": "^0.8.206"
+    "@hyperframes/core": "^0.8.207",
+    "@hyperframes/parsers": "^0.8.207"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",