/vanilla

name: example-vanilla
description: Patterns for using Helios with Vanilla JavaScript/TypeScript. Use when building compositions without a framework, or for simple DOM/Canvas manipulations.

Vanilla JS Composition Patterns

Integrate Helios into standard HTML/JS applications using direct DOM manipulation and subscriptions.

Quick Start

1. Setup

Initialize Helios and bind to the document timeline.

import { Helios } from '@helios-project/core';

// 1. Initialize Helios
const helios = new Helios({
  duration: 10,
  fps: 30,
  width: 1920,
  height: 1080,
  autoSyncAnimations: true // Sync WAAPI/CSS animations
});

// 2. Expose for Player/Studio
(window as any).helios = helios;

// 3. Bind to external timeline (important for Renderer/Studio)
helios.bindToDocumentTimeline();

2. Subscribe to Updates

Use `subscribe` to update the DOM or Canvas on every frame.

const box = document.getElementById('box');

helios.subscribe((state) => {
  if (!box) return;

  const { currentFrame, fps } = state;
  const time = currentFrame / fps;

  // Animate based on time
  const x = time * 100;
  box.style.transform = `translateX(${x}px)`;

  // Update text
  box.textContent = `Frame: ${currentFrame}`;
});

3. Captions Example

Driven by SRT content.

const captionBox = document.getElementById('captions');

helios.subscribe((state) => {
  if (!captionBox) return;

  const activeCues = state.activeCaptions;

  if (activeCues.length > 0) {
    captionBox.innerText = activeCues.map(c => c.text).join('\n');
    captionBox.style.opacity = '1';
  } else {
    captionBox.innerText = '';
    captionBox.style.opacity = '0';
  }
});

Key Concepts

• **Direct DOM Manipulation:** Use `style.transform`, `textContent`, etc., inside the `subscribe` callback.
• **`bindToDocumentTimeline`:** Crucial for allowing the `HeliosPlayer` or `Renderer` to drive the animation.
• **Performance:** Avoid expensive layout thrashing (reading offsets then writing styles) inside the loop.

Source Files

• Example: `examples/vanilla-captions-animation/`
• Example: `examples/simple-canvas-animation/`