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. The package root is imperative and framework-free; React hooks are published from ./react.

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 from the ./react entry point for the normal React path. It creates the adapter, wires it to timeline playback, returns transport helpers, and exposes immutable source lifecycle snapshots.

  1. 1Give each media clip a stable sourceId.
  2. 2Create a sources array of { sourceId, input } descriptors, one per logical source.
  3. 3Resolve originals or proxies in your media library, then pass equivalent load fallbacks only when needed.
  4. 4Create the hook with sources and a layer selector inside a TimelineProvider.
  5. 5Attach the returned mediaRef to one <video> or <audio> element.
  6. 6Treat ready as element-connection readiness and inspect sourceStateById for native source loading or recovery.

Example

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


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


export function NativePreview() {
  const media = useHTMLTimelineMedia({
    sources,
    layers,
    onError: (error) => console.error(error.reason, error.message),
  });


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