Files
hyperframes/packages/engine/src/index.ts
T
Vance Ingalls ee48280fe0 fix(engine): convert sRGB DOM overlays to BT.2020 primaries before HDR composite
DOM overlays composited onto HDR video frames were oversaturated because
`blitRgba8OverRgb48le` mapped sRGB 8-bit values directly through an
HDR OETF (HLG or PQ) without first converting from BT.709 to BT.2020
color primaries. Treating sRGB values as if they already lived in the
much wider BT.2020 gamut pushed saturated colors well past the
designer's intent — e.g. sRGB pure blue (0,0,255) landed on BT.2020
blue, which is far more vivid than what was specified.

Replace `buildSrgbToHdrLut` with the full pipeline:
  sRGB 8-bit
    → linear BT.709 (sRGB EOTF, 256-entry LUT)
    → linear BT.2020 (3×3 BT.2087-0 primary matrix)
    → HDR signal 16-bit (HLG/PQ OETF, 4096-entry LUT)

The matrix rows sum to 1.0, so neutral content (R=G=B) is invariant —
text and grayscale UI render identically. Chromatic content (icons,
accent colors, progress bars) is now color-accurate against BT.2020
HDR video. PQ scales relative to 203 nits SDR white per BT.2408 so
SDR overlays sit at conventional brightness inside the HDR frame.

Verified end-to-end with hdr-smoke (sdr-baseline, hdr-pq,
mixed-sdr-hdr): sampled red overlay pixels (#C1121F) in the rendered
PQ output match the calculated post-conversion 16-bit values
(~30837/18894/15630), versus the old buggy pipeline's
~33820/10529/13663 (visibly oversaturated).

Removes the `getSrgbToHdrLut` public export — the LUT is now an
internal pipeline stage, not a single-step conversion.

Made-with: Cursor
2026-04-19 18:34:32 -07:00

218 lines
7.7 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,
CaptureResult,
CaptureBufferResult,
CapturePerfSummary,
} from "./types.js";
// ── Configuration ──────────────────────────────────────────────────────────────
export { resolveConfig, DEFAULT_CONFIG, type EngineConfig } from "./config.js";
// ── Browser management ─────────────────────────────────────────────────────────
export {
acquireBrowser,
releaseBrowser,
resolveHeadlessShellPath,
buildChromeArgs,
ENABLE_BROWSER_POOL,
type BuildChromeArgsOptions,
type CaptureMode,
type AcquiredBrowser,
} from "./services/browserManager.js";
// ── Frame capture pipeline ──────────────────────────────────────────────────────
export {
createCaptureSession,
initializeSession,
closeCaptureSession,
captureFrame,
captureFrameToBuffer,
getCompositionDuration,
getCapturePerfSummary,
prepareCaptureSessionForReuse,
type CaptureSession,
type BeforeCaptureHook,
} from "./services/frameCapture.js";
// ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
export {
beginFrameCapture,
pageScreenshotCapture,
getCdpSession,
injectVideoFramesBatch,
syncVideoFrameVisibility,
cdpSessionCache,
initTransparentBackground,
captureAlphaPng,
applyDomLayerMask,
removeDomLayerMask,
DOM_LAYER_MASK_STYLE_ID,
type BeginFrameResult,
} from "./services/screenshotService.js";
// ── Encoding ───────────────────────────────────────────────────────────────────
export {
encodeFramesFromDir,
encodeFramesChunkedConcat,
muxVideoWithAudio,
applyFaststart,
detectGpuEncoder,
ENCODER_PRESETS,
getEncoderPreset,
type GpuEncoder,
} 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,
extractVideoFramesRange,
extractAllVideoFrames,
getFrameAtTime,
createFrameLookupTable,
FrameLookupTable,
type VideoElement,
parseImageElements,
type ImageElement,
type ExtractedFrames,
type ExtractionOptions,
type ExtractionResult,
} from "./services/videoFrameExtractor.js";
export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
export { parseAudioElements, processCompositionAudio } from "./services/audioMixer.js";
export type { AudioElement, AudioTrack, MixResult } from "./services/audioMixer.types.js";
// ── Parallel rendering ─────────────────────────────────────────────────────────
export {
calculateOptimalWorkers,
distributeFrames,
executeParallelCapture,
mergeWorkerFrames,
getSystemResources,
type WorkerTask,
type WorkerResult,
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 {
extractVideoMetadata,
extractAudioMetadata,
analyzeKeyframeIntervals,
type VideoMetadata,
type AudioMetadata,
type KeyframeAnalysis,
} from "./utils/ffprobe.js";
export { downloadToTemp, isHttpUrl } from "./utils/urlDownloader.js";
export { runFfmpeg, type RunFfmpegOptions, type RunFfmpegResult } from "./utils/runFfmpeg.js";
export {
decodePng,
decodePngToRgb48le,
blitRgba8OverRgb48le,
blitRgb48leRegion,
blitRgb48leAffine,
parseTransformMatrix,
roundedRectAlpha,
} from "./utils/alphaBlit.js";
export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.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,
type HdrTransfer,
type HdrEncoderColorParams,
type CompositionHdrInfo,
} from "./utils/hdr.js";
export type { VideoColorSpace } from "./utils/ffprobe.js";