/** * @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. * */ export { REFERENCE_BACKGROUND_FIELD, referenceBackgroundResult, createReferenceBackgroundRecorder, readReferenceBackground, type ReferenceBackground, type ReferenceBackgroundResult, } from "./services/referenceBackground.js"; // ── Protocol types ───────────────────────────────────────────────────────────── export type { HfProtocol, HfMediaElement, HfTransitionMeta, CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, CaptureWarningCode, SubTimelineWaitMemo, SubTimelineWaitOutcome, } from "./types.js"; // ── Configuration ────────────────────────────────────────────────────────────── export { resolveConfig, resolvePageNavigationTimeout, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, type EngineConfig, type ExtractCacheDirResolution, } from "./config.js"; export { SDR_RGB_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "./utils/sdrCaptureColor.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, 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"; // ── Frame capture pipeline ────────────────────────────────────────────────────── export { forcePreservedDrawingBuffer } from "./services/drawElementService.js"; export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, type CompositionLengthSource, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, ImageMissingFromFrameError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, applyVideoMetadataHints, } 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 { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js"; export { holdRenderFrameVideos } from "./services/renderFrameVideoHold.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"; // ── Encoding ─────────────────────────────────────────────────────────────────── export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, 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 { spawnChunkStreamingEncoder, buildChunkStreamingArgs, BT709_LIMITED, type ChunkColour, type ChunkStreamingOptions, } from "./services/chunkStreamingEncoder.js"; export { resolveInPageEncode, type InPageEncodeDecision, type InPageEncodeInput, } from "./services/inPageEncodeEligibility.js"; // ── Media processing ─────────────────────────────────────────────────────────── export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, 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, buildVideoLayerInput, type VideoLayerInput, } from "./services/videoFrameExtractor.js"; export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js"; export { isSelfOrAncestorHidden } from "./services/mediaHidden.js"; export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js"; export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js"; export { createVideoFrameInjector } from "./services/videoFrameInjector.js"; export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, videoAudioId, } from "./services/audioMixer.js"; export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js"; export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js"; export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, 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 WorkerSizingConfig, type LandedFrame, type ParallelProgress, type ParallelWorkerPhaseDiagnostic, } 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 { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js"; export { frameSequencePath } from "./services/extractedFrameIndex.js"; export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js"; export type { PageMotionBlurOff, PageMotionBlurSummary } from "./types.js"; export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js"; export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js"; export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js"; export { extractMediaMetadata, displaySize, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, 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 { _setDownloadFetchForTests, assertPublicHttpsUrl, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js"; export { isBlockedNetworkHost } from "./utils/networkPolicy.js"; export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js"; export { aacSegmentCount, encodeAac } from "./services/aacEncode.js"; export { applyAudioFxChain } from "./services/audioFxRender.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 "@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"; 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, measureVideoShownBoxes, type ShownBox, type VideoElementBounds, type ElementStackingInfo, } from "./services/videoFrameInjector.js"; export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompositionHdr, findHdrAutoPromotion, gradingKeepsSdr, 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"; export { inAgentSandbox, isOneProcessOverPipe, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./services/sandboxLaunch.js";