> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/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

**input** `string` *required*

Path to composition HTML file or HTTP(S) URL.

## Output options

**--output** `string` (default: output.mp4)

Output file path. Short form: `-o`.

**--width** `number` (default: 1920)

Viewport width in pixels.

**--height** `number` (default: 1080)

Viewport height in pixels.

**--fps** `number` (default: 30)

Frames per second for output video.

**--duration** `number` (default: 1)

Duration in seconds.

**--quality** `number`

CRF quality value (0-51). Lower values = higher quality. Default varies by codec.

## Rendering options

**--mode** `string` (default: canvas)

Render mode: `canvas` or `dom`. Canvas mode is faster and more reliable.

**--no-headless** `boolean`

Run browser in visible window instead of headless mode. Useful for debugging.

**--start-frame** `number`

Frame number to start rendering from (0-based).

**--frame-count** `number`

Number of frames to render. Used for chunked rendering.

**--concurrency** `number` (default: 1)

Number of concurrent render jobs to execute in parallel.

## Codec options

**--video-codec** `string`

Video codec. Examples: `libx264`, `libx265`, `libvpx`, `libvpx-vp9`.

**--audio-codec** `string`

Audio codec. Examples: `aac`, `mp3`, `pcm_s16le`.

## Distributed rendering

**--emit-job** `string`

Generate a distributed render job specification (JSON) instead of rendering immediately.

**--base-url** `string`

Base URL for remote asset resolution in distributed jobs. Alias for `--job-base-url`.

**--job-base-url** `string`

Base URL for remote asset resolution. Used when generating job specs for distributed rendering.

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

**HELIOS\_BROWSER\_ARGS** `string`

Space-separated browser command-line arguments.

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

**PUPPETEER\_EXECUTABLE\_PATH** `string`

Path to custom Chromium/Chrome executable.

```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](https://docs.heliosrender.com/api/cli-commands.md#distributed-rendering) - Execute distributed render jobs
* [helios merge](https://docs.heliosrender.com/api/cli-commands.md#rendering-and-video-output) - Combine video chunks


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.