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.