Regions plugin

Regions are visual overlays on the waveform that mark segments of audio. They can be dragged, resized, clicked, and played back independently. See the live demo to explore them interactively.

Setup

Install wavesurfer.js (if you haven’t already — see Getting started), then import and register the plugin:

import WaveSurfer from 'wavesurfer.js'
import RegionsPlugin from 'wavesurfer.js/dist/plugins/regions.js'

const ws = WaveSurfer.create({
  container: '#waveform',
  url: '/audio.mp3',
})

const regions = ws.registerPlugin(RegionsPlugin.create())

CDN / UMD:

<script src="https://unpkg.com/wavesurfer.js@7"></script>
<script src="https://unpkg.com/wavesurfer.js@7/dist/plugins/regions.js"></script>
<script>
  const ws = WaveSurfer.create({ container: '#waveform', url: '/audio.mp3' })
  const regions = ws.registerPlugin(WaveSurfer.RegionsPlugin.create())
</script>

RegionsPlugin.create() takes no options — the constructor argument is undefined.

Adding regions

Call regions.addRegion(options) after the plugin is registered. The full set of accepted options:

ws.on('ready', () => {
  // Basic region
  const intro = regions.addRegion({
    start: 0,
    end: 10,
    color: 'rgba(255, 100, 0, 0.2)',
    content: 'Intro',
  })

  // Marker (zero-width, rendered as a vertical line)
  regions.addRegion({
    start: 30,
    color: 'rgba(0, 0, 200, 0.8)',
    content: 'Drop',
  })

  // Region with an HTML element as label
  const badge = document.createElement('span')
  badge.className = 'badge'
  badge.textContent = 'Chorus'
  regions.addRegion({ start: 60, end: 90, content: badge })
})

addRegion() returns the Region instance synchronously. However, wait for ready before calling it — see the pitfalls section below.

Drag-to-create

enableDragSelection(options) lets users draw new regions by clicking and dragging on empty waveform space. It accepts any RegionParams except start and end (those come from the drag gesture):

ws.on('ready', () => {
  const disableDrag = regions.enableDragSelection({
    color: 'rgba(0, 150, 255, 0.2)',
  })

  // Call disableDrag() later to stop accepting new drag-created regions
  // disableDrag()
})

The returned function tears down the drag listener when called. Newly drawn regions fire the same region-created event as programmatically added ones.

Styling regions

Color via option

Pass a CSS color string to color when creating:

regions.addRegion({ start: 5, end: 15, color: 'rgba(200, 0, 100, 0.25)' })

Updating color with setOptions

region.setOptions(options) accepts a subset of RegionParams:

region.setOptions({
  color: 'rgba(0, 200, 100, 0.3)',  // updates backgroundColor immediately
  start: 5,
  end: 20,
  drag: false,
  resize: true,
  resizeStart: false,
  resizeEnd: true,
  content: 'Updated label',
  id: 'my-region',
})

setOptions({ color }) works as expected in v7. It directly sets element.style.backgroundColor — however it only sets backgroundColor, not the border (which is used by markers). If you created a zero-width marker and call setOptions({ color }), the left-border color is not updated. For regions (non-markers) color updates take effect immediately.

Note that minLength, maxLength, channelIdx, and contentEditable are not accepted by setOptions — they can only be set at creation time via addRegion.

CSS: content and borders

Regions render with CSS part attributes you can target in a stylesheet:

/* The region overlay */
[part~="region"] {
  border-radius: 4px;
}

/* The label inside a region */
[part~="region-content"] {
  font-size: 12px;
  font-weight: bold;
  color: #333;
}

/* Resize handles */
[part~="region-handle"] {
  width: 4px;
}
[part~="region-handle-left"]  { border-left-color: red; }
[part~="region-handle-right"] { border-right-color: blue; }

/* Target a specific region by its id */
[part~="my-region"] {
  outline: 2px solid gold;
}

A marker element gets part="marker <id>" instead of part="region <id>".

Custom data

In wavesurfer.js v7 the RegionParams type has no built-in data field. There is no automatic property for attaching arbitrary metadata to a region. The idiomatic v7 approach is to hold your own side-channel map keyed on the region’s id:

const meta = new Map()

const region = regions.addRegion({ start: 10, end: 20, id: 'verse-1' })
meta.set(region.id, { label: 'Verse 1', color: '#f00', track: 2 })

// Retrieve later, e.g. in an event handler
regions.on('region-clicked', (region) => {
  const data = meta.get(region.id)
  console.log(data.label)
})

Because id defaults to a random string, set it explicitly to a stable value if you need to look things up later. Alternatively, since the region instance is a plain JavaScript object, you can attach properties directly — but that is not type-safe and may clash with future fields:

// Works today, but not type-safe
region._myData = { track: 2 }

Using meta.set(region.id, ...) is the safer pattern.

Events

Plugin events

Subscribe on the regions plugin instance:

Region instance events

Subscribe on a Region instance returned by addRegion():

Seeking on click

regions.on('region-clicked', (region, e) => {
  e.stopPropagation()       // prevent the waveform's own click-to-seek
  region.play(true)         // seek to region start and play to region end
})

Looping playback

region.play(stopAtEnd?)

region.play() seeks wavesurfer to the region’s start and begins playback.

• region.play() — plays from start, does not automatically stop at end.
• region.play(true) — plays from start and stops when playback reaches end.
• region.play(false) — same as region.play().

const loop = regions.addRegion({ start: 10, end: 20, color: 'rgba(0,100,200,0.2)' })

// One-shot: play the region once and stop
loop.play(true)

Looping with region-out

The region-out plugin event fires each time playback leaves a region. Use it to loop continuously:

let looping = false

regions.on('region-out', (region) => {
  if (looping && region === activeRegion) {
    region.play(true)
  }
})

let activeRegion = null

regions.on('region-clicked', (region, e) => {
  e.stopPropagation()
  activeRegion = region
  looping = true
  region.play(true)
})

// Stop looping on waveform click
ws.on('interaction', () => {
  looping = false
  activeRegion = null
})

For a simpler approach when you only need to loop once and don’t need to track which region is active, see the Playback docs.

Removing and clearing

// Remove a single region
region.remove()

// Remove all regions
regions.clearRegions()

// Get the current list before clearing
const all = regions.getRegions()
all.forEach((r) => console.log(r.id, r.start, r.end))
regions.clearRegions()

// Safe
ws.on('ready', () => {
  regions.addRegion({ start: 10, end: 20 })
})

// Unsafe
regions.on('region-created', (region) => {
  region.remove()  // DOM node may linger
})

// Safe — defer by one tick
regions.on('region-created', (region) => {
  if (shouldReject(region)) {
    setTimeout(() => region.remove(), 0)
  }
})

const unsub = regions.on('region-updated', (region) => {
  // ...
})

// When you no longer need this listener:
unsub()