render-video

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.

1. Prerequisites

Ensure your composition is running. The renderer needs a URL to access the composition.

• Locally: npm run dev (e.g., http://localhost:3000/composition.html)
• Remote: Any 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.

```bash
# 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 helios.bindToDocumentTimeline() is called in your composition.
• Ensure window.helios is exposed.
• 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.