Skip to main content
The render command converts a Helios composition into a video file using headless browser rendering.

​
Usage

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: 
helios render composition.html
Output: output.mp4 at 1920x1080, 30fps

​
Custom output settings

helios render composition.html -o video.mp4 --width 3840 --height 2160 --fps 60
Render 4K video at 60fps.

​
High quality render

helios render composition.html --quality 18 --video-codec libx265
Use H.265 codec with high quality settings (CRF 18).

​
Specific duration

helios render composition.html --duration 10 -o animation.mp4
Render a 10-second video.

​
Debug rendering

helios render composition.html --no-headless
Watch the rendering process in a visible browser window.

​
Render from URL

helios render https://example.com/composition.html -o remote.mp4

​
Partial render

helios render composition.html --start-frame 60 --frame-count 90
Render frames 60-149 (90 frames starting at frame 60).

​
Generate distributed job

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

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: 
{
  "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: 
helios job run job.json

​
Environment variables

​
Browser configuration

​
HELIOS_BROWSER_ARGS
string
Space-separated browser command-line arguments.
export HELIOS_BROWSER_ARGS="--no-sandbox --disable-setuid-sandbox"
​
PUPPETEER_EXECUTABLE_PATH
string
Path to custom Chromium/Chrome executable.
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/chromium"

​
Performance tips

​
Parallel rendering

Use --concurrency for faster local rendering: 
helios render composition.html --concurrency 4
This splits the render into 4 parallel chunks.

​
Codec selection

For fastest encoding: 
helios render composition.html --video-codec libx264 --preset ultrafast
For best quality: 
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

export PUPPETEER_EXECUTABLE_PATH="/usr/bin/chromium-browser"
helios render composition.html

​
Sandbox errors in Docker

export HELIOS_BROWSER_ARGS="--no-sandbox --disable-setuid-sandbox"
helios render composition.html

​
Out of memory

Reduce concurrency or render in smaller chunks: 
helios render composition.html --start-frame 0 --frame-count 100
helios render composition.html --start-frame 100 --frame-count 100

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us