@hyperframes/engine 0.8.206 → 0.8.208

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.d.ts

@@ -61,32 +61,6 @@ export declare const _closeBrowserAfterFailedProbeForTests: typeof closeBrowserA
 export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
 /** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
 export declare function captureWithoutWaylandDisplay(resolvedMode: "software" | "hardware"): Promise<boolean>;
-/**
- * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
- *
- * For `"software"` this is a pure pass-through. For `"auto"` it launches a
- * tiny Chrome with the platform's hardware GPU args, runs a one-shot WebGL
- * availability probe, and falls back to `"software"` if hardware-mode WebGL
- * is unavailable. The Promise is cached for the process lifetime, so
- * concurrent callers (parallel workers) share the same probe.
- *
- * `"hardware"` (an explicit `--browser-gpu` / `PRODUCER_BROWSER_GPU_MODE=
- * hardware`) is honoured verbatim — the operator asked for it — but runs the
- * SAME probe to VERIFY it, because Chrome's hardware GL args are advisory:
- * with no usable GPU in the sandbox (no `/dev/dri`, no NVIDIA container
- * runtime, missing EGL/driver libraries) Chrome silently falls back to
- * software WebGL and the render just runs at CPU speed. Without this check
- * the only trace is a buried `Automatic fallback to software WebGL` browser
- * warning — heygen-com/hyperframes#2967 rendered 19186 frames on CPU while
- * `--browser-gpu` was set and nothing said so. The probe result never
- * changes the returned mode; it only makes the fallback loud.
- *
- * Any probe failure (Chrome launch error, navigation timeout, missing canvas
- * API, etc.) is treated as a `"software"` result. The render path with
- * SwiftShader always works, so a misclassification toward software is the
- * safe failure mode; misclassifying toward hardware would error on the real
- * render.
- */
 export declare function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode"], options?: GpuProbeOptions): Promise<"software" | "hardware">;
 type BrowserLaunchConfig = Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">> & {
     withoutWaylandDisplay?: boolean;

package/dist/services/browserManager.js

@@ -5,6 +5,7 @@
  * Manages Puppeteer browser lifecycle: Chrome executable resolution,
  * launch args, pooled browser acquisition/release.
  */
+import { explainChromeLaunchFailure } from "./chromeStartup.js";
 import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
 import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";
 import { execSync } from "child_process";
