# wavesurfer.js Annotations Tool

Click on a region to enter an annotation.
Shift-click plays a region in a loop.

Start
End
Note
or

#### Region events:

- `region-in` – When playback enters a region. Callback will receive the `Region` object.
- `region-out`– When playback leaves a region. Callback will receive the `Region` object.
- `region-mouseenter` - When the mouse moves over a region. Callback will receive the `Region` object, and a `MouseEvent` object.
- `region-mouseleave` - When the mouse leaves a region. Callback will receive the `Region` object, and a `MouseEvent` object.
- `region-click` - When the mouse clicks on a region. Callback will receive the `Region` object, and a `MouseEvent` object.
- `region-dblclick` - When the mouse double-clicks on a region. Callback will receive the `Region` object, and a `MouseEvent` object.
- `region-created` – When a region is created. Callback will receive the `Region` object.
- `region-updated` – When a region is updated. Callback will receive the `Region` object.
- `region-update-end` – When dragging or resizing is finished. Callback will receive the `Region` object.
- `region-removed` – When a region is removed. Callback will receive the `Region` object.

#### 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`).

To enable the plugin, add the script `plugin/wavesurfer.regions.js` to your page.

After doing that, use `wavesurfer.addRegion()` to create Region objects.

##### Exposed Methods

- `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).
- `disableDragSelection()` - Disables ability to create regions.

##### Region 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.

##### Region Methods

- `remove()` - Remove the region object.
- `update(options)` - Modify the settings of the region.
- `play()` - Play the audio region from the start to end position.

##### Region Events

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

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

Fork me on GitHub