wavesurfer.js

What is wavesurfer.js?

wavesurfer.js is a customizable audio waveform visualization library, built on top of Web Audio API and HTML5 Canvas. It allows you to create interactive audio waveforms, add regions, and control playback, among other features.

What are wavesurfer.js's main functionalities?

Waveform Visualization

This feature allows you to create a visual representation of an audio file's waveform. The code sample demonstrates how to initialize WaveSurfer and load an audio file for visualization.

const WaveSurfer = require('wavesurfer.js');
const wavesurfer = WaveSurfer.create({
  container: '#waveform',
  waveColor: 'violet',
  progressColor: 'purple'
});
wavesurfer.load('path/to/audio/file.mp3');

Playback Control

This feature provides methods to control audio playback, such as play, pause, and stop. The code sample shows how to play the audio once it's ready and how to pause and stop playback.

wavesurfer.on('ready', function () {
  wavesurfer.play();
});

// Pause playback
wavesurfer.pause();

// Stop playback
wavesurfer.stop();

Regions

This feature allows you to add regions to the waveform, which can be used to highlight specific parts of the audio. The code sample demonstrates how to add a region from 5 to 10 seconds with a semi-transparent green color.

wavesurfer.on('ready', function () {
  wavesurfer.addRegion({
    start: 5,    // time in seconds
    end: 10,     // time in seconds
    color: 'rgba(0, 255, 0, 0.1)'
  });
});

Plugins

wavesurfer.js supports various plugins to extend its functionality. The code sample demonstrates how to add and initialize a cursor plugin that shows the current time on the waveform.

const cursorPlugin = WaveSurfer.cursor.create({
  showTime: true,
  opacity: 1,
  customShowTimeStyle: {
    'background-color': '#000',
    color: '#fff',
    padding: '2px',
    'font-size': '10px'
  }
});
wavesurfer.addPlugin(cursorPlugin).initPlugin('cursor');

0

README

wavesurfer.js

Interactive navigable audio visualization using Web Audio and Canvas.

API in examples

Create an instance:

var wavesurfer = Object.create(WaveSurfer);

Initialize it with a container element (plus some options):

wavesurfer.init({
    container: '#wave',
    waveColor: 'violet',
    progressColor: 'purple'
});

Subscribe to some events:

wavesurfer.on('ready', function () {
    wavesurfer.play();
});

Load an audio file from a URL:

wavesurfer.load('example/media/demo.wav');

See the example code here.

WaveSurfer Options

option	type	default	description
audioContext	string	null	Use your own previously initialized AudioContext or leave blank.
audioRate	float	1	Speed at which to play audio. Lower number is slower.
backend	string	WebAudio	WebAudio or AudioElement. In most cases you don't have to set this manually. AudioElement is a fallback for unsupported browsers.
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.
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.
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.
pixelRatio	integer	window.devicePixelRatio	Can be set to 1 for faster rendering.
progressColor	string	#555	The fill color of the part of the waveform behind the cursor.
scrollParent	boolean	false	Whether to scroll the container with a lengthy waveform. Otherwise the waveform is shrinked to container width (see fillParent).
skipLength	float	2	Number of seconds to skip with the skipForward() and skipBackward() methods.
waveColor	string	#999	The fill color of the waveform after the cursor.

WaveSurfer Methods

All methods are intentionally public, but the most readily available are the following:

• init(options) – Initializes with the options listed above.
• destroy() – Removes events, elements and disconnects Web Audio nodes.
• empty() – Clears the waveform as if a zero-length audio is loaded.
• getCurrentTime() – Returns current progress in seconds.
• getDuration() – Returns the duration of an audio clip in seconds.
• load(url) – Loads an audio from URL via XHR. Returns XHR object.
• on(eventName, callback) – Subscribes to an event. See WaveSurfer Events section below for a list.
• pause() – Stops playback.
• play([start[, end]]) – Starts playback from the current position. Optional start and end measured in seconds can be used to set the range of audio to play.
• playPause() – Plays if paused, pauses if playing.
• seekAndCenter(progress) – Seeks to a progress and centers view [0..1] (0 = beginning, 1 = end).
• seekTo(progress) – Seeks to a progress [0..1] (0=beginning, 1=end).
• setFilter(filters) - For inserting your own WebAudio nodes into the graph. See Connecting Filters below.
• setPlaybackRate(rate) – Sets the speed of playback (0.5 is half speed, 1 is normal speed, 2 is double speed and so on).
• setVolume(newVolume) – Sets the playback volume to a new value [0..1] (0 = silent, 1 = maximum).
• skip(offset) – Skip a number of seconds from the current position (use a negative value to go backwards).
• skipBackward() - Rewind skipLength seconds.
• skipForward() - Skip ahead skipLength seconds.
• stop() – Stops and goes to the beginning.
• toggleMute() – Toggles the volume on and off.
• toggleInteraction() – Toggle mouse interaction.
• toggleScroll() – Toggles scrollParent.

