Files
hyperframes/packages/engine/src/index.ts
T
Miguel Ángel f421851bdd fix(producer): give each parallel segmented-capture worker its own browser (#4475)
* fix(producer): give each parallel segmented-capture worker its own browser

Segmented capture with two or more workers failed at the first frame with
"Invalid JPEG input at frame 0: empty frame". Every worker opened its page in
one pooled Chrome, and beginFrame capture does not survive a shared browser:
a worker's first beginFrame returned no screenshot. Fresh worker sessions now
follow shouldDisableBrowserPoolForParallelWorker, the rule the parallel disk
path already uses.

The default session factory was also built once per worker, so with a probe
session every worker reused that same page. It is now built once per run, so
only the first worker takes the probe.

Workers are now created inside the try, so when a later worker fails to
launch, the finally still closes the browsers opened before it.

* fix(producer): close a segmented worker session whose initialization fails

The default segmented session factory opened a fresh browser and then
initialized it with nothing owning it on failure, so a page-load or init
timeout leaked that Chrome. It now closes the session and rethrows, as the
streaming stage does.
2026-09-25 06:42:59 +00:00

450 lines
14 KiB
TypeScript

/**
* @hyperframes/engine
*
* Seekable web page to video rendering engine.
* Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations,
* or any web content that implements the window.__hf seek protocol.
*
* ## Error Convention
*
* Engine services use three error strategies depending on the operation type:
*
* - **Orchestration services throw on failure.** Browser launch, session init,
* frame capture, and CDP operations propagate errors as thrown exceptions.
* Callers are expected to catch and handle (e.g. frameCapture, browserManager,
* screenshotService, videoFrameExtractor.extractVideoFramesRange).
*
* - **FFmpeg process wrappers return `{ success, error? }` result objects.**
* Encoding, muxing, audio mixing, and streaming encode operations never reject.
* They resolve with a result that includes `success: boolean` and an optional
* `error` string (e.g. chunkEncoder, audioMixer, streamingEncoder).
*
* - **Cleanup and teardown functions never throw.** Browser close, session close,
* temp directory removal, and resource release swallow errors via `.catch(() => {})`
* to avoid masking the original failure (e.g. releaseBrowser, closeCaptureSession,
* FrameLookupTable.cleanup).
*
* - **Optional lookups return `T | undefined` or `T | null`.**
* Functions that may legitimately find nothing (resolveHeadlessShellPath,
* getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
*
*/
// ── Protocol types ─────────────────────────────────────────────────────────────
export type {
HfProtocol,
HfMediaElement,
HfTransitionMeta,
CaptureOptions,
CaptureVideoMetadataHint,
CaptureResult,
CaptureBufferResult,
CapturePerfSummary,
CaptureWarning,
CaptureWarningCode,
SubTimelineWaitOutcome,
} from "./types.js";
// ── Configuration ──────────────────────────────────────────────────────────────
export {
resolveConfig,
validateEngineConfigSnapshot,
DEFAULT_CONFIG,
scaleProtocolTimeoutForComposition,
shouldClampToScreenshotForConcreteGpu,
applyConcreteGpuScreenshotClamp,
explainDrawElementDisabled,
resolveExtractCacheDir,
defaultExtractCacheDir,
EXTRACT_CACHE_DIR_DISABLED_ALIASES,
type EngineConfig,
type ExtractCacheDirResolution,
} from "./config.js";
export {
DEFAULT_VP9_CPU_USED,
MAX_VP9_CPU_USED,
MIN_VP9_CPU_USED,
normalizeVp9CpuUsed,
} from "./services/vp9Options.js";
export {
getCgroupMemoryLimitMb,
getSystemTotalMb,
isLowMemorySystem,
LOW_MEMORY_TOTAL_MB_THRESHOLD,
} from "./services/systemMemory.js";
// ── Browser management ─────────────────────────────────────────────────────────
export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
export {
acquireBrowser,
releaseBrowser,
drainBrowserPool,
closeBrowserPool,
resolveHeadlessShellPath,
resolveBrowserGpuMode,
buildChromeArgs,
compositionRequiresWebGpu,
assertWebGpuAdapterAvailable,
WebGpuUnavailableError,
ENABLE_BROWSER_POOL,
BrowserLeasePool,
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";
// ── Frame capture pipeline ──────────────────────────────────────────────────────
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,
} from "./services/frameCapture.js";
export {
CaptureFailure,
classifyCaptureFailure,
isFatalCaptureFailure,
type CaptureFailureKind,
type CaptureWorkerDiagnostic,
} from "./services/captureFailure.js";
export {
createChromeMemorySampler,
type ChromeMemoryStats,
} from "./services/chromeMemorySampler.js";
// ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
export {
beginFrameCapture,
pageScreenshotCapture,
getCdpSession,
injectVideoFramesBatch,
syncVideoFrameVisibility,
cdpSessionCache,
probeBeginFrameLiveness,
initTransparentBackground,
captureAlphaPng,
applyDomLayerMask,
removeDomLayerMask,
DOM_LAYER_MASK_STYLE_ID,
type BeginFrameResult,
} 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,
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";
// ── Media processing ───────────────────────────────────────────────────────────
export {
parseVideoElements,
parseImageElements,
extractVideoFramesRange,
extractAllVideoFrames,
resolveTimelineExtractionWindow,
resolveVideoExtractionWindow,
resolveFinalFrameExtractionWindow,
resolveVideoExtractionDuration,
resolvePlayableVideoDuration,
extractionFrameCountForDuration,
resolveProjectRelativeSrc,
getFrameAtTime,
createFrameLookupTable,
FrameLookupTable,
analyzeClipMediaFit,
classifyVideoExtractionError,
isVideoSourceExtractionError,
runVideoExtractionWithRetry,
safeVideoExtractionSourceIdentity,
VideoSourceExtractionError,
type VideoElement,
type ImageElement,
type ExtractedFrames,
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,
} from "./services/videoFrameExtractor.js";
export {
resolveReferencedStart,
resolveReferencedDuration,
type RefResolverEl,
type RefResolverDoc,
} from "./services/referenceResolver.js";
export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
export {
MIXED_AUDIO_FILENAME,
parseAudioElements,
processCompositionAudio,
} from "./services/audioMixer.js";
export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
export type {
AudioElement,
AudioFailureReason,
AudioFailureStage,
AudioProcessingFailure,
AudioTrack,
AudioVolumeKeyframe,
MixResult,
} from "./services/audioMixer.types.js";
// ── Parallel rendering ─────────────────────────────────────────────────────────
export {
calculateOptimalWorkers,
computeWorkerSizing,
selectVerifySampleIndicesForTask,
verifyDiskDrawElementSamples,
distributeFrames,
distributeFramesInterleaved,
executeParallelCapture,
mergeWorkerFrames,
getSystemResources,
shouldDisableBrowserPoolForParallelWorker,
type WorkerTask,
type WorkerResult,
type WorkerSizing,
type WorkerSizingBound,
type ParallelProgress,
} from "./services/parallelCoordinator.js";
// ── File server ────────────────────────────────────────────────────────────────
export {
createFileServer,
type FileServerOptions,
type FileServerHandle,
} from "./services/fileServer.js";
// ── Utilities ──────────────────────────────────────────────────────────────────
export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
export { frameFileExtension } from "./services/frameCapture.js";
export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
export {
assertSwiftShader,
readWebGlVendorInfo,
SwiftShaderAssertionError,
BROWSER_GPU_NOT_SOFTWARE,
} from "./utils/assertSwiftShader.js";
export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
export {
extractMediaMetadata,
extractVideoMetadata,
extractFinalVideoFrameTimestamp,
extractAudioMetadata,
probeMediaProfile,
analyzeKeyframeIntervals,
type VideoMetadata,
type AudioMetadata,
type MediaProbeProfile,
type KeyframeAnalysis,
} from "./utils/ffprobe.js";
export {
NOT_MEDIA_PAYLOAD,
NotMediaPayloadError,
assertMediaPayload,
fingerprintElementId,
isNotMediaPayload,
} from "./utils/notMediaPayload.js";
export {
assertPublicHttpsUrl,
isBlockedNetworkHost,
downloadToTemp,
fetchPublicHttpsText,
isHttpUrl,
safeDownloadUrlIdentity,
writeUrlDownloadTelemetry,
type SafeDownloadUrlIdentity,
type UrlDownloadOptions,
type UrlDownloadTelemetry,
type PublicHttpsTextOptions,
} from "./utils/urlDownloader.js";
export {
runFfmpeg,
formatFfmpegError,
isExternalFfmpegInterruption,
type RunFfmpegOptions,
type RunFfmpegResult,
} from "./utils/runFfmpeg.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";
// drawElement self-verify comparison — shared by the streaming drain
// (producer) and the parallel disk-path verify (parallelCoordinator).
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";
export {
diffGpuParityFrames,
diffGpuParityPngs,
verifyGpuParity,
type RgbaFrame,
type GpuParityDiffOptions,
type GpuParityDiffResult,
type BlackOnlyInARegion,
type VerifyGpuParityResult,
} from "./utils/gpuParityDiff.js";
// ── Shader transitions ────────────────────────────────────────────────────────
export {
type TransitionFn,
TRANSITIONS,
crossfade,
sampleRgb48le,
hdrToLinear,
linearToHdr,
convertTransfer,
} from "./utils/shaderTransitions.js";
export {
initHdrReadback,
uploadAndReadbackHdrFrame,
float16ToPqRgb,
buildHdrChromeArgs,
launchHdrBrowser,
} from "./services/hdrCapture.js";
export { captureScreenshotWithAlpha } from "./services/screenshotService.js";
export {
hideVideoElements,
showVideoElements,
queryVideoElementBounds,
queryElementStacking,
type VideoElementBounds,
type ElementStackingInfo,
} from "./services/videoFrameInjector.js";
export {
isHdrColorSpace,
detectTransfer,
getHdrEncoderColorParams,
analyzeCompositionHdr,
findHdrAutoPromotion,
formatHdrAutoPromotionWarning,
sanitizeHdrAutoPromotionAsset,
DEFAULT_HDR10_MASTERING,
HDR_AUTO_PROMOTION_PIPELINE,
type HdrTransfer,
type HdrEncoderColorParams,
type HdrAutoPromotion,
type CompositionHdrInfo,
type HdrMasteringMetadata,
} from "./utils/hdr.js";
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";