Playback Hooks

Playback hooks provide access to the playlist’s playback system through React contexts. These hooks must be used within a WaveformPlaylistProvider.

usePlaylistControls

Access playback control methods and track manipulation functions.

Import

import { usePlaylistControls } from '@waveform-playlist/browser';

Usage

function PlaybackButtons() {
  const { play, pause, stop, setCurrentTime } = usePlaylistControls();

  return (
    <div>
      <button onClick={() => play()}>Play</button>
      <button onClick={() => pause()}>Pause</button>
      <button onClick={() => stop()}>Stop</button>
      <button onClick={() => setCurrentTime(0)}>Rewind</button>
    </div>
  );
}

Return Value

Returns an object with all playback and playlist control methods:

play

(startTime?: number, playDuration?: number) => Promise<void>

Start playback. Optionally specify a start time and duration.Parameters:

startTime - Time in seconds to start playback from (default: current time)
playDuration - Duration in seconds to play (default: play to end)

pause

() => void

Pause playback. Maintains the current position.

stop

() => void

Stop playback. May reset position depending on configuration.

seekTo

(time: number) => void

Seek to a specific time in seconds.

setCurrentTime

(time: number) => void

Set the current playback position in seconds.

setTrackMute

(trackIndex: number, muted: boolean) => void

Mute or unmute a track.

setTrackSolo

(trackIndex: number, soloed: boolean) => void

Solo or unsolo a track. Soloed tracks mute all other tracks.

setTrackVolume

(trackIndex: number, volume: number) => void

Set track volume (0-1).

setTrackPan

(trackIndex: number, pan: number) => void

Set track stereo pan (-1 to 1, where -1 is left, 0 is center, 1 is right).

setSelection

(start: number, end: number) => void

Set the time selection range in seconds.

setSelectedTrackId

(trackId: string | null) => void

Select a track by ID for editing operations.

setTimeFormat

(format: TimeFormat) => void

Set the time display format (‘seconds’, ‘hh:mm:ss’, ‘hh:mm:ss.u’).

formatTime

(seconds: number) => string

Format a time value according to the current time format.

zoomIn

() => void

Zoom in on the waveform visualization.

zoomOut

() => void

Zoom out on the waveform visualization.

setMasterVolume

(volume: number) => void

Set the master output volume (0-1).

setAutomaticScroll

(enabled: boolean) => void

Enable or disable automatic scrolling during playback.

setScrollContainer

(element: HTMLDivElement | null) => void

Set the container element for automatic scrolling.

scrollContainerRef

React.RefObject<HTMLDivElement | null>

Ref to the scroll container element.

setContinuousPlay

(enabled: boolean) => void

Enable continuous playback through annotations.

setLinkEndpoints

(enabled: boolean) => void

Link annotation endpoints for connected editing.

setAnnotationsEditable

(enabled: boolean) => void

Enable or disable annotation editing.

setAnnotations

React.Dispatch<React.SetStateAction<AnnotationData[]>>

React state setter for annotations array.

setActiveAnnotationId

(id: string | null) => void

Set the currently active annotation by ID.

setLoopEnabled

(enabled: boolean) => void

Enable or disable loop playback.

setLoopRegion

(start: number, end: number) => void

Set the loop region start and end times in seconds.

setLoopRegionFromSelection

() => void

Set the loop region to match the current selection.

clearLoopRegion

() => void

Clear the loop region.

usePlaylistState

Access current playlist state values.

Import

import { usePlaylistState } from '@waveform-playlist/browser';

Usage

function SelectionDisplay() {
  const { selectionStart, selectionEnd, isLoopEnabled, loopStart, loopEnd } = usePlaylistState();

  return (
    <div>
      <p>Selection: {selectionStart.toFixed(2)}s - {selectionEnd.toFixed(2)}s</p>
      {isLoopEnabled && (
        <p>Loop: {loopStart.toFixed(2)}s - {loopEnd.toFixed(2)}s</p>
      )}
    </div>
  );
}

Return Value

continuousPlay

boolean

Whether continuous playback through annotations is enabled.

linkEndpoints

boolean

Whether annotation endpoints are linked for connected editing.

annotationsEditable

boolean

Whether annotations can be edited.

isAutomaticScroll

boolean

Whether automatic scrolling during playback is enabled.

isLoopEnabled

boolean

Whether loop playback is enabled.

annotations

AnnotationData[]

