Skip to main content
Get up and running with Waveform Playlist in just a few steps. This guide will walk you through creating a basic audio player with waveform visualization.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 16+ installed
  • A React 18+ or React 19 project
  • Basic knowledge of React hooks

​
Installation

1

Install the package

Install the main browser package along with required peer dependencies:
npm install @waveform-playlist/browser tone @dnd-kit/core @dnd-kit/modifiers react react-dom styled-components
The peer dependencies are required:
  • tone (^15.0.0) - Audio engine powered by Tone.js
  • @dnd-kit/core and @dnd-kit/modifiers - Drag-and-drop functionality
  • react and react-dom (^18.2.0 || ^19.0.0)
  • styled-components (^6.0.0) - Styling
2

Create a basic player component

Create a new component file (e.g., AudioPlayer.tsx) with the following code:
import { useState, useEffect } from 'react';
import { 
  WaveformPlaylistProvider, 
  Waveform, 
  PlayButton, 
  PauseButton, 
  StopButton 
} from '@waveform-playlist/browser';
import { createTrack, createClipFromSeconds } from '@waveform-playlist/core';

function AudioPlayer() {
  const [tracks, setTracks] = useState([]);

  useEffect(() => {
    async function loadAudio() {
      // Fetch audio file
      const response = await fetch('/audio/song.mp3');
      const arrayBuffer = await response.arrayBuffer();
      
      // Decode audio data
      const audioContext = new AudioContext();
      const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);

      // Create track with clip
      const track = createTrack({
        name: 'My Track',
        clips: [createClipFromSeconds({ audioBuffer, startTime: 0 })],
      });

      setTracks([track]);
    }
    
    loadAudio();
  }, []);

  return (
    <WaveformPlaylistProvider tracks={tracks}>
      <div>
        <PlayButton />
        <PauseButton />
        <StopButton />
      </div>
      <Waveform />
    </WaveformPlaylistProvider>
  );
}

export default AudioPlayer;
Replace /audio/song.mp3 with the path to your audio file. The file can be an MP3, WAV, OGG, or any format supported by the Web Audio API.
3

Use the component

Import and use your AudioPlayer component in your app:
import AudioPlayer from './AudioPlayer';

function App() {
  return (
    <div>
      <h1>My Audio Player</h1>
      <AudioPlayer />
    </div>
  );
}
4

Run your app

Start your development server:
npm run dev
You should see a waveform visualization with play, pause, and stop buttons!

​
What’s Next?

Now that you have a basic player running, explore more features:

Load multiple tracks

Learn how to load and manage multiple audio tracks

Add effects

Apply 20+ audio effects powered by Tone.js

Enable recording

Record audio directly in the browser

Add annotations

Add time-synced text annotations

​
Using with useAudioTracks

For a more robust loading approach with error handling and loading states, use the useAudioTracks hook: 
import { useState } from 'react';
import { 
  WaveformPlaylistProvider, 
  Waveform, 
  useAudioTracks,
  PlayButton,
  PauseButton,
  StopButton
} from '@waveform-playlist/browser';

function AudioPlayer() {
  const { tracks, loading, error } = useAudioTracks([
    { src: '/audio/vocals.mp3', name: 'Vocals' },
    { src: '/audio/drums.mp3', name: 'Drums' },
    { src: '/audio/bass.mp3', name: 'Bass' },
  ]);

  if (loading) return <div>Loading tracks...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <WaveformPlaylistProvider tracks={tracks}>
      <div>
        <PlayButton />
        <PauseButton />
        <StopButton />
      </div>
      <Waveform />
    </WaveformPlaylistProvider>
  );
}
The useAudioTracks hook handles fetching, decoding, and track creation automatically. It also provides loading states and error handling.

​
Customizing the Waveform

You can customize the appearance of the waveform using theme props: 
const customTheme = {
  waveOutlineColor: '#63C75F',
  waveFillColor: '#c49a6c',
  timeColor: '#d08070',
  backgroundColor: '#1a1a1a',
};

<WaveformPlaylistProvider tracks={tracks} theme={customTheme}>
  <Waveform />
</WaveformPlaylistProvider>
Learn more about theming in the Theming Guide.

​
Adding Zoom Controls

Add zoom in/out buttons to navigate long audio files: 
import { ZoomInButton, ZoomOutButton } from '@waveform-playlist/browser';

<WaveformPlaylistProvider tracks={tracks}>
  <div>
    <PlayButton />
    <PauseButton />
    <StopButton />
    <ZoomInButton />
    <ZoomOutButton />
  </div>
  <Waveform />
</WaveformPlaylistProvider>

​
Troubleshooting

Make sure you have:
  • Installed all peer dependencies (tone, @dnd-kit/core, @dnd-kit/modifiers, styled-components)
  • Wrapped components in WaveformPlaylistProvider
  • Provided valid tracks prop to the provider
Check that:
  • Your audio file path is correct
  • The audio file format is supported by your browser
  • There are no CORS issues (audio file must be served from same origin or have CORS headers)
  • AudioContext is resumed (modern browsers require user interaction before playing audio)
If you’re using TypeScript, make sure you have the type definitions installed. They’re included with the package, but you may need to add "moduleResolution": "node" to your tsconfig.json.

​
Next Steps

Core concepts

Understand how Waveform Playlist works

API reference

Explore the complete API

View examples

See live examples and demos

GitHub

View source code and contribute

Build docs developers (and LLMs) love

Get started for freeTalk to us