> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## Core installation

The core package is required for all Helios projects:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

<Warning>
  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.
</Warning>

## Complete installation

For a full development setup with preview and rendering capabilities:

<CodeGroup>
  ```bash npm theme={null}
  npm install @helios-project/core @helios-project/player @helios-project/renderer
  ```

  ```bash yarn theme={null}
  yarn add @helios-project/core @helios-project/player @helios-project/renderer
  ```

  ```bash pnpm theme={null}
  pnpm add @helios-project/core @helios-project/player @helios-project/renderer
  ```

  ```bash bun theme={null}
  bun add @helios-project/core @helios-project/player @helios-project/renderer
  ```
</CodeGroup>

## Framework-specific setup

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

### React

Helios works seamlessly with React:

```bash theme={null}
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:

```bash theme={null}
npm install @helios-project/core vue
```

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

### Svelte

Svelte 5 with reactive stores:

```bash theme={null}
npm install @helios-project/core svelte
```

### Vanilla JavaScript

No framework needed:

```bash theme={null}
npm install @helios-project/core
```

Helios works directly with standard JavaScript and the DOM.

## Development tools

### TypeScript (recommended)

All Helios packages include TypeScript definitions:

```bash theme={null}
npm install -D typescript
```

**tsconfig.json:**

```json theme={null}
{
  "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:

```bash theme={null}
npm install -D vite
```

**vite.config.js:**

```javascript theme={null}
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:**

```javascript theme={null}
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:

```bash theme={null}
node test.js
```

You should see:

```
Helios version: Helios
Total frames: 150
```

## Environment diagnostics

Helios includes a diagnostic tool to check your environment capabilities:

```typescript theme={null}
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

```bash theme={null}
npm install gsap
```

GSAP timelines are driven by Helios automatically.

### Framer Motion

```bash theme={null}
npm install framer-motion
```

Framer Motion animations sync with Helios playback.

### Motion One

```bash theme={null}
npm install motion
```

Motion One uses the Web Animations API natively.

### Lottie

```bash theme={null}
npm install lottie-web
```

Render After Effects animations programmatically.

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

## Canvas library integration

For canvas-based compositions:

### Three.js (3D graphics)

```bash theme={null}
npm install three
```

Optional React bindings:

```bash theme={null}
npm install @react-three/fiber @react-three/drei
```

### Pixi.js (2D WebGL)

```bash theme={null}
npm install pixi.js
```

### P5.js (Creative coding)

```bash theme={null}
npm install p5
```

### Chart.js (Data visualization)

```bash theme={null}
npm install chart.js
```

### D3.js (Data-driven documents)

```bash theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
npx helios diagnose
```

This shows available hardware acceleration and codec support.

## Next steps

<Steps>
  <Step title="Create your first composition">
    Follow the [Quickstart](/quickstart) guide to build a working video in minutes.
  </Step>

  <Step title="Explore examples">
    Check out the [examples directory](https://github.com/BintzGavin/helios/tree/main/examples) for inspiration.
  </Step>

  <Step title="Read the API docs">
    Learn about the Helios API, animation helpers, and rendering options.
  </Step>
</Steps>

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

```html theme={null}
<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:

```bash theme={null}
npx helios diagnose
```