helios-getting-started
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.
Best use case
helios-getting-started is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using helios-getting-started should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/getting-started/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How helios-getting-started Compares
| Feature / Agent | helios-getting-started | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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.
```bash
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.
```bash
npm install @helios-project/renderer
```
### Quick Install (Core + Renderer)
For most use cases—creating MP4 videos—install both core and renderer:
```bash
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.
```bash
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:
```html
<!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:
```typescript
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
});
// Bind to document timeline (CRITICAL for Renderer/Player)
helios.bindToDocumentTimeline();
// Expose to window (CRITICAL for detection)
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:
```css
@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:
```bash
npx helios render ./composition.html -o output.mp4
```
Or use the Renderer package programmatically:
```typescript
import { render } from '@helios-project/renderer';
await render({
input: './composition.html',
output: './output.mp4',
width: 1920,
height: 1080,
fps: 30
});
```
### 5. Preview with the Player (Optional)
If you installed the player package, use the `<helios-player>` web component for preview during development:
```html
<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:**
```typescript
import { useVideoFrame } from '@helios-project/core/react';
function MyComponent() {
const { currentFrame } = useVideoFrame();
return <div>Frame: {currentFrame}</div>;
}
```
**Vue:**
```typescript
import { useVideoFrame } from '@helios-project/core/vue';
const { currentFrame } = useVideoFrame();
```
**Svelte:**
```typescript
import { videoFrame } from '@helios-project/core/svelte';
$: currentFrame = $videoFrame.currentFrame;
```
**Vanilla JS:**
```typescript
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 created**: `new Helios({ duration, fps })`
- [ ] **Timeline bound**: `helios.bindToDocumentTimeline()` called
- [ ] **Window exposed**: `window.helios = helios` set
- [ ] **State subscribed**: `helios.subscribe(...)` used to trigger renders
- [ ] **Canvas/DOM ready**: Elements are sized correctly
## Next Steps
- See `helios/core` skill for detailed API reference
- See `helios/workflows/create-composition` for composition creation workflow
- See `helios/examples/react` or `helios/examples/vue` for framework-specific patterns
- See `helios/renderer` for rendering pipeline details
## Troubleshooting
**"Cannot find module '@helios-project/core'"**
- Ensure you've run `npm install @helios-project/core`
- Check that your bundler (Vite, Webpack, etc.) is configured correctly
**Animations not syncing**
- Ensure `autoSyncAnimations: true` is set in the Helios constructor
- Call `helios.bindToDocumentTimeline()` after creating the instance
**Renderer fails**
- FFmpeg is bundled with the renderer package, so no manual installation needed
- Check that Chrome/Chromium is available (Playwright should install it automatically)
- If you need to use a custom FFmpeg path, set `ffmpegPath` in renderer options
**Player not detecting composition**
- Ensure `window.helios = helios` is set
- Verify the composition HTML file path is correctRelated Skills
helios-skills
Collection of agent skills for Helios video engine. Use when working with programmatic video creation, browser-native animations, or Helios compositions. Install individual skills by path for specific capabilities.
helios-studio
Studio tool for developing and previewing Helios compositions. Use when you want to launch the interactive development environment or manage assets.
helios-renderer
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.
helios-player
Player API for embedding Helios compositions in web pages. Use when you need to display a composition with playback controls, enable client-side exporting, or support Picture-in-Picture.
helios-core
Core API for Helios video engine. Use when creating compositions, managing timeline state, controlling playback, or subscribing to frame updates. Covers Helios class instantiation, signals, animation helpers, and DOM synchronization.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
workflow-visualize-data
Workflow for creating data-driven animations. Use when you need to visualize datasets using D3, P5, or other libraries.
render-video
Workflow for rendering a Helios composition to a video file. Use when you need to automate video production or export a high-quality animation.
create-composition
Workflow for creating a new Helios composition. Use when building a new animation project or converting an existing animation to run in Helios.
guided-testimonial-video
End-to-end guided workflow for creating a social proof or testimonial video. Extracts brand identity from the repo, generates a warm soundtrack, and produces a trust-building motion.dev composition rendered via Helios CLI. Use when making customer testimonial, review highlight, or social proof videos.
guided-social-clip
End-to-end guided workflow for creating a short-form social media clip (Reels, TikTok, Shorts). Extracts brand identity from the repo, generates a punchy soundtrack, and produces a vertical 9:16 motion.dev composition rendered via Helios CLI. Use when making Instagram Reels, TikTok videos, YouTube Shorts, or other vertical short-form content.
motion-design-rules
Motion design framework for programmatic video. Defines anti-slideshow architecture, visual layering, physics-based easing, choreography rules, and quality validation. Reference this skill from any guided video skill.