Core concepts

The instance and its options

Every wavesurfer.js integration starts with a single call:

import WaveSurfer from 'wavesurfer.js'

const ws = WaveSurfer.create(options)

WaveSurfer.create() accepts an options object of type WaveSurferOptions. Only container is required; everything else has a default.

Most-used options

Changing options after creation

Call ws.setOptions(partialOptions) at any time to update one or more options. The waveform re-renders automatically:

ws.setOptions({ waveColor: '#1a73e8', barWidth: 3 })

How audio is played: MediaElement vs WebAudio

wavesurfer.js supports two playback backends, selected via the backend option.

MediaElement (default)

The default backend uses a standard <audio> element. The browser streams and decodes the file progressively, so playback can begin before the file has fully downloaded. This is ideal for:

• Long files or podcast audio where you do not need the full file in memory
• Streaming sources (HTTP Live Streaming, etc.)
• Scenarios where low initial memory use matters

wavesurfer still fetches and decodes a copy of the audio separately (at the lower sample rate set by sampleRate) to draw the waveform. The media element and the decoded waveform data are kept in sync but are separate objects.

WebAudio backend

Pass backend: 'WebAudio' to route playback through a Web Audio AudioContext and AudioBufferSourceNode:

const ws = WaveSurfer.create({
  container: '#waveform',
  url: '/audio.mp3',
  backend: 'WebAudio',
})

The entire file is fetched and decoded into an AudioBuffer before playback can start. Trade-offs:

Lifecycle

Understanding the sequence of events helps you wire up your UI correctly.

Creation to ready

WaveSurfer.create(options)
  → (async) load starts
  → 'decode'   fired when audio data has been decoded and the waveform is drawn
  → 'ready'    fired when the audio is decoded *and* can be played

In code:

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

ws.on('decode', (duration) => {
  console.log('Waveform drawn, duration:', duration)
})

ws.on('ready', (duration) => {
  console.log('Ready to play, duration:', duration)
  ws.play()
})

When you supply pre-decoded peaks and duration (and no url), wavesurfer skips network loading and fires decode / ready immediately after the waveform is drawn.

Teardown

Always call ws.destroy() when the component or page that owns the waveform is removed. It stops playback, removes all DOM nodes, cancels any in-flight network requests, and unregisters all event listeners and plugins.

// React example
useEffect(() => {
  const ws = WaveSurfer.create({ container: ref.current, url })
  return () => ws.destroy()
}, [url])

Failing to destroy leaves orphaned DOM nodes and event listeners, which can degrade performance in single-page applications over time. See Performance for further guidance.

Sizing the waveform

The waveform always fills the full width of its container element. Do not set a fixed width on the container if you want the waveform to be responsive — let it follow the parent’s width naturally.

Height

Control the height with the height option:

// Fixed height in pixels
WaveSurfer.create({ container: '#waveform', height: 80 })

// Fill the container's height
WaveSurfer.create({ container: '#waveform', height: 'auto' })

With a numeric value, the canvas is exactly that many pixels tall regardless of the container. With 'auto', wavesurfer reads the container’s clientHeight and uses that — useful when the container is already sized by your CSS.

Responsive resizing

wavesurfer attaches a ResizeObserver to its scroll container and automatically re-renders the waveform when the container changes size. No manual intervention is needed — just make sure the container is in the DOM and has a measurable size when WaveSurfer.create() is called.