Upgrading from v1.x to version 2.x or newer

The API between v1.x and v2.x has mostly stayed the same but there are some changes to consider:

  • MultiCanvas renderer is now the default: It provides all functionality of the Canvas renderer. – Most likely you can simply remove the renderer option – The Canvas renderer has been removed. (The renderer option still exists but wavesurfer expects it to be a renderer object, not merely a string.)

  • Constructor functions instead of object constructors

    // Old:
    var wavesurfer = Object.create(WaveSurfer);
    // New:
    var wavesurfer = WaveSurfer.create(options);
    // ... or
    var wavesurfer = new WaveSurfer(options);
  • New plugin API: Previously all plugins had their own initialisation API. The new API replaces all these different ways to do the same thing with one plugin API built into the core library. Plugins are now added as a property of the wavesurfer configuration object during creation. You don't need to initialise the plugins yourself anymore. Below is an example of initialising wavesurfer with plugins (Note the different ways to import the library at the top):

    // EITHER - accessing modules with <script> tags
    var WaveSurfer = window.WaveSurfer;
    var TimelinePlugin = window.WaveSurfer.timeline;
    var MinimapPlugin = window.WaveSurfer.minimap;
    // OR - importing as es6 module
    import WaveSurfer from 'wavesurfer.js';
    import TimelinePlugin from 'wavesurfer.js/dist/plugin/wavesurfer.timeline.min.js';
    import MinimapPlugin from 'wavesurfer.js/dist/plugin/wavesurfer.minimap.min.js';
    // OR - importing as require.js/commonjs modules
    var WaveSurfer = require('wavesurfer.js');
    var TimelinePlugin = require('wavesurfer.js/dist/plugin/wavesurfer.timeline.min.js');
    var MinimapPlugin = require('wavesurfer.js/dist/plugin/wavesurfer.minimap.min.js');
    // ... initialising waveform with plugins
    var wavesurfer = WaveSurfer.create({
        container: '#waveform',
        waveColor: 'violet',
        plugins: [
                container: '#wave-timeline'
  • Standardised plugin format: all plugins now follow a common format and their initialisation is handled by wavesurfer.js core. It is no longer necessary to manually initialise them.

    export default class MyAwesomePlugin {
         * MyAwesome plugin definition factory
         * This function must be used to create a plugin definition which can be
         * used by wavesurfer to correctly instantiate the plugin.
         * @param  {MyAwesomePluginParams} params parameters use to initialise the
         * plugin
         * @return {PluginDefinition} an object representing the plugin
        static create(params) {
            return {
                name: 'myawesome',
                deferInit: params && params.deferInit ? params.deferInit : false,
                params: params,
                staticProps: {
                    staticMethod() {
                        // this will be added to the wavesurfer instance and can then be called
                        // wavesurfer.staticMethod();
                instance: MyAwesomePlugin
        constructor(params, ws) {
          // instantiate the plugin
        init() {
          // start doing something
        destroy() {
          // stop doing something
Fork me on GitHub