wavesurfer.js is a customizable audio waveform visualization, built on top of Web Audio API and HTML5 Canvas.

Getting started

First of all, you need to insert the wavesurfer.js library into your HTML page. You can grab the latest version from cdnjs.com. <script src="wavesurfer.min.js"></script>

Create a container where you want the waveform to appear: <div id="waveform"></div>

Next, in your JavaScript code, create an instance of the global WaveSurfer object. var wavesurfer = WaveSurfer.create({ container: '#waveform' });

Parameters

The only required parameter is container. It can be either a unique CSS3 selector, or a DOM element.

However, you can also pass any number of options. For example, to make the waveform scrollable, pass the the scrollParent option: var wavesurfer = WaveSurfer.create({ container: '#waveform', scrollParent: true });

See the full list of Options later in this document.

Loading the audio

After creating an instance, you may want to load an audio track and draw its waveform. You can load files either from the same domain: wavesurfer.load('../audio/song.mp3');

wavesurfer.js will load the file, decode it and display a nice waveform image. When it's done, it will fire the ready event.

Listening to events

wavesurfer.js has a number of useful events you can subscribe to. The ready event, mentioned above, can be used like this: wavesurfer.on('ready', function () { wavesurfer.play(); });

Documentation

Options

This is the list of parameters you can pass to var wavesurfer = WaveSurfer.create({ ... }) to create an instance of the player.

option type default description
audioRate float 1 Speed at which to play audio. Lower number is slower.
audioContext object none Use your own previously initialized AudioContext or leave blank.
audioScriptProcessor object none Use your own previously initialized ScriptProcessorNode or leave blank.
autoCenter boolean TRUE If a scrollbar is present, center the waveform around the progress.
backend string WebAudio WebAudio or MediaElement. In most cases you don't have to set this manually. MediaElement is a fallback for unsupported browsers.
barGap number none The optional spacing between bars of the wave, if not provided will be calculated in legacy format.
barHeight number 1 Height of the waveform bars. Higher number than 1 will increase the waveform bar heights.
barWidth number none If specified, the waveform will be drawn like this: ▁ ▂ ▇ ▃ ▅ ▂
closeAudioContext boolean FALSE Close and nullify all audio contexts when the destroy method is called.
container mixed none CSS-selector or HTML-element where the waveform should be drawn. This is the only required parameter.
cursorColor string #333 The fill color of the cursor indicating the playhead position.
cursorWidth integer 1 Measured in pixels.
fillParent boolean TRUE Whether to fill the entire container or draw only according to minPxPerSec.
forceDecode boolean FALSE Force decoding of audio using web audio when zooming to get a more detailed waveform.
height integer 128 The height of the waveform. Measured in pixels.
hideScrollbar boolean FALSE Whether to hide the horizontal scrollbar when one would normally be shown.
interact boolean TRUE Whether the mouse interaction will be enabled at initialization. You can switch this parameter at any time later on.
loopSelection boolean TRUE (Use with regions plugin) Enable looping of selected regions.
maxCanvasWidth integer 4000 Maximum width of a single canvas in pixels, excluding a small overlap (2 * pixelRatio, rounded up to the next even integer). If the waveform is longer than this value, additional canvases will be used to render the waveform, which is useful for very large waveforms that may be too wide for browsers to draw on a single canvas. This parameter is only applicable to the MultiCanvas renderer.
mediaControls boolean FALSE (Use with backend MediaElement) this enables the native controls for the media element.
mediaType string audio 'audio' or 'video'. Only used with backend MediaElement.
minPxPerSec integer 50 Minimum number of pixels per second of audio.
normalize boolean FALSE If true, normalize by the maximum peak instead of 1.0.
partialRender boolean FALSE Use the PeakCache to improve rendering speed of large waveforms.
pixelRatio integer window.devicePixelRatio Can be set to 1 for faster rendering.
plugins array [] An array of plugin definitions to register during instantiation. They will be directly initialised unless they are added with the deferInit property set to true.
progressColor string #555 The fill color of the part of the waveform behind the cursor.
removeMediaElementOnDestroy boolean TRUE Set to false to keep the media element in the DOM when the player is destroyed. This is useful when reusing an existing media element via the loadMediaElement method.
renderer Object MultiCanvas Can be used to inject a custom renderer.
responsive boolean or float FALSE If set to true resize the waveform, when the window is resized. This is debounced with a 100ms timeout by default. If this parameter is a number it represents that timeout.
scrollParent boolean FALSE Whether to scroll the container with a lengthy waveform. Otherwise the waveform is shrunk to the container width (see fillParent).
skipLength float 2 Number of seconds to skip with the skipForward() and skipBackward() methods.
splitChannels boolean FALSE Render with seperate waveforms for the channels of the audio.
waveColor string #999 The fill color of the waveform after the cursor.
xhr Object {} XHR options.

Methods

After creating an instance of the player (with var wavesurfer = WaveSurfer.create({ ... })), you can call the following methods on it:

Events

You can use on() and un() methods to subscribe and unsubscribe from various player events. For example: wavesurfer.on('pause', function () { wavesurfer.params.container.style.opacity = 0.9; });

Here's the list of available events: