Skip to main content
Waveform Playlist is distributed as npm packages. The main package @waveform-playlist/browser provides React components and hooks for building waveform-based audio applications.

​
Install the core packages

Install the main package along with its required peer dependencies: 
npm install @waveform-playlist/browser tone @dnd-kit/core @dnd-kit/modifiers react styled-components
If you already have React installed in your project, you can omit it from the installation command.

​
Peer dependencies explained

Waveform Playlist requires several peer dependencies that you must install separately:

​
Required dependencies

Tone.js is a Web Audio framework that powers the audio playback engine. Waveform Playlist uses Tone.js for:
  • Audio transport and scheduling
  • Audio effects (reverb, delay, filters, etc.)
  • Master volume and panning
  • Offline rendering for WAV export
@dnd-kit is a modern drag-and-drop library for React. Waveform Playlist uses it for:
  • Drag-to-move clips between tracks
  • Drag-to-trim clip boundaries
  • Drag-to-create and edit annotations
Both packages are required for full drag-and-drop functionality.
Waveform Playlist is built with React and requires React 18.2.0 or higher. React 19 is also supported.
styled-components is used for component styling and theming. All UI components support customization through the theme system.

​
Optional packages

Depending on your use case, you may want to install these optional packages:

​
Annotations

For time-synced text annotations with keyboard navigation: 
npm install @waveform-playlist/annotations
See the annotations guide for setup instructions and examples.

​
Recording

For AudioWorklet-based audio recording with live waveform preview: 
npm install @waveform-playlist/recording
Recording requires additional AudioWorklet setup. See the recording guide for complete setup instructions.

​
Package versions

All @waveform-playlist/* packages use synchronized versioning. When installing, make sure all packages are on the same version (e.g., all 8.1.0).
package.json
{
  "dependencies": {
    "@waveform-playlist/browser": "^8.1.0",
    "@waveform-playlist/annotations": "^8.1.0",
    "@waveform-playlist/recording": "^8.1.0",
    "tone": "^15.0.0",
    "@dnd-kit/core": "^6.0.0",
    "@dnd-kit/modifiers": "^9.0.0",
    "react": "^18.2.0",
    "styled-components": "^6.0.0"
  }
}

​
TypeScript setup

Waveform Playlist is written in TypeScript and includes full type definitions. No additional @types packages are needed. If you’re using TypeScript, ensure your tsconfig.json includes:
tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

​
Verify installation

To verify your installation is complete, try importing the main components:
App.tsx
import { WaveformPlaylistProvider, Waveform, PlayButton } from '@waveform-playlist/browser';

// If this compiles without errors, you're ready to go!

​
Next steps

Quickstart

Build your first waveform player with a complete working example

Build docs developers (and LLMs) love

Get started for freeTalk to us