0
# Visual Customization
1

2
Comprehensive waveform appearance configuration including colors, styling, dimensions, zoom, and display options for creating visually appealing and functional waveform interfaces.
3

4
## Capabilities
5

6
### Container and Dimensions
7

8
Configure the target container and waveform dimensions.
9

10
```typescript { .api }
11
interface WaveSurferOptions {
12
  /** Required: HTML element or CSS selector where the waveform will be rendered */
13
  container: HTMLElement | string;
14
  
15
  /** The height of the waveform in pixels, or "auto" to fill the container height */
16
  height?: number | 'auto';
17
  
18
  /** The width of the waveform in pixels or any CSS value; defaults to 100% */
19
  width?: number | string;
20
  
21
  /** Stretch the waveform to fill the container, true by default */
22
  fillParent?: boolean;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
// Using CSS selector
30
const wavesurfer = WaveSurfer.create({
31
  container: "#waveform",
32
  height: 200,
33
});
34

35
// Using DOM element
36
const container = document.getElementById("my-waveform");
37
const wavesurfer = WaveSurfer.create({
38
  container: container,
39
  height: "auto", // Fill container height
40
  width: 800,
41
});
42

43
// Responsive sizing
44
const wavesurfer = WaveSurfer.create({
45
  container: "#responsive-waveform",
46
  height: 150,
47
  fillParent: true, // Fill available width
48
});
49
```
50

51
### Color Customization
52

53
Configure waveform colors for wave, progress, and cursor elements.
54

55
```typescript { .api }
56
interface WaveSurferOptions {
57
  /** The color of the waveform - can be solid color, array of colors, or gradient */
58
  waveColor?: string | string[] | CanvasGradient;
59
  
60
  /** The color of the progress mask - can be solid color, array of colors, or gradient */
61
  progressColor?: string | string[] | CanvasGradient;
62
  
63
  /** The color of the playback cursor */
64
  cursorColor?: string;
65
  
66
  /** The cursor width in pixels */
67
  cursorWidth?: number;
68
}
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
// Solid colors
75
const wavesurfer = WaveSurfer.create({
76
  container: "#waveform",
77
  waveColor: "#4F4A85",
78
  progressColor: "#383351",
79
  cursorColor: "#ffffff",
80
  cursorWidth: 2,
81
});
82

83
// Multi-color waveform for stereo channels
84
const stereoWaveform = WaveSurfer.create({
85
  container: "#stereo",
86
  waveColor: ["#ff0000", "#0000ff"], // Red for left, blue for right
87
  progressColor: ["#800000", "#000080"], // Darker versions for progress
88
});
89

90
// Using CSS gradients
91
const canvas = document.createElement("canvas");
92
const ctx = canvas.getContext("2d");
93
const gradient = ctx.createLinearGradient(0, 0, 0, 150);
94
gradient.addColorStop(0, "#ff0000");
95
gradient.addColorStop(1, "#0000ff");
96

97
const gradientWaveform = WaveSurfer.create({
98
  container: "#gradient",
99
  waveColor: gradient,
100
});
101
```
102

103
### Bar Visualization
104

105
Configure bar-style waveform visualization with spacing and styling options.
106

107
```typescript { .api }
108
interface WaveSurferOptions {
109
  /** If set, the waveform will be rendered with bars like this: ▁ ▂ ▇ ▃ ▅ ▂ */
110
  barWidth?: number;
111
  
112
  /** Spacing between bars in pixels */
113
  barGap?: number;
114
  
115
  /** Rounded borders for bars (border-radius) */
116
  barRadius?: number;
117
  
118
  /** A vertical scaling factor for the waveform */
119
  barHeight?: number;
120
  
121
  /** Vertical bar alignment */
122
  barAlign?: 'top' | 'bottom';
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
// Basic bar visualization
130
const barWaveform = WaveSurfer.create({
131
  container: "#bars",
132
  barWidth: 3,
133
  barGap: 1,
134
  barRadius: 2,
135
  waveColor: "#4F4A85",
136
});
137

138
// Tall bars aligned to bottom
139
const tallBars = WaveSurfer.create({
140
  container: "#tall-bars",
141
  barWidth: 4,
142
  barGap: 2,
143
  barHeight: 2,      // 2x height scaling
144
  barAlign: "bottom",
145
  barRadius: 3,
146
});
147

148
// Thin separated bars
149
const thinBars = WaveSurfer.create({
150
  container: "#thin-bars",
151
  barWidth: 1,
152
  barGap: 2,
153
  barRadius: 0,
154
  waveColor: "#333",
155
});
156
```
157

