Sequencing utilities

Sequence timing, series, stagger, and shift functions

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);

options · SequenceOptions · required

Sequence configuration

Show properties

frame · number · required

Current frame number

from · number · required

Starting frame number

durationInFrames · number

Duration in frames (if undefined, sequence is infinite)

result · SequenceResult

Sequence state object

Show properties

localFrame · number

Frame number relative to sequence start (frame - from)

relativeFrame · number

Alias for localFrame

progress · number

Progress from 0 to 1 (0 if no duration)

isActive · boolean

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);

items · T[] · required

Array of items with durationInFrames property

Each item should have:

• durationInFrames: number (required)
• offset: number (optional) - Shifts this item relative to the previous item’s end

startFrame · number · default: "0"

Starting frame for the sequence

items · (T & { from: number })[]

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);

items · T[] · required

Array of items to stagger

interval · number · required

Number of frames between each item

startFrame · number · default: "0"

Starting frame for the first item

items · (T & { from: number })[]

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);

items · T[] · required

Array of items with from property

offset · number · required

Number of frames to shift (can be negative)

items · T[]

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
  }
});