Releasing 2.0.0

There has been an extensive refactor of wavesurfer within the last half year which resulted in a version which includes a lot of new features (namely a dynamic plugin system) but also some breaking changes. We have decided to release it as a version two. Changes to either branch will be ported to each other (especially bug fixes of course).

This issue is intended as a place for general discussion and feedback regarding the v2 release.

Edit 1: Added change I forgot to mention: MultiCanvas is the default and only inbuilt renderer

The version is mostly stable and functional. Due to the nature of the refactor (an integrated plugin system for adding, initialising and destroying of plugin instances) all plugins are somehow affected. Some plugins are still buggy when used with the dynamic plugin API. Conventional use cases (i.e. cases where you just want to create an instance with some plugins – no dynamic adding or removing – should work just fine) (Below in the plugin API examples, this means 1. should already work, 2. and 3. don’t yet always work in all situations and for all plugins)

Installing the release

To get the current beta release (at the time of writing) do npm install wavesurfer.js@2.0.0-beta01

You can find the beta release(s) on the releases page or by running npm show wavesurfer.js | grep beta

Developing

To work on the new branch checkout the next branch, do npm install and then npm start – The library directory is exposed under http://localhost:8080

Generate the documention by running npm run doc (see below) – Tests can be run by calling npm run test

There are still lots of things which need doing. We welcome and are thankful for any help we can get. Please see right at the bottom of this post how you can help us.

Changes

(See a full list of all merged PRs for v2)

• ES6 Syntax: Refactored all code to use the new ES6/ES2015 syntax (especially arrow functions, classes, spread operators etc.)
• New build system: Webpack is being used as a build system to compile the code. It can be imported like this:

// 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');

• Documentation: Added loads of jsdoc style documentation tags and the esdoc documentation generator (the documentation needs to be also made public, currently it is generated into ./doc by calling npm run doc) – The idea being that it is easier to keep documentation up to date easier than having to always edit HTML code in the gh-pages branch.
• New plugin API: Previously all plugins, backends and drawers relied on the window.WaveSurfer global variable. This made it difficult to work with module bundlers (You had to expose the WaveSurfer object, which means it’s not really modular) – To fix this plugins now all follow a common format which is used by wavesurfer core to register the plugins correctly. (see an example of a plugin class at the bottom of this post)

There are three ways to add a plugin:

1. Adding and initialising plugin immediately (this will do in 99% of the cases):

var wavesurfer = WaveSurfer.create({
    container: '#waveform',
    waveColor: 'violet',
    plugins: [
        TimelinePlugin.create({
            container: '#wave-timeline'
        })
    ]
});

1. Adding a plugin immediately and initialising it dynamically:

var wavesurfer = WaveSurfer.create({
    container: '#waveform',
    plugins: [
        TimelinePlugin.create({
            container: '#wave-timeline',
            deferInit: true // stop the plugin from initialising immediately
        })
    ]
});
wavesurfer.initPlugin('timeline');

1. Adding and initialising a plugin dynamically:

var wavesurfer = WaveSurfer.create({
    container: '#waveform',
    waveColor: 'violet'
});
// adding and initialising a plugin after initialisation
wavesurfer.addPlugin(TimelinePlugin.create({
    container: '#wave-timeline',
})).initPlugin('timeline');

Also a plugin can be destroyed like this:

wavesurfer.destroyPlugin('timeline');

• New HTML init script: The html-init.js was extended to allow more complicated initialisation options (including autoloading of plugin code) – see #946 – Example usage:

<wavesurfer
  data-url="../media/demo.wav"
  data-plugins="minimap,timeline"
  data-minimap-height="30"
  data-minimap-wave-color="#ddd"
  data-minimap-progress-color="#999"
  data-timeline-font-size="13px"
  data-timeline-container="#timeline"
>
</wavesurfer>
<div id="timeline"></div>

• MultiCanvas is the default renderer: It supports the functionality of the default renderer but is not constrained by maximum canvas sizes.

Plugin class format

All plugins now follow a common format and their initialisation is handled by wavesurfer 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
    }
}

Things left to do!

• Wavesurfer.js (including plugins) is a fairly complex piece of software, that’s why it’s very important to have lots of people test it and file bugs!
• Although the core library has been refactored and documented very thoroughly the changes in the plugin code have been very minimal. They still lack jsdoc style comments* and can still be optimised/need to be debugged for use by the dynamic plugin API (*This would be very useful since that would make them appear in the generated documentation.)
• There are still some memory leaks (which is also true of the current version) – identifying and fixing them would make the whole library stabler.
• In general a lot of issues are documentation issues in the sense that they crop up because stuff is undocumented. Documenting is a proactive way of stopping those issues from every cropping up. Correcting and writing documentation, writing tutorials and how tos and so on would be very cool!

[thijstriemstra]

A beta 2 would not hurt (or RC1).

[thijstriemstra]

I opened #1274 that will build the dist folder when you run npm publish, can you take a look @katspaugh and release a new 2.0.1?