@hyperframes/engine 0.8.199 → 0.8.201

package/dist/config.d.ts

@@ -163,9 +163,9 @@ export interface EngineConfig {
      * renders stream. Env: PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED.
      */
     streamingEncodeDurationCapEnabled: boolean;
-    /** Timeout for FFmpeg frame encoding (ms). Default: 600_000 */
+    /** How long a disk-frame encode may go without a new frame before it is stopped (ms). Default: 600_000 */
     ffmpegEncodeTimeout: number;
-    /** FFmpeg mux/faststart timeout (ms); extraction waits this long for each new frame. Default: 300_000 */
+    /** How long any other FFmpeg step (audio, mux, extraction) may go without progress (ms). Default: 300_000 */
     ffmpegProcessTimeout: number;
     /**
      * Inactivity timeout for FFmpeg streaming encode (ms). The timer resets on

package/dist/index.d.ts

@@ -42,11 +42,12 @@ export { createCaptureSession, initializeSession, closeCaptureSession, captureFr
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type CaptureFailureKind, type CaptureWorkerDiagnostic, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
-export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.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 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, } from "./services/videoFrameExtractor.js";
+export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/index.js

@@ -45,12 +45,13 @@ export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
-export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, } from "./services/screenshotService.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 { 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, } from "./services/videoFrameExtractor.js";
+export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/services/audioMixer.js

@@ -339,7 +339,7 @@ function ffmpegFailure(stage, result, timeoutMs, elementId) {
         reason = "cancelled";
         owner = "user";
     }
-    else if (result.terminationReason === "deadline" || result.terminationReason === "inactivity") {
+    else if (result.terminationReason === "inactivity") {
         reason = "ffmpeg_timeout";
         retryable = true;
     }
@@ -692,14 +692,8 @@ async function generateSilence(outputPath, duration, signal, config) {
         failure,
     };
 }
-/** A mix graph's work grows with the film length (about 11 ms per film second at 96 inputs); so does its deadline. */
-const MIX_TIMEOUT_MS_PER_FILM_SECOND = 100;
-function mixProcessTimeout(config, totalDuration) {
-    const configured = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
-    return Math.max(configured, Math.ceil(totalDuration * MIX_TIMEOUT_MS_PER_FILM_SECOND));
-}
 async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, config) {
-    const ffmpegProcessTimeout = mixProcessTimeout(config, totalDuration);
+    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;
     if (tracks.length === 0) {
         const result = await generateSilence(outputPath, totalDuration, signal, config);
@@ -876,7 +870,7 @@ function groupNormalizeOptionUnsupported(stderr) {
  * only runs when this ffmpeg build's `amix` rejects the option.
  */
 async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, signal, config) {
-    const ffmpegProcessTimeout = mixProcessTimeout(config, totalDuration);
+    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });

package/dist/services/browserManager.d.ts

@@ -124,13 +124,13 @@ export declare function usesSoftwareWebGpu(requiresWebGpu: boolean | undefined,
 export declare function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuConfig): string[];
 /** Does the root, or a mounted root (data-hf-inner-root once bundled), declare `data-requires-webgpu`? */
 export declare function compositionRequiresWebGpu(html: string): boolean;
-/** No hardware WebGPU adapter on this host; distinct from a browser or navigation failure. */
+/** No usable WebGPU device on this launch; distinct from a browser or navigation failure. */
 export declare class WebGpuUnavailableError extends Error {
     constructor();
 }
 /**
- * Confirms the already-navigated page can obtain a hardware WebGPU adapter, or any adapter when the launch runs
- * software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
+ * Confirms the already-navigated page can create a device on a hardware WebGPU adapter, or any adapter when
+ * the launch runs software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
  * `page` must be on a secure-context origin, or navigator.gpu always reads absent.
  */
 export declare function assertWebGpuAdapterAvailable(page: Page, requiresWebGpu: boolean, softwareWebGpu?: boolean): Promise<void>;

package/dist/services/browserManager.js

@@ -666,7 +666,7 @@ async function launchBrowser(fingerprint) {
         });
         const browserVersion = await browser.version().catch(() => "unknown");
         const gpuFlags = fingerprint.args.filter((a) => a.startsWith("--use-gl=") || a.startsWith("--use-angle="));