158
### Zoom and Scaling
159

160
Control waveform zoom level and pixel density for detailed visualization.
161

162
```typescript { .api }
163
interface WaveSurferOptions {
164
  /** Minimum pixels per second of audio (i.e. the zoom level) */
165
  minPxPerSec?: number;
166
  
167
  /** Stretch the waveform to the full height */
168
  normalize?: boolean;
169
}
170

171
interface WaveSurfer {
172
  /**
173
   * Zoom the waveform by a given pixels-per-second factor
174
   * @param minPxPerSec - Pixels per second zoom level
175
   */
176
  zoom(minPxPerSec: number): void;
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
// High zoom level for detailed view
184
const detailedWaveform = WaveSurfer.create({
185
  container: "#detailed",
186
  minPxPerSec: 200, // 200 pixels per second
187
  normalize: true,  // Stretch to full height
188
});
189

190
// Dynamic zoom control
191
wavesurfer.zoom(100); // Zoom to 100 pixels per second
192
wavesurfer.zoom(50);  // Zoom out to 50 pixels per second
193

194
// Zoom controls
195
document.getElementById("zoom-in").addEventListener("click", () => {
196
  const currentZoom = wavesurfer.options.minPxPerSec || 0;
197
  wavesurfer.zoom(currentZoom * 2);
198
});
199

200
document.getElementById("zoom-out").addEventListener("click", () => {
201
  const currentZoom = wavesurfer.options.minPxPerSec || 100;
202
  wavesurfer.zoom(currentZoom / 2);
203
});
204
```
205

206
### Scrolling and Navigation
207

208
Configure scrolling behavior and scrollbar visibility.
209

210
```typescript { .api }
211
interface WaveSurferOptions {
212
  /** Hide the scrollbar */
213
  hideScrollbar?: boolean;
214
  
215
  /** Automatically scroll the container to keep the current position in viewport */
216
  autoScroll?: boolean;
217
  
218
  /** If autoScroll is enabled, keep the cursor in the center of the waveform during playback */
219
  autoCenter?: boolean;
220
}
221

222
interface WaveSurfer {
223
  /**
224
   * Get the current scroll position in pixels
225
   * @returns Scroll position in pixels from left
226
   */
227
  getScroll(): number;
228
  
229
  /**
230
   * Set the current scroll position in pixels
231
   * @param pixels - Scroll position in pixels from left
232
   */
233
  setScroll(pixels: number): void;
234
  
235
  /**
236
   * Move the start of the viewing window to a specific time in the audio
237
   * @param time - Time in seconds to scroll to
238
   */
239
  setScrollTime(time: number): void;
240
}
241
```
242

243
**Usage Examples:**
244

245
```typescript
246
// Custom scroll behavior
247
const customScrollWaveform = WaveSurfer.create({
248
  container: "#custom-scroll",
249
  hideScrollbar: true,
250
  autoScroll: false, // Manual scroll control
251
  autoCenter: false,
252
});
253

254
// Manual scroll control
255
wavesurfer.setScrollTime(30); // Scroll to 30 seconds
256
wavesurfer.setScroll(500);    // Scroll 500 pixels from left
257

258
// Get current scroll position
259
const scrollPos = wavesurfer.getScroll();
260
console.log(`Scrolled ${scrollPos} pixels from left`);
261

262
// Auto-centered playback
263
const centeredWaveform = WaveSurfer.create({
264
  container: "#centered",
265
  autoScroll: true,
266
  autoCenter: true, // Keep playback cursor centered
267
});
268
```
269

270
### Multi-Channel Visualization
271

272
Render multiple audio channels as separate waveforms with individual styling.
273

274
```typescript { .api }
275
interface WaveSurferOptions {
276
  /** Render each audio channel as a separate waveform */
277
  splitChannels?: Array<Partial<WaveSurferOptions> & { overlay?: boolean }>;
278
}
279
```
280

281
**Usage Examples:**
282

