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

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

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 ajax 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): string

Save waveform image as data URI.

public

exportPCM(length: number, accuracy: number, noWindow: boolean, start: number): string

Exports PCM data into a JSON array and opens in a new window.

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

Get the current ready status.

public

load(url: string | HTMLMediaElement, peaks: number[] | number[][], preload: string, duration: number): *

Loads audio and re-renders the waveform.

public

loadBlob(blob: Blob | File)

Loads audio data from a Blob or File object

public

Stops 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 current play time in seconds.

public

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

public

setHeight(height: number)

Set the height of the waveform.

public

setMute(mute: boolean)

Enable or disable muted audio

public

Set the playback rate.

public

Set the fill color of the waveform behind the cursor.

public

setSinkId(deviceId: string): *

Set the playback volume.

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

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

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

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

Example:

const wavesurfer = new WaveSurfer(params);

Public Members

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 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

Emit:

WaveSurfer#plugin-added

Called with the name of the plugin that was added

Example:

wavesurfer.addPlugin(WaveSurfer.minimap());

public cancelAjax() source

Cancel any ajax 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

Emit:

*

WaveSurfer#plugin-destroyed

Example:

wavesurfer.destroyPlugin('minimap');

public empty() source

Display empty waveform.

public exportImage(format: string, quality: number): string 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'
quality number
  • default: 1

Return:

string

data URI of image

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

Exports PCM data into a JSON array and opens in a new window.

Params:

NameTypeAttributeDescription
length number
  • default: 1024

The scale in which to export the peaks. (Integer)

accuracy number
  • default: 10000

(Integer)

noWindow boolean
  • nullable: true

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

start number

Return:

string

JSON of peaks

TODO:

  • Update exportPCM to work with new getPeaks signature

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

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

Example:

const isMuted = wavesurfer.getMute();

public getPlaybackRate(): number source

Get the playback rate.

Return:

number

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

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

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 isReady(): boolean source

Get the current ready status.

Return:

boolean

Example:

const isReady = wavesurfer.isReady();

public load(url: string | HTMLMediaElement, peaks: number[] | number[][], preload: string, duration: number): * 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[][]
  • nullable: true

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

preload string
  • nullable: true

(Use with backend MediaElement) '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:

*

Example:

// using ajax or media element to load (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 playback

Return:

Promise

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

Emit:

*

WaveSurfer#interaction

Example:

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

public playPause(): Promise source

Toggle playback

Return:

Promise

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

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)

Return:

*

Emit:

*

WaveSurfer#interaction

*

WaveSurfer#seek

Example:

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

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 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

Emit:

*

WaveSurfer#volume

*

WaveSurfer#mute

Example:

// unmute
wavesurfer.setMute(false);

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): * source

Set the playback volume.

Params:

NameTypeAttributeDescription
deviceId string

String value representing underlying output device

Return:

*

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