@hyperframes/engine 0.8.208 → 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";
@@ -73,8 +73,8 @@ export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
-export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
-export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
+export { renameWithRetry, renameWithRetryAsync } from "@hyperframes/core/rename-retry";
+export { removeScratch, collectScratchLeftovers } from "@hyperframes/core/remove-scratch";
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
 export { decodePng, decodePngToRgb48le, blitRgba8OverRgb48le, blitRgb48leRegion, blitRgb48leAffine, parseTransformMatrix, roundedRectAlpha, resampleRgb48leObjectFit, normalizeObjectFit, type ObjectFit, } from "./utils/alphaBlit.js";
 export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";
@@ -87,3 +87,4 @@ export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompo
 export type { VideoColorSpace } from "./utils/ffprobe.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, type RenderProvenance, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";
+export { inAgentSandbox, isOneProcessOverPipe, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./services/sandboxLaunch.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";
@@ -77,8 +77,8 @@ export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
-export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
-export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
+export { renameWithRetry, renameWithRetryAsync } from "@hyperframes/core/rename-retry";
+export { removeScratch, collectScratchLeftovers } from "@hyperframes/core/remove-scratch";
 // drawElement self-verify comparison — shared by the streaming drain
 // (producer) and the parallel disk-path verify (parallelCoordinator).
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
@@ -93,3 +93,4 @@ export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryEle
 export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompositionHdr, findHdrAutoPromotion, formatHdrAutoPromotionWarning, sanitizeHdrAutoPromotionAsset, DEFAULT_HDR10_MASTERING, HDR_AUTO_PROMOTION_PIPELINE, } from "./utils/hdr.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";
+export { inAgentSandbox, isOneProcessOverPipe, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./services/sandboxLaunch.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

@@ -4,7 +4,7 @@
  */
 import { execFile } from "node:child_process";
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { removeScratch } from "../utils/removeScratch.js";
+import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { dirname, join } from "node:path";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";

package/dist/services/audioFxRender.js

@@ -18,8 +18,8 @@ import { pathToFileURL } from "node:url";
 import { getAudioFxRuntimeScript } from "@hyperframes/core/audio-fx-runtime";
 import { enabledAudioFxNodes } from "@hyperframes/core/audio-fx";
 import { serializeAutomation } from "@hyperframes/core/audio-automation";
-import { removeScratch } from "../utils/removeScratch.js";
-import { acquireBrowser } from "./browserManager.js";
+import { removeScratch } from "@hyperframes/core/remove-scratch";
+import { acquireBrowser, buildChromeArgs } from "./browserManager.js";
 import { createEnvelopeWalker } from "./audioVolumeEnvelope.js";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
 import { windowPrerollSeconds } from "./audioFxWarmup.js";
@@ -439,6 +439,9 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
         }
     });
 }
