Core library for Helios video engine.
npm install @helios-project/coreThe headless logic engine for Helios. This package provides the core state management, timing, and animation primitives for programmatic video creation. It is framework-agnostic and runs in both the browser and Node.js.
- Headless State Machine: Manages frame, playback state, and input properties via reactive Signals.
- Time Driver: Abstracted time control via DomDriver (Browser default, supports WAAPI & Media Elements) and TimeoutTicker (Node.js).
- Sequencing: Helpers for relative timing (sequence) and sequential layout (series).
- Animation Helpers: Functions for interpolate (with easing) and spring physics.
- Diagnostics: Environment capability detection (diagnose).
This package is intended for use within the Helios monorepo.
``bash`
npm install @helios-project/core
`typescript
import { Helios } from '@helios-project/core';
const helios = new Helios({
fps: 30,
duration: 10, // seconds
autoSyncAnimations: true // Sync with document.timeline
});
// Subscribe to frame updates
helios.currentFrame.subscribe((frame) => {
console.log(Current Frame: ${frame});
});
// Start playback
helios.play();
`
Helios uses a lightweight Signals implementation for reactive state.
`typescript
// Access values directly
console.log(helios.isPlaying.peek()); // false
// Subscribe to changes
const unsubscribe = helios.isPlaying.subscribe((playing) => {
console.log(playing ? 'Playing' : 'Paused');
});
// Set input properties (reactive)
helios.setInputProps({ text: 'Hello World' });
`
Coordinate animations relative to a parent time or in a sequence.
`typescript
import { sequence, series, stagger, shift } from '@helios-project/core';
// Calculate local time for an item starting at frame 0 with duration 30
const { localFrame, progress, isActive } = sequence({
frame: currentFrame,
from: 0,
durationInFrames: 30
});
if (isActive) {
// Render item using localFrame (0-29)
}
// Layout items in a series (one after another)
const items = [
{ id: 'intro', durationInFrames: 60 },
{ id: 'body', durationInFrames: 120 },
{ id: 'outro', durationInFrames: 60 }
];
const sequencedItems = series(items);
// sequencedItems[0].from = 0
// sequencedItems[1].from = 60
// sequencedItems[2].from = 180
// Stagger items by a fixed interval
const letters = [{ char: 'H' }, { char: 'i' }];
const staggered = stagger(letters, 5, 10); // interval: 5, startFrame: 10
// staggered[0].from = 10
// staggered[1].from = 15
// Shift a group of items
const shifted = shift(staggered, 100);
// shifted[0].from = 110
// shifted[1].from = 115
`
Interpolate values and use physics-based springs.
`typescript
import { interpolate, spring, Easing } from '@helios-project/core';
// Linear interpolation with easing
const opacity = interpolate(frame, [0, 30], [0, 1], {
easing: Easing.quadOut,
extrapolateRight: 'clamp'
});
// Spring physics
const x = spring({
frame: frame,
fps: 30,
from: 0,
to: 100,
config: { stiffness: 100, damping: 10 }
});
`
Check environment capabilities.
`typescript
import { Helios } from '@helios-project/core';
Helios.diagnose().then((report) => {
console.log('WebCodecs:', report.webCodecs);
console.log('WAAPI:', report.waapi);
});
``
Elastic License 2.0 (ELv2)