Skip to main content

​
Waveform

The main waveform visualization component that uses the WaveformPlaylistProvider context. Composes PlaylistVisualization (waveform + tracks) and PlaylistAnnotationList (annotation text list). Package: @waveform-playlist/browser Requires: WaveformPlaylistProvider context

​
Props

​
renderTrackControls
(trackIndex: number) => ReactNode
Custom render function for track controls panel. Receives the track index.
​
renderTimestamp
(timeMs: number, pixelPosition: number) => ReactNode
Custom render function for timescale timestamps. Receives time in milliseconds and pixel position.
​
renderPlayhead
RenderPlayheadFunction
Custom playhead render function. Receives position (pixels) and color from theme.
​
annotationControls
AnnotationAction[]
Action controls to show on each annotation item (e.g., delete, split). Only rendered when annotations are editable.
​
annotationListConfig
AnnotationActionOptions
Configuration options for the annotation list behavior.
​
annotationTextHeight
number
Height in pixels for the annotation text list below the waveform.
​
renderAnnotationItem
(props: RenderAnnotationItemProps) => ReactNode
Custom render function for annotation items in the text list. Use this to completely customize how each annotation is displayed.
​
getAnnotationBoxLabel
(annotation: AnnotationData, index: number) => string
Custom function to generate the label shown on annotation boxes in the waveform. Receives the annotation data and its index, returns a string label. Default: annotation.id
​
scrollActivePosition
'center' | 'start' | 'end' | 'nearest'
default:"center"
Where to position the active annotation when auto-scrolling.
​
scrollActiveContainer
'nearest' | 'all'
default:"nearest"
Which scrollable containers to scroll: ‘nearest’ (only the annotation list) or ‘all’ (including viewport).
​
className
string
Additional CSS class name.
​
showClipHeaders
boolean
default:"false"
Show headers on clips for visual organization.
​
interactiveClips
boolean
default:"false"
Enable dragging/trimming interactions on clips (requires @dnd-kit setup).
​
showFades
boolean
default:"false"
Show fade in/out overlays on clips.
​
touchOptimized
boolean
default:"false"
Enable mobile-optimized touch interactions. When true, increases touch target sizes for clip boundaries. Use with useDragSensors({ touchOptimized: true }) for best results.
​
onRemoveTrack
(trackIndex: number) => void
Callback when a track’s close button is clicked. Only renders close button when provided.
​
recordingState
object
Live recording state for real-time waveform preview.

​
Usage

import { WaveformPlaylistProvider, Waveform } from '@waveform-playlist/browser';

function App() {
  return (
    <WaveformPlaylistProvider tracks={tracks}>
      <Waveform 
        showClipHeaders
        interactiveClips
        showFades
        annotationTextHeight={200}
      />
    </WaveformPlaylistProvider>
  );
}

​
MediaElementWaveform

Simplified waveform component for the MediaElementPlaylistProvider context. A stripped-down version that works with the MediaElement context for single-track visualization with annotations. Package: @waveform-playlist/browser Requires: MediaElementPlaylistProvider context Use case: Single track visualization, click to seek, annotation display and click-to-play, playhead animation. For multi-track editing, use the full Waveform component.

​
Props

​
annotationTextHeight
number
Height in pixels for the annotation text list.
​
getAnnotationBoxLabel
(annotation: AnnotationData, index: number) => string
Custom function to generate the label shown on annotation boxes.
​
renderAnnotationItem
(props: RenderAnnotationItemProps) => React.ReactNode
Custom render function for annotation items in the text list. When provided, completely replaces the default annotation item rendering. Use this to customize the appearance of each annotation (e.g., add furigana).
​
editable
boolean
default:"false"
Whether annotation boundaries can be edited by dragging.
​
linkEndpoints
boolean
default:"false"
Whether dragging one annotation boundary also moves the adjacent annotation’s boundary.
​
onAnnotationUpdate
(annotations: AnnotationData[]) => void
Callback when annotations are updated (e.g., boundaries dragged). Called with the full updated annotations array.
​
scrollActivePosition
'center' | 'start' | 'end' | 'nearest'
default:"center"
Where to position the active annotation when auto-scrolling.
​
scrollActiveContainer
'nearest' | 'all'
default:"nearest"
Which scrollable containers to scroll: ‘nearest’ (only the annotation list) or ‘all’ (including viewport).
​
className
string
Additional CSS class name.

​
Usage

import { MediaElementPlaylistProvider, MediaElementWaveform } from '@waveform-playlist/browser';

function SimplePlayer() {
  const [annotations, setAnnotations] = useState([]);
  
  return (
    <MediaElementPlaylistProvider 
      audioUrl="/audio.mp3"
      annotations={annotations}
    >
      <MediaElementWaveform 
        editable
        linkEndpoints
        onAnnotationUpdate={setAnnotations}
        annotationTextHeight={150}
      />
    </MediaElementPlaylistProvider>
  );
}

​
PlaylistVisualization

Standalone playlist visualization component (WebAudio version). Renders the waveform tracks, timescale, annotation boxes, selection, playhead, loop regions, and track controls — everything inside <Playlist> plus wrapping providers. Package: @waveform-playlist/browser Requires: WaveformPlaylistProvider context Note: Does NOT render the annotation text list. Pair with PlaylistAnnotationList for a full annotation editing UI, or use the Waveform component which includes both.

​
Props

Accepts the same props as Waveform except for annotation list-specific props (annotationTextHeight, renderAnnotationItem, scrollActivePosition, scrollActiveContainer).
​
renderTrackControls
(trackIndex: number) => ReactNode
Custom render function for track controls panel.
​
renderTimestamp
(timeMs: number, pixelPosition: number) => ReactNode
Custom render function for timescale timestamps.
​
renderPlayhead
RenderPlayheadFunction
Custom playhead render function.
​
annotationControls
AnnotationAction[]
Action controls for annotations.
​
getAnnotationBoxLabel
(annotation: AnnotationData, index: number) => string
Custom function to generate annotation box labels.
​
className
string
Additional CSS class name.
​
showClipHeaders
boolean
default:"false"
Show headers on clips.
​
interactiveClips
boolean
default:"false"
Enable dragging/trimming interactions on clips.
​
showFades
boolean
default:"false"
Show fade in/out overlays.
​
touchOptimized
boolean
default:"false"
Enable mobile-optimized touch interactions.
​
onRemoveTrack
(trackIndex: number) => void
Callback when track close button is clicked.
​
recordingState
object
Live recording state for real-time waveform preview.

​
Usage

import { WaveformPlaylistProvider, PlaylistVisualization } from '@waveform-playlist/browser';

function CustomEditor() {
  return (
    <WaveformPlaylistProvider tracks={tracks}>
      <PlaylistVisualization 
        showClipHeaders
        interactiveClips
      />
      {/* Custom annotation UI */}
    </WaveformPlaylistProvider>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us