Canvas Timeline
Function

useTimelineMediaPlayback

Coordinates timeline playback with an external media clock.

Usage notes

The hook is media-library agnostic. Apps provide a clock and a single layer sync callback while the hook advances the TimelineEngine playhead and decides when active layer clips need to be resynchronized.

Signature

Type Definition
useTimelineMediaPlayback(options: UseTimelineMediaPlaybackOptions<LayerName>): UseTimelineMediaPlaybackResult

Type parameters

NameConstraintDefaultDescription
LayerNamestringstringNamed media layer keys inferred from `options.layers`, such as `"visuals" | "audio"`.

Parameters

NameTypeDescription
optionsUseTimelineMediaPlaybackOptions<LayerName>External media clock, active layer selectors, sync callback, and status callback.

Returns

UseTimelineMediaPlaybackResult

Timeline playback state and commands backed by the external media clock.

Examples

tsx Example
import { useMemo, useRef } from 'react';
import { useTimelineMediaPlayback } from '#react/hooks';


const previewLayers = {
  visuals: { trackKind: 'visual' },
  audio: { trackKind: 'audio' },
} as const;


export function CustomClockTransport() {
  const clockSecondsRef = useRef(0);
  const layers = useMemo(() => previewLayers, []);
  const playback = useTimelineMediaPlayback({
    layers,
    getClockTime: () => clockSecondsRef.current,
    stopClock: () => {
      clockSecondsRef.current = 0;
    },
    syncLayers: ({ activeLayers, reason }) => {
      const visualClip = activeLayers.primary.visuals?.clip;
      console.info(reason, visualClip?.id ?? 'blank frame');
    },
  });


  return (
    <button type="button" onClick={() => playback.playing ? playback.pause() : playback.play()}>
      {playback.playing ? 'Pause' : 'Play'}
    </button>
  );
}

Related links