mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-20 03:47:38 +00:00
Three follow-ups from Vai's staff-eng review: 1. Concurrent-probe race (real bug): the parallel coordinator runs N workers via Promise.all, so `--workers 4` on a no-GPU host fired 4 simultaneous probe Chromes — each paying the same 240 ms launch cost. Cache the *Promise* (not the resolved value): first caller assigns the in-flight Promise, every other concurrent caller awaits the same one. Verified with a new test asserting all concurrent callers get the identical Promise reference. 2. Stale rendering.md (lines 23, 29): user-visible contract said "browser GPU enabled by default", which was wrong post-auto. Now describes the auto / hardware / software trichotomy explicitly. 3. Silent fallback: auto-mode produced no output, so a regression to "always falls back to software even with GPU present" would have been invisible in production logs. Added a single stderr line per process when the probe resolves: `[hyperframes] browserGpuMode auto → <mode> (<reason>)`. Cache hits don't re-log. Verification: - Engine 536/536 (incl. new concurrent-dedup test asserting Promise reference equality across simultaneous callers) - CLI 256/256 - Format / lint / typecheck clean
1.5 KiB
1.5 KiB
Rendering
Render compositions to MP4 with npx hyperframes render.
Local Mode (default)
Uses Puppeteer (bundled Chromium) + system FFmpeg. Fast for iteration.
Requires: FFmpeg installed (brew install ffmpeg or apt install ffmpeg).
Docker Mode (--docker)
Deterministic output with exact Chrome version and fonts. For production. Requires: Docker installed and running.
Options
-f, --fps— 24, 30, or 60 (default: 30)-q, --quality— draft, standard, high (default: standard)-w, --workers— Parallel workers 1-8 (default: auto)--crf— Override encoder CRF (mutually exclusive with--video-bitrate)--video-bitrate— Target video bitrate such as10M(mutually exclusive with--crf)--gpu— Use GPU encoding (NVENC, VideoToolbox, VAAPI, QSV)--browser-gpu/--no-browser-gpu— Force host GPU or software (SwiftShader) for Chrome/WebGL capture. Default for local renders isauto— probe WebGL availability on first launch and fall back to software if no GPU is reachable. Docker mode always uses software.-o, --output— Custom output path
Tips
- Use
draftquality for fast previews during development - Local renders auto-detect GPU on first launch; use
--browser-gputo force hardware (errors if no GPU) or--no-browser-gputo force SwiftShader - Use
--gpuwhen a local render also benefits from hardware FFmpeg encoding - Use
npx hyperframes benchmarkto find optimal settings - 4 workers is usually the sweet spot for most compositions