heygen-com__hyperframes/docs/guides/rendering.mdx

---
title: Rendering
description: "Render compositions to MP4, MOV, or WebM locally or in Docker."
---

Render your Hyperframes [compositions](/concepts/compositions) to MP4, MOV, or WebM with the [CLI](/packages/cli). The rendering pipeline is frame-by-frame and seek-driven — see [Deterministic Rendering](/concepts/determinism) for how this works under the hood.

## Getting Started

<Steps>
  <Step title="Verify your environment">
    Run the diagnostics command to check for required dependencies:

    ```bash Terminal
    npx hyperframes doctor
    ```

    Expected output:

    ```
    ✓ Node.js    v22.x
    ✓ FFmpeg      7.x
    ✓ FFprobe     7.x
    ✓ Chrome      (bundled)
    ✓ Docker      available
    ```
  </Step>
  <Step title="Preview your composition">
    Before rendering, preview your composition in the browser to verify it looks correct:

    ```bash Terminal
    npx hyperframes preview
    ```
  </Step>
  <Step title="Render to MP4">
    Run the render command from your project directory:

    ```bash Terminal
    npx hyperframes render --output 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)
    ```
  </Step>
</Steps>

## Rendering Modes

<Tabs>
  <Tab title="Local Mode">
    ### 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](/guides/troubleshooting) if FFmpeg is not found.

    ```bash Terminal
    npx hyperframes render --output 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
  </Tab>
  <Tab title="Docker Mode">
    ### Docker Mode

    [Deterministic](/concepts/determinism) output with an exact Chrome version and font set. Use this for production renders and CI pipelines.

    **Requires:** Docker installed and running.

    ```bash Terminal
    npx hyperframes render --docker --output output.mp4
    ```

    **Pros:**
    - Identical output on every platform — same Chrome, same fonts, same FFmpeg
    - The same pipeline used in production
    - Ideal for CI/CD and automated workflows

    **Cons:**
    - Slower startup due to container initialization
    - No GPU acceleration inside the container

    <Note>
      Docker mode uses `chrome-headless-shell` with [BeginFrame](/concepts/determinism#how-it-works) control for frame-perfect, deterministic capture.
    </Note>
  </Tab>
</Tabs>

## When to Use Each Mode

| Scenario | Recommended Mode |
|----------|-----------------|
| Local development and iteration | Local |
| CI/CD pipeline | Docker |
| Sharing renders with a team | Docker |
| Quick preview export | Local |
| AI agent-driven rendering | Docker |
| Benchmarking performance | Local |

## Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--output` | path | `renders/<name>.mp4` | Output file path |
| `--format` | mp4, mov, webm | mp4 | Output format (see [Transparent Video](#transparent-video) below) |
| `--fps` | 24, 30, 60 | 30 | Frames per second |
| `--quality` | draft, standard, high | standard | Encoding quality preset |
| `--workers` | 1-8 or `auto` | auto | Parallel render workers (see [Workers](#workers) below) |
| `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, VAAPI) |
| `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
| `--quiet` | — | off | Suppress verbose output |

## Workers

Each render worker launches a **separate Chrome browser process** to capture frames in parallel. More workers can speed up rendering, but each one consumes ~256 MB of RAM and significant CPU.

### Default behavior

By default, Hyperframes uses **half of your CPU cores, capped at 4**:

| Machine | CPU cores | Default workers |
|---------|-----------|----------------|
| MacBook Air (M1) | 8 | 4 |
| MacBook Pro (M3) | 12 | 4 (capped) |
| 4-core laptop | 4 | 2 |
| 2-core VM | 2 | 1 |

This is intentionally conservative. Each worker spawns its own Chrome process, so the per-worker overhead is significant. Fewer workers avoids resource contention with FFmpeg encoding and your other applications.

### Choosing a worker count

```bash Terminal
# Explicit worker count
npx hyperframes render --workers 1 --output output.mp4

# Let Hyperframes pick based on your CPU
npx hyperframes render --workers auto --output output.mp4

# Maximum parallelism (use with caution on laptops)
npx hyperframes render --workers 8 --output output.mp4
```

<Tip>
  Start with the default. If renders feel slow and your system has headroom (check Activity Monitor / `htop`), try increasing `--workers`. If you see high memory pressure or fan noise, reduce it.
</Tip>

### When to use 1 worker

- Short compositions (under 2 seconds / 60 frames) — parallelism overhead exceeds the benefit
- Low-memory machines (4 GB or less)
- Running renders alongside other heavy processes (video editing, large builds)

### When to increase workers

- Long compositions (30+ seconds) on a machine with 8+ cores and 16+ GB RAM
- Dedicated render machines or CI runners
- Docker mode on a well-provisioned host

## Transparent Video

Hyperframes supports rendering with a transparent background — useful for overlays, lower thirds, subscribe cards, and any element you want to composite over other footage in a video editor.

### Recommended format: MOV (ProRes 4444)

```bash Terminal
npx hyperframes render --format mov --output overlay.mov
```

**MOV with ProRes 4444** is the industry standard for transparent video. It works in all major video editors:

- CapCut
- Final Cut Pro
- Adobe Premiere Pro
- DaVinci Resolve
- After Effects

<Warning>
  ProRes MOV files are large (typically 5-40 MB for short clips) because ProRes is a high-quality intermediate codec optimized for editing, not delivery. This is expected — the same tradeoff Remotion and professional pipelines make.
</Warning>

### Format comparison

| Format | Codec | Transparency | Video editors | Browsers | File size |
|--------|-------|-------------|---------------|----------|-----------|
| **MOV** | ProRes 4444 | Yes | CapCut, Final Cut, Premiere, DaVinci, After Effects | No | Large |
| **WebM** | VP9 | Yes | None (shows black background) | Chrome, Firefox | Small |
| **MP4** | H.264 | No | All | All | Small |

<Note>
  **WebM VP9 alpha** is technically supported but all major video editors ignore the alpha channel and render transparent areas as black. Only Chromium-based browsers (Chrome, Arc, Brave, Edge) decode VP9 alpha correctly. Safari does not support it. Use MOV for editor workflows and WebM only for browser-based playback.
</Note>

### How it works

When you render with `--format mov` or `--format webm`, Hyperframes:

1. Captures each frame as a **PNG with alpha channel** (instead of JPEG for MP4)
2. Sets Chrome's page background to transparent via `Emulation.setDefaultBackgroundColorOverride`
3. Encodes with an alpha-capable codec (ProRes 4444 for MOV, VP9 for WebM)

Your composition's HTML should **not** set a `background` on `html` or `body` — leave it unset so the transparent background comes through.

### Authoring transparent compositions

```html
<style>
  /* Do NOT set background on html/body — leave them transparent */
  * { margin: 0; padding: 0; box-sizing: border-box; }

  [data-composition-id="my-overlay"] {
    position: relative;
    width: 1920px;
    height: 1080px;
    overflow: hidden;
    /* No background here either */
  }
</style>
```

Only the visible elements (cards, text, images) will appear in the final video. Everything else will be transparent.

### Verifying transparency

- **In a browser:** Open the MOV file — it won't play (ProRes is not a browser codec). Instead, render a WebM copy and open it in Chrome on a checkerboard background page.
- **In a video editor:** Import the MOV file and place it on a track above other footage. Transparent areas should show the footage below.
- **Online tool:** Use [rotato.app/tools/transparent-video](https://rotato.app/tools/transparent-video) to verify your MOV or WebM has working transparency.

## Tips

<Tip>
  Use `draft` quality during development for fast previews. Switch to `standard` or `high` for final output.
</Tip>

- Use `npx hyperframes benchmark` to find optimal settings for your system
- Docker mode is slower but guarantees [identical output](/concepts/determinism) across platforms
- For compositions with many frames, `--gpu` can significantly speed up local encoding

## Next Steps

<CardGroup cols={2}>
  <Card title="Deterministic Rendering" icon="lock" href="/concepts/determinism">
    Understand the determinism guarantees
  </Card>
  <Card title="CLI Reference" icon="terminal" href="/packages/cli">
    Full list of CLI commands and flags
  </Card>
  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
    Fix common rendering issues
  </Card>
  <Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
    Avoid pitfalls that affect render output
  </Card>
</CardGroup>