Canvas Timeline
Package

HTML Media Sync Adapter

HTMLMediaElement adapter for timeline media playback.

Use the HTML media adapter when you want a simple HTML media or audio element to drive or follow Canvas Timeline playback.

Installation

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

When to use it

You are building a standard video or audio preview player using a native HTML5 `<video>` or `<audio>` element.
You want simple playback synchronization without the weight of decoding frameworks or canvas-drawn video sinks.

How it fits together

Canvas Timeline owns tracks, clips, source time mapping, playback intent, and the active playhead. The HTML media adapter owns one mounted HTMLMediaElement, loads the active clip source into that element, seeks it to the clip source time, and reports the element clock back to timeline playback.

Setup flow

  1. 1Give each media clip a stable `sourceId`; this is the join key between timeline state and your media sources.
  2. 2Create a `sources` record where each key is a `sourceId` and each value is a URL, Blob, or File.
  3. 3Attach a React ref to one `<video>` or `<audio>` element.
  4. 4Pass `ref`, `sources`, and your active layer selector to `useHTMLTimelineMedia` inside a `TimelineProvider`.
  5. 5Use the returned transport helpers for play, pause, and playback-rate UI.
Minimal React sync
import { useRef } from 'react';
import { useHTMLTimelineMedia } from '@techsquidtv/canvas-timeline-html-media-adapter';


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


// Render inside <TimelineProvider engine={engine}>.
export function NativePreview() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const media = useHTMLTimelineMedia({
    ref: videoRef,
    sources,
    layers: previewLayers,
  });


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

What to look for in the demo

  • •The HTML Media Adapter Sync demo uses `useHTMLTimelineMedia` with `videoRef` as the single preview surface controlled by the adapter.
  • •`sampleSourceId` appears in both the clip data and the `sources` record, showing how `clip.sourceId` selects the media URL.
  • •The visual layer selector tells the high-level hook which active timeline clip should drive the native element.
  • •The rate buttons and readouts come from timeline transport state plus native element events, not from duplicated media state in the timeline.

Common imports

High-level React sync hook
import { useHTMLTimelineMedia } from '@techsquidtv/canvas-timeline-html-media-adapter';
Low-level React adapter hook
import { useHTMLMediaAdapter } from '@techsquidtv/canvas-timeline-html-media-adapter';
Imperative adapter factory
import { createHTMLMediaAdapter } from '@techsquidtv/canvas-timeline-html-media-adapter';

Usage notes

  • •Use this adapter for simple native single-element sync; embedded video audio is handled by the same HTMLMediaElement.
  • •The adapter maps `clip.sourceId` to one configured media source and keeps Blob/File object URLs out of timeline state.
  • •Use `useHTMLTimelineMedia` for the common React path; use `useHTMLMediaAdapter`, `createHTMLMediaAdapter`, and `useTimelineMediaSync` when you need custom clocks or nonstandard sync behavior.
  • •For decoded frame access, canvas preview rendering, or separate visual/audio source scheduling, use the Mediabunny adapter instead.

API Surface

Explore the key components, hooks, and classes exported by this package. Click any symbol to view its full TSDoc parameter signatures.

Key Entry Points

FunctionuseHTMLTimelineMedia

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

FunctioncreateHTMLMediaAdapter

Create an adapter that maps active timeline clips to one HTMLMediaElement.

FunctionuseHTMLMediaAdapter

Create and dispose an HTML media element timeline adapter from a React ref.

InterfaceHTMLMediaAdapter

Timeline media sync adapter backed by one HTMLMediaElement.

Subpath Imports

Import specific files or modules directly to reduce bundle size or target specialized package layers.

Import PathDescription
@techsquidtv/canvas-timeline-html-media-adapterReact adapter hooks, imperative adapter factory, and types.