helios-renderer
Skill130 starsChanged 38 days agoApache-2.0View on GitHub
Renderer API for generating video/image output from Helios compositions. Use when you need to programmatically render a composition to a file using Node.js.
In this repository38 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- llms.txtllms.txt
- skill-creatorSkill
- helios-coreSkill
- animated-video-philosophySkill
- cinematic-product-promo-planSkill
- motion-stylesSkill
- example-canvasSkill
- example-chartjsSkill
- example-d3-animationSkill
- example-framer-motionSkill
- example-gsapSkill
- example-lottieSkill
- example-p5-animationSkill
- example-pixiSkill
- example-podcast-visualizerSkill
- example-reactSkill
- example-signals-animationSkill
- example-solidSkill
- example-svelteSkill
- example-tailwind-animationSkill
- example-threejsSkill
- example-vanillaSkill
- example-vueSkill
- helios-getting-startedSkill
- guided-brand-videoSkill
- guided-cartoon-shortSkill
- motion-design-rulesSkill
- guided-music-videoSkill
- guided-video-recipesSkill
- helios-playerSkill
- helios-skillsSkill
- helios-studioSkill
- archive-brollSkill
- create-compositionSkill
- render-videoSkill
- workflow-visualize-dataSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 109
Check the rendering environment (Playwright, WebCodecs support, FFmpeg).
- Distinctive: line 209
Use JPEG instead of PNG for faster intermediate screenshots during DOM rendering.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Helios Renderer API
The Renderer class enables headless rendering of Helios compositions using Playwright and FFmpeg. It supports both DOM-based and Canvas-based rendering strategies.
Quick Start
import { Renderer } from '@helios-project/renderer';
const renderer = new Renderer({
width: 1920,
height: 1080,
fps: 30,
durationInSeconds: 10,
mode: 'canvas', // or 'dom'
inputProps: { title: "Render Job 1" }
});
await renderer.render(
'http://localhost:3000/composition.html',
'./output.mp4',
{
onProgress: (progress) => console.log(`Rendering: ${(progress * 100).toFixed(1)}%`)
}
);API Reference
Constructor
new Renderer(options: RendererOptions)
interface RendererOptions {
width: number; // Output width
height: number; // Output height
fps: number; // Frames per second
durationInSeconds: number; // Duration of the clip
frameCount?: number; // Exact total frames (overrides durationInSeconds)
startFrame?: number; // Frame to start rendering from (default: 0)
mode?: 'dom' | 'canvas'; // Rendering strategy (default: 'canvas')
inputProps?: Record<string, any>; // Inject props into window.__HELIOS_PROPS__
// Audio Configuration
audioFilePath?: string; // Path to single audio file
audioTracks?: (string | AudioTrackConfig)[]; // List of audio tracks
audioCodec?: string; // e.g., 'aac', 'libvorbis'
audioBitrate?: string; // e.g., '128k', '192k'
// Video Encoding
videoCodec?: string; // e.g., 'libx264' (default, prioritized), 'libvpx'
pixelFormat?: string; // e.g., 'yuv420p' (default)
crf?: number; // Constant Rate Factor (quality control)
preset?: string; // Encoding preset (e.g., 'fast')
videoBitrate?: string; // e.g., '5M', '1000k'
subtitles?: boolean; // Burn subtitles into video (requires libx264)
// Intermediate Capture (Canvas Mode)
intermediateVideoCodec?: string; // 'vp8' (default), 'vp9', 'av1'
// Intermediate Capture (DOM Mode)
intermediateImageFormat?: 'png' | 'jpeg'; // Default: 'png'
intermediateImageQuality?: number; // 0-100 (only for jpeg)
// System
ffmpegPath?: string; // Custom FFmpeg binary path
browserConfig?: { // Playwright Launch Options
headless?: boolean;
executablePath?: string;
args?: string[];
};
}
interface AudioTrackConfig {
path: string;
volume?: number; // 0.0 to 1.0
offset?: number; // Start time in composition (seconds)
seek?: number; // Start time in source file (seconds)
playbackRate?: number; // Speed multiplier (default: 1.0)
}Methods
Render
Renders the composition at the given URL to a video file.
async render(
compositionUrl: string,
outputPath: string,
jobOptions?: RenderJobOptions
): Promise<void>
interface RenderJobOptions {
onProgress?: (progress: number) => void; // Callback 0.0 to 1.0
signal?: AbortSignal; // For cancellation
tracePath?: string; // Path to save Playwright trace (for debugging)
}Diagnose
Check the rendering environment (Playwright, WebCodecs support, FFmpeg).
// Returns a comprehensive diagnostic report
const diagnostics = await renderer.diagnose();
/*
{
browser: {
waapi: boolean,
webCodecs: boolean,
offscreenCanvas: boolean,
userAgent: string
},
ffmpeg: {
version: string,
encoders: string[],
filters: string[]
}
}
*/Rendering Modes
Canvas Mode (mode: 'canvas')
- Best for: WebGL, Three.js, Pixi.js, 2D Canvas.
- Mechanism: Uses
CdpTimeDriverto control time andCanvasStrategyto capture the canvas context directly. - Performance: High. Fast capture via CDP.
- Sync: Uses
TreeWalkerto recursively discover and sync media in Shadow DOMs.
DOM Mode (mode: 'dom')
- Best for: CSS Animations, HTML/DOM elements, complex video/audio compositions.
- Mechanism: Uses
SeekTimeDriver(seek & screenshot) to ensure DOM layouts settle. - Performance: Slower than Canvas mode due to full-page screenshots.
- Implicit Audio: Automatically discovers
<audio>and<video>tags in the DOM and includes their audio in the render. - Media Synchronization: Supports precise control over nested media elements using attributes:
data-helios-offset="2.5": Delay playback start by 2.5 seconds.data-helios-seek="10": Start playing from 10s into the source file.muted: Respects the HTMLmutedattribute.
- Recursive Sync: Traverses Shadow DOMs (open and closed) to find and synchronize animations and media elements.
- Stability: Waits for
seekedevents on all media elements (Multi-Frame Seek) to ensure frames are perfectly aligned before capturing.
Utilities
Distributed Rendering
Split a render job into multiple chunks to run concurrently (e.g., on multiple cores).
import { RenderOrchestrator, DistributedRenderOptions } from '@helios-project/renderer';
const options: DistributedRenderOptions = {
// ...standard Renderer options...
concurrency: 4 // Number of parallel workers (default: CPU cores - 1)
};
await RenderOrchestrator.render(
'http://localhost:3000/composition.html',
'output.mp4',
options,
{ onProgress: (p) => console.log(`Total Progress: ${p}`) }
);Concatenate Videos
Combine multiple video files into one.
import { concatenateVideos } from '@helios-project/renderer';
await concatenateVideos(['part1.mp4', 'part2.mp4'], 'full-video.mp4');Common Patterns
Caption Burning
Burn subtitles (e.g. from the player) into the video output. Requires videoCodec: 'libx264'.
const renderer = new Renderer({
// ...
videoCodec: 'libx264',
subtitles: './captions.srt' // path to an SRT file
});Range Rendering
Render only a specific section of the composition (e.g., for distributed rendering).
const renderer = new Renderer({
// ...
startFrame: 0,
durationInSeconds: 5 // Render only first 5 seconds
});
// To render the next 5 seconds:
// startFrame: 150, durationInSeconds: 5Fast Draft Renders (DOM Mode)
Use JPEG instead of PNG for faster intermediate screenshots during DOM rendering.
const renderer = new Renderer({
mode: 'dom',
intermediateImageFormat: 'jpeg',
intermediateImageQuality: 80
});Audio Mixing
Mix multiple audio tracks with offsets and volume control.
const renderer = new Renderer({
// ...
audioTracks: [
{ path: 'music.mp3', volume: 0.5 },
{ path: 'voiceover.wav', volume: 1.0, offset: 2 } // Start voice at 2s
]
});Source Files
- Main class:
packages/renderer/src/index.ts - Strategies:
packages/renderer/src/strategies/ - Types:
packages/renderer/src/types.ts
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

