@hyperframes/engine 0.8.196 → 0.8.198

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool, closeBrowserPool, resolveHeadlessShellPath, resolveBrowserGpuMode, buildChromeArgs, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, WebGpuUnavailableError, ENABLE_BROWSER_POOL, BrowserLeasePool, type GpuProbeLifecycle, type BuildChromeArgsOptions, type BrowserLaunchFingerprint, type BrowserLease, type BrowserPoolState, type CaptureMode, type AcquiredBrowser, } from "./services/browserManager.js";
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type NavigationTimeoutHintContext, } from "./services/pageNavigationTimeoutErrorHint.js";
-export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, waitForImagesReady, } from "./services/frameCapture.js";
+export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 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";
@@ -46,7 +46,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 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, 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 { 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 { 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

@@ -40,7 +40,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, } from "./services/pageNavigationTimeoutErrorHint.js";
 // ── Frame capture pipeline ──────────────────────────────────────────────────────
-export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, } from "./services/frameCapture.js";
+export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
@@ -50,7 +50,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 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, 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 { 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 { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/services/frameCapture.d.ts

@@ -410,6 +410,7 @@ export interface HfDiagnostic {
     rejectedBuildReadyKeys: string[];
 }
 export declare function buildZeroDurationDiagnostic(diag: HfDiagnostic): string;
+export declare function evaluateHfDiagnostic(page: Page): Promise<HfDiagnostic>;
 export declare function pollHfReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<void>;
 export declare function waitForSubCompositionTimelines(session: CaptureSession, page: Page, timeoutMs: number, options?: {
     scriptErrorGraceMs?: number;

package/dist/services/frameCapture.js

@@ -1131,7 +1131,7 @@ export function buildZeroDurationDiagnostic(diag) {
         `data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` +
         (hints.length > 0 ? hints.map((h) => `  → ${h}`).join("\n") : ""));
 }
-async function evaluateHfDiagnostic(page) {
+export async function evaluateHfDiagnostic(page) {
     return (await page.evaluate(HF_READY_DIAGNOSTIC_EXPR));
 }
 export async function pollHfReady(page, timeoutMs, intervalMs = 100) {

package/dist/services/videoFrameExtractor.js

@@ -972,7 +972,7 @@ export function resolveVideoExtractionDuration(video, metadata, timelineEnd) {
 }
 /** Codecs whose bitstream can carry alpha: decoded with the alpha-aware decoder whether or not a tag says so. */
 const ALPHA_CAPABLE_CODECS = new Set(["vp9", "vp8", "prores"]);
-/** Their alpha rides a side channel ffprobe can miss, so frames stay PNG; ProRes alpha shows in its pixel format. */
+/** Alpha can hide from ffprobe: PNG unless a decoded frame had no alpha; ProRes alpha shows in pix_fmt. */
 const SIDECAR_ALPHA_CODECS = new Set(["vp9", "vp8"]);
 export function codecMayHaveAlpha(codec) {
     return ALPHA_CAPABLE_CODECS.has((codec ?? "").toLowerCase());
@@ -981,7 +981,8 @@ export function decoderForCodec(codec) {
     return alphaDecoderFor(codec) ?? (codec ?? "").toLowerCase();
 }
 export function resolveFrameFormat(metadata, requested) {
-    if (metadata.hasAlpha || SIDECAR_ALPHA_CODECS.has((metadata.videoCodec ?? "").toLowerCase()))
+    const sidecar = SIDECAR_ALPHA_CODECS.has((metadata.videoCodec ?? "").toLowerCase());
+    if (metadata.hasAlpha || (sidecar && metadata.alphaPlaneDecoded !== false))
         return "png";
     if (requested === "png" || requested === "jpg")
         return requested;

package/dist/utils/ffprobe.d.ts

@@ -29,6 +29,9 @@ export interface VideoMetadata {
     isVFR: boolean;
     /** True when the stream carries an alpha channel. */
     hasAlpha: boolean;
+    /** VP8/VP9 without an alpha tag: whether a frame decoded with the alpha-aware decoder had an alpha plane.
+     * Absent when not probed or the probe failed. */
+    alphaPlaneDecoded?: boolean;
     /** Color space info from the video stream. Null if ffprobe didn't report it. */
     colorSpace: VideoColorSpace | null;
     colorRange?: string;
@@ -155,6 +158,11 @@ export declare function readTagCI(tags: Record<string, string | undefined> | und
  *    smallest representable 2dp rate instead.
  */
 export declare function parseFrameRate(frameRateStr: string | undefined): number;
+/**
+ * Whether the first frame decoded with `decoder` (alpha-aware) has an alpha pixel format; undefined on any
+ * failure. ffprobe cannot pick a decoder, so ffmpeg writes the frame as rawvideo, which keeps its pix_fmt.
+ */
+export declare function probeDecodedAlphaPlane(filePath: string, decoder: string): Promise<boolean | undefined>;
 /**
  * Probe a media file (video, image, or container) and return normalized metadata.
  *

package/dist/utils/ffprobe.js

@@ -1,12 +1,14 @@
 // fallow-ignore-file code-duplication complexity
 import { spawn } from "child_process";
-import { createReadStream, readFileSync, statSync } from "fs";
+import { createReadStream, mkdtempSync, readFileSync, rmSync, statSync } from "fs";
 import { chunkCrc32 } from "./crc32.js";
 import { StringDecoder } from "node:string_decoder";
-import { basename } from "path";
+import { tmpdir } from "os";
+import { basename, join } from "path";
 import { redactTelemetryString } from "@hyperframes/core";
-import { videoStreamHasAlpha } from "@hyperframes/parsers/media-alpha";
+import { alphaDecoderFor, pixelFormatHasAlpha, videoStreamHasAlpha, } from "@hyperframes/parsers/media-alpha";
 import { urlInputArgs } from "./urlInput.js";
+import { runFfmpeg } from "./runFfmpeg.js";
 import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js";
 import { ManagedChildProcess } from "./managedChildProcess.js";
 import { trackChildProcess } from "./processTracker.js";
@@ -617,6 +619,54 @@ export function parseFrameRate(frameRateStr) {
     // caller's 30fps default.
     return rounded > 0 ? rounded : 0.01;
 }
+/**
+ * Whether the first frame decoded with `decoder` (alpha-aware) has an alpha pixel format; undefined on any
+ * failure. ffprobe cannot pick a decoder, so ffmpeg writes the frame as rawvideo, which keeps its pix_fmt.
+ */
+export async function probeDecodedAlphaPlane(filePath, decoder) {
+    let probeDir;
+    try {
+        probeDir = mkdtempSync(join(tmpdir(), "hf-decoded-alpha-"));
+        const framePath = join(probeDir, "frame.nut");
+        const decoded = await runFfmpeg([
+            "-v",
+            "error",
+            ...urlInputArgs(filePath),
+            "-c:v",
+            decoder,
+            "-i",
+            filePath,
+            "-frames:v",
+            "1",
+            "-vf",
+            "scale=8:8",
+            "-c:v",
+            "rawvideo",
+            "-f",
+            "nut",
+            framePath,
+        ], { timeout: 30_000 });
+        if (!decoded.success)
+            return undefined;
+        const stdout = await runFfprobe(framePath, [
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "stream=pix_fmt",
+            "-of",
+            "json",
+        ]);
+        const pixFmt = JSON.parse(stdout).streams?.[0]?.pix_fmt;
+        return pixFmt ? pixelFormatHasAlpha(pixFmt) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (probeDir)
+            rmSync(probeDir, { recursive: true, force: true });
+    }
+}
 /**
  * Probe a media file (video, image, or container) and return normalized metadata.
  *
@@ -697,6 +747,10 @@ export async function extractMediaMetadata(filePath) {
         const colorSpace = merged.colorTransfer || merged.colorPrimaries || merged.colorSpace ? merged : null;
         const pixelFormat = videoStream.pix_fmt || "";
         const hasAlpha = videoStreamHasAlpha(videoStream);
+        const alphaDecoder = hasAlpha ? null : alphaDecoderFor(videoStream.codec_name);
+        const alphaPlaneDecoded = alphaDecoder
+            ? await probeDecodedAlphaPlane(filePath, alphaDecoder)
+            : undefined;
         const containerDuration = output?.format.duration ? parseFloat(output.format.duration) : 0;
         const streamDuration = videoStream.duration ? parseFloat(videoStream.duration) : 0;
         const parsedStreamStart = videoStream.start_time ? parseFloat(videoStream.start_time) : 0;
@@ -739,6 +793,7 @@ export async function extractMediaMetadata(filePath) {
             hasAudio: output?.streams.some((s) => s.codec_type === "audio") ?? false,
             isVFR,
             hasAlpha,
+            ...(alphaPlaneDecoded === undefined ? {} : { alphaPlaneDecoded }),
             colorSpace,
             colorRange: videoStream.color_range,
             pixelFormat,

package/package.json

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