Canvas Timeline
Function

useHTMLTimelineMedia

Create a native media adapter and bind it to timeline-synchronized playback.

Usage notes

This hook is the simplest route for browser-native video or audio previews: create a stable `sources` map, name the active layers you want to sync, and render standard transport buttons from the returned commands. It is best for straightforward media previews; use the Mediabunny adapter when you need decoded canvas frames, audio scheduling, or richer source inspection.

Signature

Type Definition
useHTMLTimelineMedia(options: UseHTMLTimelineMediaOptions<LayerName, TMediaElement>): UseHTMLTimelineMediaResult<LayerName>

Type parameters

NameConstraintDefaultDescription
LayerNamestringstringNamed media layer keys inferred from `options.layers`.
TMediaElementHTMLMediaElementHTMLMediaElementNative element type held by `options.ref`.

Parameters

NameTypeDescription
optionsUseHTMLTimelineMediaOptions<LayerName, TMediaElement>Media element ref, source map, active layers, and optional error callback.

Returns

UseHTMLTimelineMediaResult<LayerName>

Timeline transport state, readiness, active layers, and the underlying adapter.

Examples

tsx Example
import { useMemo, useRef } from 'react';
import { useHTMLTimelineMedia } from '@techsquidtv/canvas-timeline-html-media-adapter';


const previewLayers = {
  visuals: { trackKind: 'visual', sourceId: 'sample-video' },
} as const;


export function NativeVideoPreview() {
  const ref = useRef<HTMLVideoElement>(null);
  const sources = useMemo(() => ({ 'sample-video': '/media/sample.mp4' }), []);
  const media = useHTMLTimelineMedia({
    ref,
    sources,
    layers: previewLayers,
    onError: console.error,
  });


  return (
    <>
      <video ref={ref} muted playsInline />
      <button type="button" disabled={!media.ready} onClick={() => void media.play()}>
        {media.playing ? 'Playing' : 'Play'}
      </button>
    </>
  );
}

Related links