Regions plugin

Regions are visual overlays on waveform that can be used to play and loop portions of audio. Regions can be dragged and resized.

Visual customization is possible via CSS (using the selectors .wavesurfer-region and .wavesurfer-handle).

Quick start

Methods added to the WaveSurfer object

  • addRegion(options) – Creates a region on the waveform. Returns a Region object. See Region Options, Region Methods and Region Events below. Note: You cannot add regions until the audio has finished loading, otherwise the start: and end: properties of the new region will be set to 0, or an unexpected value.
  • clearRegions() – Removes all regions.
  • enableDragSelection(options) – Lets you create regions by selecting. areas of the waveform with mouse. options are Region objects' params (see below).

To get the list of existing regions: wavesurfer.regions.list.


Region objects have the following options:

option type default description
id string random The id of the region.
start float 0 The start position of the region (in seconds).
end float 0 The end position of the region (in seconds).
loop boolean false Whether to loop the region when played back.
drag boolean true Allow/dissallow dragging the region.
resize boolean true Allow/dissallow resizing the region.
color string "rgba(0, 0, 0, 0.1)" HTML color code.
minLength number null Optional minimum length for the region (in seconds).
maxLength number null Optional maximum length for the region (in seconds).

Region Methods

Some useful region methods:

  • play() - plays the region once from start to end.
  • playLoop() - plays the region on a loop.
  • remove() - removes the region.
  • onDrag(timeInSeconds) - adds timeInSeconds to the start and end params.
  • onResize(timeInSeconds, 'start') - Adds timeInSeconds to end by default. The optional parameter 'start' will add timeInSeconds to start.


Each region object has the following events:

Generic events

  • in - When playback enters the region.
  • out - When playback leaves the region.
  • remove - Happens just before the region is removed.
  • update - When the region's options are updated.
  • update-end - When dragging or resizing is finished.

Mouse events

  • click - When the mouse clicks on the region. Callback will receive a MouseEvent.
  • dblclick - When the mouse double-clicks on the region. Callback will receive a MouseEvent.
  • over - When mouse moves over the region. Callback will receive a MouseEvent.
  • leave - When mouse leaves the region. Callback will receive a MouseEvent.

WaveSurfer events

In addition, the WaveSurfer instance also fires a set of matching events (passing a region object):

  • region-created
  • region-updated
  • region-update-end
  • region-removed
  • region-play
  • region-in
  • region-out
  • region-mouseenter
  • region-mouseleave
  • region-click
  • region-dblclick
Fork me on GitHub