0
# Core Waveform Control
1

2
Primary waveform creation, audio loading, and playback control functionality for managing audio playback and waveform interaction.
3

4
## Capabilities
5

6
### WaveSurfer Class Creation
7

8
Create new WaveSurfer instances with configuration options.
9

10
```typescript { .api }
11
/**
12
 * Create a new WaveSurfer instance with the specified options
13
 * @param options - Configuration options for the waveform
14
 * @returns New WaveSurfer instance
15
 */
16
static create(options: WaveSurferOptions): WaveSurfer;
17

18
/**
19
 * Constructor for WaveSurfer instance (use create() instead)
20
 * @param options - Configuration options for the waveform  
21
 */
22
constructor(options: WaveSurferOptions);
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import WaveSurfer from "wavesurfer.js";
29

30
// Basic waveform creation
31
const wavesurfer = WaveSurfer.create({
32
  container: "#waveform",
33
  waveColor: "#4F4A85",
34
  progressColor: "#383351",
35
});
36

37
// Advanced configuration
38
const advancedWaveform = WaveSurfer.create({
39
  container: document.getElementById("advanced-waveform"),
40
  height: 200,
41
  waveColor: ["#ff0000", "#00ff00", "#0000ff"],
42
  progressColor: "#666",
43
  cursorColor: "#fff",
44
  barWidth: 2,
45
  barGap: 1,
46
  barRadius: 2,
47
  normalize: true,
48
  fillParent: true,
49
  autoScroll: true,
50
  interact: true,
51
});
52
```
53

54
### Audio Loading
55

56
Load audio files from URLs or Blob objects, with optional pre-computed peaks data.
57

58
```typescript { .api }
59
/**
60
 * Load an audio file by URL, with optional pre-decoded audio data
61
 * @param url - URL of the audio file to load
62
 * @param peaks - Optional pre-computed peaks data for faster rendering
63
 * @param duration - Optional pre-computed duration in seconds
64
 * @returns Promise that resolves when audio is loaded and ready
65
 */
66
load(url: string, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;
67

68
/**
69
 * Load an audio blob with optional pre-decoded audio data
70
 * @param blob - Audio blob to load
71
 * @param peaks - Optional pre-computed peaks data for faster rendering  
72
 * @param duration - Optional pre-computed duration in seconds
73
 * @returns Promise that resolves when audio is loaded and ready
74
 */
75
loadBlob(blob: Blob, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;
76

77
/**
78
 * Empty the waveform (load silent audio)
79
 */
80
empty(): void;
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
// Load from URL
87
await wavesurfer.load("/path/to/audio.mp3");
88

89
// Load with pre-computed peaks for performance
90
const peaks = [[0.1, 0.3, -0.2, 0.8, -0.4], [0.05, 0.2, -0.1, 0.6, -0.3]];
91
await wavesurfer.load("/path/to/audio.mp3", peaks, 120.5);
92

93
// Load from blob (e.g., from file input)
94
const fileInput = document.querySelector('input[type="file"]');
95
const file = fileInput.files[0];
96
await wavesurfer.loadBlob(file);
97

98
// Clear waveform
99
wavesurfer.empty();
100
```
101

102
### Playback Control
103

104
Control audio playback with play, pause, stop, and playback position methods.
105