-        console.log(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!fingerprint.executablePath}, platform=${process.platform})`);
+        console.error(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!fingerprint.executablePath}, platform=${process.platform})`);
         if (captureMode === "beginframe") {
             const probe = await probeBeginFrameSupport(browser).catch((error) => ({
                 supported: true,
@@ -909,43 +909,63 @@ export function compositionRequiresWebGpu(html) {
     }
     return false;
 }
-/** No hardware WebGPU adapter on this host; distinct from a browser or navigation failure. */
+/** No usable WebGPU device on this launch; distinct from a browser or navigation failure. */
 export class WebGpuUnavailableError extends Error {
     constructor() {
-        super("This composition declares data-requires-webgpu, but no hardware WebGPU adapter could be " +
-            "obtained on this browser launch. Run on a host with a GPU, set " +
+        super("This composition declares data-requires-webgpu, but a usable WebGPU device could not be " +
+            "created on this browser launch. Run on a host with a GPU, set " +
             "PRODUCER_ALLOW_SOFTWARE_WEBGPU=true to render it on SwiftShader (slow), or remove " +
             "data-requires-webgpu.");
         this.name = "WebGpuUnavailableError";
     }
 }
-const WEBGPU_ADAPTER_PROBE_TIMEOUT_MS = 10_000;
+const WEBGPU_DEVICE_PROBE_TIMEOUT_MS = 10_000;
 /**
- * Confirms the already-navigated page can obtain a hardware WebGPU adapter, or any adapter when the launch runs
- * software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
+ * Confirms the already-navigated page can create a device on a hardware WebGPU adapter, or any adapter when
+ * the launch runs software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
  * `page` must be on a secure-context origin, or navigator.gpu always reads absent.
  */
 export async function assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu = false) {
     if (!requiresWebGpu)
         return;
-    // requestAdapter() has no native timeout; a broken driver can hang it
-    // indefinitely. Race it in-page so a stuck adapter reads as "unavailable"
-    // instead of hanging the caller.
-    const hasUsableAdapter = await page.evaluate(async (timeoutMs, acceptFallback) => {
+    // An adapter can exist even when missing driver libraries make device creation fail.
+    // Both requests can hang; share one deadline and release late devices as well.
+    const hasUsableDevice = await page.evaluate(async (timeoutMs, acceptFallback) => {
         if (typeof navigator === "undefined" || !navigator.gpu)
             return false;
+        let expired = false;
+        let timer;
         try {
-            const adapter = await Promise.race([
-                navigator.gpu.requestAdapter(),
-                new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs)),
+            const probe = async () => {
+                const adapter = await navigator.gpu.requestAdapter();
+                if (!adapter || expired || (!acceptFallback && adapter.info.isFallbackAdapter))
+                    return false;
+                const device = await adapter.requestDevice();
+                try {
+                    return !expired;
+                }
+                finally {
+                    device.destroy();
+                }
+            };
+            return await Promise.race([
+                probe(),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        expired = true;
+                        resolve(false);
+                    }, timeoutMs);
+                }),
             ]);
-            return !!adapter && (acceptFallback || !adapter.info.isFallbackAdapter);
         }
         catch {
             return false;
         }
-    }, WEBGPU_ADAPTER_PROBE_TIMEOUT_MS, softwareWebGpu);
-    if (!hasUsableAdapter)
+        finally {
+            clearTimeout(timer);
+        }
+    }, WEBGPU_DEVICE_PROBE_TIMEOUT_MS, softwareWebGpu);
+    if (!hasUsableDevice)
         throw new WebGpuUnavailableError();
 }
 function getBrowserGpuArgs(mode, platform) {

package/dist/services/chunkEncoder.js

@@ -27,15 +27,9 @@ export const ENCODER_PRESETS = {
 function appendEncodeTimeoutMessage(error, timedOut, timeoutMs) {
     if (!timedOut)
         return error;
-    // Two independent reports of this exact timeout, both resolved by env vars
-    // that already exist but aren't named anywhere the user would see them at
-    // the point of failure — they had to go find FFMPEG_ENCODE_TIMEOUT_MS and
-    // PRODUCER_ENABLE_CHUNKED_ENCODE themselves. Name both here instead of
-    // just stating what happened.
-    return (`${error}\nFFmpeg killed after exceeding ffmpegEncodeTimeout (${timeoutMs} ms). ` +
-        "Long or high-frame-count renders may need more time: set FFMPEG_ENCODE_TIMEOUT_MS " +
-        "to a higher value (ms), or set PRODUCER_ENABLE_CHUNKED_ENCODE=true to encode in " +
-        "smaller chunks instead of one long-running ffmpeg process.");
+    return (`${error}\nFFmpeg killed after writing no new frame for ffmpegEncodeTimeout (${timeoutMs} ms). ` +
+        "An encode that is still writing frames is never stopped; if this encoder legitimately " +
+        "pauses longer between frames, raise FFMPEG_ENCODE_TIMEOUT_MS (ms).");
 }
 function isAacSidecar(audioPath) {
     return extname(audioPath).toLowerCase() === ".aac";
@@ -430,7 +424,7 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
             framesEncoded: 0,
             fileSize: 0,
             error: appendEncodeTimeoutMessage(frameReadFailure(result.stderr, framePattern, 0, framesRead, frameCount) +
-                formatFfmpegError(result.exitCode, result.stderr), result.terminationReason === "deadline", encodeTimeout),
+                formatFfmpegError(result.exitCode, result.stderr), result.terminationReason === "inactivity", encodeTimeout),
             failureReason: isExternalFfmpegInterruption(result) ? "external_interruption" : undefined,
         };
     }
