Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

react-wavesurfer

mspae1.8kBSD-3-Clause0.8.6

React component wrapper for wavesurfer.js

react, reactjs, wavesurfer, audio, react-component, component

readme

react-wavesurfer

npm version styled with prettier

Wrapper component for wavesurfer.js. Includes support for the timeline, minimap and regions plugins.

Note: Since v0.8.6 react-wavesurfer no longer comes bundled with the wavesurfer files. You need to explicitely import the correct files before using the react component!

Note: This component expects wavesurfer.js to be available as a global variable (WaveSurfer). Wavesurfer plugins need to be attached to this global variable for the react component to work. Read more about Prerequisites and common pitfalls at the bottom of this document.

Note: This version does not work for the version 2 (beta) of wavesurfer.js – A version of react-wavesurfer that will work with the new version is in the making.

Note to contributors: The development workflow has changed, please refer to the Developing & contributing section below for more info.

Basic Usage

For more advanced examples check the example directory.

You can also easily extend the core functionality by hooking into the wavesurfer.js callbacks (by defining callback props).

// In my bundle config this is setup to export to window.WaveSurfer
require('wavesurfer.js');

import React from 'react';
import ReactDOM from 'react-dom';
import Wavesurfer from 'react-wavesurfer';

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      playing: false,
      pos: 0
    };
    this.handleTogglePlay = this.handleTogglePlay.bind(this);
    this.handlePosChange = this.handlePosChange.bind(this);
  }
  handleTogglePlay() {
    this.setState({
      playing: !this.state.playing
    });
  }
  handlePosChange(e) {
    this.setState({
      pos: e.originalArgs[0]
    });
  }
  render() {
    return (
      <div>
        <Wavesurfer
          audioFile={'path/to/audio/file.mp3'}
          pos={this.state.pos}
          onPosChange={this.handlePosChange}
          playing={this.state.playing}
        />
      </div>
      );
  }
}

API

Wavesurfer (Base component)

The base component includes core wavesurfer.js features without plugins. Any plugin components should be included as child components of the base component.

Props

playing [bool]

starts/stops playback

volume [float]

0-1

zoom [float]

responsive [bool]

(default: true) resize the waveform on browser resize events

pos [number]

position of playback in seconds

audioPeaks [array]

an array of peaks for use by wavesurfer

audioFile [string|blob]

the audio as file or url

mediaElt [string|HTMLElement]

the audio as a selector for a media element or the element itself

options [object]

The instantiation options for wavesurfer. See documentation of wavesurfer.js. The defaults values are the default values of wavesurfer.js

onPosChange [function]

Is basically called on audioprocess and seek events and consolidates the received time formats into the same type of argument object as the onAudioprocess callback (time in seconds, not as a relative value):

{
  wavesurfer: wavesurferInstance,
  originalArgs: [playBackPositionInSecs]
}

This is necessary to fix any inconsistencies between WebAudio and MediaElement APIs.

on[WaveSurferEvent] [function]

Callbacks passed in as props, which are fired when the event on the underlying wavesurfer.js instance is fired.

Possible callback prop names are: onAudioprocess, onError, onFinish, onLoading, onMouseup, onPause, onPlay, onReady, onScroll, onSeek, onZoom

The callbacks receive an object as parameter:

{
  wavesurfer: wavesurferInstance,
  originalArgs: [originalArgs]
}

Regions (plugin child component)

Props

regions [object]

An object of region config objects which have the form:

// ...
uniqueKey: {
  id: uniqueKey
  start: startInSeconds
  end: endInSeconds
},
// ...

on[RegionsEvent] [function]

Callbacks for the events the region plugin adds to the wavesurfer.js instance: onRegionIn, onRegionOut, onRegionMouseenter, onRegionMouseleave, onRegionClick, onRegionDblclick, onRegionUpdated, onRegionUpdateEnd, onRegionRemoved, onRegionPlay

They receive an object as parameter which has the same form as the base component callbacks.

on[RegionEvent] [function]

Callbacks for the events fired on the single region instances. The Prop names are prefixed with Single, the available props are:

