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

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

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@7"></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@7/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.

API reference

See the wavesurfer.js documentation on our website:

• 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

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:

#waveform ::part(cursor):before {
  content: '🏄';
}
#waveform ::part(region) {
  font-family: fantasy;
}

You can see which elements you can style in the DOM inspector – they will have a part attribute. See this example to play around with styling.

Questions

Have a question about integrating wavesurfer.js on your website? Feel free to ask in our Discussions forum.

However, please keep in mind that this forum is dedicated to wavesurfer-specific questions. If you're new to JavaScript and need help with the general basics like importing NPM modules, please consider asking ChatGPT or StackOverflow first.

FAQ

I'm having CORS issues

Wavesurfer fetches audio from the URL you specify in order to decode it. Make sure this URL allows fetching data from your domain. In browser JavaScript, you can only fetch data eithetr from the same domain or another domain if and only if that domain enables CORS. So if your audio file is on an external domain, make sure that domain sends the right Access-Control-Allow-Origin headers. There's nothing you can do about it from the requesting side (i.e. your JS code).

Does wavesurfer support large files?

Since wavesurfer decodes audio entirely in the browser using Web Audio, large clips may fail to decode due to memory constraints. We recommend using pre-decoded peaks for large files (see this example). You can use a tool like bbc/audiowaveform to generate peaks.

What about streaming audio?

Streaming audio is supported only with pre-decoded peaks and duration.

There is a mismatch between my audio and the waveform. How do I fix it?

If you're using a VBR (variable bit rate) audio file, there might be a mismatch between the audio and the waveform. This can be fixed by converting your file to CBR (constant bit rate).

Alternatively, you can use the Web Audio shim which is more accurate.

How do I connect wavesurfer.js to Web Audio effects?

Generally, wavesurfer.js doesn't aim to be a wrapper for all things Web Audio. It's just a player with a waveform visualization. It does allow connecting itself to a Web Audio graph by exporting its audio element (see this example) but nothign more than that. Please don't expect wavesurfer to be able to cut, add effects, or process your audio in any way.

v7 – a new TypeScript version

Wavesurfer.js v7 is a TypeScript rewrite of wavesurfer.js that brings several improvements:

• Typed API for better development experience
• Enhanced decoding and rendering performance
• New and improved plugins

Upgrading from v6

Most options, events, and methods are similar to those in previous versions.

Notable differences

• HTML audio playback by default (used to be an opt-in via backend: "MediaElement")
• The Markers plugin is removed – you should use the Regions plugin with just a startTime.
• No Microphone plugin – superseded by the new Record plugin with more features.
• The Cursor plugin is replaced by the Hover plugin.

Removed options

• audioContext, closeAudioContext, audioScriptProcessor
• autoCenterImmediately – autoCenter is now always immediate unless the audio is playing
• backgroundColor, hideCursor – this can be easily set via CSS
• mediaType – you should instead pass an entire media element in the media option. Example.
• partialRender – done by default
• pixelRatio – window.devicePixelRatio is used by default
• renderer – there's just one renderer for now, so no need for this option
• responsive – responsiveness is enabled by default
• scrollParent – the container will scroll if minPxPerSec is set to a higher value
• skipLength – there's no skipForward and skipBackward methods anymore
• splitChannelsOptions – you should now use splitChannels to pass the channel options. Pass height: 0 to hide a channel. See this example.
• drawingContextAttributes, maxCanvasWidth, forceDecode – removed to reduce code complexity
• xhr - please use fetchParams instead
• barMinHeight - the minimum bar height is now 1 pixel by default

Removed methods

• getFilters, setFilter – see the Web Audio example
• drawBuffer – to redraw the waveform, use setOptions instead and pass new rendering options
• cancelAjax – you can pass an AbortSignal in fetchParams
• skipForward, skipBackward, setPlayEnd – can be implemented using setTime(time)
• exportPCM is replaced with exportPeaks which returns arrays of floats
• toggleMute is now called setMuted(true | false)
• setHeight, setWaveColor, setCursorColor, etc. – use setOptions with the corresponding params instead. E.g., wavesurfer.setOptions({ height: 300, waveColor: '#abc' })

See the complete documentation of the new API.

Development

To get started with development, follow these steps:

1. Install dev dependencies:

yarn

1. Start the TypeScript compiler in watch mode and launch an HTTP server:

yarn start

This command will open http://localhost:9090 in your browser with live reload, allowing you to see the changes as you develop.

Tests

The tests are written in the Cypress framework. They are a mix of e2e and visual regression tests.

To run the test suite locally, first build the project:

yarn build

Then launch the tests:

yarn cypress

Feedback

We appreciate your feedback and contributions!

If you encounter any issues or have suggestions for improvements, please don't hesitate to post in our forum.

We hope you enjoy using wavesurfer.js and look forward to hearing about your experiences with the library!