Files
hyperframes/packages/engine/src/index.ts
T
Miguel Ángel 663b02297d feat(cli): add hyperframes clean to find and remove what HyperFrames left on disk (#4701)
* feat(cli): add hyperframes clean to find and remove what HyperFrames left on disk

`hyperframes clean` lists leftover render work dirs, debug renders, the history of projects
that no longer exist, idle video proxies and extracted video frames, with sizes, and removes
them. `--dry-run` removes nothing, `--json` is for agents, `--snapshots` also removes
snapshot folders (otherwise listed as reclaimable). It never touches outputs, sources or
anything a running render or preview still owns.

* docs(cli): say that clean does not search a project's subfolders

* fix(cli): clean test compares folder names on Windows and the skills manifest is regenerated

* fix(studio-server): the proxy cache sweep removes only files the transcoder named

It removed any idle .mp4 or .webm in .transcode-cache, so a user file placed there, or reached through
a symlinked cache folder, could go. Proxies are always <sha256>.<ext> and their temp files
.tmp-<uuid>-<proxy name>; nothing else is swept.

* style(producer): keep a renderDirOwner doc comment within 120 columns
2026-09-29 00:43:42 +00:00

453 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,
setHostHandlesSigint,
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,
EXTRACT_CACHE_MIN_AGE_MS,
} from "./services/videoFrameExtractor.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,
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";