Render from the command line

Check a project and render MP4, MOV, WebM, GIF, or PNG output.

Studio is the simplest place to export a project. Use the command line when an agent, script, CI job, or advanced delivery workflow needs to control the render.

The whole loop: the project, the render command, progress, and the finished file playing. The flags shown are the ones people actually reach for — format, resolution, frame rate, quality.

Render a normal video

From the project folder:

npx hyperframes render --output final.mp4

If you omit --output, HyperFrames writes the result under renders/.

The normal workflow is:

npx hyperframes lint
npx hyperframes check
npx hyperframes render --output final.mp4

lint checks the project structure. check opens the project in a browser and looks for runtime, layout, motion, media, and contrast problems.

Choose a format

Format	Use it for
MP4	Normal sharing, publishing, and delivery
MOV	ProRes workflows and transparent editing intermediates
WebM	Web delivery and transparent overlays
GIF	Short previews in issues, pull requests, and documentation
PNG sequence	Frame-by-frame handoff to compositing software

Examples:

# Transparent web overlay
npx hyperframes render --format webm --output overlay.webm

# ProRes editing file
npx hyperframes render --format mov --output master.mov

# Short looping preview
npx hyperframes render --format gif --fps 15 --output preview.gif

# RGBA frames in a directory
npx hyperframes render --format png-sequence --output frames

GIF has no audio and limited transparency. Prefer MP4 or WebM for normal playback.

Transparent video

Use WebM for a transparent web overlay or MOV for a ProRes 4444 editing intermediate. Leave the composition background unpainted wherever the output must remain transparent; an opaque html, body, or full-frame background will be encoded as visible pixels.

npx hyperframes render --format webm --output overlay.webm
npx hyperframes render --format mov --output overlay.mov

MP4 is the normal opaque delivery format. After rendering transparency, inspect the file over a contrasting background rather than trusting a player that always shows black behind alpha.

Input video codecs

Studio, preview, check, and published projects normally create cached browser proxies for local video that Chrome cannot decode reliably, including common HEVC and ProRes inputs. The original file stays in the project and remains the render source.

If a clip is black only in preview, keep automatic proxying enabled, confirm the source is local, and run npx hyperframes check. Disable proxying only when the browser already supports the source or you are diagnosing the proxy itself.

Choose quality and frame rate

The default standard quality is the right choice for most finished work.

# Faster review version
npx hyperframes render --quality draft --output review.mp4

# Larger final master
npx hyperframes render --quality high --output master.mp4

# Explicit frame rate
npx hyperframes render --fps 60 --output final-60fps.mp4

Use a higher frame rate only when the source or destination needs it. It creates more frames, so rendering takes longer.

The CLI uses the composition’s data-fps when present and otherwise defaults to 30 fps.

Local or Docker

Local rendering is the normal choice:

npx hyperframes render --output final.mp4

It starts quickly and can use the computer’s browser GPU.

Use Docker when a controlled Chrome, FFmpeg, and font environment matters:

npx hyperframes render --docker --output final.mp4

Docker adds startup and infrastructure overhead. It is useful for CI and repeatable production environments, not a requirement for every final render.

Render another composition

The root index.html is rendered by default. To target another standalone composition:

npx hyperframes render \
  --composition compositions/intro.html \
  --output intro.mp4

Nested compositions that use <template> wrappers should be rendered through the root composition that includes them.

Batch and cloud work

For several variable-driven versions, use batch rendering. For remote infrastructure, use HyperFrames cloud, AWS Lambda, or Google Cloud Run.

Those workflows involve output naming, credentials, concurrency, and infrastructure choices. Start in the CLI guide and use the complete CLI reference when you need every flag.

If rendering fails

Run:

npx hyperframes doctor
npx hyperframes lint
npx hyperframes check

Keep the first exact error rather than only the final “render failed” message. See Troubleshooting for the next checks.

Always watch the exported file itself. Preview proves that the project can play; the output file proves that the delivery is correct.

Related topics

• Compare local, hosted, and self-managed rendering
• Render and export from Studio
• Diagnose a failed render