0
# WaveSurfer.js
1
2
WaveSurfer.js is an interactive audio waveform rendering and playback library for web applications. It leverages modern web technologies including HTML5 Audio and Web Audio APIs to create responsive, customizable waveform visualizations with extensive plugin architecture supporting regions, timeline, minimap, and advanced audio analysis features.
3
4
## Package Information
5
6
- **Package Name**: wavesurfer.js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install wavesurfer.js`
10
11
## Core Imports
12
13
```typescript
14
import WaveSurfer from "wavesurfer.js";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const WaveSurfer = require("wavesurfer.js");
21
```
22
23
Plugin imports:
24
25
```typescript
26
import Regions from "wavesurfer.js/dist/plugins/regions.esm.js";
27
import Timeline from "wavesurfer.js/dist/plugins/timeline.esm.js";
28
```
29
30
## Basic Usage
31
32
```typescript
33
import WaveSurfer from "wavesurfer.js";
34
35
// Create waveform instance
36
const wavesurfer = WaveSurfer.create({
37
container: "#waveform", // Required: target element
38
waveColor: "#4F4A85",
39
progressColor: "#383351",
40
url: "/audio.mp3", // Audio file to load
41
});
42
43
// Control playback
44
await wavesurfer.play();
45
wavesurfer.pause();
46
wavesurfer.stop();
47
48
// Listen to events
49
wavesurfer.on("ready", (duration) => {
50
console.log("Audio loaded, duration:", duration);
51
});
52
53
wavesurfer.on("play", () => {
54
console.log("Playback started");
55
});
56
57
wavesurfer.on("pause", () => {
58
console.log("Playback paused");
59
});
60
```
61
62
## Architecture
63
64
WaveSurfer.js is built around several key components:
65
66
- **Core WaveSurfer Class**: Main API providing waveform rendering, audio playback, and event management
67
- **Player System**: Audio playback abstraction supporting both MediaElement and WebAudio backends
68
- **Renderer**: Canvas-based waveform visualization with customizable styling and interaction
69
- **Plugin Architecture**: Extensible system with official plugins for regions, timeline, recording, and more
70
- **Event System**: Comprehensive event emitter for lifecycle, playback, and interaction events
71
- **Audio Processing**: Built-in audio decoding, peaks generation, and Web Audio integration
72
73
## Capabilities
74
75
### Core Waveform Control
76
77
Primary waveform creation, audio loading, and playback control functionality.
78
79
```typescript { .api }
80
class WaveSurfer {
81
static create(options: WaveSurferOptions): WaveSurfer;
82
83
// Audio loading
84
load(url: string, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;
85
loadBlob(blob: Blob, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;
86
87
// Playback control
88
play(start?: number, end?: number): Promise<void>;
89
pause(): void;
90
playPause(): Promise<void>;
91
stop(): void;
92
93
// Navigation
94
setTime(time: number): void;
95
seekTo(progress: number): void;
96
getCurrentTime(): number;
97
getDuration(): number;
98
}
99
```
100
101
[Core Waveform Control](./core-waveform-control.md)
102
103
### Visual Customization
104
105
Waveform appearance configuration including colors, styling, zoom, and display options.
106
107
```typescript { .api }
108
interface WaveSurferOptions {
109
// Required
110
container: HTMLElement | string;
111
112
// Visual appearance
113
height?: number | 'auto';
114
width?: number | string;
115
waveColor?: string | string[] | CanvasGradient;
116
progressColor?: string | string[] | CanvasGradient;
117
cursorColor?: string;
118
cursorWidth?: number;
119
120
// Bar visualization
121
barWidth?: number;
122
barGap?: number;
123
barRadius?: number;
124
barHeight?: number;
125
barAlign?: 'top' | 'bottom';
126
}
127
```
128
129
[Visual Customization](./visual-customization.md)
130
131
### Audio Processing
132
133
Audio decoding, peaks generation, and Web Audio integration for advanced audio manipulation.
134
135
```typescript { .api }
136
interface WaveSurfer {
137
// Audio data
138
getDecodedData(): AudioBuffer | null;
139
exportPeaks(options?: ExportPeaksOptions): Array<number[]>;
140
141
// Zoom and navigation
142
zoom(minPxPerSec: number): void;
143
getScroll(): number;
144
setScroll(pixels: number): void;
145
setScrollTime(time: number): void;
146
}
147
148
interface ExportPeaksOptions {
149
channels?: number;
150
maxLength?: number;
151
precision?: number;
152
}
153
```
154
155
[Audio Processing](./audio-processing.md)
156
157
### Event System
158
159
Comprehensive event handling for lifecycle, playback, and user interaction events.
160
161
```typescript { .api }
162
interface WaveSurferEvents {
163
// Lifecycle
164
init: [];
165
ready: [duration: number];
166
destroy: [];
167
168
// Loading
169
load: [url: string];
170
loading: [percent: number];
171
decode: [duration: number];
172
173
// Playback
174
play: [];
175
pause: [];
176
finish: [];
177
timeupdate: [currentTime: number];
178
seeking: [currentTime: number];
179
180
// Interaction
181
click: [relativeX: number, relativeY: number];
182
drag: [relativeX: number];
183
scroll: [visibleStartTime: number, visibleEndTime: number, scrollLeft: number, scrollRight: number];
184
zoom: [minPxPerSec: number];
185
}
186
```
187
188
[Event System](./event-system.md)
189
190
### Plugin System
191
192
Extensible plugin architecture with official plugins for regions, timeline, recording, and visualization.
193
194
```typescript { .api }
195
interface WaveSurfer {
196
registerPlugin<T extends GenericPlugin>(plugin: T): T;
197
unregisterPlugin(plugin: GenericPlugin): void;
198
getActivePlugins(): GenericPlugin[];
199
}
200
201
class BasePlugin<EventTypes, Options> {
202
constructor(options: Options);
203
destroy(): void;
204
}
205
```
206
207
[Plugin System](./plugin-system.md)
208
209
### Regions Plugin
210
211
Visual overlays and markers for audio segments with interactive drag, resize, and content support.
212
213
```typescript { .api }
214
class RegionsPlugin extends BasePlugin<RegionsPluginEvents, RegionsPluginOptions> {
215
addRegion(params: RegionParams): Region;
216
clearRegions(): void;
217
getRegions(): Region[];
218
enableDragSelection(options?: DragSelectionOptions): () => void;
219
}
220
221
interface Region {
222
id: string;
223
start: number;
224
end: number;
225
play(end?: number): Promise<void>;
226
setOptions(params: Partial<RegionParams>): void;
227
remove(): void;
228
}
229
```
230
231
[Regions Plugin](./regions-plugin.md)
232
233
### Audio Recording
234
235
Real-time audio recording with waveform visualization and MediaRecorder integration.
236
237
```typescript { .api }
238
class RecordPlugin extends BasePlugin<RecordPluginEvents, RecordPluginOptions> {
239
startRecording(options?: StartRecordingOptions): Promise<void>;
240
stopRecording(): Blob;
241
pauseRecording(): void;
242
resumeRecording(): void;
243
getRecordedData(): Blob | null;
244
}
245
```
246
247
[Audio Recording](./audio-recording.md)
248
249
### Timeline and Navigation
250
251
Timeline display, minimap navigation, and zoom controls for enhanced waveform interaction.
252
253
```typescript { .api }
254
class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOptions> {
255
// Automatically renders time labels and notches
256
}
257
258
class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions> {
259
// Provides overview waveform for navigation
260
}
261
262
class ZoomPlugin extends BasePlugin<ZoomPluginEvents, ZoomPluginOptions> {
263
zoomIn(): void;
264
zoomOut(): void;
265
}
266
```
267
268
[Timeline and Navigation](./timeline-navigation.md)
269
270
## Types
271
272
```typescript { .api }
273
interface WaveSurferOptions {
274
// Required
275
container: HTMLElement | string;
276
277
// Visual options
278
height?: number | 'auto';
279
width?: number | string;
280
waveColor?: string | string[] | CanvasGradient;
281
progressColor?: string | string[] | CanvasGradient;
282
cursorColor?: string;
283
cursorWidth?: number;
284
barWidth?: number;
285
barGap?: number;
286
barRadius?: number;
287
barHeight?: number;
288
barAlign?: 'top' | 'bottom';
289
290
// Audio options
291
url?: string;
292
peaks?: Array<Float32Array | number[]>;
293
duration?: number;
294
media?: HTMLMediaElement;
295
mediaControls?: boolean;
296
autoplay?: boolean;
297
audioRate?: number;
298
backend?: 'WebAudio' | 'MediaElement';
299
300
// Interaction options
301
interact?: boolean;
302
dragToSeek?: boolean | { debounceTime: number };
303
hideScrollbar?: boolean;
304
autoScroll?: boolean;
305
autoCenter?: boolean;
306
307
// Rendering options
308
fillParent?: boolean;
309
minPxPerSec?: number;
310
sampleRate?: number;
311
normalize?: boolean;
312
splitChannels?: Array<Partial<WaveSurferOptions> & { overlay?: boolean }>;
313
renderFunction?: (peaks: Array<Float32Array | number[]>, ctx: CanvasRenderingContext2D) => void;
314
315
// Advanced options
316
plugins?: GenericPlugin[];
317
fetchParams?: RequestInit;
318
cspNonce?: string;
319
blobMimeType?: string;
320
}
321
322
type GenericPlugin = BasePlugin<BasePluginEvents, unknown>;
323
324
interface BasePluginEvents {
325
destroy: [];
326
}
327
```