Files
hyperframes/packages/cli/src/docs/rendering.md
T
James f635deb86a feat(engine): cache probe Promise + log resolved mode + sync docs
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
2026-05-06 17:33:55 +00:00

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 as 10M (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 is auto — 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 draft quality for fast previews during development
  • Local renders auto-detect GPU on first launch; use --browser-gpu to force hardware (errors if no GPU) or --no-browser-gpu to force SwiftShader
  • Use --gpu when a local render also benefits from hardware FFmpeg encoding
  • Use npx hyperframes benchmark to find optimal settings
  • 4 workers is usually the sweet spot for most compositions