@@ -462,7 +463,8 @@ async function probeWebGlMode(ppt, options, env, label = "") {
     }
     catch (err) {
         logResolvedBrowserGpuMode("software", label + formatProbeFailure(err));
-        return { mode: "software", cause: "probe-error" };
+        const aborted = err instanceof Error && err.name === "AbortError";
+        return { mode: "software", cause: "probe-error", ...(aborted && { aborted }) };
     }
 }
 function envWithoutWaylandDisplay() {
@@ -524,12 +526,24 @@ function wslAccess(options) {
  * safe failure mode; misclassifying toward hardware would error on the real
  * render.
  */
+async function sharedGpuProbe(options) {
+    const shared = (_autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options));
+    const outcome = await shared;
+    if (!outcome.aborted)
+        return outcome;
+    if (_autoBrowserGpuModeCache === shared)
+        _autoBrowserGpuModeCache = undefined;
+    const own = await probeAutoBrowserGpuMode(options);
+    if (!own.aborted)
+        _autoBrowserGpuModeCache ??= Promise.resolve(own);
+    return own;
+}
 export function resolveBrowserGpuMode(mode, options = {}) {
     if (mode === "software")
         return Promise.resolve(mode);
-    _autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options);
+    const probe = sharedGpuProbe(options);
     if (mode === "auto") {
-        return _autoBrowserGpuModeCache.then((probed) => {
+        return probe.then((probed) => {
             if (probed.mode === "software" && probed.wslAccess && !_wslSoftwareNoteLogged) {
                 _wslSoftwareNoteLogged = true;
                 console.error(buildWslSoftwareNote(probed));
@@ -537,7 +551,7 @@ export function resolveBrowserGpuMode(mode, options = {}) {
             return probed.mode;
         });
     }
-    return _autoBrowserGpuModeCache.then((probed) => {
+    return probe.then((probed) => {
         // Warn once per cache lifetime, not once per caller: `createCaptureSession`
         // resolves the mode for the probe browser AND every parallel worker, so
         // an un-deduplicated warning prints N+1 times and buries itself.
@@ -658,7 +672,8 @@ async function launchBrowser(fingerprint) {
     const env = launchEnv(fingerprint);
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
-    const launch = (args) => ppt.launch({
+    const launch = (args) => ppt
+        .launch({
         ...ownedLaunchOptions(),
         headless: true,
         args: withHyperframesBrowserMarker(args),
@@ -667,6 +682,13 @@ async function launchBrowser(fingerprint) {
         env,
         timeout: fingerprint.browserTimeoutMs,
         protocolTimeout: fingerprint.protocolTimeoutMs,
+    })
+        .catch(async (error) => {
+        const defaults = await ppt.defaultArgs({
+            headless: true,
+            args: withHyperframesBrowserMarker(args),
+        });
+        throw await explainChromeLaunchFailure(error, fingerprint.executablePath, defaults);
     });
     const probe = (target, timeoutMs) => probeBeginFrameSupport(target, timeoutMs).catch((error) => ({
         supported: true,
@@ -706,6 +728,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/chromeHostCeiling.d.ts

@@ -7,7 +7,7 @@ export declare const isManagedChromeDir: (versionName: string) => boolean;
 /** Newest first, by numeric build (`linux-148.0.1` before `linux-99.0.1`). */
 export declare function compareBrowserVersionsDescending(left: string, right: string): number;
 /** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
-export declare function shellStarts(binary: string): boolean;
+export declare function shellStarts(binary: string, timeoutMs?: number): boolean;
 /** The shared Puppeteer cache's shell: the managed build, else the newest under the host's ceiling that starts.
  * `shell` names a version dir's executable, or undefined when it holds no usable file. */
 export declare function pickSharedShell(versions: readonly string[], shell: (version: string) => string | undefined): string | undefined;

package/dist/services/chromeHostCeiling.js

@@ -52,11 +52,13 @@ export function compareBrowserVersionsDescending(left, right) {
 const starts = new Map();
 const debug = debuglog("hyperframes:browser");
 /** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
-export function shellStarts(binary) {
+export function shellStarts(binary, timeoutMs = 10_000) {
     let answer = starts.get(binary);
     if (answer === undefined) {
         const probe = ["--no-sandbox", "--dump-dom", "about:blank"];
-        answer = spawnSync(binary, probe, { stdio: "ignore", timeout: 10_000 })?.status === 0;
+        answer =
+            spawnSync(binary, probe, { stdio: "ignore", timeout: timeoutMs, killSignal: "SIGKILL" })
+                ?.status === 0;
         if (!answer)
             debug("skipping %s: it did not start", binary);
         starts.set(binary, answer);

package/dist/services/chromeStartup.d.ts

@@ -0,0 +1,10 @@
+/** Names an exit code the way a person can act on it; undefined when it has no name. */
+export declare function nameChromeExit(code: number | null, platform?: NodeJS.Platform): string | undefined;
+/** Starts the browser once more with the failed launch's flags and says how it ended. */
+export declare function diagnoseChromeStartup(executablePath: string, args: readonly string[], options?: {
+    timeoutMs?: number;
+    platform?: NodeJS.Platform;
+    signal?: AbortSignal;
+}): Promise<string>;
+/** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
+export declare function explainChromeLaunchFailure(error: unknown, executablePath: string | undefined, args: readonly string[] | undefined, signal?: AbortSignal): Promise<unknown>;

package/dist/services/chromeStartup.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeTreeBestEffort } from "@hyperframes/core/remove-tree";
+const STDERR_TAIL_LINES = 8;
+const PROBE_TIMEOUT_MS = 8_000;
+// NTSTATUS codes a Windows process dies with before it can print anything.
+const WINDOWS_EXITS = [
+    [0xc0000135, "0xC0000135: a required runtime or DLL is missing (Visual C++ runtime)."],
+    [0xc0000017, "0xC0000017: Windows had no memory to start it (out of memory)."],
+    [0xc0000142, "0xC0000142: a DLL failed to initialise, often security software blocking it."],
+    [0xc0000022, "0xC0000022: access denied, often antivirus or a policy blocking the executable."],
+    [0xc000007b, "0xC000007B: the executable and a DLL do not match (32-bit and 64-bit)."],
+];
+/** Names an exit code the way a person can act on it; undefined when it has no name. */
+export function nameChromeExit(code, platform = process.platform) {
+    if (platform !== "win32" || code === null)
+        return undefined;
+    const unsigned = code >>> 0;
+    return WINDOWS_EXITS.find(([known]) => known === unsigned)?.[1];
+}
+function startupArgs(args, profile) {
+    const kept = args.filter((arg) => arg.startsWith("--") &&
+        !arg.startsWith("--remote-debugging") &&
+        !arg.startsWith("--user-data-dir"));
+    return [...kept, `--user-data-dir=${profile}`, "--remote-debugging-port=0", "about:blank"];
+}
+function tail(stderr) {
+    return stderr
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-STDERR_TAIL_LINES)
+        .join("\n");
+}
+/** Starts the browser once more with the failed launch's flags and says how it ended. */
+export async function diagnoseChromeStartup(executablePath, args, options = {}) {
+    const profile = mkdtempSync(join(tmpdir(), "hf-chrome-probe-"));
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    try {
+        return await new Promise((resolve) => {
+            let stderr = "";
+            const child = spawn(executablePath, startupArgs(args, profile), {
+                stdio: ["ignore", "ignore", "pipe"],
+                windowsHide: true,
+            });
+            const timer = setTimeout(() => {
+                child.kill();
+                resolve(`Chrome started and kept running for ${timeoutMs} ms when launched on its own.`);
+            }, timeoutMs);
+            options.signal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                child.kill();
+                resolve("The startup check was cancelled.");
+            }, { once: true });
+            child.stderr.on("data", (chunk) => {
+                stderr = (stderr + chunk.toString()).slice(-4000);
+            });
+            child.once("error", (error) => {
+                clearTimeout(timer);
+                resolve(`Chrome could not be started: ${error.message}`);
+            });
+            child.once("exit", (code, signal) => {
+                clearTimeout(timer);
+                const how = signal ? `was stopped by ${signal}` : `exited with code ${code}`;
+                const named = nameChromeExit(code, options.platform);
+                const lines = tail(stderr);
+                resolve([`Chrome ${how} when launched on its own.`, named, lines && `stderr:\n${lines}`]
+                    .filter(Boolean)
+                    .join("\n"));
+            });
+        });
+    }
+    finally {
+        removeTreeBestEffort(profile);
+    }
+}
+/** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
+export async function explainChromeLaunchFailure(error, executablePath, args, signal) {
+    if (!executablePath || !(error instanceof Error))
+        return error;
+    const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });
+    return new Error(`${error.message}\n${diagnosis}`, { cause: error });
+}

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,9 @@ export interface ParallelCaptureHooks {
      * frame (the ordered writer) with the original error, not a stall.
      */
     onWorkerFailure?: (failure: CaptureFailure) => void;
+    onWorkerOperation?: (diagnostic: ParallelWorkerPhaseDiagnostic) => void;
+    /** Worker 0 runs this on its initialised session; the other workers wait for it. A rejection fails the pool. */
+    verifyFirstSession?: (session: CaptureSession) => Promise<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, gate) {
     const startTime = Date.now();
     let framesCaptured = 0;
     if (!existsSync(task.outputDir))
@@ -601,11 +603,13 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
                 await assertSwiftShader(activeSession.page, readWebGlVendorInfoFromCanvas);
             }
             await initializeSession(activeSession);
+            if (gate)
+                await (task.workerId === 0 ? gate.verify(activeSession) : gate.wait());
         });
         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 {
@@ -620,6 +624,8 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         };
     }
     catch (error) {
+        if (task.workerId === 0)
+            gate?.fail(error);
         const diagnostics = session ? selectWorkerDiagnostics(session.browserConsoleBuffer) : [];
         const workerDiagnostic = {
             workerId: task.workerId,
@@ -685,6 +691,23 @@ export function isPoolFatalWorkerFailure(failure, streaming) {
         return failure.kind !== "cancelled";
     return isFatalCaptureFailure(failure);
 }
+function createFirstSessionGate(verify) {
+    let fail;
+    let pass;
+    const settled = new Promise((resolve, reject) => {
+        pass = resolve;
+        fail = reject;
+    });
+    settled.catch(() => { });
+    return {
+        verify: (session) => verify(session).then(pass, (error) => {
+            fail(error);
+            throw error;
+        }),
+        wait: () => settled,
+        fail,
+    };
+}
 function pageErrorLinesOf(session) {
     return session.browserConsoleBuffer.filter((line) => line.includes("PAGEERROR"));
 }
@@ -775,7 +798,8 @@ 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 gate = hooks?.verifyFirstSession && createFirstSessionGate(hooks.verifyFirstSession);
+    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation, gate)));
     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.d.ts

@@ -188,6 +188,8 @@ export interface VideoExtractionFailure {
      * can contain a local path or a signed source URL.
      */
     error: string;
+    /** ffmpeg's last stderr lines, without paths or URLs: what a producer-facing error may say. */
+    ffmpegReason?: string;
 }
 export type VideoExtractionFailureStatusClass = "http_4xx" | "http_5xx" | "timeout" | "network" | "other";
 export interface VideoExtractionFailureRetry {
@@ -211,8 +213,9 @@ export declare class VideoSourceExtractionError extends Error {
     readonly kind: VideoExtractionFailureKind;
     readonly retryable: boolean;
     readonly diagnostic: string;
+    readonly ffmpegReason?: string | undefined;
     readonly hyperframesVideoSourceExtractionError: true;
-    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string);
+    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string, ffmpegReason?: string | undefined);
 }
 export declare function isVideoSourceExtractionError(error: unknown): error is VideoSourceExtractionError;
 /**

package/dist/services/videoFrameExtractor.js

@@ -7,7 +7,7 @@
  */
 import { audioGroupsById, isMemberGroupHidden, isSelfOrAncestorHidden } from "./mediaHidden.js";
 import { copyFileSync, existsSync, linkSync, mkdirSync, rmSync } from "fs";
-import { join } from "path";
+import { basename, join } from "path";
 import { cpus } from "os";
 import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { parseHTML } from "linkedom";
@@ -208,15 +208,34 @@ export class VideoSourceExtractionError extends Error {
     kind;
     retryable;
     diagnostic;
+    ffmpegReason;
     hyperframesVideoSourceExtractionError = true;
-    constructor(kind, retryable, message, diagnostic = message) {
+    constructor(kind, retryable, message, diagnostic = message, ffmpegReason) {
         super(message);
         this.kind = kind;
         this.retryable = retryable;
         this.diagnostic = diagnostic;
+        this.ffmpegReason = ffmpegReason;
         this.name = "VideoSourceExtractionError";
     }
 }
+const FFMPEG_REASON_LINES = 3;
+const FFMPEG_REASON_CHARS = 300;
+/** ffmpeg's last stderr lines for an error that leaves this host: no local path, file name or URL. */
+function ffmpegReasonFrom(stderr, paths) {
+    let text = stderr;
+    for (const known of paths.filter(Boolean).sort((a, b) => b.length - a.length))
+        text = text.split(known).join("<path>");
+    return text
+        .replace(/[a-z][a-z\d+.-]*:\/\/[^\s'"]+/gi, "<url>")
+        .replace(/(?:[a-z]:)?(?:[\\/][^\s\\/:'"]+){2,}/gi, "<path>")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-FFMPEG_REASON_LINES)
+        .join(" | ")
+        .slice(-FFMPEG_REASON_CHARS);
+}
 export function isVideoSourceExtractionError(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -623,9 +642,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 +724,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 +735,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)}`);
     }
@@ -741,13 +764,18 @@ outputDirOverride) {
         const timeoutSuffix = timedOut ? ` (no new frame for ${ffmpegProcessTimeout} ms)` : "";
         const diagnostic = `${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ` +
             processResult.stderr.slice(-500);
+        const ffmpegReason = ffmpegReasonFrom(processResult.stderr, [
+            videoPath,
+            basename(videoPath),
+            videoOutputDir,
+        ]);
         if (timedOut) {
-            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic);
+            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic, ffmpegReason);
         }
         const transientIo = /resource temporarily unavailable|device or resource busy|input\/output error/i.test(processResult.stderr);
         throw new VideoSourceExtractionError(transientIo ? "ffmpeg_transient" : "ffmpeg_failed", transientIo, transientIo
             ? "Video frame extraction hit a transient I/O failure"
-            : "Video source could not be decoded", diagnostic);
+            : "Video source could not be decoded", diagnostic, ffmpegReason);
     }
     const framePaths = framePathsFromDirectory(videoOutputDir, format, !!options.frameRanges);
     if (framePaths.size === 0 && duration > 0) {
@@ -1219,13 +1247,9 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             resolvedVideos.push({ video, videoPath });
         }
         catch (err) {
-            const classified = classifyVideoExtractionError(err);
             errors.push({
-                videoId: video.id,
-                kind: classified.kind,
-                retryable: classified.retryable,
+                ...extractionError(video.id, err),
                 ...(err instanceof UrlDownloadError ? { group: downloadFailureGroup(video.src, err) } : {}),
-                error: classified.diagnostic,
             });
         }
     }
@@ -1413,6 +1437,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             kind: classified.kind,
             retryable: classified.retryable,
             error: classified.diagnostic,
+            ...(classified.ffmpegReason ? { ffmpegReason: classified.ffmpegReason } : {}),
         };
     }
     function scopedExtractionOptions(work) {
@@ -1771,12 +1796,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                 ? `[shared extraction, leader ${outcome.error.videoId}] ${outcome.error.error}`
                 : outcome.error.error;
             results.push({
-                error: {
-                    videoId: prepared.work.video.id,
-                    kind: outcome.error.kind,
-                    retryable: outcome.error.retryable,
-                    error: message,
-                },
+                error: { ...outcome.error, videoId: prepared.work.video.id, error: message },
             });
             continue;
         }

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.208",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -27,6 +27,10 @@
       "import": "./dist/services/chromeHostCeiling.js",
       "types": "./dist/services/chromeHostCeiling.d.ts"
     },
+    "./chrome-startup": {
+      "import": "./dist/services/chromeStartup.js",
+      "types": "./dist/services/chromeStartup.d.ts"
+    },
     "./system-memory": {
       "import": "./dist/services/systemMemory.js",
       "types": "./dist/services/systemMemory.d.ts"
@@ -50,8 +54,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.208",
+    "@hyperframes/parsers": "^0.8.208"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",