wavesurfer.js documentation

What is wavesurfer.js

wavesurfer.js is an interactive waveform rendering and audio playback library for the web. It lets you embed a visual, interactive audio player in any web page — users can see the waveform, click to seek, and control playback. Under the hood it combines the Web Audio API with standard HTML5 <audio>/<video> elements to decode and play audio. Version 7 (targeted here, v7.12.6) is a ground-up TypeScript rewrite with a cleaner API, Shadow DOM isolation, and first-class plugin support.

How it fits together

wavesurfer.js has three main pieces:

• Player — manages audio playback through an <audio> or <video> element (the default) or a Web Audio AudioContext when you opt into the WebAudio backend.
• Renderer — draws the waveform onto an HTML Canvas inside a Shadow DOM, keeping its styles isolated from the rest of your page.
• Plugins — optional add-ons (Regions, Timeline, Spectrogram, Minimap, Record, Envelope, Hover, …) that extend the core with extra visual or interactive behaviour.

A 30-second example

Install the package and create a waveform with four lines of configuration:

npm install wavesurfer.js

import WaveSurfer from 'wavesurfer.js'

const ws = WaveSurfer.create({
  container: '#waveform',
  waveColor: '#4F4A85',
  progressColor: '#383351',
  url: '/audio.mp3',
})

ws.on('click', () => ws.playPause())

container is the only required option — every other option has a sensible default. The click event fires whenever the user clicks on the waveform, and playPause() toggles playback.

Where to go next

• Getting started — installation, CDN usage, and your first working example.
• Core concepts — options, events, and methods explained in depth.
• Plugins overview — how to add Regions, Timeline, Spectrogram, and more.
• API reference — full TypeDoc reference for every option, method, and event.

You can also explore the live Examples to see wavesurfer.js in action and copy patterns directly from the source.

Browser support

wavesurfer.js works in all modern evergreen browsers — Chrome, Firefox, Edge, and Safari (desktop and iOS). Internet Explorer is not supported.