☀️ Helios

<!-- AGENT_SKIP_START: This section is for human readers only. Planning agents should skip to the next section. -->
<details>
<summary>About the development model behind Helios</summary>

> **Status:** 🚀 **Beta**

Helios is developed with AI-assisted tooling. A fleet of specialized agents handles planning, implementation, testing, and documentation — orchestrated through a structured planning-execution cycle. Human oversight directs architecture and reviews all changes before merge.

The agent prompts that drive this workflow are available in [`docs/prompts/`](./docs/prompts/) for transparency.

For project governance and roadmap, see [`docs/AGENTS.md`](./docs/AGENTS.md).
</details>
<!-- AGENT_SKIP_END -->

<div align="center">

# ☀️ Helios

### Video is Light Over Time

[![License](https://img.shields.io/badge/license-ELv2-blue.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-beta-yellow.svg)](#project-status)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![npm](https://img.shields.io/badge/npm-workspace-red.svg)](https://www.npmjs.com/)
[![GitHub](https://img.shields.io/badge/GitHub-BintzGavin%2Fhelios-black.svg)](https://github.com/BintzGavin/helios)
[![Made with](https://img.shields.io/badge/made%20with-AI%20Agents-purple.svg)](./docs/prompts/)

**A programmatic video engine that runs on web standards.**  
Stop reinventing animation in JavaScript. Use the platform.

[The Thesis](#the-thesis) • [Quick Start](#quick-start) • [Why Helios?](#why-helios) • [Documentation](#architecture) • [Roadmap](#roadmap--governance)

</div>


https://github.com/user-attachments/assets/89ee2a20-77c5-4440-ad68-9f9180d969bd


(Video created with Helios)


---

## ⚡️ Recommended Quickstart: Helios Skills

**The fastest way to get started.** We offer guided skills so that with one prompt into Claude Code, Cursor, or Opencode, Openclaw, Pi, Hermes, etc. you can generate one of six professional video types:

**1 prompt →**
• Launch announcement
• Promo
• Explainer
• Product demo
• Testimonial
• Social cut

Run this in an existing repo (preferably your marketing site):

```bash
npx skills add BintzGavin/helios-skills
```

Then tell your agent something like:

```bash
generate a product demo video using the guided helios skill.
```

This tends to get the best results using Opus 4.6 or GPT 5.4. I've gotten mixed results with Gemini 3.1 so far.

---

## Quick Start

### Installation

```bash
npm install @helios-project/core @helios-project/player
```

### Create a Composition

```typescript
import { Helios } from '@helios-engine/core';

// Create a 10-second video at 30fps
const helios = new Helios({
  duration: 10,
  fps: 30,
  autoSyncAnimations: true
});

// Subscribe to frame updates
helios.subscribe(({ currentFrame, duration, fps }) => {
  const progress = currentFrame / (duration * fps);
  // Use progress (0-1) to drive your animations
  document.querySelector('.my-element').style.opacity = progress;
});

// Control playback
helios.play();
helios.pause();
helios.seek(150); // Jump to frame 150
```

### Use Standard CSS Animations

```css
/* Your existing CSS animations just work */
@keyframes fadeIn {
  from { opacity: 0; transform: scale(0.9); }
  to { opacity: 1; transform: scale(1); }
}

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

### Preview with the Player

```html
<!-- Drop-in Web Component works anywhere -->
<helios-player src="./composition.html" width="1920" height="1080"></helios-player>
<script type="module" src="@helios-project/player"></script>
```

### Render to Video

```bash
npx helios render ./composition.html -o output.mp4
```

---

## The Thesis

### Native Always Wins

The history of software teaches a consistent lesson: **betting on native platform capabilities almost always beats simulation.**

- CSS animations replaced jQuery `.animate()` and JS-driven motion
- Native `<video>` and `<audio>` killed Flash
- IntersectionObserver replaced expensive scroll-listener hacks
- CSS Scroll Snap is displacing JavaScript carousel libraries

When the platform catches up, the abstractions built to work around it become legacy debt.

### The Remotion Era: Simulating What the Browser Already Does

[Remotion](https://www.remotion.dev/) solved programmatic video by treating the browser as a **static image generator**. Stop time. Inject a frame number. Render. Screenshot. Repeat 30 times per second.

```typescript
// Remotion: The browser is a screenshot machine
function MyComponent() {
  const frame = useCurrentFrame();  // Frame number injected from outside
  const opacity = interpolate(frame, [0, 30], [0, 1]);  // YOU calculate every value
  return <div style={{ opacity }}>Hello</div>;
}
```

This works. It's deterministic. Remotion is brilliant engineering, battle-tested, and has earned its place as the market leader.

But look at what this arc

... (truncated)