Files
hyperframes/packages/engine/src/index.ts
T
James 67bb56c703 feat(engine): browserGpuMode "auto" — probe WebGL once, fall back to software
When the host doesn't have a usable GPU (CI containers, eval rigs without
GPU passthrough, dev VMs), Chrome's hardware-mode WebGL flags
(`--use-gl=egl/metal/d3d11`) silently leave WebGL unavailable —
`getContext("webgl")` returns null, three.js' WebGLRenderer dies, the
canvas stays black. Surfaced today by Abhay's c2v-eval failing on a
docker render of an hf bundle that uses three.js + a custom fragment
shader.

The fix that's been there: `--use-gl=angle --use-angle=swiftshader` (CPU
software WebGL, ~5-50× slower but pixel-identical). The engine already
exposed `browserGpuMode: "software"` for this. The gap was discovery —
users had to know to pass `--no-browser-gpu` on no-GPU hosts.

This change adds `browserGpuMode: "auto"` (now the CLI default for local
renders): on first launch in the process, probe Chrome with hardware
args, check `canvas.getContext("webgl") !== null`, cache the result.
~1-2 s on first render, free on every subsequent render in the same
worker. Hardware GPUs keep their fast path; no-GPU hosts get SwiftShader
without ceremony.

Behaviour matrix:
- No flag, no env, local       → "auto" (NEW default)
- `--browser-gpu`              → "hardware" (force; errors if no GPU)
- `--no-browser-gpu`           → "software" (force SwiftShader)
- `PRODUCER_BROWSER_GPU_MODE`  → "hardware" / "software" / "auto" / unset
- Docker mode                  → forced "software" (unchanged)

Engine-config default stays "software" (conservative for embedders); the
"auto" default lives in the CLI's `resolveBrowserGpuForCli` so producer
embedders aren't surprised by a probe-on-launch.

Also adds `--enable-unsafe-swiftshader` to the software flag set —
Chrome 120+ deprecated implicit SwiftShader fallback and emits a
deprecation warning unless the flag is set explicitly. Despite the
"unsafe" name this is exactly the pre-deprecation behaviour; the rename
is about Chrome's threat model on the open web, not about the rendering
itself.

Verification:
- Engine 535/535 + CLI 256/256 (incl. new probe tests + tri-state CLI test)
- Empirical: probe on this no-GPU devbox returns "software" in 240 ms,
  cached 0 ms on subsequent calls
- Format / lint / typecheck clean across all packages

Refs the Abhay/Slack thread on c2v-eval rendering without a GPU node.
2026-05-06 17:33:55 +00:00

228 lines
8.0 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,
} from "./types.js";
// ── Configuration ──────────────────────────────────────────────────────────────
export { resolveConfig, DEFAULT_CONFIG, type EngineConfig } from "./config.js";
// ── Browser management ─────────────────────────────────────────────────────────
export {
acquireBrowser,
releaseBrowser,
resolveHeadlessShellPath,
resolveBrowserGpuMode,
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,
parseImageElements,
extractVideoFramesRange,
extractAllVideoFrames,
resolveProjectRelativeSrc,
getFrameAtTime,
createFrameLookupTable,
FrameLookupTable,
type VideoElement,
type ImageElement,
type ExtractedFrames,
type ExtractionOptions,
type ExtractionResult,
type ExtractionPhaseBreakdown,
} 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 {
extractMediaMetadata,
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,
resampleRgb48leObjectFit,
normalizeObjectFit,
type ObjectFit,
} 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,
DEFAULT_HDR10_MASTERING,
type HdrTransfer,
type HdrEncoderColorParams,
type CompositionHdrInfo,
type HdrMasteringMetadata,
} from "./utils/hdr.js";
export type { VideoColorSpace } from "./utils/ffprobe.js";