hyperframes/docs/guides/rendering.mdx

---
title: "Render from the command line"
description: "Check a project and render MP4, MOV, WebM, GIF, or PNG output."
---

import { DocsVideo } from "/snippets/docs-video.jsx";

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.

<DocsVideo
  title="One command turns the project into an MP4"
  src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/render-loop-demo-v2.mp4"
  poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/render-loop-demo-v2.jpg"
/>

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:

```bash
npx hyperframes render --output final.mp4
```

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

The normal workflow is:

```bash
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             |
| HLS          | VOD streaming from a playlist directory                    |

Examples:

```bash
# 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

# HLS VOD stream in a directory
npx hyperframes render --format hls --output stream
```

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.

```bash
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.

For VP9 WebM, `ffprobe` reporting `pix_fmt=yuv420p` does not by itself mean
transparency was lost. FFmpeg's default VP9 decoder can also produce an opaque
image from a file that contains alpha. To inspect a frame, explicitly select
the alpha-aware decoder **before** the input:

```bash
ffmpeg -c:v libvpx-vp9 -i overlay.webm -frames:v 1 -pix_fmt rgba overlay-frame.png
```

View the PNG over a checkerboard or contrasting background. If it is still
opaque, compare it with the composition's PNG-sequence output to check whether
transparency was already missing before video encoding.

### HLS streaming output

`--format hls` writes an HLS VOD stream into the output **directory**:
`master.m3u8`, `video.m3u8` and `video_NNNNN.ts`, plus `audio.m3u8` and
`audio_NNNNN.ts` when the composition has audio. The video and audio encodes
are identical to MP4; only the delivery container differs, and packaging is a
stream copy rather than a second encode.

```bash
npx hyperframes render --format hls --output stream
npx hyperframes render --format hls --hls-segment-seconds 6 --output stream
```

Segments are exactly `--hls-segment-seconds` long (default 4) except the last,
and every segment starts on a keyframe. HLS output is SDR only, so `--hdr` is
rejected, and `--gpu` is rejected because GPU encoders ignore the forced-keyframe
lock that fixed-length segments depend on. Cloud rendering (`lambda`,
`cloudrun`) does not offer HLS yet.

## 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.
MOV is an alpha-preserving editing intermediate and always uses the fixed
ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
and are rejected for MOV; choose MP4 or WebM when you need those controls.

```bash
# 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:

```bash
npx hyperframes render --output final.mp4
```

It starts quickly and can use the computer’s browser GPU.
On WSL2, Chrome may not reach the GPU; see
[the render is slow under WSL2](/guides/troubleshooting#the-render-is-slow-under-wsl2).

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

```bash
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:

```bash
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](/developers/cli) and use the complete [CLI reference](/packages/cli) when you need every flag.

## Render provenance

Rendered video carries two container metadata tags that say which tool wrote the file:

```bash
ffprobe -v error -show_entries format_tags -of json out.mp4
```

```json
{ "hyperframes_renderer": "hyperframes", "hyperframes_version": "0.7.107" }
```

That is the whole of it. The tags name the renderer and its version, and nothing else: no file
paths, usernames, machine names, project names, or anything about the composition. They are
container metadata, not a visible watermark, so no pixel of your video changes. Matroska
uppercases tag names on read, so a `.webm` reports `HYPERFRAMES_RENDERER`.

Strip them whenever you like:

```bash
ffmpeg -i out.mp4 -map_metadata -1 -c copy clean.mp4
```

<Note>
  These tags are an unauthenticated diagnostic hint, not proof of origin. They are ordinary unsigned
  container keys, so anything can write the same two values with a single `ffmpeg -metadata`
  command: a tag that is present means the file *claims* to be HyperFrames output, not that
  HyperFrames wrote it. A tag that is absent means just as little, because re-encoding, remuxing, or
  any tool that drops unknown keys strips it, and files rendered by older versions never carried it.
  Treat it as a "what probably produced this file?" hint for support and debugging, never as an
  authenticity, attribution, or licensing check. Verifiable provenance needs signed claims such as
  C2PA.
</Note>

## If rendering fails

Run:

```bash
npx hyperframes doctor
npx hyperframes lint
npx hyperframes check
```

Keep the first exact error rather than only the final “render failed” message. See [Troubleshooting](/guides/troubleshooting) for the next checks.

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

## Related topics

- [Compare local, hosted, and self-managed rendering](/deploy/overview)
- [Render and export from Studio](/studio/export)
- [Diagnose a failed render](/guides/troubleshooting)