Getting started

Want to see wavesurfer.js running immediately? Jump to the live Basic example — you can read and edit the source right in the browser.

Install

npm

npm install --save wavesurfer.js

Then import the default export in your JavaScript or TypeScript file:

import WaveSurfer from 'wavesurfer.js'

TypeScript types are bundled in the package — no separate @types/ package is needed.

CDN (UMD global)

Add a single <script> tag and the library is available as window.WaveSurfer:

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

After the script loads, use WaveSurfer.create(...) directly — no import statement required.

ESM from CDN

If you prefer native ES modules without a build step, import the ESM bundle directly in a <script type="module">:

import WaveSurfer from 'https://unpkg.com/wavesurfer.js@7/dist/wavesurfer.esm.js'

Your first waveform

Paste this complete HTML page into a file, point url at an audio file on the same server, and open it in a browser:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My first waveform</title>
</head>
<body>

  <div id="waveform"></div>
  <button id="play-btn">Play / Pause</button>

  <script src="https://unpkg.com/wavesurfer.js@7"></script>
  <script>
    const ws = WaveSurfer.create({
      container: '#waveform',
      waveColor: '#4F4A85',
      progressColor: '#383351',
      url: '/audio.mp3',
    })

    // Click the waveform itself to seek
    ws.on('click', () => ws.playPause())

    // Or use the button
    document.getElementById('play-btn').addEventListener('click', () => ws.playPause())
  </script>

</body>
</html>

Replace /audio.mp3 with a path to a real audio file served from the same origin, or a public URL such as https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3. Browsers block cross-origin audio unless the server sends appropriate CORS headers.

The mental model

One instance per container. Each call to WaveSurfer.create() controls exactly one waveform in exactly one DOM element. If you need multiple waveforms on the same page, call create() once per container.

Give it audio via url or load(). You can pass audio at construction time with the url option, or load it later with ws.load(url). Both are equivalent — url just calls load() for you automatically.

Wait for ready before inspecting duration. The waveform is drawn and the duration is available after the 'ready' event fires. Register the listener before calling load() (or before the constructor returns when using url):

ws.on('ready', () => {
  console.log('Duration:', ws.getDuration(), 'seconds')
})

Control playback with methods. The most common methods are:

Method	What it does
`ws.play()`	Start playback
`ws.pause()`	Pause playback
`ws.playPause()`	Toggle play/pause
`ws.seekTo(progress)`	Jump to a position — `progress` is 0 (start) to 1 (end)
`ws.load(url)`	Load a new audio file

Next steps

Core concepts — all options, events, and methods explained in depth.
Loading audio — pre-decoded peaks, blobs, and media elements.