helios render

Render a composition to video file

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

• helios job run - Execute distributed render jobs
• helios merge - Combine video chunks