Installation

Install Helios packages and set up your development environment for programmatic video creation.

Installation

Helios is distributed as npm packages and works with any modern JavaScript toolchain. This guide covers installation for all supported environments.

Requirements

Before installing Helios, ensure your environment meets these requirements:

• Node.js ≥18.0.0
• npm or your preferred package manager (yarn, pnpm, bun)
• A modern browser for preview (Chrome, Edge, or Chromium-based)

For production rendering, Helios uses headless Chromium via Playwright. The browser will be automatically installed when you install the renderer package.

Core installation

The core package is required for all Helios projects:

npm install @helios-project/core

This gives you the headless Helios engine that manages animation state, timeline control, and framework adapters.

What’s included

• Helios class - Main animation engine
• Animation helpers - interpolate(), spring(), easing functions
• Framework adapters - React hooks, Vue composables, Svelte stores
• Utilities - Caption parsing, color helpers, timecode conversion
• TypeScript types - Full type definitions included

Player installation

The player package provides a Web Component for instant preview:

npm install @helios-project/player

This gives you the <helios-player> custom element that works in any HTML page, with or without a framework.

Features

• HTMLMediaElement parity - Standard play, pause, seek controls
• Client-side export - Export videos directly in the browser using WebCodecs
• Audio mixing - Multi-track audio support with volume control
• Captions - SRT subtitle rendering
• Sandboxed iframe - Composition isolation for security

Renderer installation

The renderer package enables production video output:

npm install @helios-project/renderer

This includes:

• Playwright for headless browser control
• FFmpeg binaries for video encoding
• Dual rendering strategies (DOM and Canvas)
• Distributed rendering orchestrator

The renderer package includes large dependencies (Playwright, FFmpeg). It’s recommended to install this only in your build/server environment, not in client-side bundles.

Complete installation

For a full development setup with preview and rendering capabilities:

npm

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

yarn add @helios-project/core @helios-project/player @helios-project/renderer

pnpm add @helios-project/core @helios-project/player @helios-project/renderer

bun add @helios-project/core @helios-project/player @helios-project/renderer

Framework-specific setup

Helios works with any framework. Here’s how to set up your preferred environment:

React

Helios works seamlessly with React:

npm install @helios-project/core react react-dom

Project structure:

my-helios-project/
├── package.json
├── vite.config.ts
├── index.html
└── src/
    ├── main.tsx
    ├── App.tsx
    └── hooks/
        └── useVideoFrame.ts

Vue

Vue 3 with Composition API:

npm install @helios-project/core vue

Recommended: Use Vite with the Vue plugin for optimal development experience.

Svelte

Svelte 5 with reactive stores:

npm install @helios-project/core svelte

Vanilla JavaScript

No framework needed:

npm install @helios-project/core

Helios works directly with standard JavaScript and the DOM.

Development tools

TypeScript (recommended)

All Helios packages include TypeScript definitions:

npm install -D typescript

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["vite/client"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Vite (recommended bundler)

Vite provides the best development experience with Helios:

npm install -D vite

vite.config.js:

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 3000,
  },
  build: {
    target: 'es2020',
  },
});

Verify installation

Create a simple test file to verify your installation:

test.js:

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

const helios = new Helios({
  duration: 5,
  fps: 30,
});

console.log('Helios version:', helios.constructor.name);
console.log('Total frames:', helios.getState().duration * helios.getState().fps);

Run with Node.js:

node test.js

You should see:

Helios version: Helios
Total frames: 150

Environment diagnostics

Helios includes a diagnostic tool to check your environment capabilities:

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

const report = await Helios.diagnose();
console.log(report);

// Output:
// {
//   waapi: true,           // Web Animations API
//   webCodecs: true,       // VideoEncoder support
//   offscreenCanvas: true,
//   webgl: true,
//   webgl2: true,
//   webAudio: true,
//   colorGamut: 'p3',
//   videoCodecs: {
//     h264: true,
//     vp8: true,
//     vp9: true,
//     av1: true
//   },
//   audioCodecs: {
//     aac: true,
//     opus: true
//   },
//   userAgent: '...'
// }

This helps verify that your browser supports all Helios features.

Animation library integration

Helios works with popular animation libraries out of the box:

GSAP

npm install gsap

GSAP timelines are driven by Helios automatically.

Framer Motion

npm install framer-motion

Framer Motion animations sync with Helios playback.

Motion One

npm install motion

Motion One uses the Web Animations API natively.

Lottie

npm install lottie-web

Render After Effects animations programmatically.

These libraries work with Helios because it drives the browser’s animation engine. No special integration code required—just create your animations normally.

Canvas library integration

For canvas-based compositions:

Three.js (3D graphics)

npm install three

Optional React bindings:

npm install @react-three/fiber @react-three/drei

Pixi.js (2D WebGL)

npm install pixi.js

P5.js (Creative coding)

npm install p5

Chart.js (Data visualization)

npm install chart.js

D3.js (Data-driven documents)

npm install d3

FFmpeg (for rendering)

The renderer package includes FFmpeg binaries automatically via @ffmpeg-installer/ffmpeg. No manual installation needed.

Using system FFmpeg

If you prefer to use your system’s FFmpeg installation:

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

const renderer = new Renderer({
  width: 1920,
  height: 1080,
  fps: 30,
  ffmpegPath: '/usr/local/bin/ffmpeg', // Your system path
});

Verify FFmpeg

Check FFmpeg capabilities:

npx helios diagnose

This shows available hardware acceleration and codec support.

Next steps

1. Create your first composition

   Follow the Quickstart guide to build a working video in minutes.

2. Explore examples

   Check out the examples directory for inspiration.

3. Read the API docs

   Learn about the Helios API, animation helpers, and rendering options.

Troubleshooting

Module not found errors

Ensure you’re using a bundler that supports ES modules (Vite, Webpack 5+, Rollup).

TypeScript errors

Make sure "moduleResolution": "bundler" or "moduleResolution": "node" is set in your tsconfig.json.

Player not rendering

The <helios-player> Web Component must be imported before use:

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

Rendering fails

Check that:

1. Your composition exposes a helios instance on window
2. FFmpeg is installed and accessible
3. The composition URL is reachable

Run diagnostics:

npx helios diagnose