Utilities for organizing and timing sequences of animations.
sequence()
Calculates the local time and progress of a sequence relative to a start frame.
const result = sequence(options);
Sequence configuration
Duration in frames (if undefined, sequence is infinite)
Sequence state object
Frame number relative to sequence start (frame - from)
Progress from 0 to 1 (0 if no duration)
True if within sequence duration
Example
import { sequence } from '@heliosvideo/core';
const seq = sequence({
frame: currentFrame,
from: 30,
durationInFrames: 60,
});
if (seq.isActive) {
const opacity = seq.progress;
const scale = 0.5 + seq.progress * 0.5;
}
series()
Calculates start frames for items placed one after another.
const items = series(itemsWithDuration, startFrame);
Array of items with durationInFrames propertyEach item should have:
durationInFrames: number (required)offset: number (optional) - Shifts this item relative to the previous item’s end
Starting frame for the sequence
Items with added from property indicating start frame
Example
import { series } from '@heliosvideo/core';
const scenes = series([
{ id: 'intro', durationInFrames: 60 },
{ id: 'main', durationInFrames: 120 },
{ id: 'outro', durationInFrames: 30, offset: -15 }, // Overlap by 15 frames
]);
// Result:
// [
// { id: 'intro', durationInFrames: 60, from: 0 },
// { id: 'main', durationInFrames: 120, from: 60 },
// { id: 'outro', durationInFrames: 30, offset: -15, from: 165 },
// ]
stagger()
Staggers items by a fixed interval.
const items = stagger(items, interval, startFrame);
Array of items to stagger
Number of frames between each item
Starting frame for the first item
Items with added from property
Example
import { stagger } from '@heliosvideo/core';
const letters = ['H', 'E', 'L', 'L', 'O'].map(letter => ({ letter }));
const staggered = stagger(letters, 5, 0);
// Result:
// [
// { letter: 'H', from: 0 },
// { letter: 'E', from: 5 },
// { letter: 'L', from: 10 },
// { letter: 'L', from: 15 },
// { letter: 'O', from: 20 },
// ]
staggered.forEach(({ letter, from }) => {
const seq = sequence({
frame: currentFrame,
from,
durationInFrames: 30,
});
if (seq.isActive) {
// Animate letter
}
});
shift()
Shifts the start time of sequenced items.
const shifted = shift(items, offset);
Array of items with from property
Number of frames to shift (can be negative)
Items with updated from values
Example
import { stagger, shift } from '@heliosvideo/core';
const items = stagger([1, 2, 3], 10);
// [{ from: 0 }, { from: 10 }, { from: 20 }]
const delayed = shift(items, 30);
// [{ from: 30 }, { from: 40 }, { from: 50 }]
const earlier = shift(items, -5);
// [{ from: -5 }, { from: 5 }, { from: 15 }]
Complete example
import { sequence, series, stagger, shift } from '@heliosvideo/core';
// Create a series of scenes
const scenes = series([
{ name: 'Scene 1', durationInFrames: 90 },
{ name: 'Scene 2', durationInFrames: 120 },
{ name: 'Scene 3', durationInFrames: 60 },
]);
// Stagger elements within each scene
const elements = stagger(
['element-1', 'element-2', 'element-3'].map(id => ({ id })),
8 // 8 frames apart
);
// Shift elements to start at frame 20
const delayedElements = shift(elements, 20);
// Render logic
delayedElements.forEach(({ id, from }) => {
const seq = sequence({
frame: currentFrame,
from,
durationInFrames: 30,
});
if (seq.isActive) {
const opacity = seq.progress;
// Render element with animated opacity
}
});