Home Reference Source
import WaveSurfer from 'wavesurfer.js/src/wavesurfer.js'
public class | source

WaveSurfer

Extends:

Observer → WaveSurfer

WaveSurfer core library class

Example:

const params = {
  container: '#waveform',
  waveColor: 'violet',
  progressColor: 'purple'
};

// initialise like this
const wavesurfer = WaveSurfer.create(params);

// or like this ...
const wavesurfer = new WaveSurfer(params);
wavesurfer.init();

// load audio file
wavesurfer.load('example/media/demo.wav');

Static Member Summary

Static Public Members
public static

The library version number is available as a static property of the WaveSurfer class

public static

Functions in the util property are available as a static property of the WaveSurfer class

Static Method Summary

Static Public Methods
public static

Instantiate this class, call its init function and returns it

Constructor Summary

Public Constructor
public

constructor(params: WavesurferParams): this

Initialise wavesurfer instance

Member Summary

Public Members
public

Backend: *

public

Instantiated plugin classes are added as a property of the wavesurfer instance

public

Properties defined in a plugin definition's staticProps property are added as staticProps properties of the WaveSurfer instance

public

Get the current ready status.

public

Functions in the util property are available as a prototype property to all instances

Method Summary

Public Methods
public

addPlugin(plugin: PluginDefinition): this

Add a plugin object to wavesurfer

public

Cancel any fetch request currently in progress

public

Remove events, elements and disconnect WebAudio nodes.

public

destroyPlugin(name: string): this

Destroy a plugin

public

empty()

Display empty waveform.

public

exportImage(format: string, quality: number, type: string): string | string[] | Promise

Save waveform image as data URI.

public

exportPCM(length: number, accuracy: number, noWindow: boolean, start: number, end: number): Promise

Exports PCM data into a JSON array and optionally opens in a new window as valid JSON Blob instance.

public

Get a map of plugin names that are currently initialised

public

Get the background color of the waveform container.

public

Get the current playback position

public

Get the fill color of the cursor indicating the playhead position.

public

Get the duration of the audio clip

public

getFilters(): array

Get the list of current set filters as an array.

public

Get the height of the waveform.

public

Get the current mute status.

public

Get the playback rate.

public

Get the fill color of the waveform behind the cursor.

public

Get the playback volume.

public

Get the fill color of the waveform after the cursor.

public

init(): this

Initialise the wave

public

initPlugin(name: string): this

Initialise a plugin

public

Get the current playback state

public

load(url: string | HTMLMediaElement, peaks: number[] | Number<Array[]>, preload: string, duration: number): void

Loads audio and re-renders the waveform.

public

loadBlob(blob: Blob | File)

Loads audio data from a Blob or File object

public

Stops and pauses playback

public

play(start: number, end: number): Promise

Starts playback from the current position.

public

Toggle playback

public

registerPlugins(plugins: PluginDefinition[]): this

Add and initialise array of plugins (if plugin.deferInit is falsey), this function is called in the init function of wavesurfer

public

seekAndCenter(progress: number)

Seeks to a position and centers the view

public

seekTo(progress: number)

Seeks to a position

public

Set the background color of the waveform container.

public

Set the current play time in seconds.

public

Set the fill color of the cursor indicating the playhead position.

public

setFilteredChannels(channelIndices: array)

Hide channels from being drawn on the waveform if splitting channels.

version 4.0.0
public

setHeight(height: number)

Set the height of the waveform.

public

setMute(mute: boolean)

Enable or disable muted audio

public

setPlayEnd(position: number)

Set a point in seconds for playback to stop at.

version 3.3.0
public

Set the playback rate.

public

Set the fill color of the waveform behind the cursor.

public

setSinkId(deviceId: string): Promise

Sets the ID of the audio device to use for output and returns a Promise.

public

setVolume(newVolume: number)

Set the playback volume.

public

Set the fill color of the waveform after the cursor.

public

skip(offset: number)

Skip a number of seconds from the current position (use a negative value to go backwards).

public

skipBackward(seconds: number)

Skip backward

public

skipForward(seconds: number)

Skip forward

public

stop()

Stops and goes to the beginning.

public

Toggle mouse interaction

public

Toggle the volume on and off.

public

Toggles scrollParent and redraws

public

zoom(pxPerSec: number)

Horizontally zooms the waveform in and out.

Inherited Summary

From class Observer
public
public

fireEvent(event: string, args: ...any)

Manually fire an event

public

Attach a handler function for an event.

public

once(event: string, handler: function): ListenerDescriptor

Attach a handler to an event.

public

