/getting-started

name: helios-getting-started
description: Installation and quick start guide for Helios video engine. Use when setting up a new Helios project, installing packages, or creating your first composition. Covers package installation, requirements, basic setup, and initial composition structure.

Helios Getting Started

Quick installation and setup guide for Helios, a browser-native video engine for programmatic animation and rendering.

Requirements

Before installing Helios, ensure you have:

• **Node.js**: v18 or higher (recommended)
• **npm** or **yarn** package manager
• **Chrome/Chromium**: Required for rendering (automatically installed by Playwright)

FFmpeg (Automatically Included)

**Good news:** FFmpeg is automatically bundled with `@helios-project/renderer` via the `@ffmpeg-installer/ffmpeg` package. You don't need to install it manually!

The renderer package includes platform-specific FFmpeg binaries that work out of the box. If you prefer to use a system-installed FFmpeg instead, you can specify a custom path via the `ffmpegPath` option in the renderer configuration.

Installation

Helios is modular—install only what you need.

Core Package (Required)

The `@helios-project/core` package contains the engine logic, timing drivers, and animation helpers. This is required for any composition.

npm install @helios-project/core

Renderer Package (Recommended)

The `@helios-project/renderer` package is a Node.js library for rendering compositions to video files (MP4, etc.) using Headless Chrome and FFmpeg. **Most users want to create MP4 files**, so this is the recommended second package.

npm install @helios-project/renderer

Quick Install (Core + Renderer)

For most use cases—creating MP4 videos—install both core and renderer:

npm install @helios-project/core @helios-project/renderer

Player Package (Optional - For Preview/Development)

The `@helios-project/player` package provides the `<helios-player>` web component for embedding compositions with playback controls. Useful for previewing compositions during development, but not required for rendering.

npm install @helios-project/player

Basic Setup

1. Create a Composition File

Create an HTML file (e.g., `composition.html`) that will serve as your composition:

<!DOCTYPE html>
<html>
<head>
    <title>My Composition</title>
    <style>
        body { margin: 0; overflow: hidden; background: black; }
        canvas { display: block; width: 100vw; height: 100vh; }
    </style>
</head>
<body>
    <canvas id="canvas"></canvas>
    <script type="module" src="./src/main.js"></script>
</body>
</html>

2. Initialize Helios

In your JavaScript file (`src/main.js`), import and initialize Helios:

import { Helios } from '@helios-project/core';

// Create a 10-second video at 30fps
const helios = new Helios({
  duration: 10,  // seconds
  fps: 30,
  width: 1920,
  height: 1080,
  autoSyncAnimations: true  // Sync CSS/WAAPI animations
});

// Optional: follow the page clock, so opening the file in a browser plays it.
helios.bindToDocumentTimeline();

// Required: the renderer and the player find and drive the composition through window.helios.
window.helios = helios;

// Subscribe to frame updates
helios.subscribe((state) => {
  const { currentFrame, duration, fps } = state;
  const progress = currentFrame / (duration * fps);
  
  // Render your frame here
  const canvas = document.getElementById('canvas');
  const ctx = canvas.getContext('2d');
  
  // Example: Draw something based on progress
  ctx.fillStyle = 'white';
  ctx.fillRect(0, 0, canvas.width * progress, canvas.height);
});

// Initial render
const state = helios.getState();
helios.subscribe((state) => {
  // Render logic here
})();

3. Use Standard CSS Animations

Your existing CSS animations work without modification:

@keyframes fadeIn {
  from { opacity: 0; transform: scale(0.9); }
  to { opacity: 1; transform: scale(1); }
}

.my-element {
  animation: fadeIn 1s ease-out forwards;
}

When you call `helios.seek(45)`, all CSS/WAAPI animations instantly update to frame 45.

4. Render to Video

**This is the primary use case**—most users want to create MP4 files from their compositions.

Use the CLI to render your composition:

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

Or use the Renderer package programmatically:

import { Renderer } from '@helios-project/renderer';
import { pathToFileURL } from 'node:url';

const renderer = new Renderer({ width: 1920, height: 1080, fps: 30, durationInSeconds: 10, mode: 'dom' });
await renderer.render(pathToFileURL('./composition.html').href, './output.mp4');

5. Preview with the Player (Optional)

If you installed the player package, use the `<helios-player>` web component for preview during development:

<helios-player src="./composition.html" width="1920" height="1080"></helios-player>
<script type="module" src="@helios-project/player"></script>

Framework Integration

Helios works with any framework or vanilla JavaScript:

**React:**

import { useVideoFrame } from '@helios-project/core/react';

function MyComponent() {
  const { currentFrame } = useVideoFrame();
  return <div>Frame: {currentFrame}</div>;
}

**Vue:**

import { useVideoFrame } from '@helios-project/core/vue';

const { currentFrame } = useVideoFrame();

**Svelte:**

import { videoFrame } from '@helios-project/core/svelte';

$: currentFrame = $videoFrame.currentFrame;

**Vanilla JS:**

helios.subscribe(state => {
  console.log(state.currentFrame);
});

Checklist

When setting up a new Helios composition, ensure:

• [ ] **Core package installed**: `npm install @helios-project/core`
• [ ] **Renderer package installed** (for MP4 output): `npm install @helios-project/renderer`
• [ ] **Helios instance