106
```typescript { .api }
107
/**
108
 * Start playing the audio from current position or specified time range
109
 * @param start - Optional start time in seconds
110
 * @param end - Optional end time in seconds (will stop at this time)
111
 * @returns Promise that resolves when playback starts
112
 */
113
play(start?: number, end?: number): Promise<void>;
114

115
/**
116
 * Pause the audio playback
117
 */
118
pause(): void;
119

120
/**
121
 * Toggle between play and pause states
122
 * @returns Promise that resolves when state change completes
123
 */
124
playPause(): Promise<void>;
125

126
/**
127
 * Stop the audio and return to the beginning
128
 */
129
stop(): void;
130

131
/**
132
 * Skip forward or backward by specified number of seconds
133
 * @param seconds - Number of seconds to skip (positive or negative)
134
 */
135
skip(seconds: number): void;
136

137
/**
138
 * Check if the audio is currently playing
139
 * @returns True if playing, false if paused or stopped
140
 */
141
isPlaying(): boolean;
142

143
/**
144
 * Check if the audio is currently seeking
145
 * @returns True if seeking, false otherwise
146
 */
147
isSeeking(): boolean;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
// Basic playback control
154
await wavesurfer.play();
155
wavesurfer.pause();
156
await wavesurfer.playPause(); // Toggle state
157

158
// Play specific segment
159
await wavesurfer.play(30, 60); // Play from 30s to 60s
160

161
// Skip forward/backward
162
wavesurfer.skip(10);  // Skip forward 10 seconds
163
wavesurfer.skip(-5);  // Skip backward 5 seconds
164

165
// Stop and reset
166
wavesurfer.stop();
167

168
// Check playback state
169
if (wavesurfer.isPlaying()) {
170
  console.log("Audio is playing");
171
}
172
```
173

174
### Time and Position Control
175

176
Control and query the current playback position and audio duration.
177

178
```typescript { .api }
179
/**
180
 * Jump to a specific time in the audio (in seconds)
181
 * @param time - Time position in seconds
182
 */
183
setTime(time: number): void;
184

185
/**
186
 * Seek to a percentage of audio as [0..1] (0 = beginning, 1 = end)
187
 * @param progress - Progress as decimal between 0 and 1
188
 */
189
seekTo(progress: number): void;
190

191
/**
192
 * Get the current audio position in seconds
193
 * @returns Current playback position in seconds
194
 */  
195
getCurrentTime(): number;
196

197
/**
198
 * Get the duration of the audio in seconds
199
 * @returns Audio duration in seconds, or 0 if not loaded
200
 */
201
getDuration(): number;
202
```
203

204
**Usage Examples:**
205

206
```typescript
207
// Jump to specific times
208
wavesurfer.setTime(45.7); // Jump to 45.7 seconds
209
wavesurfer.seekTo(0.5);   // Jump to middle of audio
210
wavesurfer.seekTo(0.25);  // Jump to 25% through audio
211

212
// Get timing information
213
const currentTime = wavesurfer.getCurrentTime();
214
const duration = wavesurfer.getDuration();
215
const progress = currentTime / duration;
216

217
console.log(`Playing at ${currentTime}s of ${duration}s (${Math.round(progress * 100)}%)`);
218
```
219

220
### Volume and Playback Rate Control
221

222
Control audio volume, muting, and playback speed.
223

224
```typescript { .api }
225
/**
226
 * Get the current audio volume
227
 * @returns Volume level between 0 and 1
228
 */
229
getVolume(): number;
230

231
/**
232
 * Set the audio volume
233
 * @param volume - Volume level between 0 and 1
234
 */
235
setVolume(volume: number): void;
236

237
/**
238
 * Get the current muted state
239
 * @returns True if muted, false otherwise
240
 */
241
getMuted(): boolean;
242

243
/**
244
 * Mute or unmute the audio
245
 * @param muted - True to mute, false to unmute
246
 */
247
setMuted(muted: boolean): void;
248

249
/**
250
 * Get the current playback rate/speed
251
 * @returns Playback rate (1.0 = normal speed)
252
 */
253
getPlaybackRate(): number;
254

255
/**
256
 * Set the playback speed, with optional pitch preservation
257
 * @param rate - Playback rate (0.5 = half speed, 2.0 = double speed)
258
 * @param preservePitch - Whether to preserve pitch (default: true)
259
 */
260
setPlaybackRate(rate: number, preservePitch?: boolean): void;
261
```
262

263
**Usage Examples:**
264

