/render-video

name: render-video
description: Workflow for rendering a Helios composition to a video file. Use when you need to automate video production or export a high-quality animation.

Render Video Workflow

Rendering is the process of capturing a composition frame-by-frame and encoding it into a video file (e.g., MP4). This is done using the `@helios-project/renderer` package in a Node.js environment.

The quick path: one command

npx -y @helios-project/cli@latest render composition.html -o output.mp4

• The duration, fps and size come from the composition's `window.helios`. To set them yourself, pass `--duration`, `--fps`, `--width` and `--height`.
• A page that draws itself with `window.renderAt(t)` needs `--duration`.
• `--audio track.mp3` adds a soundtrack.
• A plain HTML file renders directly from disk. If a bundler has to build the composition, run `npm run dev` and pass its URL instead.

Use the script below only when you need a custom pipeline, such as input props, several audio tracks, or progress callbacks.

1. Prerequisites

The renderer needs a URL for the composition:

• A file on disk: `file:///path/to/composition.html`
• A dev server: `npm run dev`, e.g. `http://localhost:3000/composition.html`
• Any other accessible URL

2. Create Render Script

Create a file named `render.js` (or `render.ts` if using `ts-node`).

import { Renderer } from '@helios-project/renderer';
import path from 'path';

async function main() {
    // 1. Configuration
    const compositionUrl = 'http://localhost:3000/composition.html';
    const outputPath = path.resolve('output.mp4');

    // 2. Initialize Renderer
    const renderer = new Renderer({
        width: 1920,
        height: 1080,
        fps: 30,
        durationInSeconds: 10,
        // frameCount: 300, // Optional: Override durationInSeconds with exact frame count
        mode: 'canvas', // Use 'dom' if your animation uses CSS/HTML elements

        // Audio Configuration
        audioTracks: [
            { path: 'background.mp3', volume: 0.5 },
            { path: 'voiceover.wav', offset: 2 }
        ],
        audioCodec: 'aac',

        // Input Props (Dynamic Content)
        inputProps: {
            title: "Custom Render",
            color: "#00ff00"
        }
    });

    console.log(`Starting render of ${compositionUrl}...`);

    // 3. Execute Render
    try {
        await renderer.render(compositionUrl, outputPath, {
            onProgress: (p) => {
                const percent = Math.round(p * 100);
                process.stdout.write(`\rProgress: ${percent}%`);
            }
        });
        console.log(`\nDone! Saved to ${outputPath}`);
    } catch (err) {
        console.error('\nRender failed:', err);
        process.exit(1);
    }
}

main();

3. Run Render

Execute the script.

# If using ts-node
npx ts-node render.ts

# If using node (compiled js)
node render.js

Troubleshooting

"Page timeout" or "Connection refused"

• Ensure the local server hosting the composition is running.
• Check if the URL is correct and accessible in a regular browser.

"Black output" or "Empty video"

• Ensure `window.helios` is exposed (or the page defines `window.renderAt(t)`).
• If using `mode: 'canvas'`, ensure you are drawing to a `<canvas>` element.
• If using `mode: 'dom'`, ensure elements are visible.

"Render hangs"

• Check if the composition has errors in the browser console.
• Enable tracing to debug:

  await renderer.render(url, out, { tracePath: 'trace.zip' });

Audio Issues

• Ensure audio file paths are correct relative to where the script is run.
• If using `mode: 'dom'` and relying on implicit audio (e.g. `<audio>` tags), ensure the elements are present in the DOM.