Canvas Timeline
Package

Mediabunny Audio & Video Sync Adapter

Optional Mediabunny adapter for timeline media playback and frame access.

Use the Mediabunny adapter when timeline clips need to drive decoded video frames, local media files, and Web Audio scheduling through Mediabunny.

Installation

pnpm
pnpm add @techsquidtv/canvas-timeline-mediabunny-adapter mediabunny

When to use it

You already use Mediabunny and want Canvas Timeline clips to drive decoded video frames and audio playback.
You need local `Blob` or `File` sources mapped by `clip.sourceId` without putting media objects in timeline state.
You want lower-level frame access for custom canvas composition while keeping timeline playback synchronized.

How it fits together

Canvas Timeline still owns the timeline state, active clips, source offsets, and playback intent. The Mediabunny adapter owns decoded media inputs, frame sinks, optional audio scheduling, and the media clock needed to render the active visual/audio clips in sync.

Setup flow

  1. 1Give timeline media clips stable `sourceId` values and keep media files, blobs, or Mediabunny inputs in application state.
  2. 2Build a `sources` array where each item has an `id` matching a clip `sourceId` plus `url`, `blob`, `input`, or `createInput`.
  3. 3Attach a `canvasRef` when decoded video frames should be painted to a preview canvas.
  4. 4Pass `canvasRef`, `sources`, and your visual/audio layer selectors to `useMediabunnyTimelineMedia` inside a `TimelineProvider`.
  5. 5Pass a custom `mediabunny` module or loader only when you need explicit dependency control; otherwise the hook uses a browser lazy import.
Minimal React sync
import { useRef } from 'react';
import { useMediabunnyTimelineMedia } from '@techsquidtv/canvas-timeline-mediabunny-adapter/react';


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


// Render inside <TimelineProvider engine={engine}>.
export function DecodedPreview() {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const media = useMediabunnyTimelineMedia({
    canvasRef,
    sources,
    layers: previewLayers,
  });


  return <canvas ref={canvasRef} width={1280} height={720} onClick={() => void media.play()} />;
}

What to look for in the demo

  • •The Mediabunny Adapter Sync demo uses `useMediabunnyTimelineMedia` so the visible code matches the recommended setup path.
  • •`sampleSourceId` appears in the visual/audio clips and in the Mediabunny source descriptors, showing the same `clip.sourceId` join key.
  • •The `canvasRef` preview receives decoded frames while the high-level hook returns the transport controls, status, duration, and last-frame readouts.
  • •The status panel reads `durationBySourceId` and `lastFrameTime`, which are useful for preview UI but do not need to be copied into timeline state.

Common imports

High-level React sync hook
import { useMediabunnyTimelineMedia } from '@techsquidtv/canvas-timeline-mediabunny-adapter/react';
Low-level React adapter hook
import { useMediabunnyAdapter } from '@techsquidtv/canvas-timeline-mediabunny-adapter/react';
Imperative adapter
import {
  createMediabunnyAdapter,
} from '@techsquidtv/canvas-timeline-mediabunny-adapter';

Usage notes

  • •`mediabunny` is a peer dependency; the high-level hook lazy-loads it in the browser by default, while low-level APIs can still receive an explicit module or loader for dependency control.
  • •The adapter maps `clip.sourceId` to Mediabunny sources and keeps heavy media objects outside serialized timeline state.
  • •Use `useMediabunnyTimelineMedia` for the common React path; use `useMediabunnyAdapter`, `createMediabunnyAdapter`, and `useTimelineMediaSync` when you need custom clock or layer synchronization.
  • •For ordinary single-element playback, prefer the native HTML media adapter from `@techsquidtv/canvas-timeline-html-media-adapter`.

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

FunctionuseMediabunnyTimelineMedia

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

FunctioncreateMediabunnyAdapter

Create a Mediabunny adapter that drives Canvas Timeline media playback.

FunctionuseMediabunnyAdapter

Create and dispose a Mediabunny timeline adapter from React state.

InterfaceMediabunnyAdapter

Adapter that connects Canvas Timeline playback and frame rendering to Mediabunny.

Subpath Imports

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

Import PathDescription
@techsquidtv/canvas-timeline-mediabunny-adapterImperative Mediabunny timeline adapter and types.
@techsquidtv/canvas-timeline-mediabunny-adapter/reactReact hook for creating and disposing the adapter.