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 v6

Interactive navigable audio visualization using Web Audio and Canvas.

See docs and examples on wavesurfer-js.org.

For a video tutorial, watch this series by Live Blogger on YouTube. 📺

Questions

Have a question about integrating wavesurfer.js on your website? Feel free to ask in our forum: https://github.com/wavesurfer-js/wavesurfer.js/discussions/categories/q-a

Quick start

Install the package:

npm install wavesurfer.js --save

# or

yarn add wavesurfer.js

And import it like so:

import WaveSurfer from 'wavesurfer.js'

If you're not using a package manager, simply insert the script from a CDN:

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

Create a container in your HTML:

<div id="waveform"></div>

Create an instance of wavesufer.js, passing the container selector and a few options:

var wavesurfer = WaveSurfer.create({
    container: '#waveform',
    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');

Documentation

See the documentation on all available methods, options and events on the homepage.

Projects using wavesurfer.js

For the list of projects using wavesurfer.js, check out the projects page.

Contributing

Have an idea and want to contribute to wavesurfer.js? Please first start a discussion in the Ideas section of our forum to coordinate with the maintainers.

Development

Install development dependencies:

npm install

Development tasks automatically rebuild certain parts of the library when files are changed (start – wavesurfer, start:plugins – plugins). Start a dev task and go to localhost:8080/example/ to test the current build.

Start development server for core library:

npm run start

Start development server for plugins:

npm run start:plugins

Build all the files. (generated files are placed in the dist directory.)

npm run build

Running tests only:

npm run test

Build documentation with esdoc (generated files are placed in the doc directory.)

npm run doc

If you want to use the VS Code - Debugger for Chrome, there is already a launch.json with a properly configured sourceMapPathOverrides for you.

Editing documentation

The homepage and documentation files are maintained in the gh-pages branch. Contributions to the documentation are especially welcome.

Releasing a new version

To release a new version and publish it to NPM, follow the steps below.

Switch to the master branch and make sure it's up-to-date

git checkout master
git fetch --all; git reset --hard origin/master

Run the release script:

yarn release

This will update the version, generate a changelog, and push everything to a new branch called release/X.X.X.

A browser window will open to create a PR from this new branch to the master branch. Once the PR is approved and merged, an automated workflow will kick in and publish a release both on GitHub and NPM.

Credits

The main maintainer: Thijs Triemstra

Many thanks to all the awesome contributors!

License

This work is licensed under a BSD 3-Clause License.