@hyperframes/engine 0.8.209 → 0.8.210

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, 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";

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, 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";

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

@@ -54,14 +54,24 @@ 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;
+}, proresProfile?: ProresProfile): EncoderPreset;
 export { detectGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
 /** The `lockGopForChunkConcat` / `gopSize` pair, shared by every encoder entry point. */
 export interface LockedGopOptions {

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 {
@@ -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/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/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

@@ -1084,6 +1084,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/package.json

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