283
```typescript
284
// Separate channel visualization
285
const multiChannelWaveform = WaveSurfer.create({
286
  container: "#multi-channel",
287
  splitChannels: [
288
    {
289
      waveColor: "#ff0000",
290
      progressColor: "#800000",
291
      overlay: false, // Separate visual tracks
292
    },
293
    {
294
      waveColor: "#0000ff", 
295
      progressColor: "#000080",
296
      overlay: false,
297
    },
298
  ],
299
});
300

301
// Overlaid stereo channels
302
const overlaidStereo = WaveSurfer.create({
303
  container: "#overlaid",
304
  splitChannels: [
305
    {
306
      waveColor: "rgba(255, 0, 0, 0.7)",
307
      progressColor: "rgba(128, 0, 0, 0.7)",
308
      overlay: true, // Overlay on same track
309
    },
310
    {
311
      waveColor: "rgba(0, 0, 255, 0.7)",
312
      progressColor: "rgba(0, 0, 128, 0.7)", 
313
      overlay: true,
314
    },
315
  ],
316
});
317
```
318

319
### Custom Rendering
320

321
Provide custom rendering functions for advanced waveform visualization.
322

323
```typescript { .api }
324
interface WaveSurferOptions {
325
  /** Custom render function for waveform drawing */
326
  renderFunction?: (peaks: Array<Float32Array | number[]>, ctx: CanvasRenderingContext2D) => void;
327
}
328
```
329

330
**Usage Examples:**
331

332
```typescript
333
// Custom visualization function
334
const customRenderWaveform = WaveSurfer.create({
335
  container: "#custom-render",
336
  renderFunction: (peaks, ctx) => {
337
    const width = ctx.canvas.width;
338
    const height = ctx.canvas.height;
339
    
340
    ctx.clearRect(0, 0, width, height);
341
    ctx.fillStyle = "#4F4A85";
342
    
343
    // Custom rendering logic
344
    peaks[0].forEach((peak, i) => {
345
      const x = (i / peaks[0].length) * width;
346
      const y = height / 2;
347
      const amplitude = Math.abs(peak) * height / 2;
348
      
349
      // Draw custom shape (e.g., circles instead of bars)
350
      ctx.beginPath();
351
      ctx.arc(x, y, amplitude / 10, 0, 2 * Math.PI);
352
      ctx.fill();
353
    });
354
  },
355
});
356

357
// Frequency spectrum visualization
358
const spectrumWaveform = WaveSurfer.create({
359
  container: "#spectrum",
360
  renderFunction: (peaks, ctx) => {
361
    // Custom spectrum analyzer rendering
362
    const gradient = ctx.createLinearGradient(0, 0, 0, ctx.canvas.height);
363
    gradient.addColorStop(0, "#ff0000");
364
    gradient.addColorStop(0.5, "#ffff00");
365
    gradient.addColorStop(1, "#00ff00");
366
    
367
    ctx.fillStyle = gradient;
368
    
369
    // Render frequency bars
370
    peaks[0].forEach((peak, i) => {
371
      const barWidth = ctx.canvas.width / peaks[0].length;
372
      const barHeight = Math.abs(peak) * ctx.canvas.height;
373
      ctx.fillRect(i * barWidth, ctx.canvas.height - barHeight, barWidth - 1, barHeight);
374
    });
375
  },
376
});
377
```
378

379
### Responsive Design
380

381
Create responsive waveforms that adapt to container size changes.
382

383
```typescript { .api }
384
interface WaveSurfer {
385
  /**
386
   * Get the current waveform width in pixels
387
   * @returns Width in pixels
388
   */
389
  getWidth(): number;
390
}
391
```
392

393
**Usage Examples:**
394

395
```typescript
396
// Responsive waveform setup
397
const responsiveWaveform = WaveSurfer.create({
398
  container: "#responsive",
399
  height: 200,
400
  fillParent: true,
401
  autoScroll: true,
402
});
403

404
// Handle window resize
405
window.addEventListener("resize", () => {
406
  // WaveSurfer automatically handles resize when fillParent: true
407
  console.log(`New width: ${responsiveWaveform.getWidth()}px`);
408
});
409

410
// Mobile-optimized settings
411
const isMobile = window.innerWidth < 768;
412
const mobileWaveform = WaveSurfer.create({
413
  container: "#mobile",
414
  height: isMobile ? 100 : 200,
415
  barWidth: isMobile ? 2 : 3,
416
  barGap: isMobile ? 0 : 1,
417
  autoCenter: isMobile,
418
  hideScrollbar: isMobile,
419
});
420
```