Array of annotation data objects.

activeAnnotationId

string | null

ID of the currently active annotation.

selectionStart

number

Start time of the current selection in seconds.

selectionEnd

number

End time of the current selection in seconds.

selectedTrackId

string | null

ID of the currently selected track for editing operations.

loopStart

number

Start time of the loop region in seconds.

loopEnd

number

End time of the loop region in seconds.

usePlaybackAnimation

Access playback animation state and timing information. Use this for components that need to render in sync with audio playback at 60fps.

Import

import { usePlaybackAnimation } from '@waveform-playlist/browser';

Usage

function AnimatedPlayhead() {
  const { isPlaying, getPlaybackTime } = usePlaybackAnimation();
  const [position, setPosition] = useState(0);
  const animationRef = useRef<number | null>(null);

  useEffect(() => {
    if (!isPlaying) {
      if (animationRef.current) {
        cancelAnimationFrame(animationRef.current);
        animationRef.current = null;
      }
      return;
    }

    const animate = () => {
      const currentTime = getPlaybackTime();
      setPosition(currentTime);
      animationRef.current = requestAnimationFrame(animate);
    };

    animate();

    return () => {
      if (animationRef.current) {
        cancelAnimationFrame(animationRef.current);
      }
    };
  }, [isPlaying, getPlaybackTime]);

  return <div style={{ left: `${position * 100}px` }} />;
}

Return Value

isPlaying

boolean

Whether audio is currently playing.

currentTime

number

Current playback time in seconds. Updates at 60fps during playback.

currentTimeRef

React.RefObject<number>

Ref to the current time value. Use this in animation loops to avoid stale closures.

playbackStartTimeRef

React.RefObject<number>

AudioContext currentTime when playback started. Used for drift-free timing calculations.

audioStartPositionRef

React.RefObject<number>

Audio position in seconds when playback started.

getPlaybackTime

() => number

Returns the current playback time from the engine. Auto-wraps at loop boundaries.This is the recommended way to get playback time in animation loops as it reads directly from Transport.seconds for perfect audio sync.

usePlaylistData

Access playlist data including tracks, audio buffers, and peaks.

Import

import { usePlaylistData } from '@waveform-playlist/browser';

Usage

function PlaylistInfo() {
  const { duration, tracks, isReady, samplesPerPixel, sampleRate, canZoomIn, canZoomOut } = usePlaylistData();

  if (!isReady) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <p>Duration: {duration.toFixed(2)}s</p>
      <p>Tracks: {tracks.length}</p>
      <p>Sample Rate: {sampleRate} Hz</p>
      <p>Zoom: {samplesPerPixel} samples/pixel</p>
    </div>
  );
}

Return Value

duration

number

Total duration of the playlist in seconds.

audioBuffers

AudioBuffer[]

Array of AudioBuffer objects for all tracks.

peaksDataArray

TrackClipPeaks[]

Array of peak data for all tracks. Each track contains an array of clip peaks.

tracks

ClipTrack[]

Array of track objects with clips and metadata.

trackStates

TrackState[]

Array of track state objects (muted, soloed, volume, pan).

isReady

boolean

Whether the playlist has finished loading and is ready for playback.

samplesPerPixel

number

Current zoom level in samples per pixel.

sampleRate

number

Sample rate of the audio in Hz.

masterVolume

number

Master output volume (0-1).

canZoomIn

boolean

Whether zoom in is currently available.

canZoomOut

boolean

Whether zoom out is currently available.

timeFormat

TimeFormat

Current time display format.

Packages

Providers & Context

Hooks

Components

Types & Interfaces

usePlaylistControls

Import

Usage

Return Value

usePlaylistState

Import

Usage

Return Value

usePlaybackAnimation

Import

Usage

Return Value

usePlaylistData

Import

Usage

Return Value

Build docs developers (and LLMs) love

Packages

Providers & Context

Hooks

Components

Types & Interfaces

​usePlaylistControls

​Import

​Usage

​Return Value

​usePlaylistState

​Import

​Usage

​Return Value

​usePlaybackAnimation

​Import

​Usage

​Return Value

​usePlaylistData

​Import

​Usage

​Return Value

Build docs developers (and LLMs) love

usePlaylistControls

Import

Usage

Return Value

usePlaylistState

Import

Usage

Return Value

usePlaybackAnimation

Import

Usage

Return Value

usePlaylistData

Import

Usage

Return Value