wavesurfer.js

Wavesurfer.js is an interactive waveform rendering and audio playback library, perfect for web applications. It leverages modern web technologies to provide a robust and visually engaging audio experience.

---

Gold Sponsor 💖 Closed Caption Creator – Professional Subtitle Editor

---

Table of contents

1. Getting started
2. API reference
3. Plugins
4. Advanced / reactive API
5. CSS styling
6. Frequent questions
7. Development
8. Tests
9. Feedback

Getting started

Install and import the package:

npm install --save wavesurfer.js

import WaveSurfer from 'wavesurfer.js'

Alternatively, insert a UMD script tag which exports the library as a global WaveSurfer variable:

<script src="https://unpkg.com/wavesurfer.js@8"></script>

Create a wavesurfer instance and pass various options:

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

To import one of the plugins, e.g. the Regions plugin:

import Regions from 'wavesurfer.js/dist/plugins/regions.esm.js'

Or as a script tag that will export WaveSurfer.Regions:

<script src="https://unpkg.com/wavesurfer.js@8/dist/plugins/regions.min.js"></script>

TypeScript types are included in the package, so there's no need to install @types/wavesurfer.js.

See more examples.

Documentation

See the wavesurfer.js guide on our website for beginner-friendly, practical documentation covering common use cases, plugins, framework integration, and troubleshooting.

API reference

The full generated API reference lives at wavesurfer.xyz/docs/api:

• methods
• options
• events

Plugins

We maintain a number of official plugins that add various extra features:

• Regions – visual overlays and markers for regions of audio
• Timeline – displays notches and time labels below the waveform
• Minimap – a small waveform that serves as a scrollbar for the main waveform
• Envelope – a graphical interface to add fade-in and -out effects and control volume
• Record – records audio from the microphone and renders a waveform
• Spectrogram – visualization of an audio frequency spectrum (written by @akreal)
• Hover – shows a vertical line and timestmap on waveform hover

Advanced / reactive API

Beyond the imperative wavesurfer.on(...) events, v8 exposes a small reactive surface for apps that want to read state instead of tracking it themselves:

const state = wavesurfer.getState()

state.isPlaying.subscribe((playing) => console.log('playing:', playing))
console.log(state.loadPhase.value) // 'idle' | 'fetching' | 'decoding' | 'ready' | 'error'

const { startTime, endTime } = wavesurfer.getRenderer().getVisibleRange().value

getState() returns read-only Signal objects (.value to read, .subscribe(fn) to watch) for things like currentTime, isPlaying, volume, muted, loadPhase and scrollPosition. getRenderer().getVisibleRange() is a derived signal with the currently visible {startTime, endTime} of the viewport, useful for plugins that need to sync to what's on screen (e.g. a custom minimap or timeline).

If you're writing a plugin, WaveSurfer.definePlugin(name, (ctx, options) => api) is an alternative to subclassing BasePlugin: ctx gives you { wavesurfer, scope, state, emit }, and anything you register on ctx.scope (listeners, timers, child scopes) is torn down automatically on destroy() — no manual cleanup array required.

import WaveSurfer from 'wavesurfer.js'

const MyPlugin = WaveSurfer.definePlugin('MyPlugin', (ctx, options) => {
  ctx.scope.listen(ctx.wavesurfer.getWrapper(), 'click', () => ctx.emit('my-event'))
  return { doSomething: () => {} }
})

The Spectrogram plugin accepts a rendering: 'windowed' option for very long audio files: it renders only the visible time range and evicts off-screen segments, instead of computing the whole file's frequency data up front.

SpectrogramPlugin.create({ rendering: 'windowed', /* ...other options */ })

This replaces the standalone WindowedSpectrogramPlugin (spectrogram-windowed.js), which is now deprecated in favor of the merged option above — it's kept working as a thin backward-compatible shim, but new code should use SpectrogramPlugin directly.

CSS styling

wavesurfer.js v7 is rendered into a Shadow DOM tree. This isolates its CSS from the rest of the web page. However, it's still possible to style various wavesurfer.js elements with CSS via the ::part() pseudo-selector. For example:

This is the beginning of the README. Read the rest at the original. Read the full README ↗