Files
hyperframes/packages/cli/src/docs/rendering.md
T
Miguel Ángel 54d0af57eb feat(engine): render sets a keyframe interval and a peak bitrate cap (#6444)
* feat(engine): encoders cap peak bitrate and place keyframes on a set interval

* style(engine): shorten the rate-cap comment

* style(engine): drop the doc lines the comment ratchet flagged

* feat(producer): mp4 renders honour a keyframe interval and a peak bitrate cap on every encoder path

* style(producer): shorten the delivery encoder file headers

* style(producer): drop a comment line from the segment manifest

* style(producer): shorten the integration test header

* test: delivery encoder tests follow the ffprobe argv contract and run in the integration lane

* feat: the render request, server and Lambda plan carry the keyframe interval and peak bitrate cap

* fix(studio): the Studio render route passes the keyframe interval and bitrate cap to the encoder

* chore(studio-server): drop a comment the helper's name already says

* feat(cli): render and lambda render take --keyframe-interval, --max-bitrate and --buffer-size
2026-10-27 00:29:06 +00:00

2.3 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 — 1-240 or a rational such as 30000/1001 (default: root data-fps, else 30)
  • -q, --quality — draft, looks, delivery, or standard/high (default: looks)
  • -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)
  • --keyframe-interval — MP4 only: a keyframe at least every N seconds (default: encoder's choice)
  • --max-bitrate — MP4 only: peak video bitrate cap such as 8M, kept alongside the quality target (default: uncapped)
  • --buffer-size — MP4 only: buffer for --max-bitrate, such as 16M (default: twice --max-bitrate)
  • --vp9-cpu-used — WebM VP9 speed/quality tradeoff (-8 to 8, default: 4). Higher values encode faster with larger output / quality tradeoff.
  • --video-frame-format — Source video frame extraction format: auto, jpg, or png (default: auto). Use png for UI recordings, screen captures, and color-sensitive source videos.
  • --gpu — Use GPU encoding (NVENC, VideoToolbox, AMF, 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 --video-frame-format png when source videos contain saturated UI colors that should avoid JPEG extraction
  • Use npx hyperframes benchmark to find optimal settings
  • 4 workers is usually the sweet spot for most compositions