helios

About the development model behind Helios

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/ for transparency.

For project governance and roadmap, see docs/AGENTS.md.

Video is light over time.

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

The Thesis • Quick Start • Why Helios? • Documentation • Roadmap

⚡️ 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):

npx skills add BintzGavin/helios

Then tell your agent something like:

generate a product demo video using the guided helios skill.

Quick Start

Installation

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

Create a Composition

import { Helios } from '@helios-project/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;
});

// Let the renderer (and the player) drive it
window.helios = helios;

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

Use Standard CSS Animations

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

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

npx @helios-project/cli render ./composition.html -o output.mp4

The duration, frame rate and size come from the composition. Any page that draws its own frames renders too, with no Helios import. The renderer calls window.renderAt(t) once per frame, with t in seconds:

<canvas id="c" width="1920" height="1080"></canvas>
<script>
  const ctx = document.getElementById('c').getContext('2d');
  window.renderAt = (t) => {
    ctx.fillStyle = '#111'; ctx.fillRect(0, 0, 1920, 1080);
    ctx.fillStyle = '#f5b700'; ctx.fillRect(200 + 300 * t, 480, 120, 120);
  };
</script>

npx @helios-project/cli render ./page.html -o output.mp4 --duration 5 --audio song.mp3

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

// 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 architecture requires: reimplementing animation in JavaScript. The browser has a world-class animation engine—CSS @keyframes, hardware-accelerated compositing, the Web Animations API—but the frame-based model says: "Ignore all of that. We'll simulate it ourselves."

Your CSS animations? Broken—the system clock drifts during render.
Your GSAP timelines? Need custom integration.
The browser's C++ compositor? Bypassed entirely.

This is a simulation-based architecture. It works despite the browser, not with it.

The Helios Bet: Drive the Browser, Don't Simulate It

Helios takes a different bet: what if we drove the browser's native animation engine instead of replacing it?

The approach varies by context:

For Production Rendering: Helios uses the Chrome DevTools Protocol (CDP) to virtualize time at the environment level. The Emulation.setVirtualTimePolicy command detaches the browser's internal clock from wall-clock time, allowing the renderer to advance time frame-by-frame as fast as the CPU allows. The browser's native animation engine calculates all interpolated values—we just tell it what time it is.

For Preview/Development: Helios uses the Web Animations API to seek individual animations. Every Animation object has a writable .currentTime property:

// Seek all animations to 1.5 seconds
document.getAnimations().forEach(anim => {
  anim.currentTime = 1500;
  anim.pause();
});

When you set animation.currentTime, the browser's C++ rendering engine recalculates all interpolated values. Hardware-accelerated. Using the same optimized code that powers every CSS animation on the web.

The result for developers:

/* Your existing CSS. No changes. */
@keyframes fadeIn {
  from { opacity: 0; transform: scale(0.9); }
  to { opacity: 1; transform: scale(1); }
}

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

// Helios drives the browser's animation engine
const helios = new Helios({ duration: 10, fps: 30, autoSyncAnimations: true });
helios.seek(45); // All CSS/WAAPI animations instantly update to frame 45

That's it. Your CSS animations, your GSAP timelines, your Framer Motion springs—they work because the browser is doing the animation, not JavaScript.

The Honest Trade-off

This is a native-aligned architecture, but it's not without constraints:

• Browser-specific: CDP is Chromium-only. Helios renders in headless Chrome.
• Non-standard time control: The W3C spec marks document.timeline.currentTime as read-only. We work around this via protocol-level control, not by violating the spec.
• A bet, not a certainty: We're betting that platform capabilities will mature and this approach will become standard. If we're wrong, simulation-based architectures like Remotion will continue to dominate.

But if history is any guide—native mobile vs PhoneGap, CSS Grid vs JavaScript layouts, fetch() vs jQuery—native-aligned architectures eventually win.

We named this engine after the sun because video is, fundamentally, light over time.

Why Helios?

Use What You Know

No proprietary APIs to learn. Your existing CSS animations, GSAP timelines, and Motion/Framer Motion animations work out of the box.

Any Framework (or None)

// React
const { currentFrame } = useVideoFrame();

// Vue
const { currentFrame } = useVideoFrame();

// Svelte
$: currentFrame = $videoFrame.currentFrame;

// Vanilla JS
helios.subscribe(state => console.log(state.currentFrame));

Free for Commercial Use

Build and sell products with Helios. No per-seat fees, no render limits.

Core Principles

The development of Helios is guided by foundational principles that inform every architectural decision:

Agent Experience First

As AI agents become primary users of developer tools, Helios prioritizes Agent Experience (AX)—the holistic experience AI agents have when using our APIs and platform. Great AX means:

• Predictable APIs - Consistent patterns, no magic
• Clear error messages - Machine-readable, actionable errors
• Machine-readable documentation - Structured for LLM consumption
• Composable primitives - Work well with LLM-driven workflows

DX and AX are deeply aligned—what works for agents works for humans too.

Prototype Fast, Scale Later

Start with a simple composition, preview instantly in your browser, and only worry about rendering infrastructure when you're ready to ship.

Use What You Know

Pure TypeScript with zero framework dependencies. Use React, Vue, Svelte, or vanilla JS—whatever you're already comfortable with.

Leverage Web Standards

Native browser APIs over custom implementations. CSS animations, Web Animations API (WAAPI), and standard DOM APIs. Your existing web development skills transfer directly.

Performance When It Matters

Hardware-accelerated rendering, in-memory data piping, and WebCodecs support for canvas-heavy work. Performance is there when you need it.

AI & Agent Integration

Helios is designed from the ground up for AI-assisted development. Whether you're using Claude, Cursor, GitHub Copilot, or autonomous agent systems, Helios provides first-class support.

For AI Coding Assistants

AI-Ready Documentation:

• llms.txt - Machine-readable project overview at /llms.txt
• Markdown URLs - Add .md to any doc URL for raw markdown (planned)
• Structured errors - All errors are machine-parseable with actionable guidance

For Autonomous Agent Systems

Helios uses a Black Hole Architecture where AI agents continuously pull the codebase toward this documented vision. If you're building similar systems: