Skip to main content
Render your Hyperframes compositions to MP4 with the CLI. The rendering pipeline is frame-by-frame and seek-driven — see Deterministic Rendering for how this works under the hood.

​
Getting Started

1

Verify your environment

Run the diagnostics command to check for required dependencies:
Terminal
npx hyperframes doctor
Expected output:
✓ Node.js 20.x
✓ FFmpeg found (7.x)
✓ Docker available
✓ Disk space OK
2

Preview your composition

Before rendering, preview your composition in the browser to verify it looks correct:
Terminal
npx hyperframes dev
3

Render to MP4

Run the render command from your project directory:
Terminal
npx hyperframes render -o output.mp4
Expected output:
⠋ Rendering composition "root" (30fps, standard quality)
✓ Captured 240 frames in 8.2s
✓ Encoded to output.mp4 (8.0s, 1920x1080, 4.2MB)

​
Rendering Modes

​
Local Mode (default)

Uses Puppeteer (bundled Chromium) and your system’s FFmpeg. Fast for iteration during development.Requires: FFmpeg installed on your system. See Troubleshooting if FFmpeg is not found.
Terminal
npx hyperframes render -o output.mp4
Pros:
  • Fast startup, no container overhead
  • Uses your system GPU for hardware-accelerated encoding (with --gpu)
  • Best for iterative development
Cons:
  • Output may vary across platforms due to font and Chrome version differences
  • Not suitable for CI/CD pipelines that require reproducibility

​
When to Use Each Mode

ScenarioRecommended Mode
Local development and iterationLocal
CI/CD pipelineDocker
Sharing renders with a teamDocker
Quick preview exportLocal
AI agent-driven renderingDocker
Benchmarking performanceLocal

​
Options

FlagValuesDefaultDescription
-f, --fps24, 30, 6030Frames per second
-q, --qualitydraft, standard, highstandardEncoding quality preset
-w, --workers1-8autoParallel render workers
--gpu—offGPU encoding (NVENC, VideoToolbox, VAAPI)
-o, --outputpath—Output file path
--docker—offUse Docker for deterministic rendering

​
Tips

Use draft quality during development for fast previews. Switch to standard or high for final output.
  • Use npx hyperframes benchmark to find optimal settings for your system
  • 4 workers is usually the sweet spot for most compositions
  • Docker mode is slower but guarantees identical output across platforms
  • For compositions with many frames, --gpu can significantly speed up local encoding

​
Next Steps

Deterministic Rendering

Understand the determinism guarantees

CLI Reference

Full list of CLI commands and flags

Troubleshooting

Fix common rendering issues

Common Mistakes

Avoid pitfalls that affect render output