onSingleRegionIn, onSingleRegionOut, onSingleRegionRemove, onSingleRegionUpdate, onSingleRegionClick, onSingleRegionDbclick, onSingleRegionOver, onSingleRegionLeave

They receive an object as parameter which has the same form as the other callbacks, but also includes a reference to the region which fired the event:

{
  wavesurfer: wavesurferInstance,
  originalArgs: [originalArgs],
  region: regionInstance
}

Timeline (plugin child component)

Props

options [object]

An object containing configuration for the timeline plugin. (See the wavesurfer.js timeline example for information about available options.

Note: the options container and wavesurfer need not be set, this is done by the plugin component.

Minimap (plugin child component)

Props

options [object]

An object containing configuration for the minimap plugin. Example:

{
  height: 30,
  waveColor: '#ddd',
  progressColor: '#999',
  cursorColor: '#999'
}

Developing & contributing

Thank you for contributing to this project! Your help is very welcome. Please read the information below to find out how to start.

This project uses yarn as package manager. Please install it globally with npm install yarn --global if you haven't already done so.

Please apply the precommit hook before commiting, it will lint and format your code before it is saved in version control. To set it up run chmod +x pre-commit.sh && ln -s ../../pre-commit.sh .git/hooks/pre-commit once in the root directory of this project before commiting.

  • yarn – Install dependencies
  • npm start – Start development server (webpack-dev-server) at localhost:8080
  • npm run format – Format the code
  • npm run lint – Lint code
  • npm run build – Lint and build distributable files

Prerequisites and common pitfalls

This library does not include wavesurfer.js itself. You need to include it in your project yourself.

The (optional) plugin components do include the specific plugin code of wavesurfer.js. They augment the wavesurfer.js object, this is the reason why the root wavesurfer.js component does not include the wavesurfer.js code.

The plugin components require window.WaveSurfer to have all the respective plugin properties set. (e.g. the Regions component needs window.WaveSurfer.Regions etc.)

Webpack

  // provide WaveSurfer as a globally accessible variable
  plugins: [
    new webpack.ProvidePlugin({
      WaveSurfer: 'wavesurfer.js'
    })
  ],
  // Alias `wavesurfer` to the correct wavesurfer package.
  // (wavesurfer.js has some non-standard naming convention)
  resolve: {
    alias: {
      wavesurfer: require.resolve('wavesurfer.js')
    }
  },

Then import all the wavesurfer files you need:

require('wavesurfer.js');
require('wavesurfer.js/dist/plugin/wavesurfer.timeline.min.js');
require('wavesurfer.js/dist/plugin/wavesurfer.regions.min.js');
require('wavesurfer.js/dist/plugin/wavesurfer.minimap.min.js');

Global objects

Simply include the wavesurfer.js library and any plugins you want to include before you call the component code. (The component will be exposed as window.Wavesurfer.default)

I have not tested AMD or System.js, if you have any experience, please feel free to update this document, or file an issue.

changelog

Change Log

upcoming (2017/08/20 10:50 +00:00)

  • 46df85e updated changelog for v0.8.5 (@mspae)

v0.8.5 (2017/08/18 11:46 +00:00)

  • bd79e36 bumped version to v0.8.5 (@mspae)
  • 6f8752b minified code has source maps, removed unused deps from build config (@mspae)
  • add54eb updated readme (@mspae)
  • 185b4e1 updated pre commit hook and README with dev infos (@mspae)
  • 5dcceb9 added LICENSE for BSD-3 clause (@mspae)
  • 85e0f01 formatting of source code, also removed manual imports loader config, which is in the webpack config now, also added WaveSurfer as global in the eslint config (@mspae)
  • 106d37f updated deps, changed to yarn, removed jscs, switched to purely eslint linting with pretty plugin and formatting with pre commit hook (@mspae)
  • 225de44 removed shouldComponentUpdate hook on root component since it stopped children from updating and doesn't provide perf benefits (@mspae)
  • ba20e09 Added support for gradients for the waveColor prop (@mspae)
  • #61 fixed React.PropTypes deprecation warning (#61) (@rijk)
  • d368e28 updated changelog for v0.8.4 (@mspae)

v0.8.4 (2017/08/10 18:16 +00:00)

  • 92a7f7f bumped version to 0.8.4 (@mspae)
  • adf93bc changed references to the wavesurfer.js plugin files to the minified versions to fix the build (@mspae)
  • c129566 linting issues (@mspae)
  • #44 Fix minor linting errors (#44) (@tf)
  • #37 Fixing edge cases (#37) (@TrevorHinesley)
  • #55 handle nextProps.pos with value of 0 (falsey) (#55) (@eviltwin)
  • #59 added missing semicolon to example code (#59) (@acollier88)
  • #34 Update react-wavesurfer.js (#34) (@TrevorHinesley)
  • #32 Merge pull request #32 from JungJinuk/patch-1 (@JungJinuk)
  • a81b31e Update simple.js (@JungJinuk)
  • cc3ec46 changelog and bump for v0.8.3 (@mspae)

v0.8.3 (2017/02/05 19:36 +00:00)

  • afce60f updated changelog and bumped version for 0.8.3 (@mspae)
  • #30 Merge pull request #30 from omerts/master (@omerts)
  • 4fcd41c add support for responsiveness when peaks are pre-rendered
  • a731025 updated CHANGELOG.md for 0.8.2 (@mspae)
  • 4c77e86 updated CHANGELOG.md for 0.8.2 (@mspae)

v0.8.2 (2016/10/28 14:15 +00:00)

  • ecdc3d5 bump version to 0.8.2 (@mspae)
  • ff54576 resize operation stops playback and restores playback position after resize is complete (@mspae)
  • adae27d bumped version because of wrong build (@mspae)
  • 4aedb61 updated CHANGELOG.md for 0.8.0 (@mspae)

v0.8.0 (2016/09/25 15:57 +00:00)

  • 86b588b bumped version to 0.8.0 (@mspae)
  • 1fc6106 updated documentation with common pitfalls (@mspae)
  • d7ee588 removed excess space (@mspae)
  • c53e434 fixed formatting issues, remove log statement (@mspae)
  • 879025c better event listener for ready event in minimap plugin (@mspae)
  • 588e771 working on minimap init bug (@mspae)
  • d7f610b responsive prop (@mspae)
  • bbb922a updated CHANGELOG.md for 0.7.4 (@mspae)

v0.7.4 (2016/09/23 20:55 +00:00)

  • c0ad38f bumped version to 0.7.4 (@mspae)
  • 06a7a9d fixed minimap bug which caused it to not render sometimes (@mspae)
  • 8db939e root component's isReady flag is now normal state (@mspae)
  • dbf117d removed gui keys (@mspae)
  • 90d25d2 added audio rate dynamic setting in componentWillReceiveProps (@mspae)
  • 8fd7a11 updated CHANGELOG.md for v0.7.3 (@mspae)

v0.7.3 (2016/08/22 19:01 +00:00)

  • 6d4cbe8 bumped version (@mspae)
  • 777a728 updated CHANGELOG.md with v0.7.3 (@mspae)
  • efe4156 webpack dev server is using eval-source-map now (@mspae)
  • fdf11d3 made linting pass without error, updating legacy patterns and tweaking linting settings (@mspae)
  • ddfb699 updated dependencies (@mspae)
  • 9316c2f updated CHANGELOG.md for v0.7.2 (@mspae)

v0.7.2 (2016/08/21 15:53 +00:00)

  • 21f021a bumped version to 0.7.2 (@mspae)
  • f0a0816 guid key for plugin components (@mspae)
  • 6fbe4f1 minimap init function uses global.WaveSurfer not the wavesurfer prop so lazy loading of plugin code is supported (@mspae)
  • 4514c64 updated CHANGELOG.md for 0.7.1 (@mspae)

v0.7.1 (2016/08/21 14:45 +00:00)

  • d900ba4 formatting (@mspae)
  • 0d870a8 wavesurfer.js is a peerDependency (@mspae)
  • ba4edd4 formatting (@mspae)
  • be5360b bumped version to 0.7.1 (@mspae)
  • 1bf6077 wavesurfer.js is a devDependency (@mspae)
  • b073f0b prop type for children allows several child components (@mspae)
  • c9e07f1 updated CHANGELOG.md and README.md (@mspae)
  • 53b9a36 updated CHANGELOG.md for v0.7.0 (@mspae)

v0.7.0 (2016/08/17 18:14 +00:00)

  • 777b836 bumped version to 0.7.0 (@mspae)
  • a5063ba added minimap build target to config (@mspae)
  • 2a45537 added minimap plugin component (@mspae)
  • a64e7ee removed unused reference to onReady callback in timeline example (@mspae)
  • b700117 updated CHANGELOG.md for 0.6.0 (@mspae)

v0.6.0 (2016/08/16 13:33 +00:00)

  • a14459d bumped version to 0.6.0 (@mspae)
  • 0b39ad9 changed github username in CHANGELOG.md (@mspae)
  • 78d7269 expose wavesurfer.js to global in main build (@mspae)
  • ca9b8ae exposed WaveSurfer to window object to attach plugins to it (@mspae)
  • aaca4a6 renamed webpack.config.js to more descriptive dev.config.js (@mspae)
  • 8a83e28 updated changelog (@mspae)

v0.5.2 (2016/06/12 12:18 +00:00)

  • c5cdd22 0.5.2 (@mspae)
  • 2b01d1a updated README (@mspae)
  • 0eeba95 corrected comment (@mspae)
  • 29ea327 added more comments (@mspae)
  • 2145a6d add check for updated mediaElt prop (@mspae)
  • 740c165 updated mediaElt example (@mspae)
  • 29b0719 refactored mediaElt loading into _loadMediaElt, added support for html element (@mspae)
  • 325233e update prop type validation to allow an html element for mediaElt (@mspae)
  • d91a6d8 removed obsolete _isPlaying flag (@mspae)
  • 2f91847 added changelog and changelog gen script (@mspae)

v0.5.1 (2016/06/10 17:40 +00:00)

  • bd899cd bumped version (@mspae)
  • dc176a2 removed unnecessary default props (@mspae)
  • c4c9419 update mediaElement example with new mediaElt prop name (@mspae)
  • 3b07924 updating peaks works for audioFile and mediaElt audio source (@mspae)
  • 811b968 if using mediaElt, set the backend to MediaElement (@mspae)
  • 096a3b2 updated propname mediaEltId to mediaElt to make it more generic (@mspae)
  • dadac1b updated wavesurfer dependency (@mspae)
  • 8cec2b1 media element example (@mspae)
  • 6e007a9 added peaks example (@mspae)

v0.5.0 (2016/06/09 20:29 +00:00)

  • 5a7c66a updated documentation (@mspae)
  • ddfab71 bumped version (@mspae)
  • b4aa696 added shouldComponentUpdate (@mspae)
  • 5d90b48 updated comments (@mspae)
  • 64d8b3a Added initial check for the mediaEltId (@mspae)
  • #18 Merge pull request #18 from timbofield/master (@timbofield)
  • 0ed252c Merge branch 'master' into HEAD (@tim-field)
  • 3f9b56c fix typo (@tim-field)
  • #17 Merge pull request #17 from therewasaguy/loadMediaElt (@therewasaguy)
  • a55a98b add prop validation (@tim-field)
  • 58a881c Enable peaks property (@tim-field)
  • 8f98cc2 remove logging (@therewasaguy)
  • fac3667 load existing media element with precomputed peaks (@therewasaguy)
  • 4622a72 update load type checker and wavesurfer version to allow loadMediaElt (@therewasaguy)
  • #15 Merge pull request #15 from alfonsodev/regions-events-fix (@alfonsodev)
  • 11faa37 removing trailing spaces that were stopping events to be hooked (@alfonsodev)

v0.4.4 (2016/04/20 09:40 +00:00)

  • 8e748ce bumped version (@mspae)
  • 066d97c removed duplicate entry from npmignore (@mspae)

v0.4.3 (2016/04/20 09:38 +00:00)

  • cdabd55 bumped version and fixed formatting (@mspae)
  • b6a5c96 Merge branch 'ffxsam-init-call-fix' (@mspae)
  • d4db46c fixed merge conflicts (@mspae)

v0.4.2 (2016/04/19 20:21 +00:00)

  • aa32b15 bumped version (@mspae)
  • 9c0d94c only update regions if the wavesurfer instance was ready before, see #11 (@mspae)
  • 30a27d1 added build directory to .gitignore, see #13 (@mspae)
  • 62c3850 Fixed a bad method call (init should've been _init) (@ffxsam)

v0.4.1 (2016/03/29 22:33 +00:00)

  • 98150ae bumped version (@mspae)
  • 0b97301 updated linting task (@mspae)
  • 320c407 added timeline to Readme, added development docs, other minor corrections (@mspae)
  • 48b535d updated build (@mspae)
  • 82b05bd refactoring of regions plugins, fixed wrong object iteration (@mspae)
  • d146f65 fixed wrong prop type checks (@mspae)
  • fe54bcb plugin child components don't receive props of parents directly (@mspae)
  • 3f840da wavesurfer prop is optional in checks so no errors are thrown when the element is cloned to add props (@mspae)
  • dfa0f04 better timeline option example (@mspae)

v0.4.0 (2016/03/28 14:41 +00:00)

  • f2ac417 Bumped version number (@mspae)
  • f405387 Updated build (@mspae)
  • 52f1309 Updated Readme with cool badges (@mspae)
  • e31f4f9 code checking with eslint & jscs (@mspae)
  • 153bdb6 removed obsolete vendor files (@mspae)
  • 8bb6cc0 base component children prop merge hierarchy (@mspae)
  • 12a96fe Updated .npmignore (@mspae)
  • 60ead5b added new eslint/jscs config (@mspae)
  • d273ed5 Updated Readme (@mspae)
  • a5ca5a5 Updated build (@mspae)
  • d464fbe Updated regions example (@mspae)
  • 117c506 cooler simple example (@mspae)
  • 1efd94c Regions are updated via props (@mspae)
  • 196efcf wavesurfer.js is now a dependency and not a dev-dependency (@mspae)
  • d1319de deep-assign instead of object-assign (@mspae)
  • 27fbd84 updated eslint config (@mspae)
  • a2b8b94 Removing obsolete debugging console log statement (@mspae)
  • dd8db69 wavesurfer.js is now an external dependency of the component and any plugin components (@mspae)
  • 1764a29 updated builds (@mspae)
  • dd9d6d3 trying out builds (@mspae)
  • 82fd33b New build (@mspae)
  • c622acf Added timeline plugin and example (@mspae)
  • e7ee383 Updated build process: plugins now don't bundle wavesurfer.js, only the wavesurfer plugin code, the root component does bundle wavesurfer.js. (@mspae)
  • 11ee017 refactored example code into seperate files (@mspae)
  • 6669126 layout using bootstrap (@mspae)
  • e8f1070 added bootstrap html markup (@mspae)
  • a1c104b Added call to zoom example component (@mspae)
  • a8a8dc5 removed old handleReady function from example (@mspae)
  • 6797815 added zoom prop (@mspae)
  • 2f7d099 added bootstrap to index html and remove old styles (@mspae)
  • 42c1d01 added zoom example (@mspae)
  • bf48424 added no Errors plugin to webpack dev config (@mspae)
  • 1d604c7 Merge branch 'regions-plugin' (@mspae)
  • 5a9f91b Better regions click example (@mspae)
  • 15598c7 added region events, updated hookUpEvents function with support for hyphens in event names (@mspae)
  • e60951e Rename dist directory to lib, more efficient minification config by using assign to extend the default dist.config.js (@mspae)
  • 4157b08 working wavesurfer webpack alias with path joined location (@mspae)
  • 3f8c7ff Removed obsolete react-wavesurfer entry point in development webpack config (@mspae)
  • b2211ef Updated examples with regions example (@mspae)
  • 3eee67e react-wavesurfer root script renders child components and passes them the wavesurfer instance along with the props (@mspae)
  • ee0fef6 added plugin source file, updated webpack dist config (@mspae)
  • 9c32e02 Merge branch 'volume-prop' (@mspae)
  • a306acd class → className (@mspae)

v0.3.0 (2016/03/20 16:55 +00:00)

  • 90420ea bumped version (@mspae)
  • 05334a9 updated example with volume options, updated README.md to document new prop (@mspae)
  • 83d09a6 removed dev console log statement (@mspae)
  • 7ac1808 added volume prop and volume prop example (@mspae)
  • 4c5d535 fixes #8 (@mspae)
  • ea671b8 Added playing status on example page (@mspae)
  • 2a8f04b removed old commented code for plugins (@mspae)
  • 1bb7397 updated example with pos number input and initial loading pos (@mspae)
  • 81c39d6 added pos input element to example (@mspae)
  • 12dfe92 Removed obsolete dependencies (@mspae)
  • aaf42cd Removed obsolete lodash dependency and changed from merge to object-assign (@mspae)
  • ee48eb8 Removed commented regions code (@mspae)
  • 29d2934 Updated to new wavesurfer.js version (@mspae)
  • 9470c0e Updated build system to use npm scripts object instead of dedicated server.js file, dev server is now provided via http://localhost:8080/webpack-dev-server/ (@mspae)

v0.2.4 (2016/02/26 15:23 +00:00)

  • 6a5d50a bumped version (@mspae)
  • #5 Merge pull request #5 from omerts/master (@omerts)
  • a928786 Fix issue (@omerts)
  • #3 Merge pull request #3 from omerts/patch-1 (@omerts)
  • 2ccc9fe Fixed pos prop (@omerts)
  • #2 Merge pull request #2 from austinpray/patch-1 (@austinpray)
  • 8b29474 fix props in readme (@austinpray)

v0.2.3 (2016/01/19 17:54 +00:00)

  • e2a999f passing the position to a callback works now thanks to the newly added onPosChange which merges audioprocess and seek events into one (to fix audioprocess not being fired on seek), documentation and example have been updated accordingly (@mspae)

v0.2.2 (2016/01/15 16:31 +00:00)

  • f31ab47 bumped version (@mspae)
  • d76b3f7 fixed callback props not getting the originalArgs of the wavesurfer event (@mspae)

v0.2.1 (2016/01/15 14:52 +00:00)

  • 804c77e removed regions code for now, using defaultProps directly from Wavesurfer (@mspae)

v0.2.0 (2016/01/15 14:36 +00:00)

  • 3c3a1bc rollback plugin importing to have a working base functionality for publishing, update docs (@mspae)
  • 8538fd4 put regions functionality in different bundle (@mspae)
  • 4828cc9 better regions example (@mspae)
  • 11dbc58 better examples and added region support (@mspae)
  • afab027 bundling of timeline plugin for support of common js (@mspae)
  • 36550e7 better docs, better examples, added timeline plugin (@mspae)
  • 08d0f6f fixed example not working because of old dir string, included wavesurfer.js commonjs file instead of building our own (@mspae)

v0.1.5 (2016/01/09 16:38 +00:00)

  • 1819f06 updated readme (@mspae)
  • 983a00b renamed dev to example dir (@mspae)

v0.1.4 (2016/01/02 16:43 +00:00)

  • 9652eb2 removed debugging console.log statements, bumped version number (@mspae)

v0.1.3 (2015/12/31 18:42 +00:00)

  • 6e52c4d fallback using wavesurfer bundle (@mspae)

v0.1.2 (2015/12/30 21:54 +00:00)

  • 802995a bumped version (@mspae)
  • f46a016 added bugs and repo property to package.json (@mspae)
  • 9774045 added bugs and repo property to package.json (@mspae)

v0.1.1 (2015/12/29 20:39 +00:00)

  • a04c3c1 bumper version (@mspae)
  • 18a235e put dev js wrappers in their own folder (@mspae)
  • ad878f2 fixed wrong main file (@mspae)
  • 1a2990b fixed wrong main file (@mspae)
  • 0e8de8a added Readme with status (@mspae)

v0.1.0 (2015/12/29 20:07 +00:00)

  • 39256e0 added author email (@mspae)
  • c81ff34 wrapper component for dev (@mspae)
  • 38c1706 tests working basically (@mspae)
  • e4c78fe moved to babel 6.0.0, jest doesnt want to work :/ (@mspae)
  • 660d30d pos prop (@mspae)
  • 7d061bb added demo.wav, loading audio files works basically (@mspae)
  • 3b9ca11 initial commit (@mspae)