Table of Contents
- Using the Plugin
- Plugin Options
- Customizing controls
- Responsive layout
- Text Tracks
- Microphone plugin
- Using peaks for long audio files
- Change audio output or input device
- Using with React
- Using other frameworks
- More features using other plugins
Since v3.0 this plugin is compatible with video.js 7.0.5 and wavesurfer.js 3.2.0 and newer. If you want to use this plugin with an older video.js or wavesurfer.js version, check the archived releases for an older release of this plugin.
Take a look at the changelog when upgrading from a previous version of videojs-wavesurfer.
Using the Plugin
The plugin depends on the video.js and wavesurfer.js libraries:
<!-- style --><!-- libraries -->
The plugin automatically registers itself when the
script is loaded:
let player =;
The additional options for this plugin are:
||The URL of the JSON file with peaks data corresponding to the source audio/video file. See the peaks section below for more information.|
||Display internal log messages using the
||Indicates the number of seconds that is considered the boundary value for displaying milliseconds in the time controls. An audio clip with a total length of 2 seconds and a
To try out the examples locally, download the zipfile and unpack it, or checkout the repository using Git:
git clone https://github.com/collab-project/videojs-wavesurfer.git
And install the dependencies using npm:
cd videojs-wavesurfer npm install
Build the library and assets once:
npm run build
And start the local webserver for the examples:
npm run start
And open http://localhost:8080/examples/index.html in a browser.
Methods for this plugin documented below are available on the
of the video.js player instance. For example:
||Destroys the wavesurfer instance and children (including the video.js player).|
||Load the clip at
||Set the volume level (value between 0.0 and 1.0).|
||Get the length of the stream in seconds. Returns 0 if no stream is available (yet).|
||Get the current time (in seconds) of the stream during playback. Returns 0 if no stream is available (yet).|
||Save waveform image as data URI. Default format is
||Change the audio output device using its deviceId.|
Other wavesurfer.js methods
You can access the wavesurfer instance, for example to call the
seekTo method, by using the
surfer property of the
wavesurfer plugin instance:
Plugin events that are available on the video.js player instance. For example:
||Audio is loaded, decoded and the waveform is drawn.|
||Audio playback finished.|
||Audio output was changed and is now active.|
||Audio loading process was interrupted and cancelled.|
To disable and hide specific controls, use the video.js
controlBar:// hide fullscreen controlfullscreenToggle: false
fluid option for video.js will resize the player according to the size
of the window.
Configure the player; enable the video.js
Text tracks (or captions/subtitles) are a feature of HTML5 for displaying time-triggered text to the user. Video.js offers a cross-browser implementation of text tracks. For more information, check the documentation.
It's also possible to use a microphone for real-time rendering of the audio waveform. This uses the microphone plugin that comes with wavesurfer.js.
Include the additional
wavesurfer.microphone.js plugin on your page.
Hide irrelevant controls, specify the
WebAudio backend and enable the microphone plugin:
let player =;
The microphone plugin has additional configuration options.
Using peaks for large audio files
When you're dealing with long audio files, it's sometimes useful to generate the waveform data, called peaks, on the server. This allows wavesurfer.js to load the peaks JSON data and create the waveform from that pre-rendered peak data. This JSON file can be generated using the bbc/audiowaveform utility. For more information, see the wavesurfer.js FAQ.
Change audio output or input device
If your device has multiple audio output devices, use
setAudioOutput(deviceId) to change
the active audio output device, and listen for the
audioOutputReady event to be notified
when the new output device is active.
// change audio output deviceplayer;
The webpack wiki page shows how to configure webpack for videojs-wavesurfer.
Using with React
Using other frameworks
The Angular wiki page shows how to setup Angular and videojs-wavesurfer.
The Vue.js wiki page shows how to setup Vue.js and videojs-wavesurfer.
More features using other plugins
The Video.js community created
lots of plugins
that can be used to enhance the player's functionality. Plugins actually
- videojs-record - Adds support for recording audio/video/image files.
Install dependencies using npm:
Build development and minified versions of the library and stylesheets:
npm run build
Generated files are placed in the
npm run start
This will watch the source directory and rebuild when any changes are detected. It will also serve the files on http://127.0.0.1:8080.
Generate the API documentation (placed in the
npm run docs
All commands for development are listed in the
package.json file and
are run using:
npm run <command>
This work is licensed under the MIT License.
Please consider donating if you like this project. Bitcoin is accepted
and can be sent to