Disable firing a list of events by name.

since 4.0.0
public

un(event: string, fn: function)

Remove an event handler.

public

unAll()

Remove all event handlers.

Static Public Members

public static VERSION: String source

The library version number is available as a static property of the WaveSurfer class

Example:

console.log('Using wavesurfer.js ' + WaveSurfer.VERSION);

public static util: Object source

Functions in the util property are available as a static property of the WaveSurfer class

Example:

WaveSurfer.util.style(myElement, { background: 'blue' });

Static Public Methods

public static create(params: WavesurferParams): Object source

Instantiate this class, call its init function and returns it

Params:

NameTypeAttributeDescription
params WavesurferParams

The wavesurfer parameters

Return:

Object

WaveSurfer instance

Example:

const wavesurfer = WaveSurfer.create(params);

Public Constructors

public constructor(params: WavesurferParams): this source

Initialise wavesurfer instance

Override:

Observer#constructor

Params:

NameTypeAttributeDescription
params WavesurferParams

Instantiation options for wavesurfer

Return:

this

Wavesurfer instance

Example:

const wavesurfer = new WaveSurfer(params);

Public Members

public Backend: * source

public [plugin.name]: Object source

Instantiated plugin classes are added as a property of the wavesurfer instance

public [pluginStaticProp]: * source

Properties defined in a plugin definition's staticProps property are added as staticProps properties of the WaveSurfer instance

public isReady: boolean: boolean source

Get the current ready status.

Return:

boolean

Example:

const isReady = wavesurfer.isReady;

public util: Object source

Functions in the util property are available as a prototype property to all instances

Example:

const wavesurfer = WaveSurfer.create(params);
wavesurfer.util.style(myElement, { background: 'blue' });

Public Methods

public addPlugin(plugin: PluginDefinition): this source

Add a plugin object to wavesurfer

Params:

NameTypeAttributeDescription
plugin PluginDefinition

A plugin definition

Return:

this

The wavesurfer instance

Emit:

WaveSurfer#plugin-added

Called with the name of the plugin that was added

Example:

wavesurfer.addPlugin(WaveSurfer.minimap());

public cancelAjax() source

Cancel any fetch request currently in progress

public destroy() source

Remove events, elements and disconnect WebAudio nodes.

Emit:

*

WaveSurfer#destroy

public destroyPlugin(name: string): this source

Destroy a plugin

Params:

NameTypeAttributeDescription
name string

A plugin name

Return:

this

The wavesurfer instance

Emit:

*

WaveSurfer#plugin-destroyed

Example:

wavesurfer.destroyPlugin('minimap');

public empty() source

Display empty waveform.

public exportImage(format: string, quality: number, type: string): string | string[] | Promise source

Save waveform image as data URI.

The default format is 'image/png'. Other supported types are 'image/jpeg' and 'image/webp'.

Params:

NameTypeAttributeDescription
format string
  • default: 'image/png'

A string indicating the image format. The default format type is 'image/png'.

quality number
  • default: 1