Connecting Filters

You can insert your own Web Audio nodes into the graph using the method setFilter(). Example:

var lowpass = wavesurfer.backend.ac.createBiquadFilter();
wavesurfer.backend.setFilter(lowpass);

WaveSurfer Events

General events:

• error – Occurs on error. Callback will receive (string) error message.
• finish – When it finishes playing.
• loading – Fires continuously when loading via XHR or drag'n'drop. Callback will receive (integer) loading progress in percents [0..100] and (object) event target.
• mouseup - When a mouse button goes up. Callback will receive MouseEvent object.
• play – When play starts.
• ready – When audio is loaded, decoded and the waveform drawn.
• scroll - When the scrollbar is moved. Callback will receive a ScrollEvent object.
• seek – On seeking. Callback will receive (float) progress [0..1].

Region events (exposed by the Regions plugin):

• region-in – When playback enters a region. Callback will receive the Region object.
• region-out– When playback leaves a region. Callback will receive the Region object.
• region-mouseenter - When the mouse moves over a region. Callback will receive the Region object, and a MouseEvent object.
• region-mouseleave - When the mouse leaves a region. Callback will receive the Region object, and a MouseEvent object.
• region-click - When the mouse clicks on a region. Callback will receive the Region object, and a MouseEvent object.
• region-dblclick - When the mouse double-clicks on a region. Callback will receive the Region object, and a MouseEvent object.
• region-created – When a region is created. Callback will receive the Region object.
• region-updated – When a region is updated. Callback will receive the Region object.
• region-removed – When a region is removed. Callback will receive the Region object.

Regions Plugin

Regions are visual overlays on waveform that can be used to play and loop portions of audio. Regions can be dragged and resized.

Visual customization is possible via CSS (using the selectors .wavesurfer-region and .wavesurfer-handle).

To enable the plugin, add the script plugin/wavesurfer.regions.js to your page.

After doing that, use wavesurfer.addRegion() to create Region objects.

Exposed Methods

• addRegion(options) – Creates a region on the waveform. Returns a Region object. See Region Options, Region Methods and Region Events below.
• clearRegions() – Removes all regions.
• enableDragSelection(options) – Lets you create regions by selecting. areas of the waveform with mouse. options are Region objects' params (see below).

Region Options

option	type	default	description
start	float	0	The start position of the region (in seconds).
end	float	0	The end position of the region (in seconds).
loop	boolean	false	Whether to loop the region when played back.
drag	boolean	true	Allow/dissallow dragging the region.
resize	boolean	true	Allow/dissallow resizing the region.
color	string	"rgba(0, 0, 0, 0.1)"	HTML color code.

Region Methods

• remove() - Remove the region object.
• update(options) - Modify the settings of the region.
• play() - Play the audio region from the start to end position.

Region Events

General events:

• in - When playback enters the region.
• out - When playback leaves the region.
• remove - Happens just before the region is removed.
• update - When the region's options are updated.

Mouse events:

• click - When the mouse clicks on the region. Callback will receive a MouseEvent.
• dblclick - When the mouse double-clicks on the region. Callback will receive a MouseEvent.
• over - When mouse moves over the region. Callback will receive a MouseEvent.
• leave - When mouse leaves the region. Callback will receive a MouseEvent.

Credits

Initial idea by Alex Khokhulin. Many thanks to the awesome contributors!

License

This work is licensed under a Creative Commons Attribution 3.0 Unported License.