@hyperframes/engine 0.8.209 → 0.8.211

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, appendRateCapArgs, keyframeIntervalToGopSize, 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, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, type ProresProfile, 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, type ParallelWorkerPhaseDiagnostic, } from "./services/parallelCoordinator.js";
+export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type WorkerSizingConfig, 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";
@@ -64,6 +64,7 @@ export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
 export type { PageMotionBlurOff } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
+export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.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, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
+export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, 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";
@@ -68,6 +68,7 @@ export { frameFileExtension } from "./services/frameCapture.js";
 export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js";
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
+export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";

package/dist/services/__fixtures__/loopback.js

@@ -7,12 +7,17 @@ export async function listenOnLoopback(server) {
         throw new Error("No test server address");
     return `http://127.0.0.1:${address.port}`;
 }
-export function launchTestChrome(executablePath) {
-    return puppeteer.launch({
+export async function launchTestChrome(executablePath) {
+    const startedAt = Date.now();
+    const browser = await puppeteer.launch({
         executablePath,
         headless: true,
         args: ["--no-sandbox", "--disable-dev-shm-usage"],
     });
+    const launchedAt = Date.now();
+    await (await browser.newPage()).close();
+    console.info(`[engine-test-chrome] launch ${launchedAt - startedAt} ms, first page ${Date.now() - launchedAt} ms`);
+    return browser;
 }
 /** Closes a test Chrome, killing it when close hangs (seen on Windows runners) so afterAll never times out. */
 export async function closeTestChrome(browser, timeoutMs = 5_000) {

package/dist/services/aacEncode.js

@@ -57,7 +57,7 @@ function supportsSettsDuration(binary = getFfmpegBinary()) {
     let supported = settsDurationSupport.get(binary);
     if (!supported) {
         supported = new Promise((resolve) => {
-            execFile(binary, ["-hide_banner", "-h", "bsf=setts"], (error, stdout) => {
+            execFile(binary, ["-hide_banner", "-h", "bsf=setts"], { windowsHide: true }, (error, stdout) => {
                 // A binary that cannot even print help fails the encode with its own error, not this one.
                 resolve(error !== null || stdout.includes("duration"));
             });

package/dist/services/chromeHostCeiling.js

@@ -57,8 +57,12 @@ export function shellStarts(binary, timeoutMs = 10_000) {
     if (answer === undefined) {
         const probe = ["--no-sandbox", "--dump-dom", "about:blank"];
         answer =
-            spawnSync(binary, probe, { stdio: "ignore", timeout: timeoutMs, killSignal: "SIGKILL" })
-                ?.status === 0;
+            spawnSync(binary, probe, {
+                stdio: "ignore",
+                timeout: timeoutMs,
+                killSignal: "SIGKILL",
+                windowsHide: true,
+            })?.status === 0;
         if (!answer)
             debug("skipping %s: it did not start", binary);
         starts.set(binary, answer);

package/dist/services/chunkEncoder.d.ts

@@ -54,15 +54,25 @@ export interface MuxVideoWithAudioOptions extends Partial<Pick<EngineConfig, "ff
      */
     preserveAudioPrimingEditList?: boolean;
 }
+/** ProRes profile names in the order users are told about them. */
+export declare const PRORES_PROFILE_NAMES: readonly ["4444", "hq", "422", "lt", "proxy"];
+export type ProresProfile = (typeof PRORES_PROFILE_NAMES)[number];
+/** The one table for `-profile:v` and pixel format; all but 4444 are 4:2:2 without alpha. */
+export declare const PRORES_PROFILES: Record<ProresProfile, {
+    profile: string;
+    pixelFormat: string;
+    alpha: boolean;
+}>;
+export declare function isProresProfile(value: unknown): value is ProresProfile;
 /**
  * Get encoder preset for a given quality and output format.
  * WebM uses VP9 with alpha-capable pixel format; MP4 uses h264 (or h265 for HDR);
- * MOV uses ProRes 4444 with alpha for editor-compatible transparency.
+ * MOV uses ProRes 4444 with alpha for editor-compatible transparency, or a 422 profile without alpha.
  */
 export declare function getEncoderPreset(quality: "draft" | "standard" | "high", format?: "mp4" | "webm" | "mov", hdr?: {
     transfer: HdrTransfer;
-}): EncoderPreset;
-export { detectGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
+}, proresProfile?: ProresProfile): EncoderPreset;
+export { detectGpuEncoder, getCachedGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
 /** The `lockGopForChunkConcat` / `gopSize` pair, shared by every encoder entry point. */
 export interface LockedGopOptions {
     lockGopForChunkConcat?: boolean;

package/dist/services/chunkEncoder.js

@@ -59,12 +59,25 @@ async function shouldCopyAacSidecar(audioPath, options) {
         return false;
     }
 }
+/** ProRes profile names in the order users are told about them. */
+export const PRORES_PROFILE_NAMES = ["4444", "hq", "422", "lt", "proxy"];
+/** The one table for `-profile:v` and pixel format; all but 4444 are 4:2:2 without alpha. */
+export const PRORES_PROFILES = {
+    "4444": { profile: "4444", pixelFormat: "yuva444p10le", alpha: true },
+    hq: { profile: "3", pixelFormat: "yuv422p10le", alpha: false },
+    "422": { profile: "2", pixelFormat: "yuv422p10le", alpha: false },
+    lt: { profile: "1", pixelFormat: "yuv422p10le", alpha: false },
+    proxy: { profile: "0", pixelFormat: "yuv422p10le", alpha: false },
+};
+export function isProresProfile(value) {
+    return typeof value === "string" && PRORES_PROFILE_NAMES.includes(value);
+}
 /**
  * Get encoder preset for a given quality and output format.
  * WebM uses VP9 with alpha-capable pixel format; MP4 uses h264 (or h265 for HDR);
- * MOV uses ProRes 4444 with alpha for editor-compatible transparency.
+ * MOV uses ProRes 4444 with alpha for editor-compatible transparency, or a 422 profile without alpha.
  */
-export function getEncoderPreset(quality, format = "mp4", hdr) {
+export function getEncoderPreset(quality, format = "mp4", hdr, proresProfile = "4444") {
     const base = ENCODER_PRESETS[quality];
     if (format === "webm") {
         return {
@@ -75,12 +88,8 @@ export function getEncoderPreset(quality, format = "mp4", hdr) {
         };
     }
     if (format === "mov") {
-        return {
-            preset: "4444",
-            quality: base.quality,
-            codec: "prores",
-            pixelFormat: "yuva444p10le",
-        };
+        const { profile, pixelFormat } = PRORES_PROFILES[proresProfile];
+        return { preset: profile, quality: base.quality, codec: "prores", pixelFormat };
     }
     if (hdr) {
         return {
@@ -94,7 +103,7 @@ export function getEncoderPreset(quality, format = "mp4", hdr) {
     return { ...base, pixelFormat: "yuv420p" };
 }
 // Re-export GPU utilities so existing consumers that import from chunkEncoder still work.
-export { detectGpuEncoder } from "../utils/gpuEncoder.js";
+export { detectGpuEncoder, getCachedGpuEncoder } from "../utils/gpuEncoder.js";
 /**
  * Integer GOP length, or `null` when no lock was requested. Throws on a lock
  * with an invalid size — a silent fallback ships open-GOP output that only
@@ -635,8 +644,9 @@ export async function muxVideoWithAudio(videoPath, audioPath, outputPath, signal
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
-    const isWebm = outputPath.endsWith(".webm");
-    const isMov = outputPath.endsWith(".mov");
+    const outputExtension = extname(outputPath).toLowerCase();
+    const isWebm = outputExtension === ".webm";
+    const isMov = outputExtension === ".mov";
     const shouldCopyAudio = isWebm ? false : await shouldCopyAacSidecar(audioPath, config);
     const args = [...(config?.videoInputArgs ?? ["-i", videoPath]), "-i", audioPath, "-c:v", "copy"];
     if (isWebm) {

package/dist/services/parallelCoordinator.d.ts

@@ -83,6 +83,8 @@ export interface WorkerSizingConfig extends Partial<Pick<EngineConfig, "concurre
      * than a plain DOM screenshot. Explicit --workers requests ignore this hint.
      */
     captureCostMultiplier?: number;
+    /** macOS, hardware GPU, screenshot frames written to disk (not streamed through this process). */
+    appleGpuDiskCapture?: boolean;
 }
 type WorkerBrowserPoolDecision = {
     parallel?: boolean;

package/dist/services/parallelCoordinator.js

@@ -32,6 +32,10 @@ const HEAP_RESERVED_MB = 1024;
 // default heap ⇒ >~500MB/worker + base. Caps auto sizing; an explicit
 // `--workers N` is still the operator's call.
 const HEAP_PER_WORKER_MB = 640;
+// Apple-GPU disk capture measured ~15-25 MB parent heap per worker; 14 cores kept gaining to 8.
+const APPLE_DISK_HEAP_PER_WORKER_MB = 128;
+const APPLE_DISK_CORES_PER_WORKER = 1.75;
+const APPLE_DISK_MAX_WORKERS = 8;
 const MIN_WORKERS = 1;
 const MAX_WORKER_DIAGNOSTIC_LINES = 8;
 // Hard ceiling on explicit `--workers N` requests. Above this, the cost of
@@ -133,7 +137,9 @@ export function computeWorkerSizing(totalFrames, requested, config) {
     // is immediately reclaimable.
     const totalMemoryMb = getSystemTotalMb();
     const heapLimitMb = Math.round(getHeapStatistics().heap_size_limit / (1024 * 1024));
-    const heapBasedWorkers = Math.max(1, Math.floor((heapLimitMb - HEAP_RESERVED_MB) / HEAP_PER_WORKER_MB));
+    const appleDisk = config?.appleGpuDiskCapture === true;
+    const heapBasedWorkers = Math.max(1, Math.floor((heapLimitMb - HEAP_RESERVED_MB) /
+        (appleDisk ? APPLE_DISK_HEAP_PER_WORKER_MB : HEAP_PER_WORKER_MB)));
     const cpuBasedWorkers = Math.max(1, cpuCount - 2);
     const memoryBasedWorkers = Math.max(1, Math.floor((totalMemoryMb * 0.5) / MEMORY_PER_WORKER_MB));
     const frameBasedWorkers = Math.floor(totalFrames / MIN_FRAMES_PER_WORKER);
@@ -164,9 +170,14 @@ export function computeWorkerSizing(totalFrames, requested, config) {
         if (concurrency !== "auto") {
             return Math.max(MIN_WORKERS, Math.min(ABSOLUTE_MAX_WORKERS, Math.floor(concurrency)));
         }
-        return defaultSafeMaxWorkers();
+        return appleDisk
+            ? Math.max(defaultSafeMaxWorkers(), APPLE_DISK_MAX_WORKERS)
+            : defaultSafeMaxWorkers();
     })();
-    const effectiveCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
+    const configuredCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
+    const effectiveCoresPerWorker = appleDisk && configuredCoresPerWorker === DEFAULT_CONFIG.coresPerWorker
+        ? APPLE_DISK_CORES_PER_WORKER
+        : configuredCoresPerWorker;
     const effectiveMinParallelFrames = config?.minParallelFrames ?? DEFAULT_CONFIG.minParallelFrames;
     const effectiveLargeRenderThreshold = config?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
     if (totalFrames < MIN_FRAMES_PER_WORKER * 2) {

package/dist/services/videoFrameExtractor.js

@@ -17,7 +17,7 @@ import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
 import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, writeMetadataCache, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -508,6 +508,22 @@ export function sdrCanvasColourFilters(metadata, toneMappedToSdr = false) {
  * frames are byte-identical to it.
  */
 const EXTRACTION_SEGMENT_SECONDS = 120;
+/** Slowest decode rate the stall clock allows while ffmpeg discards frames from a keyframe up to the seek point. */
+const SKIP_DECODE_FPS_FLOOR = 30;
+async function leadInSecondsUnlessAborted(videoPath, seek, signal) {
+    try {
+        return await keyframeGapSeconds(videoPath, seek, signal);
+    }
+    catch (error) {
+        // Aborted: let runFfmpeg report the abort, so a segment stopped by another's failure reads as stopped.
+        if (signal?.aborted)
+            return 0;
+        throw error;
+    }
+}
+function stallTimeoutMs(baseMs, skippedSeconds, sourceFps) {
+    return baseMs + Math.ceil((skippedSeconds * sourceFps * 1000) / SKIP_DECODE_FPS_FLOOR);
+}
 /** Frame times since file start are `PTS*TB + seek`; snapping them to `lead + k/FR` gives every process one grid. */
 function undoTickRoundingOnTheSourceFrameGrid(seek, lead) {
     const sinceFileStart = `(PTS*TB+${seek}-${lead})`;
@@ -535,7 +551,7 @@ function splitFrameRanges(ranges, segmentFrames) {
     return segments;
 }
 async function runSegmentedExtraction(job) {
-    const { decodeArgs, filterAndEncodeArgs, videoPath, startTime, fps, segments, gate } = job;
+    const { decodeArgs, filterAndEncodeArgs, videoPath, startTime, fps, sourceFps, segments, gate } = job;
     const segmentCount = segments.length;
     // One failed segment fails the range, so stop the others instead of finishing them.
     const failed = new AbortController();
@@ -549,7 +565,7 @@ async function runSegmentedExtraction(job) {
             const index = next++;
             const { firstFrame, frames } = segments[index];
             const seek = startTime + firstFrame / fps;
-            const result = await gate(() => runFfmpeg([
+            const result = await gate(async () => runFfmpeg([
                 ...decodeArgs,
                 "-noaccurate_seek",
                 "-ss",
@@ -564,14 +580,21 @@ async function runSegmentedExtraction(job) {
                 "-start_number",
                 String(firstFrame + 1),
                 ...filterAndEncodeArgs(seek),
-            ], { ...job.runOptions, signal }), signal);
+            ], {
+                ...job.runOptions,
+                signal,
+                timeout: stallTimeoutMs(job.runOptions.timeout, await leadInSecondsUnlessAborted(videoPath, seek, signal), sourceFps),
+            }), signal);
             results[index] = result;
             if (!result.success)
                 failed.abort();
         }
     };
     const workers = Math.min(segmentCount, EXTRACTION_SLOTS);
-    await Promise.all(Array.from({ length: workers }, worker));
+    await Promise.all(Array.from({ length: workers }, worker)).catch((error) => {
+        failed.abort();
+        throw error;
+    });
     const ran = results.filter(Boolean);
     // Report the segment that failed, not the ones stopped because of it.
     const failure = ran.find((r) => !r.success && r.terminationReason !== "abort") ?? ran.find((r) => !r.success);
@@ -731,11 +754,17 @@ outputDirOverride) {
             videoPath,
             startTime,
             fps,
+            sourceFps: metadata.fps,
             gate: options.tailProbe ? inTailProbeSlot : inExtractionSlot,
             segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
             runOptions,
         })
-        : inExtractionSlot(() => runFfmpeg([...hwaccel, ...args, ...filterArgsFor(startTime), ...encodeArgs], runOptions), signal);
+        : inExtractionSlot(async () => runFfmpeg([...hwaccel, ...args, ...filterArgsFor(startTime), ...encodeArgs], {
+            ...runOptions,
+            timeout: stallTimeoutMs(ffmpegProcessTimeout, options.finalFrameOnly
+                ? startTime
+                : await leadInSecondsUnlessAborted(videoPath, startTime, signal), metadata.fps),
+        }), signal);
     let processResult = await extract(decodeWithVideoToolbox ? ["-hwaccel", "videotoolbox"] : []);
     const ffmpegExitedFailing = processResult.terminationReason === "exit" &&
         !processResult.success &&
@@ -1349,7 +1378,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
     // Phase 3 still calls `extractVideoFramesRange` on the same past-EOF
     // mediaStart, surfacing a second raw FFmpeg error for the same clip.
     const hdrSkippedIndices = new Set();
-    if (hdrInfo.hasHdr && hdrInfo.dominantTransfer) {
+    if (!options.toneMapHdrToSdr && hdrInfo.hasHdr && hdrInfo.dominantTransfer) {
         // dominantTransfer is "majority wins" — if a composition mixes PQ and HLG
         // sources (rare but legal), the minority transfer's videos get converted
         // with the wrong curve. We treat this as caller-error: a single composition

package/dist/utils/browserSafePort.d.ts

@@ -0,0 +1,8 @@
+import type { Server } from "node:net";
+export declare const isBrowserSafePort: (port: number) => boolean;
+type Bindable = Pick<Server, "address" | "close" | "listen" | "once" | "off">;
+/** Rebinds an already-listening server until the OS hands it a port a browser will load from. */
+export declare function settleOnBrowserSafePort(server: Bindable, host: string): Promise<number>;
+/** `server.listen(0, host)` that never lands on a port Chromium blocks; resolves to the bound port. */
+export declare function listenOnBrowserSafePort(server: Bindable, host: string): Promise<number>;
+export {};

package/dist/utils/browserSafePort.js

@@ -0,0 +1,38 @@
+// Chromium refuses to load from these ports (net::ERR_UNSAFE_PORT); net/base/port_util.cc kRestrictedPorts.
+const RESTRICTED_PORTS = new Set([
+    1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
+    103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465,
+    512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993,
+    995, 1719, 1720, 1723, 2049, 3659, 4045, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669,
+    6697, 10080,
+]);
+const MAX_ATTEMPTS = 32;
+export const isBrowserSafePort = (port) => !RESTRICTED_PORTS.has(port);
+function listenOnce(server, host) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, host, () => {
+            server.off("error", reject);
+            resolve(server.address().port);
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+/** Rebinds an already-listening server until the OS hands it a port a browser will load from. */
+export async function settleOnBrowserSafePort(server, host) {
+    let port = server.address().port;
+    for (let attempt = 1; !isBrowserSafePort(port); attempt++) {
+        if (attempt >= MAX_ATTEMPTS)
+            throw new Error(`The OS kept offering browser-restricted ports (last: ${port}).`);
+        await closeServer(server);
+        port = await listenOnce(server, host);
+    }
+    return port;
+}
+/** `server.listen(0, host)` that never lands on a port Chromium blocks; resolves to the bound port. */
+export async function listenOnBrowserSafePort(server, host) {
+    await listenOnce(server, host);
+    return settleOnBrowserSafePort(server, host);
+}

package/dist/utils/ffprobe.d.ts

@@ -219,4 +219,6 @@ export interface KeyframeAnalysis {
  * Pass the stream's own duration/start (not the container's), which can overstate a single-keyframe GOP.
  */
 export declare function analyzeKeyframeIntervals(filePath: string, metadata: Pick<VideoMetadata, "videoStreamDurationSeconds" | "videoStreamStartSeconds">): Promise<KeyframeAnalysis>;
+/** Seconds ffmpeg decodes without output after a seek to `seekSeconds`: back to the keyframe it lands on. */
+export declare function keyframeGapSeconds(filePath: string, seekSeconds: number, signal?: AbortSignal): Promise<number>;
 export {};

package/dist/utils/ffprobe.js

@@ -296,7 +296,10 @@ function ffprobeMajor() {
     runtimeFfprobeMajor ??= new Promise((resolve) => {
         let out = "";
         const binary = getFfprobeBinary();
-        const proc = spawn(binary, ["-version"], { stdio: ["ignore", "pipe", "ignore"] });
+        const proc = spawn(binary, ["-version"], {
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        });
         proc.stdout.on("data", (chunk) => (out += String(chunk)));
         proc.on("error", () => resolve(undefined));
         proc.on("close", () => resolve(Number(/version n?(\d+)/.exec(out)?.[1]) || undefined));
@@ -1084,6 +1087,15 @@ export async function analyzeKeyframeIntervals(filePath, metadata) {
     });
     return promise;
 }
+/** Seconds ffmpeg decodes without output after a seek to `seekSeconds`: back to the keyframe it lands on. */
+export async function keyframeGapSeconds(filePath, seekSeconds, signal) {
+    const stdout = await runFfprobe(filePath, [
+        ...["-select_streams", "v:0", "-show_entries", "packet=pts_time", "-of", "csv=p=0"],
+        ...["-read_intervals", `${seekSeconds}%+#1`],
+    ], signal);
+    const keyframe = parseFloat(stdout.split("\n")[0] ?? "");
+    return Number.isFinite(keyframe) ? Math.max(0, seekSeconds - keyframe) : 0;
+}
 async function analyzeKeyframeIntervalsUncached(filePath, videoStreamStartSeconds, videoStreamDurationSeconds) {
     const stdout = await runFfprobe(filePath, [
         "-select_streams",

package/dist/utils/gpuEncoder.d.ts

@@ -10,6 +10,7 @@ export declare function getCompiledGpuEncoders(ffmpegEncodersStdout: string): Co
 export declare function selectUsableGpuEncoder(candidates: readonly ConcreteGpuEncoder[], isUsable: (encoder: ConcreteGpuEncoder) => Promise<boolean>): Promise<GpuEncoder>;
 export declare function detectGpuEncoder(): Promise<GpuEncoder>;
 export declare function getCachedGpuEncoder(): Promise<GpuEncoder>;
+export declare function resetCachedGpuEncoder(): void;
 export declare function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"): string;
 export declare function buildVideoToolboxRateControlArgs(input: {
     bitrate?: string;

package/dist/utils/gpuEncoder.js

@@ -64,12 +64,13 @@ export async function detectGpuEncoder() {
     return selectUsableGpuEncoder(candidates, canUseGpuEncoder).catch(() => null);
 }
 let cachedGpuEncoder = undefined;
-export async function getCachedGpuEncoder() {
-    if (cachedGpuEncoder === undefined) {
-        cachedGpuEncoder = await detectGpuEncoder();
-    }
+export function getCachedGpuEncoder() {
+    cachedGpuEncoder ??= detectGpuEncoder();
     return cachedGpuEncoder;
 }
+export function resetCachedGpuEncoder() {
+    cachedGpuEncoder = undefined;
+}
 export function getGpuEncoderName(encoder, codec) {
     if (!encoder)
         return codec === "h264" ? "libx264" : "libx265";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.209",
+  "version": "0.8.211",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -52,10 +52,10 @@
     "@hono/node-server": "^2.0.5",
     "hono": "^4.6.0",
     "linkedom": "^0.18.12",
-    "puppeteer": "^25.8.0",
-    "puppeteer-core": "^25.8.0",
-    "@hyperframes/parsers": "^0.8.209",
-    "@hyperframes/core": "^0.8.209"
+    "puppeteer": "~25.11.0",
+    "puppeteer-core": "^25.11.0",
+    "@hyperframes/parsers": "^0.8.211",
+    "@hyperframes/core": "^0.8.211"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",