> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# helios render

> Render a composition to video file

The `render` command converts a Helios composition into a video file using headless browser rendering.

## Usage

```bash theme={null}
helios render <input> [options]
```

## Arguments

<ParamField path="input" type="string" required>
  Path to composition HTML file or HTTP(S) URL.
</ParamField>

## Output options

<ParamField path="--output" type="string" default="output.mp4">
  Output file path. Short form: `-o`.
</ParamField>

<ParamField path="--width" type="number" default="1920">
  Viewport width in pixels.
</ParamField>

<ParamField path="--height" type="number" default="1080">
  Viewport height in pixels.
</ParamField>

<ParamField path="--fps" type="number" default="30">
  Frames per second for output video.
</ParamField>

<ParamField path="--duration" type="number" default="1">
  Duration in seconds.
</ParamField>

<ParamField path="--quality" type="number">
  CRF quality value (0-51). Lower values = higher quality. Default varies by codec.
</ParamField>

## Rendering options

<ParamField path="--mode" type="string" default="canvas">
  Render mode: `canvas` or `dom`. Canvas mode is faster and more reliable.
</ParamField>

<ParamField path="--no-headless" type="boolean">
  Run browser in visible window instead of headless mode. Useful for debugging.
</ParamField>

<ParamField path="--start-frame" type="number">
  Frame number to start rendering from (0-based).
</ParamField>

<ParamField path="--frame-count" type="number">
  Number of frames to render. Used for chunked rendering.
</ParamField>

<ParamField path="--concurrency" type="number" default="1">
  Number of concurrent render jobs to execute in parallel.
</ParamField>

## Codec options

<ParamField path="--video-codec" type="string">
  Video codec. Examples: `libx264`, `libx265`, `libvpx`, `libvpx-vp9`.
</ParamField>

<ParamField path="--audio-codec" type="string">
  Audio codec. Examples: `aac`, `mp3`, `pcm_s16le`.
</ParamField>

## Distributed rendering

<ParamField path="--emit-job" type="string">
  Generate a distributed render job specification (JSON) instead of rendering immediately.
</ParamField>

<ParamField path="--base-url" type="string">
  Base URL for remote asset resolution in distributed jobs. Alias for `--job-base-url`.
</ParamField>

<ParamField path="--job-base-url" type="string">
  Base URL for remote asset resolution. Used when generating job specs for distributed rendering.
</ParamField>

## Examples

### Basic rendering

Render a composition with default settings:

```bash theme={null}
helios render composition.html
```

Output: `output.mp4` at 1920x1080, 30fps

### Custom output settings

```bash theme={null}
helios render composition.html -o video.mp4 --width 3840 --height 2160 --fps 60
```

Render 4K video at 60fps.

### High quality render

```bash theme={null}
helios render composition.html --quality 18 --video-codec libx265
```

Use H.265 codec with high quality settings (CRF 18).

### Specific duration

```bash theme={null}
helios render composition.html --duration 10 -o animation.mp4
```

Render a 10-second video.

### Debug rendering

```bash theme={null}
helios render composition.html --no-headless
```

Watch the rendering process in a visible browser window.

### Render from URL

```bash theme={null}
helios render https://example.com/composition.html -o remote.mp4
```

### Partial render

```bash theme={null}
helios render composition.html --start-frame 60 --frame-count 90
```

Render frames 60-149 (90 frames starting at frame 60).

### Generate distributed job

```bash theme={null}
helios render composition.html \
  --emit-job job.json \
  --concurrency 4 \
  --base-url https://cdn.example.com/assets
```

This creates `job.json` with 4 parallel chunks, configured to load assets from the CDN.

### Custom browser arguments

```bash theme={null}
export HELIOS_BROWSER_ARGS="--no-sandbox --disable-gpu"
helios render composition.html
```

Useful for rendering in Docker or restricted environments.

## Job specification format

When using `--emit-job`, the output is a JSON file:

```json theme={null}
{
  "metadata": {
    "totalFrames": 300,
    "fps": 30,
    "width": 1920,
    "height": 1080,
    "duration": 10
  },
  "chunks": [
    {
      "id": 0,
      "startFrame": 0,
      "frameCount": 75,
      "outputFile": "chunk-0.mp4",
      "command": "helios render composition.html -o chunk-0.mp4 --start-frame 0 --frame-count 75 ..."
    },
    {
      "id": 1,
      "startFrame": 75,
      "frameCount": 75,
      "outputFile": "chunk-1.mp4",
      "command": "helios render composition.html -o chunk-1.mp4 --start-frame 75 --frame-count 75 ..."
    }
  ],
  "mergeCommand": "helios merge output.mp4 chunk-0.mp4 chunk-1.mp4 chunk-2.mp4 chunk-3.mp4"
}
```

Execute the job with:

```bash theme={null}
helios job run job.json
```

## Environment variables

### Browser configuration

<ParamField path="HELIOS_BROWSER_ARGS" type="string">
  Space-separated browser command-line arguments.
</ParamField>

```bash theme={null}
export HELIOS_BROWSER_ARGS="--no-sandbox --disable-setuid-sandbox"
```

<ParamField path="PUPPETEER_EXECUTABLE_PATH" type="string">
  Path to custom Chromium/Chrome executable.
</ParamField>

```bash theme={null}
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/chromium"
```

## Performance tips

### Parallel rendering

Use `--concurrency` for faster local rendering:

```bash theme={null}
helios render composition.html --concurrency 4
```

This splits the render into 4 parallel chunks.

### Codec selection

For fastest encoding:

```bash theme={null}
helios render composition.html --video-codec libx264 --preset ultrafast
```

For best quality:

```bash theme={null}
helios render composition.html --video-codec libx265 --quality 16
```

### Canvas vs DOM mode

Canvas mode (default) is recommended for:

* Better performance
* Consistent cross-platform results
* Complex animations

DOM mode may be better for:

* Text-heavy compositions
* Complex CSS effects
* Debugging layout issues

## Troubleshooting

### Browser not found

```bash theme={null}
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/chromium-browser"
helios render composition.html
```

### Sandbox errors in Docker

```bash theme={null}
export HELIOS_BROWSER_ARGS="--no-sandbox --disable-setuid-sandbox"
helios render composition.html
```

### Out of memory

Reduce concurrency or render in smaller chunks:

```bash theme={null}
helios render composition.html --start-frame 0 --frame-count 100
helios render composition.html --start-frame 100 --frame-count 100
```

## See also

* [helios job run](/api/cli-commands#distributed-rendering) - Execute distributed render jobs
* [helios merge](/api/cli-commands#rendering-and-video-output) - Combine video chunks