mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(engine): a render no longer finishes without an image that loaded late * style(engine): format the frame gate * fix(engine): an image outside the frame no longer stops a render * fix(engine): a render stops and warns when a frame's image never arrives, with no cloud retries * fix(producer): a cloud chunk keeps the missing image's error name so retries stop
556 lines
17 KiB
TypeScript
556 lines
17 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.
|
|
*
|
|
*/
|
|
|
|
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";
|