Skip to main content

​
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 install @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

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 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

Build docs developers (and LLMs) love

Get started for freeTalk to us