265
```typescript
266
// Volume control
267
wavesurfer.setVolume(0.8);        // 80% volume
268
console.log(wavesurfer.getVolume()); // 0.8
269

270
// Muting
271
wavesurfer.setMuted(true);        // Mute
272
wavesurfer.setMuted(false);       // Unmute
273
console.log(wavesurfer.getMuted()); // false
274

275
// Playback speed
276
wavesurfer.setPlaybackRate(1.5);     // 1.5x speed
277
wavesurfer.setPlaybackRate(0.75, false); // 0.75x speed, pitch not preserved
278
console.log(wavesurfer.getPlaybackRate()); // 0.75
279
```
280

281
### Media Element Integration
282

283
Access and control the underlying HTML audio/video element.
284

285
```typescript { .api }
286
/**
287
 * Get the HTML media element (audio/video)
288
 * @returns The underlying HTMLMediaElement
289
 */
290
getMediaElement(): HTMLMediaElement;
291

292
/**
293
 * Set a custom HTML media element to use
294
 * @param element - HTMLAudioElement or HTMLVideoElement to use
295
 */
296
setMediaElement(element: HTMLMediaElement): void;
297

298
/**
299
 * Set audio output device (if supported by browser)
300
 * @param sinkId - Device ID for audio output
301
 * @returns Promise that resolves when device is set
302
 */
303
setSinkId(sinkId: string): Promise<void>;
304
```
305

306
**Usage Examples:**
307

308
```typescript
309
// Access the media element for advanced control
310
const mediaElement = wavesurfer.getMediaElement();
311
mediaElement.playsinline = true;
312
mediaElement.crossOrigin = "anonymous";
313

314
// Use custom audio element
315
const customAudio = document.createElement("audio");
316
customAudio.crossOrigin = "anonymous";
317
wavesurfer.setMediaElement(customAudio);
318

319
// Set audio output device (if supported)
320
try {
321
  await wavesurfer.setSinkId("device-id-here");
322
  console.log("Audio output device changed");
323
} catch (error) {
324
  console.log("Device change not supported");
325
}
326
```
327

328
### Configuration Updates
329

330
Update waveform options after initialization.
331

332
```typescript { .api }
333
/**
334
 * Set new wavesurfer options and re-render
335
 * @param options - Partial options object with properties to update
336
 */
337
setOptions(options: Partial<WaveSurferOptions>): void;
338

339
/**
340
 * Toggle if the waveform should react to clicks and interactions
341
 * @param isInteractive - True to enable interaction, false to disable
342
 */
343
toggleInteraction(isInteractive: boolean): void;
344
```
345

346
**Usage Examples:**
347

348
```typescript
349
// Update visual appearance
350
wavesurfer.setOptions({
351
  waveColor: "#ff0000",
352
  progressColor: "#00ff00",
353
  height: 150,
354
});
355

356
// Update behavior
357
wavesurfer.setOptions({
358
  autoScroll: false,
359
  dragToSeek: true,
360
  minPxPerSec: 100,
361
});
362

363
// Disable interaction
364
wavesurfer.toggleInteraction(false);
365
```
366

367
### Lifecycle Management
368

369
Destroy the waveform instance and clean up resources.
370

371
```typescript { .api }
372
/**
373
 * Destroy the WaveSurfer instance and clean up all resources
374
 * Removes event listeners, stops audio, and cleans up DOM elements
375
 */
376
destroy(): void;
377
```
378

379
**Usage Examples:**
380

381
```typescript
382
// Clean up when done
383
wavesurfer.destroy();
384

385
// Example cleanup in framework
386
// React useEffect cleanup
387
useEffect(() => {
388
  const ws = WaveSurfer.create({...});
389
  return () => ws.destroy();
390
}, []);
391

392
// Vue beforeUnmount
393
beforeUnmount(() => {
394
  wavesurfer.destroy();
395
});
396
```