DOCSEARCHbyAlgolia
Submit Docs

Canvas Timeline API Reference

website·Indexed 30 days ago

https://canvastimeline.com/

Technical documentation for Canvas Timeline, featuring the TimelineEngine core, React integration hooks like useTimelineKeyframes and TimelineProvider, and utility functions for timecode parsing and rational time calculations.

Tokens
164.3K
Snippets
802
Records
1.1K
Agent score
55%

What's inside Canvas Timeline

  1. Overview of @techsquidtv/canvas-timeline-react capabilities

    The React package provides a bridge between a TimelineEngine and React. It is renderer-agnostic, meaning it can be paired with the default canvas renderer or used with custom rendering via its hooks and interaction primitives.

    Key features include:

    • Provider & Components: TimelineProvider and Timeline namespace components for playheads, range controls, scrollbars, and track interaction.
    • Headless Hooks: Hooks for managing editing, selection, keyframes, playback, viewport, and track state.
    • Interaction Chrome: Built-in components for playhead grabbers, clip handles, and range controls.
    • Coordination: Ability to coordinate custom media decoders or external clocks while remaining framework-neutral.

  2. Overview of Canvas Timeline architecture

    Canvas Timeline is a modular framework for building professional-grade video, audio, or animation timelines. It utilizes a 2D HTML5 canvas context running in a background worker to bypass DOM reflows during scrubbing, zooming, and playback, ensuring 60fps performance. The architecture is split into a headless state engine, React interaction layers, and a canvas rendering pipeline.

  3. Overview of the HTML Media Adapter

    The HTML media adapter maps timeline clips to a single mounted HTMLMediaElement. It seeks the element to the active clip source time and allows the native media clock to drive playback. This adapter is ideal for straightforward previews using a single native <video> or <audio> element where browser-native loading and controls are sufficient. It manages URL, Blob, or File sources keyed by clip.sourceId without requiring manual object URL management. For decoded frames on a canvas or custom Mediabunny inputs, use the Mediabunny adapter instead.

  4. Overview of HTMLMediaAdapter

    The HTMLMediaAdapter is a lightweight adapter that maps the first active clip from configured layers to a native <video> or <audio> element. It seeks the element to the clip's source time and allows the native element's clock to drive timeline playback. It is recommended for simple browser-native previews where frame-accurate decoded playback is not required.

  5. Overview of the Mediabunny adapter

    The Mediabunny adapter is designed for timeline preview monitors that require decoded media. Instead of simply mounting a <video> tag, it opens registered sources when active or preloaded, paints decoded video frames to a canvas, queues audio via Web Audio, and provides per-source timing and track metadata.

  6. Use the ClipCreatedEvent interface

    The ClipCreatedEvent interface is triggered when a new clip is created. It provides details about the created clip, the reason for its creation, and optionally the ID of a source clip if the new clip was derived from another.
    interface ClipCreatedEvent {
  /** Newly created clip */
  clip: Clip;
  /** Command that created the clip */
  reason: ClipCreatedReason;
  /** Source clip ID from which this clip was created (useful for copying external metadata or tracking clip lineage) */
  originClipId?: string;
}

  7. Understand the role of Canvas Timeline demos

    The demos section provides source-backed examples where each route pairs a live Canvas Timeline surface with the corresponding TSX, data, and CSS files. While guides explain concepts, demos allow developers to inspect a working surface and copy the actual source code used to render it.

  8. Understand the core components of a video editor timeline

    A video editor timeline is the primary workspace where raw footage is assembled into a final video. It consists of a horizontal time scale and a vertical stack of tracks. Key components include:

    • Sequence: The container for the entire edit, including duration, frame rate, and all clips.
    • Timeline Ruler: The horizontal time scale used for reference and scrubbing.
    • Playhead: The vertical line indicating the current frame being previewed.
    • Clips: Individual pieces of media (video, audio, images) placed on the timeline.
    • Tracks: Horizontal lanes used to organize clips; video tracks typically stack visually (top layers cover bottom layers), while audio tracks mix together.
    • Markers: Annotations pinned to specific times or clips for notes, beats, or sync points.
    • In and Out Points: Defined time ranges used for playback, exporting, or inserting footage.

  9. Use the ClipMoveEvent interface to handle clip movement

    The ClipMoveEvent interface provides detailed metadata about a clip move operation, including source and destination tracking, timing changes, and whether the move is currently in a preview state or has been committed.
    interface ClipMoveEvent {
  changedClips: Clip[];             // All clips changed by the move, including linked group members
  clip: Clip;                      // Moved clip after the operation
  clipId: string;                  // Moved clip id
  destinationClipIndex: number;     // Destination clip index after sorting
  destinationTrackId: string;       // Track containing the clip after the move
  destinationTrackIndex: number;    // Destination track index after the move
  endTime: RationalTime;           // Clip end after the move
  phase: "preview" | "commit";    // Whether this event describes live preview state or a settled committed move
  previousEndTime: RationalTime;    // Clip end before the move
  previousStartTime: RationalTime; // Clip start before the move
  sourceClipIndex: number;          // Source clip index before the move
  sourceTrackId: string;            // Track that contained the clip before the move
  sourceTrackIndex: number;         // Source track index before the move
  startTime: RationalTime;          // Clip start after the move
}

  10. Use ActiveClip to bridge timeline structure and source media

    The ActiveClip interface is used by media adapters to seek source files without duplicating timeline calculations. It provides the mapping between the inspected timeline time and the corresponding source-media timestamp, including the original Clip and Track context. A syncKey is provided to detect when timing-affecting clip data has changed, signaling that the media may need to be re-synced.

  11. TimelineSnapTarget Interface Reference

    The TimelineSnapTarget interface defines a target point within a prepared snap index. It is used to identify specific locations on a timeline that the playback head or user interface can 'snap' to, providing metadata about the target's position, category, and ownership.
    interface TimelineSnapTarget {
  id: string;
  kind: TimelineSnapTargetKind;
  label?: string;
  metadata?: TimelineMetadata;
  ownerId?: string;
  priority?: number;
  time: RationalTime;
  trackId?: string;
}

  12. Use TimecodeField components for timecode editing

    The TimecodeField is a set of components used to implement a timecode input field that toggles between a compact display and an active editing state. It consists of three primary parts:

    • Root: The state manager that coordinates the swap between the display trigger and the active input field.
    • Trigger: A button that displays the formatted timecode and activates the editing mode when clicked.
    • Input: The actual input field rendered while the user is actively editing the timecode.
    import { TimecodeField } from '@canvastimeline/react';

// Usage structure:
<TimecodeField.Root>
  <TimecodeField.Trigger />
  <TimecodeField.Input />
</TimecodeField.Root>