+/** Audio processing needs no GPU, so software mode; every other launch detail is the shared one. */
+let fxBrowserArgs;
+const fxChromeArgs = () => (fxBrowserArgs ??= buildChromeArgs({ width: 1280, height: 720, captureMode: "screenshot" }, { browserGpuMode: "software" }));
 /** Run `body` with a leased browser and a way to open pages on the runtime; both are released in the same try that takes them. */
 async function withFxBrowser(options, body) {
     const hostDir = mkdtempSync(join(tmpdir(), "hf-fx-host-"));
@@ -451,7 +454,7 @@ async function withFxBrowser(options, body) {
         if (options.signal?.aborted) {
             throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
         }
-        lease = await acquireBrowser(["--no-sandbox", "--autoplay-policy=no-user-gesture-required"]);
+        lease = await acquireBrowser(fxChromeArgs());
         const { browser } = lease;
         return await body(() => openFxPage(browser, hostDir));
     }

package/dist/services/audioMixer.js

@@ -1,8 +1,8 @@
 // fallow-ignore-file complexity code-duplication
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
 import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
-import { renameWithRetry } from "../utils/renameWithRetry.js";
-import { removeScratch } from "../utils/removeScratch.js";
+import { renameWithRetry } from "@hyperframes/core/rename-retry";
+import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
@@ -78,11 +78,11 @@ function buildAtempoFilter(playbackRate) {
 const RAMP_SLICE_SECONDS = 0.25;
 const MAX_RAMP_SLICES = 240;
 /** Bake a rate lane as consecutive source slices, each stretched by its mean `sourceTimeAt` rate, keeping pitch. */
-function buildRampFilterComplex(lane, duration, headFilter, tailFilter) {
+function buildRampFilterComplex(lane, duration, headFilter, tailFilter, input) {
     const slices = Math.min(MAX_RAMP_SLICES, Math.max(1, Math.ceil(duration / RAMP_SLICE_SECONDS)));
     const step = duration / slices;
     const split = Array.from({ length: slices }, (_, i) => `[s${i}]`).join("");
-    const parts = [`[0:a]${headFilter ? `${headFilter},` : ""}asplit=${slices}${split}`];
+    const parts = [`[${input}]${headFilter ? `${headFilter},` : ""}asplit=${slices}${split}`];
     for (let i = 0; i < slices; i += 1) {
         const from = sourceTimeAt(lane, i * step);
         const to = sourceTimeAt(lane, (i + 1) * step);
@@ -103,17 +103,17 @@ function buildRampFilterComplex(lane, duration, headFilter, tailFilter) {
         parts.push(`[cat]${tailFilter}[out]`);
     return parts.join(";");
 }
-function preparedAudioOutputArgs(metadata, playbackRate, duration, headFilter) {
+function preparedAudioOutputArgs(metadata, playbackRate, duration, headFilter, stream) {
     const channelFilter = metadata?.channels === 1 ? STEREO_CHANNEL_FILTER : null;
     const outputArgs = channelFilter ? [] : ["-ac", "2"];
     if (typeof playbackRate === "object") {
-        const graph = buildRampFilterComplex(playbackRate, duration, headFilter, channelFilter);
+        const graph = buildRampFilterComplex(playbackRate, duration, headFilter, channelFilter, stream ?? "0:a");
         return ["-filter_complex", graph, "-map", "[out]", ...outputArgs];
     }
     const filters = [headFilter, channelFilter, buildAtempoFilter(playbackRate)].filter(Boolean);
     if (filters.length > 0)
         outputArgs.push("-af", filters.join(","));
-    return outputArgs;
+    return [...(stream ? ["-map", stream] : []), ...outputArgs];
 }
 function escapeExpressionCommas(expression) {
     return expression.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
@@ -545,7 +545,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             const cycle = await extractAudioSegment(srcPath, cyclePath, stage, mediaStart, loopDuration, 1, signal, config, audioSidecarUrl, { padToDuration: true });
             if (!cycle.success)
                 return { ...cycle, outputPath };
-            const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, null);
+            const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, null, null);
             const result = await runFfmpeg([
                 "-stream_loop",
                 "-1",
@@ -591,7 +591,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         ...(options?.padToDuration ? ["apad"] : []),
     ]
         .filter(Boolean)
-        .join(",") || null);
+        .join(",") || null, metadata ? `0:a:${metadata.audioStream}` : null);
     const readFrom = fromSidecar ? audioSidecarUrl : srcPath;
     const args = [
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),

package/dist/services/audioVolumeEnvelope.js

@@ -15,7 +15,7 @@
  * the caller can fall back to the expression path rather than corrupting audio.
  */
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { renameWithRetry } from "../utils/renameWithRetry.js";
+import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { dirname, join } from "path";
 import { normaliseEnvelope } from "@hyperframes/core/media-volume-envelope";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";

package/dist/services/browserManager.js

@@ -7,6 +7,7 @@
  */
 import { explainChromeLaunchFailure } from "./chromeStartup.js";
 import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
+import { inAgentSandbox, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./sandboxLaunch.js";
 import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";
 import { execSync } from "child_process";
 import { existsSync, readdirSync, statSync } from "fs";
@@ -666,14 +667,27 @@ export async function acquireBrowser(chromeArgs, config) {
     const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
     return browserLeasePool.acquire(createBrowserLaunchFingerprint(chromeArgs, config), enablePool);
 }
+/** An agent's macOS seatbelt allows one launch shape only: Chrome in one process over a pipe. */
+async function launchInsideSandbox(ppt, options) {
+    const sandboxed = inAgentSandbox();
+    try {
+        return await ppt.launch(sandboxed ? oneProcessOverPipe(options) : options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "";
+        const refused = machServiceDenied(message) || pipeLaunchClosedOnMac(error);
+        if (process.platform !== "darwin" || sandboxed || !refused)
+            throw error;
+        return ppt.launch(oneProcessOverPipe(options));
+    }
+}
 // fallow-ignore-next-line complexity
 async function launchBrowser(fingerprint) {
     const ppt = await getPuppeteer();
     const env = launchEnv(fingerprint);
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
-    const launch = (args) => ppt
-        .launch({
+    const launch = (args) => launchInsideSandbox(ppt, {
         ...ownedLaunchOptions(),
         headless: true,
         args: withHyperframesBrowserMarker(args),
@@ -682,8 +696,11 @@ async function launchBrowser(fingerprint) {
         env,
         timeout: fingerprint.browserTimeoutMs,
         protocolTimeout: fingerprint.protocolTimeoutMs,
-    })
-        .catch(async (error) => {
+    }).catch(async (error) => {
+        const remediation = process.platform === "darwin" &&
+            sandboxDeniedRemediation(error instanceof Error ? error.message : "");
+        if (remediation)
+            throw new Error(remediation, { cause: error });
         const defaults = await ppt.defaultArgs({
             headless: true,
             args: withHyperframesBrowserMarker(args),

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/extractionCache.js

@@ -33,7 +33,7 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
-import { renameWithRetry } from "../utils/renameWithRetry.js";
+import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { join } from "node:path";
 import { FRAME_FILENAME_PREFIX, framePathsFromDirectory } from "./extractedFrameIndex.js";
 /** Filename prefix for extracted frames. Shared with the extractor. */

package/dist/services/parallelCoordinator.js

@@ -7,7 +7,7 @@
 import { cpus, freemem } from "os";
 import { existsSync, mkdirSync, readdirSync } from "fs";
 import { copyFile, readFile } from "fs/promises";
-import { renameWithRetryAsync } from "../utils/renameWithRetry.js";
+import { renameWithRetryAsync } from "@hyperframes/core/rename-retry";
 import { join } from "path";
 import { getHeapStatistics } from "v8";
 import { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBufferPipelined, captureFrameToBuffer, getCapturePerfSummary, DrawElementVerificationError, } from "./frameCapture.js";

package/dist/services/sandboxLaunch.d.ts

@@ -0,0 +1,10 @@
+import type { LaunchOptions } from "puppeteer-core";
+export declare function machServiceDenied(errorMessage: string): boolean;
+export declare function pipeLaunchClosedOnMac(error: unknown, platform?: NodeJS.Platform): boolean;
+/** Codex runs agent commands in a macOS seatbelt, which names itself in the environment. */
+export declare function inAgentSandbox(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** The one launch a seatbelt allows: no child process registers a mach port, nothing listens, no GPU composites. */
+export declare function oneProcessOverPipe(options: LaunchOptions): LaunchOptions;
+export declare function isOneProcessOverPipe(options: LaunchOptions): boolean;
+/** A process sandbox (an agent's macOS seatbelt) refused Chrome its mach service, so no browser starts here. */
+export declare function sandboxDeniedRemediation(errorMessage: string): string | undefined;

package/dist/services/sandboxLaunch.js

@@ -0,0 +1,31 @@
+const MACH_SERVICE_DENIED = /bootstrap_check_in\b[^\n]*Permission denied/;
+const SINGLE_PROCESS = "--single-process";
+const CPU_COMPOSITING = "--disable-gpu-compositing";
+export function machServiceDenied(errorMessage) {
+    return MACH_SERVICE_DENIED.test(errorMessage);
+}
+export function pipeLaunchClosedOnMac(error, platform = process.platform) {
+    return platform === "darwin" && error instanceof Error && error.name === "TargetCloseError";
+}
+/** Codex runs agent commands in a macOS seatbelt, which names itself in the environment. */
+export function inAgentSandbox(env = process.env, platform = process.platform) {
+    return platform === "darwin" && env.CODEX_SANDBOX === "seatbelt";
+}
+/** The one launch a seatbelt allows: no child process registers a mach port, nothing listens, no GPU composites. */
+export function oneProcessOverPipe(options) {
+    const args = options.args ?? [];
+    const missing = [SINGLE_PROCESS, CPU_COMPOSITING].filter((flag) => !args.includes(flag));
+    return { ...options, pipe: true, args: [...args, ...missing] };
+}
+export function isOneProcessOverPipe(options) {
+    return options.pipe === true && (options.args ?? []).includes(SINGLE_PROCESS);
+}
+/** A process sandbox (an agent's macOS seatbelt) refused Chrome its mach service, so no browser starts here. */
+export function sandboxDeniedRemediation(errorMessage) {
+    if (!machServiceDenied(errorMessage))
+        return undefined;
+    return [
+        "The browser can't start inside this sandbox: macOS refused Chrome's mach service (bootstrap_check_in: Permission denied).",
+        "Rerun this command with escalation, outside the sandbox.",
+    ].join("\n");
+}

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

@@ -61,6 +61,8 @@ export interface AudioMetadata {
     latestStreamLeadSeconds?: number;
     audioStreamLeadSeconds?: number;
     audioStreamCount?: number;
+    /** The track read for these facts and for the mix, by its place among the audio streams (decodableAudioStream). */
+    audioStream: number;
 }
 interface FFProbeStream {
     codec_type: string;
@@ -217,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

@@ -8,6 +8,7 @@ import { basename, join } from "path";
 import { redactTelemetryString } from "@hyperframes/core";
 import { alphaDecoderFor, pixelFormatHasAlpha, videoStreamHasAlpha, } from "@hyperframes/parsers/media-alpha";
 import { urlInputArgs } from "./urlInput.js";
+import { decodableAudioStream } from "@hyperframes/parsers/media-streams";
 import { runFfmpeg } from "./runFfmpeg.js";
 import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js";
 import { ManagedChildProcess } from "./managedChildProcess.js";
@@ -445,7 +446,7 @@ export async function probeMediaProfile(filePath, options) {
         }
         return {
             hasVideoStream: videoStreams.length > 0,
-            hasAudioStream: output.streams.some((stream) => stream.codec_type === "audio"),
+            hasAudioStream: decodableAudioStream(output.streams) !== null,
             visualKind: isStillImage ? "still" : hasMovingVideoStream ? "moving" : "none",
         };
     }
@@ -790,7 +791,7 @@ export async function extractMediaMetadata(filePath) {
             height: videoStream.height || stillImage()?.height || 0,
             fps,
             videoCodec: videoStream.codec_name || "unknown",
-            hasAudio: output?.streams.some((s) => s.codec_type === "audio") ?? false,
+            hasAudio: decodableAudioStream(output?.streams ?? []) !== null,
             isVFR,
             hasAlpha,
             ...(alphaPlaneDecoded === undefined ? {} : { alphaPlaneDecoded }),
@@ -956,8 +957,10 @@ export async function extractAudioMetadata(filePath, options) {
 }
 async function probeAudioMetadata(filePath, signal) {
     const output = await probeMediaOutput(filePath, signal);
-    const audioStream = output.streams.find((s) => s.codec_type === "audio");
-    if (!audioStream)
+    const audioStreams = output.streams.filter((s) => s.codec_type === "audio");
+    const audioStreamIndex = decodableAudioStream(output.streams);
+    const audioStream = audioStreamIndex === null ? undefined : audioStreams[audioStreamIndex];
+    if (audioStreamIndex === null || !audioStream)
         throw new Error("[FFmpeg] No audio stream found");
     let durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
     const streamDuration = audioStream.duration ? parseFloat(audioStream.duration) : undefined;
@@ -966,7 +969,7 @@ async function probeAudioMetadata(filePath, signal) {
     // Container summaries can undercount intact audio, so the decoded last frame wins.
     // The probe returns null instead of throwing: a throw here drops the audio element.
     if (sampleRate > 0) {
-        const decoded = await probeDecodedAudioDuration(filePath, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, signal);
+        const decoded = await probeDecodedAudioDuration(filePath, audioStreamIndex, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, signal);
         if (decoded !== null) {
             durationSeconds = reconcileAudioDuration(durationSeconds, decoded, output.format);
         }
@@ -980,7 +983,8 @@ async function probeAudioMetadata(filePath, signal) {
         bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
         latestStreamLeadSeconds: latestStreamLeadSeconds(output),
         audioStreamLeadSeconds: streamLeadSeconds(output, audioStream),
-        audioStreamCount: output.streams.filter((s) => s.codec_type === "audio").length,
+        audioStreamCount: audioStreams.length,
+        audioStream: audioStreamIndex,
     };
 }
 /** Chrome's media time 0 is the earliest of these; a stream starting later plays that much in. */
@@ -1018,11 +1022,11 @@ function reconcileAudioDuration(containerSeconds, decodedSeconds, format) {
  * True audio duration from the last decoded frame (timestamp + nb_samples - stream start): tail
  * first, then the whole file if a bad seek finds nothing. Null, never a throw, except on abort.
  */
-async function probeDecodedAudioDuration(filePath, sampleRate, startSeconds, containerDurationSeconds, signal) {
+async function probeDecodedAudioDuration(filePath, audioStream, sampleRate, startSeconds, containerDurationSeconds, signal) {
     const probe = async (readInterval) => {
         const args = [
             "-select_streams",
-            "a:0",
+            `a:${audioStream}`,
             "-show_entries",
             "frame=best_effort_timestamp_time,nb_samples",
             "-of",
@@ -1080,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.208",
+  "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/core": "^0.8.208",
-    "@hyperframes/parsers": "^0.8.208"
+    "@hyperframes/core": "^0.8.210",
+    "@hyperframes/parsers": "^0.8.210"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/dist/utils/removeScratch.d.ts

@@ -1,5 +0,0 @@
-/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
- * delete) leaves it for the render's own cleanup and never fails the audio it served. */
-export declare function removeScratch(path: string): void;
-/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
-export declare function collectScratchLeftovers<T>(run: () => Promise<T>, report: (left: string[]) => void): Promise<T>;

package/dist/utils/removeScratch.js

@@ -1,23 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { rmSync } from "node:fs";
-const collecting = new AsyncLocalStorage();
-/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
- * delete) leaves it for the render's own cleanup and never fails the audio it served. */
-export function removeScratch(path) {
-    try {
-        rmSync(path, { recursive: true, force: true });
-    }
-    catch {
-        collecting.getStore()?.push(path);
-    }
-}
-/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
-export async function collectScratchLeftovers(run, report) {
-    const left = [];
-    try {
-        return await collecting.run(left, run);
-    }
-    finally {
-        report(left);
-    }
-}

package/dist/utils/renameWithRetry.d.ts

@@ -1,16 +0,0 @@
-interface Options {
-    platform?: NodeJS.Platform;
-    /** Copy the bytes when Windows keeps refusing (a TEMP that denies delete). Not atomic: scratch files only. */
-    copyFallback?: boolean;
-}
-/** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
-export declare function renameWithRetry(from: string, to: string, options?: Options & {
-    rename?: (from: string, to: string) => void;
-    copy?: (from: string, to: string) => void;
-}): void;
-/** Async twin of {@link renameWithRetry}. */
-export declare function renameWithRetryAsync(from: string, to: string, options?: Options & {
-    rename?: (from: string, to: string) => Promise<void>;
-    copy?: (from: string, to: string) => Promise<void>;
-}): Promise<void>;
-export {};

package/dist/utils/renameWithRetry.js

@@ -1,81 +0,0 @@
-import { copyFileSync, renameSync } from "node:fs";
-import { copyFile, rename } from "node:fs/promises";
-import { removeScratch } from "./removeScratch.js";
-// Windows reports EPERM/EACCES/EBUSY while antivirus or a just-exited process still holds the
-// file; the hold clears within milliseconds. Total wait before giving up: about 1.3 s.
-const RETRYABLE = new Set(["EPERM", "EACCES", "EBUSY"]);
-const BACKOFF_MS = [10, 20, 40, 80, 160, 320, 640];
-function isRetryable(error, platform) {
-    if (platform !== "win32")
-        return false;
-    return RETRYABLE.has(error?.code ?? "");
-}
-/** What a refused rename does next: wait and try again, fall back to a copy, or give up with the error. */
-function nextStep(error, attempt, options, platform) {
-    if (!isRetryable(error, platform))
-        return "throw";
-    if (attempt < BACKOFF_MS.length)
-        return "wait";
-    return options.copyFallback ? "copy" : "throw";
-}
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
-export function renameWithRetry(from, to, options = {}) {
-    const doRename = options.rename ?? renameSync;
-    const doCopy = options.copy ?? copyFileSync;
-    const platform = options.platform ?? process.platform;
-    for (let attempt = 0;; attempt++) {
-        try {
-            doRename(from, to);
-            return;
-        }
-        catch (error) {
-            const step = nextStep(error, attempt, options, platform);
-            if (step === "throw")
-                throw error;
-            if (step === "wait") {
-                sleepSync(BACKOFF_MS[attempt]);
-                continue;
-            }
-            try {
-                doCopy(from, to);
-            }
-            catch {
-                throw error;
-            }
-            removeScratch(from);
-            return;
-        }
-    }
-}
-/** Async twin of {@link renameWithRetry}. */
-export async function renameWithRetryAsync(from, to, options = {}) {
-    const doRename = options.rename ?? rename;
-    const doCopy = options.copy ?? copyFile;
-    const platform = options.platform ?? process.platform;
-    for (let attempt = 0;; attempt++) {
-        try {
-            await doRename(from, to);
-            return;
-        }
-        catch (error) {
-            const step = nextStep(error, attempt, options, platform);
-            if (step === "throw")
-                throw error;
-            if (step === "wait") {
-                await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
-                continue;
-            }
-            try {
-                await doCopy(from, to);
-            }
-            catch {
-                throw error;
-            }
-            removeScratch(from);
-            return;
-        }
-    }
-}