helios-core
Skill130 starsChanged 38 days agoApache-2.0View on GitHub
Core API for Helios video engine. Use when creating compositions, managing timeline state, controlling playback, or subscribing to frame updates. Covers Helios class instantiation, signals, animation helpers, and DOM synchronization.
In this repository38 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- llms.txtllms.txt
- skill-creatorSkill
- animated-video-philosophySkill
- cinematic-product-promo-planSkill
- motion-stylesSkill
- example-canvasSkill
- example-chartjsSkill
- example-d3-animationSkill
- example-framer-motionSkill
- example-gsapSkill
- example-lottieSkill
- example-p5-animationSkill
- example-pixiSkill
- example-podcast-visualizerSkill
- example-reactSkill
- example-signals-animationSkill
- example-solidSkill
- example-svelteSkill
- example-tailwind-animationSkill
- example-threejsSkill
- example-vanillaSkill
- example-vueSkill
- helios-getting-startedSkill
- guided-brand-videoSkill
- guided-cartoon-shortSkill
- motion-design-rulesSkill
- guided-music-videoSkill
- guided-video-recipesSkill
- helios-playerSkill
- helios-rendererSkill
- helios-skillsSkill
- helios-studioSkill
- archive-brollSkill
- create-compositionSkill
- render-videoSkill
- workflow-visualize-dataSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 211
Check browser capabilities for rendering.
- Very specific: line 304
All Helios state properties are available as read-only signals on the instance:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Helios Core API
The Helios class is the headless logic engine for video compositions. It manages timeline state, provides frame-accurate control, and drives animations.
Quick Start
import { Helios } from '@helios-project/core';
// Create instance
const helios = new Helios({
duration: 10, // seconds
fps: 30,
width: 1920,
height: 1080,
inputProps: { text: "Hello World" }
});
// Subscribe to state changes
const unsubscribe = helios.subscribe((state) => {
console.log(`Frame: ${state.currentFrame}, Props:`, state.inputProps);
});
// Control playback
helios.play();API Reference
Constructor
new Helios(options: HeliosOptions)
interface HeliosOptions {
duration: number; // Duration in seconds (must be >= 0)
fps: number; // Frames per second (must be > 0)
width?: number; // Canvas width (default: 1920)
height?: number; // Canvas height (default: 1080)
initialFrame?: number; // Start frame (default: 0)
loop?: boolean; // Loop playback (default: false)
autoSyncAnimations?: boolean; // Auto-sync DOM animations (WAAPI) to timeline
animationScope?: HTMLElement; // Scope for animation syncing
inputProps?: Record<string, any>; // Initial input properties
schema?: HeliosSchema; // JSON schema for inputProps validation
playbackRate?: number; // Initial playback rate (default: 1)
volume?: number; // Initial volume (0.0 to 1.0)
muted?: boolean; // Initial muted state
audioTracks?: Record<string, AudioTrackState>; // Initial track state
availableAudioTracks?: AudioTrackMetadata[]; // Headless track metadata
captions?: string | CaptionCue[]; // SRT string or cue array
markers?: Marker[]; // Initial timeline markers
playbackRange?: [number, number]; // Restrict playback to [startFrame, endFrame]
driver?: TimeDriver; // Custom time driver (mostly internal use)
}State
helios.getState(): Readonly<HeliosState>
interface HeliosState {
width: number;
height: number;
duration: number;
fps: number;
currentFrame: number;
currentTime: number;
loop: boolean;
isPlaying: boolean;
inputProps: Record<string, any>;
playbackRate: number;
volume: number;
muted: boolean;
audioTracks: Record<string, AudioTrackState>;
availableAudioTracks: AudioTrackMetadata[];
captions: CaptionCue[];
activeCaptions: CaptionCue[];
markers: Marker[];
playbackRange: [number, number] | null;
}
type AudioTrackState = {
volume: number;
muted: boolean;
}Methods
Playback Control
helios.play() // Start playback
helios.pause() // Pause playback
helios.seek(frame: number) // Jump to specific frame
helios.setPlaybackRate(rate: number) // Change playback speed (e.g., 0.5, 2.0)
// Set Playback Range (Loop/Play only within these frames)
helios.setPlaybackRange(startFrame: number, endFrame: number)
helios.clearPlaybackRange()Timeline Configuration
helios.setDuration(seconds: number) // Update total duration
helios.setFps(fps: number) // Update frame rate (preserves current playback time)
helios.setLoop(shouldLoop: boolean) // Toggle loopingResolution Control
helios.setSize(width: number, height: number) // Update canvas dimensionsAudio Control
helios.setAudioVolume(volume: number) // Set volume (0.0 to 1.0)
helios.setAudioMuted(muted: boolean) // Set muted state
// Track-specific control
// Use data-helios-track-id="myTrack" on DOM elements to group them
helios.setAudioTrackVolume(trackId: string, volume: number)
helios.setAudioTrackMuted(trackId: string, muted: boolean)
// Advanced: Audio Visualization Hooks
// Get the shared AudioContext (if supported by driver)
await helios.getAudioContext();
// Get a MediaElementAudioSourceNode for a specific track
await helios.getAudioSourceNode(trackId);
// Audio Fades:
// Use data-helios-fade-easing="quad.in" (or linear, cubic, sine, etc.)
// on DOM elements to control fade curve.Data Input & Validation
// Update input properties (triggers subscribers)
// Validates against schema if one was provided in constructor
helios.setInputProps(props: Record<string, any>)Captions
// Set captions using SRT string or CaptionCue array
helios.setCaptions(captions: string | CaptionCue[])Markers
Manage timeline markers for key events.
interface Marker {
id: string;
time: number; // Time in seconds
label?: string;
color?: string;
metadata?: Record<string, any>;
}
helios.setMarkers(markers: Marker[])
helios.addMarker(marker: Marker)
helios.removeMarker(id: string)
helios.seekToMarker(id: string)Subscription
type HeliosSubscriber = (state: HeliosState) => void;
// Callback fires immediately with current state, then on every change
const unsubscribe = helios.subscribe((state: HeliosState) => {
// Render frame based on state
});
// Cleanup
unsubscribe();Timeline Binding
Bind Helios to document.timeline when the timeline is driven externally (e.g., by the Renderer or Studio).
// Start polling document.timeline (or __HELIOS_VIRTUAL_TIME__ in Renderer)
helios.bindToDocumentTimeline()
helios.unbindFromDocumentTimeline() // Stop pollingStability Registry
Register asynchronous checks that the Renderer must await before capturing frames (e.g., loading fonts, models, or data).
// Register a promise that resolves when ready
helios.registerStabilityCheck(
fetch('/data.json').then(r => r.json()).then(data => {
// Process data...
})
);
// Renderer calls this internally to ensure readiness
await helios.waitUntilStable();Diagnostics
Check browser capabilities for rendering.
const report = await Helios.diagnose();
interface DiagnosticReport {
waapi: boolean; // Web Animations API support
webCodecs: boolean; // VideoEncoder support
offscreenCanvas: boolean;
webgl: boolean;
webgl2: boolean;
webAudio: boolean;
colorGamut: 'srgb' | 'p3' | 'rec2020' | null;
videoCodecs: {
h264: boolean;
vp8: boolean;
vp9: boolean;
av1: boolean;
};
audioCodecs: {
aac: boolean;
opus: boolean;
};
videoDecoders: {
h264: boolean;
vp8: boolean;
vp9: boolean;
av1: boolean;
};
audioDecoders: {
aac: boolean;
opus: boolean;
};
userAgent: string;
}AI Context
Generate a system prompt for AI agents that includes the current composition context.
import { createSystemPrompt, HELIOS_BASE_PROMPT } from '@helios-project/core';
const prompt = createSystemPrompt(helios);
// Returns a string containing:
// 1. HELIOS_BASE_PROMPT (Philosophy, API summary)
// 2. Composition State (Duration, FPS, Resolution)
// 3. Schema DefinitionsAdvanced Utilities
RenderSession Controlled frame iteration, typically used for custom rendering or processing loops.
import { RenderSession } from '@helios-project/core';
const session = new RenderSession(helios, {
startFrame: 0,
endFrame: 100,
abortSignal: controller.signal // Optional cancellation
});
for await (const frame of session) {
// Helios is now sought to 'frame' and is stable
console.log(`Processing frame ${frame}`);
}Signals
The Helios class exposes reactive signals for granular state management. You can also create your own signals.
import { signal, computed, effect, ReadonlySignal } from '@helios-project/core';
// 1. Create a signal
const count = signal(0);
// 2. Create a computed value (updates automatically when deps change)
const double = computed(() => count.value * 2);
// 3. React to changes
effect(() => {
console.log(`Count: ${count.value}, Double: ${double.value}`);
});
// Update signal
count.value = 1; // Logs: "Count: 1, Double: 2"Public Helios Signals
All Helios state properties are available as read-only signals on the instance:
helios.currentFrame: ReadonlySignal<number>
helios.isPlaying: ReadonlySignal<boolean>
helios.inputProps: ReadonlySignal<Record<string, any>>
helios.playbackRate: ReadonlySignal<number>
helios.volume: ReadonlySignal<number>
helios.muted: ReadonlySignal<boolean>
helios.audioTracks: ReadonlySignal<Record<string, AudioTrackState>>
helios.availableAudioTracks: ReadonlySignal<AudioTrackMetadata[]>
helios.captions: ReadonlySignal<CaptionCue[]>
helios.activeCaptions: ReadonlySignal<CaptionCue[]>
helios.markers: ReadonlySignal<Marker[]>
helios.currentTime: ReadonlySignal<number>
helios.playbackRange: ReadonlySignal<[number, number] | null>
helios.width: ReadonlySignal<number>
helios.height: ReadonlySignal<number>
helios.loop: ReadonlySignal<boolean>Animation Helpers
Spring Physics
Simulate a damped harmonic oscillator.
import { spring, calculateSpringDuration } from '@helios-project/core';
const val = spring({
frame: currentFrame,
fps: 30,
from: 0,
to: 100,
config: { stiffness: 100, damping: 10, mass: 1 }
});
// Calculate how long (in frames) the spring takes to settle
const duration = calculateSpringDuration({
fps: 30,
from: 0,
to: 100,
config: { stiffness: 100, damping: 10 }
});Series (Sequencing)
Arrange multiple items in a timeline sequence.
import { series } from '@helios-project/core';
const items = [
{ id: 'a', durationInFrames: 30 },
{ id: 'b', durationInFrames: 60, offset: -10 } // Overlap by 10 frames
];
const sequenced = series(items, 0);
// Result:
// [
// { id: 'a', durationInFrames: 30, from: 0 },
// { id: 'b', durationInFrames: 60, offset: -10, from: 20 } // 0 + 30 - 10
// ]Stagger
Stagger the start time of a list of items by a fixed interval.
import { stagger } from '@helios-project/core';
const items = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
const staggered = stagger(items, 5);
// Result:
// [
// { id: 'a', from: 0 },
// { id: 'b', from: 5 },
// { id: 'c', from: 10 }
// ]Shift
Shift the start time of a list of sequenced items.
import { shift } from '@helios-project/core';
const items = [{ from: 0 }, { from: 10 }];
const shifted = shift(items, 30);
// Result:
// [
// { from: 30 },
// { from: 40 }
// ]Interpolation
Map values from one range to another.
import { interpolate } from '@helios-project/core';
const opacity = interpolate(frame, [0, 30], [0, 1], {
extrapolateRight: 'clamp'
});Schema Validation
Define input types for validation and UI generation in Studio. Supported types now include model, json, and shader.
const schema = {
type: 'object',
properties: {
title: { type: 'string' },
logo: { type: 'image' },
video: { type: 'video' },
audio: { type: 'audio' },
font: { type: 'font' },
model: { type: 'model' }, // 3D Model URL (.glb, .gltf)
config: { type: 'json' }, // JSON Data URL
effect: { type: 'shader' }, // Shader URL (.glsl)
// Typed Arrays (float32array, uint8array, etc.)
data: { type: 'float32array' },
count: { type: 'number', minimum: 0, step: 1 },
email: { type: 'string', pattern: '^\\S+@\\S+\\.\\S+$' },
avatar: { type: 'image', accept: '.png,.jpg' },
settings: {
type: 'object',
group: 'Advanced Settings', // Collapsible group in Studio
properties: { /* ... */ }
}
}
};Source Files
- Main class:
packages/core/src/index.ts - Signals:
packages/core/src/signals.ts - Animation:
packages/core/src/animation.ts - Sequencing:
packages/core/src/sequencing.ts - Validation:
packages/core/src/schema.ts
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

