@hyperframes/engine 0.8.210 → 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, 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 { 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, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, 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/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

@@ -72,7 +72,7 @@ export declare function isProresProfile(value: unknown): value is ProresProfile;
 export declare function getEncoderPreset(quality: "draft" | "standard" | "high", format?: "mp4" | "webm" | "mov", hdr?: {
     transfer: HdrTransfer;
 }, proresProfile?: ProresProfile): EncoderPreset;
-export { detectGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
+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

@@ -103,7 +103,7 @@ export function getEncoderPreset(quality, format = "mp4", hdr, proresProfile = "
     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

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/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.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));

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.210",
+  "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/core": "^0.8.210",
-    "@hyperframes/parsers": "^0.8.210"
+    "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",