@@ -492,7 +486,7 @@ export async function concatVideoFiles(inputPaths, outputPath, signal, config) {
         return { success: true };
     return {
         success: false,
-        error: appendEncodeTimeoutMessage(`Chunk concat failed: ${result.stderr.slice(-400)}`, result.terminationReason === "deadline", encodeTimeout),
+        error: appendEncodeTimeoutMessage(`Chunk concat failed: ${result.stderr.slice(-400)}`, result.terminationReason === "inactivity", encodeTimeout),
         externalInterruption: isExternalFfmpegInterruption(result),
     };
 }
@@ -566,7 +560,7 @@ export async function encodeFramesChunkedConcat(framesDir, framePattern, outputP
             success: processResult.success,
             error: processResult.success
                 ? undefined
-                : appendEncodeTimeoutMessage(frameReadFailure(processResult.stderr, framePattern, startNumber, framesRead, framesInChunk) + `Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`, processResult.terminationReason === "deadline", encodeTimeout),
+                : appendEncodeTimeoutMessage(frameReadFailure(processResult.stderr, framePattern, startNumber, framesRead, framesInChunk) + `Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`, processResult.terminationReason === "inactivity", encodeTimeout),
         };
         if (!chunkResult.success) {
             return {

package/dist/services/frameCapture.d.ts

@@ -19,7 +19,10 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
 /** Called after seeking, before screenshot. Use for video frame injection or other pre-capture work.
  * `heldVideoTime` (motion-blur samples only) is the output frame's time: a video on screen at
  * both times shows its frame for `heldVideoTime`, so footage does not smear. */
-export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;
+export type BeforeCaptureHook = ((page: Page, time: number, heldVideoTime?: number) => Promise<void>) & {
+    /** A hook with state of its own, for a second page; absent when the hook cannot be copied. */
+    fresh?: () => BeforeCaptureHook | null;
+};
 /** The per-frame wait a capture is in, worded for the stall error a user reads. */
 type CaptureStep = "seeking the timeline" | "decoding CSS background images" | "injecting video frames" | "waiting for page seek handlers" | "loading color-grading LUTs" | "compositing the page" | "capturing the frame";
 export interface CaptureSession {
@@ -161,6 +164,13 @@ export interface CaptureSession {
      * Empty/undefined when the predictor produces no frames.
      */
     clipBoundaryFrames?: Set<number>;
+    /**
+     * Frames drawElement cannot reproduce, for the caller to capture with a screenshot session.
+     * Set only when the caller can (worker-encode pipeline); drawElement capture throws on these.
+     */
+    deRiskFrames?: Set<number>;
+    /** The effects behind {@link deRiskFrames}, for the capture log. */
+    deRiskReason?: string;
     /** Rolling drawElement frame byte-sizes (last ~60), for silent-blank-drop detection:
      * drawElement intermittently returns an anomalously small (blank) frame with no
      * throw; a frame far below the running median is re-captured via screenshot. */