useTimelineMediaPlayback API

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

useTimelineMediaPlayback(options: UseTimelineMediaPlaybackOptions<LayerName>): UseTimelineMediaPlaybackResult

Type parameters

Name	Constraint	Default	Description
`LayerName`	`string`	`string`	Named media layer keys inferred from `options.layers`, such as `"visuals" \| "audio"`.

Parameters

Name	Type	Description
options	UseTimelineMediaPlaybackOptions<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

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

- ActiveLayerSelector - ActiveLayerResult - useTimelineMediaSync - React editor hooks