A number between 0 and 1 indicating the image quality to use for image formats that use lossy compression such as 'image/jpeg'`` and'image/webp'`.

type string

Image data type to return. Either 'dataURL' (default) or 'blob'.

Return:

string | string[] | Promise

When using 'dataURL' type this returns a single data URL or an array of data URLs, one for each canvas. When using 'blob' type this returns a Promise resolving with an array of Blob instances, one for each canvas.

public exportPCM(length: number, accuracy: number, noWindow: boolean, start: number, end: number): Promise source

Exports PCM data into a JSON array and optionally opens in a new window as valid JSON Blob instance.

Params:

NameTypeAttributeDescription
length number
  • default: 1024

The scale in which to export the peaks

accuracy number
  • default: 10000
noWindow boolean
  • nullable: true

Set to true to disable opening a new window with the JSON

start number

Start index

end number

End index

Return:

Promise

Promise that resolves with array of peaks

public getActivePlugins(): Object source

Get a map of plugin names that are currently initialised

Return:

Object

Object with plugin names

Example:

wavesurfer.getPlugins();

public getBackgroundColor(): string source

Get the background color of the waveform container.

Return:

string

A CSS color string.

public getCurrentTime(): number source

Get the current playback position

Return:

number

Playback position in seconds

Example:

const currentTime = wavesurfer.getCurrentTime();

public getCursorColor(): string source

Get the fill color of the cursor indicating the playhead position.

Return:

string

A CSS color string.

public getDuration(): number source

Get the duration of the audio clip

Return:

number

Duration in seconds

Example:

const duration = wavesurfer.getDuration();

public getFilters(): array source

Get the list of current set filters as an array.

Filters must be set with setFilters method first

Return:

array

List of enabled filters

public getHeight(): number source

Get the height of the waveform.

Return:

number

Height measured in pixels.

public getMute(): boolean source

Get the current mute status.

Return:

boolean

Current mute status

Example:

const isMuted = wavesurfer.getMute();

public getPlaybackRate(): number source

Get the playback rate.

Return:

number

The current playback rate.

public getProgressColor(): string source

Get the fill color of the waveform behind the cursor.

Return:

string

A CSS color string.

public getVolume(): number source

Get the playback volume.

Return:

number

A value between 0 and 1, 0 being no volume and 1 being full volume.

public getWaveColor(): string source

Get the fill color of the waveform after the cursor.

Return:

string

A CSS color string.

public init(): this source

Initialise the wave

Return:

this

The wavesurfer instance

Example:

var wavesurfer = new WaveSurfer(params);
wavesurfer.init();

public initPlugin(name: string): this source

Initialise a plugin

Params:

NameTypeAttributeDescription
name string

A plugin name

Return:

this

The wavesurfer instance

Emit:

*

WaveSurfer#plugin-initialised

Example:

wavesurfer.initPlugin('minimap');

public isPlaying(): boolean source

Get the current playback state

Return:

boolean

False if paused, true if playing

Example:

const isPlaying = wavesurfer.isPlaying();

public load(url: string | HTMLMediaElement, peaks: number[] | Number<Array[]>, preload: string, duration: number): void source

Loads audio and re-renders the waveform.

Params:

NameTypeAttributeDescription
url string | HTMLMediaElement

The url of the audio file or the audio element with the audio

peaks number[] | Number<Array[]>

Wavesurfer does not have to decode the audio to render the waveform if this is specified

preload string
  • nullable: true

(Use with backend MediaElement and MediaElementWebAudio) 'none'|'metadata'|'auto' Preload attribute for the media element

duration number
  • nullable: true

The duration of the audio. This is used to render the peaks data in the correct size for the audio duration (as befits the current minPxPerSec and zoom value) without having to decode the audio.

Return:

void

Throw:

*

Will throw an error if the url argument is empty.

Example:

// uses fetch or media element to load file (depending on backend)
wavesurfer.load('http://example.com/demo.wav');

// setting preload attribute with media element backend and supplying
// peaks
wavesurfer.load(
  'http://example.com/demo.wav',
  [0.0218, 0.0183, 0.0165, 0.0198, 0.2137, 0.2888],
  true
);

public loadBlob(blob: Blob | File) source

Loads audio data from a Blob or File object

Params:

NameTypeAttributeDescription
blob Blob | File

Audio data

Example:


    

public pause(): Promise source

Stops and pauses playback

Return:

Promise

Result of the backend pause method

Example:

wavesurfer.pause();

public play(start: number, end: number): Promise source

Starts playback from the current position. Optional start and end measured in seconds can be used to set the range of audio to play.

Params:

NameTypeAttributeDescription
start number
  • nullable: true

Position to start at

end number
  • nullable: true

Position to end at

Return:

Promise

Result of the backend play method

Emit:

*

WaveSurfer#interaction

Example:

// play from second 1 to 5
wavesurfer.play(1, 5);

public playPause(): Promise source

Toggle playback

Return:

Promise

Result of the backend play or pause method

Example:

wavesurfer.playPause();

public registerPlugins(plugins: PluginDefinition[]): this source

Add and initialise array of plugins (if plugin.deferInit is falsey), this function is called in the init function of wavesurfer

Params:

NameTypeAttributeDescription
plugins PluginDefinition[]

An array of plugin definitions

Return:

this

The wavesurfer instance

Emit:

WaveSurfer#plugins-registered

Called with the array of plugin definitions

public seekAndCenter(progress: number) source

Seeks to a position and centers the view

Params:

NameTypeAttributeDescription
progress number

Between 0 (=beginning) and 1 (=end)

Example:

// seek and go to the middle of the audio
wavesurfer.seekTo(0.5);

public seekTo(progress: number) source

Seeks to a position

Params:

NameTypeAttributeDescription
progress number

Between 0 (=beginning) and 1 (=end)

Emit:

*

WaveSurfer#interaction

*

WaveSurfer#seek

Example:

// seek to the middle of the audio
wavesurfer.seekTo(0.5);

public setBackgroundColor(color: string) source

Set the background color of the waveform container.

Params:

NameTypeAttributeDescription
color string

A CSS color string.

Example:

wavesurfer.setBackgroundColor('#FF00FF');

public setCurrentTime(seconds: number) source

Set the current play time in seconds.

Params:

NameTypeAttributeDescription
seconds number

A positive number in seconds. E.g. 10 means 10 seconds, 60 means 1 minute

public setCursorColor(color: string) source

Set the fill color of the cursor indicating the playhead position.

Params:

NameTypeAttributeDescription
color string

A CSS color string.

Example:

wavesurfer.setCursorColor('#222');

public setFilteredChannels(channelIndices: array) version 4.0.0 source

Hide channels from being drawn on the waveform if splitting channels.

For example, if we want to draw only the peaks for the right stereo channel:

const wavesurfer = new WaveSurfer.create({...splitChannels: true}); wavesurfer.load('stereo_audio.mp3');

wavesurfer.setFilteredChannel([0]); <-- hide left channel peaks.

Params:

NameTypeAttributeDescription
channelIndices array

Channels to be filtered out from drawing.

public setHeight(height: number) source

Set the height of the waveform.

Params:

NameTypeAttributeDescription
height number

Height measured in pixels.

Example:

wavesurfer.setHeight(200);

public setMute(mute: boolean) source

Enable or disable muted audio

Params:

NameTypeAttributeDescription
mute boolean

Specify true to mute audio.

Emit:

*

WaveSurfer#volume

*

WaveSurfer#mute

Example:

// unmute
wavesurfer.setMute(false);
console.log(wavesurfer.getMute()) // logs false

public setPlayEnd(position: number) version 3.3.0 source

Set a point in seconds for playback to stop at.

Params:

NameTypeAttributeDescription
position number

Position (in seconds) to stop at

public setPlaybackRate(rate: number) source

Set the playback rate.

Params:

NameTypeAttributeDescription
rate number

A positive number. E.g. 0.5 means half the normal speed, 2 means double speed and so on.

Example:

wavesurfer.setPlaybackRate(2);

public setProgressColor(color: string) source

Set the fill color of the waveform behind the cursor.

Params:

NameTypeAttributeDescription
color string

A CSS color string.

Example:

wavesurfer.setProgressColor('#400');

public setSinkId(deviceId: string): Promise source

Sets the ID of the audio device to use for output and returns a Promise.

Params:

NameTypeAttributeDescription
deviceId string

String value representing underlying output device

Return:

Promise

Promise that resolves to undefined when there are no errors detected.

public setVolume(newVolume: number) source

Set the playback volume.

Params:

NameTypeAttributeDescription
newVolume number

A value between 0 and 1, 0 being no volume and 1 being full volume.

Emit:

*

WaveSurfer#volume

public setWaveColor(color: string) source

Set the fill color of the waveform after the cursor.

Params:

NameTypeAttributeDescription
color string

A CSS color string.

Example:

wavesurfer.setWaveColor('#ddd');

public skip(offset: number) source

Skip a number of seconds from the current position (use a negative value to go backwards).

Params:

NameTypeAttributeDescription
offset number

Amount to skip back or forwards

Example:

// go back 2 seconds
wavesurfer.skip(-2);

public skipBackward(seconds: number) source

Skip backward

Params:

NameTypeAttributeDescription
seconds number
  • nullable: true

Amount to skip back, if not specified skipLength is used

Example:

wavesurfer.skipBackward();

public skipForward(seconds: number) source

Skip forward

Params:

NameTypeAttributeDescription
seconds number
  • nullable: true

Amount to skip back, if not specified skipLength is used

Example:

wavesurfer.skipForward();

public stop() source

Stops and goes to the beginning.

Example:

wavesurfer.stop();

public toggleInteraction() source

Toggle mouse interaction

Example:

wavesurfer.toggleInteraction();

public toggleMute() source

Toggle the volume on and off. If not currently muted it will save the current volume value and turn the volume off. If currently muted then it will restore the volume to the saved value, and then rest the saved value.

Example:

wavesurfer.toggleMute();

public toggleScroll() source

Toggles scrollParent and redraws

Example:

wavesurfer.toggleScroll();

public zoom(pxPerSec: number) source

Horizontally zooms the waveform in and out. It also changes the parameter minPxPerSec and enables the scrollParent option. Calling the function with a falsey parameter will reset the zoom state.

Params:

NameTypeAttributeDescription
pxPerSec number
  • nullable: true

Number of horizontal pixels per second of audio, if none is set the waveform returns to unzoomed state

Emit:

*

WaveSurfer#zoom

Example:

wavesurfer.zoom(20);