Skip to content
Back to search

helios

MarketplaceWorks with Claude CodeGitHub

Programmatic video creation with web technologies you already know. CSS animations just work.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/BintzGavin/helios with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/BintzGavin/helios'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bintzgavin--helios/badge.svg)](/listings/bintzgavin--helios)

HTML

<a href="/listings/bintzgavin--helios"><img src="/api/listings/bintzgavin--helios/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "helios",
  3. "owner": {
  4. "name": "Gavin Bintz",
  5. "url": "https://github.com/BintzGavin"
  6. },
  7. "metadata": {
  8. "description": "Make videos from code with Helios: one HTML page, rendered frame-exact to MP4."
  9. },
  10. "plugins": [
  11. {
  12. "name": "helios",
  13. "source": "./plugins/helios",
  14. "description": "Make videos drawn with code, such as motion graphics, launch and explainer videos, animated charts, logo reveals and social clips: write one HTML page that draws each frame from its time, render it to MP4 with Helios, check the frames, add a soundtrack.",
  15. "homepage": "https://github.com/BintzGavin/helios",
  16. "keywords": ["video", "mp4", "animation", "motion graphics", "music video", "explainer", "rendering"]
  17. }
  18. ]
  19. }
README.md · README · 693 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- AGENT_SKIP_START: This section is for human readers only. Planning agents should skip to the next section. -->
  2. <details>
  3. <summary>About the development model behind Helios</summary>
  4. > **Status:** 🚀 **Beta**
  5. 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.
  6. The agent prompts that drive this workflow are available in [`docs/prompts/`](./docs/prompts/) for transparency.
  7. For project governance and roadmap, see [`docs/AGENTS.md`](./docs/AGENTS.md).
  8. </details>
  9. <!-- AGENT_SKIP_END -->
  10. <div align="center">
  11. <picture>
  12. <source media="(prefers-color-scheme: dark)" srcset="assets/brand/lockup-horizontal-bone.svg">
  13. <img src="assets/brand/lockup-horizontal.svg" alt="Helios" width="360">
  14. </picture>
  15. ### Video is light over time.
  16. [![License](https://img.shields.io/badge/license-ELv2-blue.svg)](LICENSE)
  17. [![Status](https://img.shields.io/badge/status-beta-yellow.svg)](#project-status)
  18. [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
  19. [![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
  20. [![npm](https://img.shields.io/badge/npm-workspace-red.svg)](https://www.npmjs.com/)
  21. [![GitHub](https://img.shields.io/badge/GitHub-BintzGavin%2Fhelios-black.svg)](https://github.com/BintzGavin/helios)
  22. [![Made with](https://img.shields.io/badge/made%20with-AI%20Agents-purple.svg)](./docs/prompts/)
  23. **A programmatic video engine that runs on web standards.**
  24. Stop reinventing animation in JavaScript. Use the platform.
  25. [The Thesis](#the-thesis) • [Quick Start](#quick-start) • [Why Helios?](#why-helios) • [Documentation](#architecture) • [Roadmap](#roadmap--governance)
  26. </div>
  27. ---
  28. ## ⚡️ Recommended Quickstart: Helios Skills
  29. **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:
  30. **1 prompt →**
  31. • Launch announcement
  32. • Promo
  33. • Explainer
  34. • Product demo
  35. • Testimonial
  36. • Social cut
  37. Run this in an existing repo (preferably your marketing site):
  38. ```bash
  39. npx skills add BintzGavin/helios
  40. ```
  41. Then tell your agent something like:
  42. ```bash
  43. generate a product demo video using the guided helios skill.
  44. ```
  45. ## Quick Start
  46. ### Installation
  47. ```bash
  48. npm install @helios-project/core @helios-project/player
  49. ```
  50. ### Create a Composition
  51. ```typescript
  52. import { Helios } from '@helios-project/core';
  53. // Create a 10-second video at 30fps
  54. const helios = new Helios({
  55. duration: 10,
  56. fps: 30,
  57. autoSyncAnimations: true
  58. });
  59. // Subscribe to frame updates
  60. helios.subscribe(({ currentFrame, duration, fps }) => {
  61. const progress = currentFrame / (duration * fps);
  62. // Use progress (0-1) to drive your animations
  63. document.querySelector('.my-element').style.opacity = progress;
  64. });
  65. // Let the renderer (and the player) drive it
  66. window.helios = helios;
  67. // Control playback
  68. helios.play();
  69. helios.pause();
  70. helios.seek(150); // Jump to frame 150
  71. ```
  72. ### Use Standard CSS Animations
  73. ```css
  74. /* Your existing CSS animations just work */
  75. @keyframes fadeIn {
  76. from { opacity: 0; transform: scale(0.9); }
  77. to { opacity: 1; transform: scale(1); }
  78. }
  79. .my-element {
  80. animation: fadeIn 1s ease-out;
  81. }
  82. ```
  83. ### Preview with the Player
  84. ```html
  85. <!-- Drop-in Web Component works anywhere -->
  86. <helios-player src="./composition.html" width="1920" height="1080"></helios-player>
  87. <script type="module" src="@helios-project/player"></script>
  88. ```
  89. ### Render to Video
  90. ```bash
  91. npx @helios-project/cli render ./composition.html -o output.mp4
  92. ```
  93. 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:
  94. ```html
  95. <canvas id="c" width="1920" height="1080"></canvas>
  96. <script>
  97. const ctx = document.getElementById('c').getContext('2d');
  98. window.renderAt = (t) => {
  99. ctx.fillStyle = '#111'; ctx.fillRect(0, 0, 1920, 1080);
  100. ctx.fillStyle = '#f5b700'; ctx.fillRect(200 + 300 * t, 480, 120, 120);
  101. };
  102. </script>
  103. ```
  104. ```bash
  105. npx @helios-project/cli render ./page.html -o output.mp4 --duration 5 --audio song.mp3
  106. ```
  107. ---
  108. ## The Thesis
  109. ### Native Always Wins
  110. The history of software teaches a consistent lesson: **betting on native platform capabilities almost always beats simulation.**
  111. - CSS animations replaced jQuery `.animate()` and JS-driven motion
  112. - Native `<video>` and `<audio>` killed Flash
  113. - IntersectionObserver replaced expensive scroll-listener hacks
  114. - CSS Scroll Snap is displacing JavaScript carousel libraries
  115. When the platform catches up, the abstractions built to work around it become legacy debt.
  116. ### The Remotion Era: Simulating What the Browser Already Does
  117. [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.
  118. ```typescript
  119. // Remotion: The browser is a screenshot machine
  120. function MyComponent() {
  121. const frame = useCurrentFrame(); // Frame number injected from outside
  122. const opacity = interpolate(frame, [0, 30], [0, 1]); // YOU calculate every value
  123. return <div style={{ opacity }}>Hello</div>;
  124. }
  125. ```
  126. This works. It's deterministic. Remotion is brilliant engineering, battle-tested, and has earned its place as the market leader.
  127. 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."*
  128. Your CSS animations? Broken—the system clock drifts during render.
  129. Your GSAP timelines? Need custom integration.
  130. The browser's C++ compositor? Bypassed entirely.
  131. This is a **simulation-based architecture**. It works *despite* the browser, not *with* it.
  132. ### The Helios Bet: Drive the Browser, Don't Simulate It
  133. Helios takes a different bet: **what if we drove the browser's native animation engine instead of replacing it?**
  134. The approach varies by context:
  135. **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.
  136. **For Preview/Development:** Helios uses the Web Animations API to seek individual animations. Every `Animation` object has a writable `.currentTime` property:
  137. ```typescript
  138. // Seek all animations to 1.5 seconds
  139. document.getAnimations().forEach(anim => {
  140. anim.currentTime = 1500;
  141. anim.pause();
  142. });
  143. ```
  144. 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.
  145. **The result for developers:**
  146. ```css
  147. /* Your existing CSS. No changes. */
  148. @keyframes fadeIn {
  149. from { opacity: 0; transform: scale(0.9); }
  150. to { opacity: 1; transform: scale(1); }
  151. }
  152. .my-element {
  153. animation: fadeIn 1s ease-out forwards;
  154. }
  155. ```
  156. ```typescript
  157. // Helios drives the browser's animation engine
  158. const helios = new Helios({ duration: 10, fps: 30, autoSyncAnimations: true });
  159. helios.seek(45); // All CSS/WAAPI animations instantly update to frame 45
  160. ```
  161. **That's it.** Your CSS animations, your GSAP timelines, your Framer Motion springs—they work because the browser is doing the animation, not JavaScript.
  162. ### The Honest Trade-off
  163. This is a **native-aligned architecture**, but it's not without constraints:
  164. - **Browser-specific:** CDP is Chromium-only. Helios renders in headless Chrome.
  165. - **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.
  166. - **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.
  167. But if history is any guide—native mobile vs PhoneGap, CSS Grid vs JavaScript layouts, `fetch()` vs jQuery—native-aligned architectures eventually win.
  168. We named this engine after the sun because video is, fundamentally, *light over time*.
  169. ---
  170. ## Why Helios?
  171. ### Use What You Know
  172. No proprietary APIs to learn. Your existing CSS animations, GSAP timelines, and Motion/Framer Motion animations work out of the box.
  173. | Helios | Remotion |
  174. |--------|----------|
  175. | `@keyframes fadeIn { ... }` | `interpolate(frame, [0, 30], [0, 1])` |
  176. | Standard CSS, WAAPI | Custom hooks on every frame |
  177. | Any animation library | Must use their helpers |
  178. ### Any Framework (or None)
  179. ```typescript
  180. // React
  181. const { currentFrame } = useVideoFrame();
  182. // Vue
  183. const { currentFrame } = useVideoFrame();
  184. // Svelte
  185. $: currentFrame = $videoFrame.currentFrame;
  186. // Vanilla JS
  187. helios.subscribe(state => console.log(state.currentFrame));
  188. ```
  189. ### Free for Commercial Use
  190. Build and sell products with Helios. No per-seat fees, no render limits.
  191. | | Helios | Remotion |
  192. |---|--------|----------|
  193. | **Solo developer** | Free | Free |
  194. | **4-person team** | Free | $100/mo |
  195. | **10-person team** | Free | $250/mo |
  196. | **100 renders/mo** | Free | +$10/mo |
  197. ---
  198. ## Core Principles
  199. <!-- AGENT_VISION_START: These principles guide all architectural decisions -->
  200. The development of Helios is guided by foundational principles that inform every architectural decision:
  201. ### Agent Experience First
  202. 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:
  203. - **Predictable APIs** - Consistent patterns, no magic
  204. - **Clear error messages** - Machine-readable, actionable errors
  205. - **Machine-readable documentation** - Structured for LLM consumption
  206. - **Composable primitives** - Work well with LLM-driven workflows
  207. DX and AX are deeply aligned—what works for agents works for humans too.
  208. ### Prototype Fast, Scale Later
  209. Start with a simple composition, preview instantly in your browser, and only worry about rendering infrastructure when you're ready to ship.
  210. ### Use What You Know
  211. Pure TypeScript with zero framework dependencies. Use React, Vue, Svelte, or vanilla JS—whatever you're already comfortable with.
  212. ### Leverage Web Standards
  213. Native browser APIs over custom implementations. CSS animations, Web Animations API (WAAPI), and standard DOM APIs. Your existing web development skills transfer directly.
  214. ### Performance When It Matters
  215. Hardware-accelerated rendering, in-memory data piping, and WebCodecs support for canvas-heavy work. Performance is there when you need it.
  216. <!-- AGENT_VISION_END -->
  217. ---
  218. ## AI & Agent Integration
  219. 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.
  220. ### For AI Coding Assistants
  221. **AI-Ready Documentation:**
  222. - **llms.txt** - Machine-readable project overview at [`/llms.txt`](./llms.txt)
  223. - **Markdown URLs** - Add `.md` to any doc URL for raw markdown (planned)
  224. - **Structured errors** - All errors are machine-parseable with actionable guidance
  225. ### For Autonomous Agent Systems
  226. Helios uses a **Black Hole Architecture** where AI agents continuously pull the codebase toward this documented vision. If you're building similar systems:
  227. - **Vision Document**: This README serves as the authoritative vision. Planning agents scan it to identify gaps.
  228. - **Status Files**: `docs/status/[ROLE].md` tracks each domain's progress
  229. - **Progress Log**: `docs/PROGRESS.md` records completed work
  230. - **Backlog**: `docs/BACKLOG.md` tracks planned features
  231. - **Context Files**: `.sys/llmdocs/context-*.md` provides architectural summaries
  232. See [`docs/prompts/`](./docs/prompts/) for the complete agent orchestration system.
  233. ### Diagnostics for AI Environments
  234. ```typescript
  235. // Check environment capabilities (useful for AI debugging)
  236. const report = await Helios.diagnose();
  237. console.log(report);
  238. // {
  239. // waapi: true, // Web Animations API
  240. // webCodecs: true, // VideoEncoder support
  241. // offscreenCanvas: true,
  242. // userAgent: "..."
  243. // }
  244. ```
  245. ---
  246. ## Helios vs Remotion
  247. Both Helios and [Remotion](https://www.remotion.dev/) enable programmatic video creation. Here's an honest comparison:
  248. ### Philosophical Difference
  249. | | Helios | Remotion |
  250. |---|--------|----------|
  251. | **Architecture** | Native-aligned (drive the browser's engine) | Simulation-based (treat browser as screenshot machine) |
  252. | **Animation Calculation** | Browser's C++ compositor | JavaScript on every frame |
  253. | **Time Control** | CDP virtual time (production) / WAAPI seeking (preview) | React state propagation |
  254. | **CSS `@keyframes`** | ✅ Work natively | ❌ Clock drifts during render |
  255. | **Browser Dependency** | Chromium (CDP required) | Any browser (pure JS) |
  256. | **Historical Analog** | Native apps, CSS Grid, `fetch()` | PhoneGap, layout.js, jQuery AJAX |
  257. | **Bet** | Platform capabilities will mature | Abstraction layer will remain necessary |
  258. ### Feature Comparison
  259. | Feature | Helios | Remotion |
  260. |---------|--------|----------|
  261. | **Framework** | Any (React, Vue, Svelte, vanilla) | React only |
  262. | **Animation** | CSS, WAAPI, any library | `interpolate()`, `spring()` hooks |
  263. | **Learning curve** | Use what you know | Learn Remotion APIs |
  264. | **Maturity** | 🟡 Beta | 🟢 Production-ready |
  265. | **Pricing** | Free (ELv2) | Free ≤3 devs, then $100+/mo |
  266. | **Studio IDE** | 🟢 Beta | 🟢 Available |
  267. | **Distributed rendering** | 🟡 Beta (Local Orchestrator) | 🟢 Lambda, Cloud Run |
  268. | **Captions/subtitles** | 🟡 Standard (SRT) | 🟢 Built-in |
  269. | **Audio mixing** | 🟢 Client-side (WebCodecs) | 🟢 Advanced |
  270. | **MCP Server** | 🟢 `helios mcp`: preview in the conversation, verify, render, analyse audio | 🟢 Available |
  271. | **Agent Skills** | 🟢 `npx skills add`, Claude Code and Codex plugin | 🟢 `npx skills add` |
  272. | **Transitions library** | 🟢 Available | 🟢 `@remotion/transitions` |
  273. | **Sequence/Series** | 🔴 Not yet | 🟢 Built-in components |
  274. ### Where Helios Wins
  275. - **Framework freedom** - Use React, Vue, Svelte, or vanilla JS
  276. - **Zero learning curve** - Standard web animations work out of the box
  277. - **Free commercial use** - No per-seat or per-render fees
  278. - **Canvas/WebGL performance** - WebCodecs path for Three.js, Pixi.js
  279. - **Agent-first design** - Built for AI-assisted workflows
  280. ### Where Remotion Wins
  281. - **Production maturity** - Years of battle-testing
  282. - **Distributed rendering** - Lambda and Cloud Run today
  283. - **Rich ecosystem** - Transitions, captions, templates
  284. - **Studio IDE** - Full development environment
  285. - **Documentation depth** - Extensive guides and examples
  286. ### Choose Helios If
  287. - You want familiar web APIs, not proprietary hooks
  288. - You're using Vue, Svelte, or vanilla JS
  289. - You need canvas/WebGL performance (Three.js, Pixi.js)
  290. - You want free commercial use without licensing complexity
  291. - You're comfortable with alpha software
  292. ### Choose Remotion If
  293. - You need production stability today
  294. - You're all-in on React
  295. - You need distributed rendering now
  296. - You want extensive documentation and community
  297. ---
  298. ## Architecture
  299. <!-- AGENT_ARCHITECTURE_START: Detailed architecture for planning agents -->
  300. Helios is designed with a modular architecture that separates logic from presentation.
  301. ### 1. The Composition Layer
  302. #### Headless Logic Engine
  303. The core is an instantiable JavaScript class that manages all state (`currentFrame`, `duration`, `isPlaying`, `inputProps`), exposes methods (`play`, `pause`, `seek`), and provides subscription-based reactivity. This decouples logic from any UI framework.
  304. #### Framework Adapters
  305. Lightweight packages expose the headless engine idiomatically for each framework:
  306. - **React**: `useVideoFrame()` hook
  307. - **Vue**: Composition API composables
  308. - **Svelte**: Readable stores with `$` syntax
  309. - **Vanilla**: Direct class instantiation
  310. #### Web Component Player
  311. The `<helios-player>` Web Component encapsulates the preview UI. It uses a sandboxed iframe internally for isolation, ensuring it works in any HTML page without conflicts.
  312. ### 2. The Animation System
  313. Helios drives the browser's native animation engine rather than simulating animation in JavaScript. The mechanism varies by context:
  314. #### Production Rendering (Headless Chrome)
  315. Uses Chrome DevTools Protocol to virtualize time:
  316. ```
  317. CDP: Emulation.setVirtualTimePolicy({ policy: 'advance', budget: 33.33 })
  318. → Browser advances internal clock by exactly 33.33ms
  319. → All CSS/WAAPI animations update to new time
  320. → Layout and paint complete
  321. → Frame captured
  322. ```
  323. This is deterministic: the browser cannot advance until each frame is fully rendered, regardless of scene complexity.
  324. #### Preview Mode (Browser Tab)
  325. Uses WAAPI's writable `Animation.currentTime`:
  326. ```typescript
  327. // Seek all animations to target time
  328. document.getAnimations().forEach(anim => {
  329. anim.currentTime = targetTimeMs;
  330. anim.pause();
  331. });
  332. ```
  333. This is an O(N) operation over animations, but lets developers preview without running a headless browser.
  334. **Advantages:**
  335. - Performance: Animation interpolation happens in the browser's C++ compositor
  336. - Maintainability: Declarative CSS over imperative JavaScript
  337. - Familiarity: Standard CSS and WAAPI—skills transfer directly
  338. > **Canvas MVP Note**: For canvas compositions (Three.js, Pixi.js), Helios provides `currentTime` to the canvas's internal render loop rather than controlling WAAPI.
  339. ### 3. The Rendering Pipeline
  340. Dual-path architecture selects the optimal strategy:
  341. #### Path 1: DOM-to-Video (Versatile)
  342. - Uses Playwright to render DOM, capture screenshots
  343. - Ideal for HTML, CSS, SVG compositions
  344. - Asset preloading prevents artifacts
  345. #### Path 2: Canvas-to-Video (High-Performance)
  346. - Uses WebCodecs API for direct frame encoding
  347. - Hardware-accelerated VideoEncoder
  348. - Bypasses DOM for significant speed gains
  349. - **This is the MVP priority path**
  350. #### GPU Acceleration
  351. GPU acceleration is mandatory for competitive performance. The library ships with optimized browser launch flags and includes `helios.diagnose()` to verify hardware acceleration.
  352. #### FFmpeg Integration
  353. - Direct `child_process.spawn` (no wrappers)
  354. - In-memory piping via `image2pipe` demuxer (no temp files)
  355. - Audio mixing via filter complex
  356. ### 4. The In-Browser Player
  357. WYSIWYG preview using the same bundled composition code as the final render:
  358. - DOM compositions: `requestAnimationFrame` loop
  359. - Canvas compositions: WebCodecs real-time preview
  360. <!-- AGENT_ARCHITECTURE_END -->
  361. ---
  362. ## Technology Stack
  363. | Component | Choice | Rationale |
  364. |-----------|--------|-----------|
  365. | **Browser Automation** | Playwright | Auto-waiting, cross-browser support, superior debugging (Trace Viewer, Inspector) |
  366. | **Video Encoding** | FFmpeg (spawn) | Direct `child_process.spawn` for maximum control, stability, and performance |
  367. | **Language** | TypeScript | Type safety, improved DX, maintainable codebase |
  368. | **Bundling** | Vite/Rollup | Modern, fast, optimized for building libraries |
  369. ---
  370. ## Project Status
  371. **Beta**: Architecture stable, API maturing, suitable for early adopters.
  372. ### Current Capabilities
  373. - ✅ Core `Helios` class with timeline control
  374. - ✅ Helios Studio (Beta)
  375. - ✅ Animation Helpers (`interpolate`, `spring`)
  376. - ✅ Captions Support (SRT parsing/rendering)
  377. - ✅ AI Integration (System Prompts)
  378. - ✅ Canvas-to-Video rendering path
  379. - ✅ `<helios-player>` Web Component
  380. - ✅ React, Vue examples
  381. - ✅ FFmpeg integration with piped frames
  382. - ✅ `helios.diagnose()` environment checks
  383. - ✅ Client-side export (WebCodecs) with Audio Mixing & Captions
  384. - ✅ Distributed Rendering (Local Orchestrator)
  385. - ✅ Lottie Integration (React, Vue)
  386. - ✅ Audio Visualization Examples
  387. - ✅ Audio Tracks API
  388. See [`docs/BACKLOG.md`](./docs/BACKLOG.md) for the full task list.
  389. ---
  390. ## Roadmap & Governance
  391. The authoritative roadmap and project direction are defined in [`AGENTS.md`](./AGENTS.md).
  392. This document serves as the single source of truth for:
  393. - V2 Platform Direction
  394. - Domain Posture (Core, Renderer, Studio, etc.)
  395. - Governance Laws
  396. Please refer to `AGENTS.md` to understand where Helios is going and how to contribute.
  397. ---
  398. ## Deployment Strategies
  399. A robust deployment strategy is essential for a server-side rendering tool. The architecture is designed to support both simple, single-machine deployments and highly scalable, distributed rendering on cloud infrastructure.
  400. ### Containerized Rendering with Docker
  401. Docker is the ideal packaging and deployment mechanism for the rendering engine. It ensures a consistent, reproducible environment containing Node.js, a headless browser, FFmpeg, and all necessary dependencies for GPU acceleration. The container can be designed as a microservice, exposing an HTTP endpoint to accept render jobs.
  402. ### Distributed Rendering: AWS Lambda vs. Google Cloud Run
  403. The architecture is designed to be container-native and platform-agnostic, giving users a choice of serverless platforms that fit their needs.
  404. - **AWS Lambda**: Ideal for users prioritizing hyper-parallelism and minimum render time. Lambda is optimized for massive, fine-grained parallelism, which is perfect for splitting a video render across hundreds or thousands of concurrent function executions. This requires a chunking architecture and a final stitching step.
  405. - **Google Cloud Run**: Ideal for users prioritizing simplicity and long-running jobs. Cloud Run can run standard Docker containers for extended periods (up to 24 hours), allowing a single container invocation to render an entire video from start to finish without the complexity of chunking and stitching.
  406. ### Distributed Rendering Workflow and Concatenation
  407. The success of a distributed rendering architecture hinges on the video concatenation strategy. Merging video chunks must be done without a costly re-encode. FFmpeg offers several methods, but only one is suitable:
  408. | Method | How it Works | Supported Formats | Use Case for This Project |
  409. |---|---|---|---|
  410. | **Concat Demuxer** | Operates at the file level from a text file list. Can stream copy if codecs match. | All formats, including MP4. | **Recommended**. The only method for losslessly stitching MP4 chunks. |
  411. | Concat Protocol | Operates at the bitstream level. | Simple stream formats (e.g., MPEG-2 PS). Not compatible with MP4. | Unsuitable. Will fail or corrupt MP4 files. |
  412. | Concat Filter | A complex filter that decodes and re-encodes frames. | All formats. | Unsuitable. Re-encoding is slow and causes quality loss. |
  413. The distributed workflow is as follows:
  414. 1. **Orchestration**: A coordinator function (e.g., AWS Step Function) divides the video into `N` logical chunks (e.g., frames 0-299, 300-599, etc.).
  415. 2. **Parallel Execution**: The orchestrator invokes `N` parallel workers (e.g., Lambda functions), assigning each a frame range.
  416. 3. **Chunk Rendering**: Each worker renders its video and audio segments as separate files (e.g., `chunk_1.mp4`, `chunk_1.aac`) and uploads them to a shared location like S3.
  417. 4. **Final Stitching**: A final assembly job uses FFmpeg's `concat` demuxer to perform a fast, lossless merge of the video and audio chunks into the final output file.
  418. ---
  419. ## Development
  420. ### Local Setup
  421. ```bash
  422. git clone https://github.com/gavinbintz/helios.git
  423. cd helios
  424. npm install
  425. npm run dev
  426. ```
  427. ### Testing
  428. ```bash
  429. npm test # All tests
  430. npm test -w packages/core # Core package only
  431. npm run render:canvas-example # Test render pipeline
  432. ```
  433. ### Development Workflow & Debugging
  434. A seamless local development workflow is crucial for productivity. We recommend a hot-reloading environment for developers working on the library itself or on compositions using it.
  435. - **Hot Reloading**: A recommended setup involves using `npm link` or `yarn link` to link your local library source code to a sample project (e.g., a Vite + React app). Running the library's bundler in "watch" mode alongside the sample project's dev server provides a near-instant feedback loop.
  436. - **Debugging**: Debugging issues inside a headless browser can be challenging. We provide several tools to make it easier:
  437. - **Headed Mode**: Run the render process in a visible browser window using a `--headed` flag. Often, simply watching the automation unfold is the fastest way to spot an issue.
  438. - **Remote Debugging**: A `--debug` flag can launch the browser with a remote debugging port open. This allows you to connect the familiar Chrome DevTools to the headless instance to inspect the DOM, view console logs, and debug JavaScript live.
  439. - **Playwright Trace Viewer**: For post-mortem analysis, you can enable Playwright's Trace Viewer. It captures a complete trace of a render, including a video screencast, live DOM snapshots, console logs, and network requests, which is invaluable for diagnosing failed renders.
  440. ---
  441. ## License
  442. Helios Engine is licensed under the **Elastic License 2.0 (ELv2)**. This license is designed to encourage widespread adoption while protecting our ability to build a SaaS platform.
  443. The agent skills in [`skills/`](./skills/) and the agent plugin in [`plugins/helios/`](./plugins/helios/) (its manifests, assets and the `make-video` skill) are licensed under the **Apache License 2.0**; each folder has its own LICENSE file. The rest of this repository is under ELv2 unless a file or folder says otherwise.
  444. ### What This Means
  445. **You Can:**
  446. - ✅ **Build commercial products** - Use Helios Engine in any commercial application or product
  447. - ✅ **Embed in applications** - Include Helios Engine in your software, whether open source or proprietary
  448. - ✅ **Modify and distribute** - Fork, modify, and distribute Helios Engine
  449. - ✅ **Create video platforms** - Build video creation tools, editors, or platforms using Helios Engine
  450. - ✅ **Use internally** - Use Helios Engine for internal business purposes without restrictions
  451. - ✅ **Sell products** - Sell products that use or include Helios Engine
  452. - ✅ **Contribute** - Contribute improvements back to the open source project
  453. **You Cannot:**
  454. - ❌ **Offer Helios as a managed service** - You cannot provide Helios Engine as a hosted/managed service (SaaS) to third parties
  455. - ❌ **Resell Helios infrastructure** - You cannot offer Helios Engine rendering infrastructure as a service
  456. **What This Means in Practice:**
  457. This license is **perfect for founders building video platforms**. You can:
  458. - Build a video editing SaaS platform using Helios Engine ✅
  459. - Create a video generation tool for your customers ✅
  460. - Build a white-label video creation platform ✅
  461. - Embed Helios Engine in your application ✅
  462. - Sell products that use Helios Engine ✅
  463. You just can't offer Helios Engine itself as a managed/hosted service to others.
  464. ### Why Elastic License 2.0?
  465. We chose Elastic License 2.0 because:
  466. - **Encourages adoption** - Developers can build commercial products without restrictions
  467. - **Protects SaaS opportunity** - Prevents competitors from offering Helios as a managed service
  468. - **Well-established** - Used by Elasticsearch, Kibana, and other successful projects
  469. - **Clear boundaries** - Simple rule: build products ✅, offer managed services ❌
  470. - **Founder-friendly** - Perfect for founders building video platforms (our target customers!)
  471. This license allows us to build a SaaS platform around Helios while enabling a thriving ecosystem of products built on top of it.
  472. ### Commercial Licensing
  473. If you need to offer Helios Engine as a managed service or have questions about commercial licensing, please [contact us](mailto:me@gavinbintz.com).
  474. See [LICENSE](LICENSE) for full text.
  475. ---
  476. ## Contributing
  477. We welcome contributions! This project is primarily developed by an autonomous AI agent fleet, but human contributions are valued.
  478. - **Bug reports**: Open an issue
  479. - **Feature requests**: Open an issue or PR
  480. - **Code contributions**: Fork, branch, PR
  481. ---
  482. <div align="center">
  483. **☀️ Video is light over time.**
  484. [Documentation](./docs/) • [Examples](./examples/) • [Backlog](./docs/BACKLOG.md) • [Progress](./docs/PROGRESS.md)
  485. *Built with AI agents by [Gavin Bintz](https://github.com/BintzGavin)*
  486. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.