Canvas Timeline
Package

HTML Media Sync Adapter

HTMLMediaElement adapter for timeline media playback.

Use the HTML media adapter when one native video or audio element should follow Canvas Timeline playback.

Overview

The HTML media adapter maps timeline clips to one mounted HTMLMediaElement. It seeks the element to the active clip source time, lets the native media clock drive playback, and keeps object URLs out of timeline state.

This is the right adapter for straightforward previews. If you need decoded frames on a canvas, custom Mediabunny inputs, or timeline-clocked audio playback outside a native media element, use the Mediabunny adapter instead.

Install

pnpm
pnpm add @techsquidtv/canvas-timeline-html-media-adapter

Choose this adapter for

  • Your preview is a single native <video> or <audio> element.
  • Browser-native media loading, controls, and embedded audio are enough for the editor preview.
  • You want URL, Blob, or File sources keyed by clip.sourceId without managing object URLs yourself.

Usage

Connect one media element to timeline playback

Use useHTMLTimelineMedia for the normal React path. It creates the adapter, wires it to timeline playback, and returns transport helpers for play, pause, and rate controls.

  1. 1Give each media clip a stable sourceId.
  2. 2Create a sources record where each key is a source id and each value is a URL, Blob, or File.
  3. 3Attach a ref to one <video> or <audio> element.
  4. 4Pass the ref, sources, and layer selector to useHTMLTimelineMedia inside a TimelineProvider.

Example

Native video preview
import { useRef } from 'react';
import { useHTMLTimelineMedia } from '@techsquidtv/canvas-timeline-html-media-adapter';


const sources = { 'clip-source-main': '/media/preview.mp4' };
const layers = {
  visuals: { trackKind: 'visual', sourceId: 'clip-source-main' },
} as const;


export function NativePreview() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const media = useHTMLTimelineMedia({
    ref: videoRef,
    sources,
    layers,
  });


  return <video ref={videoRef} playsInline onClick={() => void media.play()} />;
}