Events and lifecycle

Active layer lookup

While rendering the editor timeline uses the full state.tracks tree, synchronized playback and preview pipelines only care about what is active at the playhead.

To retrieve active clips at a specific time, use engine.getActiveLayers() (or the React hook useActiveLayers()). This utility filters out hidden tracks, muted tracks, and disabled clips, then returns the results in your named layer buckets:

const activeLayers = engine.getActiveLayers({
  time: engine.getTime(),
  layers: {
    visuals: { trackKind: 'visual' },
    audio: { trackKind: 'audio' },
    subtitles: { trackKind: 'subtitle' },
  },
});

// Primary active layer results
const activeVisual = activeLayers.primary.visuals; // Returns single ActiveClip or undefined
const activeAudioClips = activeLayers.layers.audio; // Returns all active clips in audio tracks
const activeSubtitleClips = activeLayers.layers.subtitles; // Returns all active subtitle clips

The returned ActiveClip provides all timing offsets required to sync players (such as <video> or wavesurfer):

• clip: The raw Clip object.
• track: The containing Track object.
• time: The query timeline time.
• sourceTime: The computed current playback position relative to the clip’s source media (sourceTime = time - timelineStart + sourceStart).
• syncKey: A unique string that changes when the clip’s boundaries are edited, informing players to resync.

Editing model & event lifecycle

The core engine is UI-agnostic. It accepts typed edit commands for move, trim, ripple trim, roll trim, slip, slide, insert, overwrite, delete range, and lift range operations. The engine validates policy, resolves snapping and structural consequences, publishes previews, commits state, and records history; it does not dictate how your toolbar or keyboard shortcuts look.

The general loop is:

1. User Gesture: The user clicks, drags, or presses a key (e.g., drags clip edges, presses split key).
2. Command Construction: React event handlers build a typed edit command with IDs and target RationalTime positions.
3. Validation & Preview: The engine validates the command, applies optional TimelineEditPolicy callbacks, resolves snapping and edit consequences, then emits edit:preview.
4. Commit: The engine applies the already-resolved edit through one history-aware path, emits structural clip events and edit:commit, then clears the active preview.
5. UI Render: The React provider publishes the state update, forcing canvas redrawing and DOM updates.

import { fromSeconds } from '@techsquidtv/canvas-timeline-utils';

const command = {
  type: 'trim',
  clipId: 'clip-intro',
  edge: 'end',
  newTime: fromSeconds(6),
} as const;

const preview = engine.previewEdit(command);

if (preview.valid) {
  engine.commitEdit(preview.command);
}

Use engine.cancelEdit() to clear the active command preview without mutating timeline state.

Pass TimelineEditPolicy callbacks when your application needs to reject edit commands for product-specific reasons. Policy callbacks return structured validation results; the engine resolves edit consequences and applies commits.

Storing Custom Clip Metadata

To keep your application data in sync with the timeline engine, attach custom properties directly to a clip’s metadata field.

The metadata property accepts a flexible key-value object (Record<string, unknown>). Since the engine serializes and snapshots track states during editing, clip metadata is automatically snapshotted, duplicated on splits, and restored via Undo/Redo operations without writing any custom event synchronization logic.

// 1. Attach custom app data when creating a clip
engine.addClip('track1', {
  sourceId: 'video-asset-1',
  timelineStart: fromSeconds(0),
  timelineEnd: fromSeconds(5),
  metadata: {
    caption: 'Intro Scene',
    colorGradeId: 'grade-abc',
  },
});

// 2. Read custom metadata anywhere you have a clip reference
const clip = engine.getClip('clip1')?.clip;
console.log(clip?.metadata?.caption); // 'Intro Scene'

// 3. Update metadata fields using updateClipProperties
engine.updateClipProperties('clip1', {
  metadata: {
    caption: 'Revised Intro Scene',
    colorGradeId: 'grade-abc',
  },
});

Keep custom metadata lightweight and serializable. For heavy assets like raw transcript logs or large media file blobs, store them in your application state and reference them from the clip using a unique ID stored in clip.metadata.id.

Engine events reference

The TimelineEngine extends TypedEventEmitter to publish type-safe events for structural modifications, live interactions, and playback updates.

You can subscribe to these events using engine.on(), which returns a cleanup function to unsubscribe:

const unsubscribe = engine.on('clip:split', ({ originalId, left, right }) => {
  console.log(`Split clip ${originalId} into ${left.id} and ${right.id}`);
});

// Clean up when done
unsubscribe();

Event Lifecycle Table