@arraypress/waveform-player 1.16.1 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/js/drawing.js CHANGED
@@ -7,22 +7,38 @@ import {resampleData, clamp} from './utils.js';
7
7
 
8
8
  /**
9
9
  * Resolve a fill value that may be a CSS colour string OR an array of colour
10
- * stops (rendered as a vertical canvas gradient). Bundle-light gradient
11
- * support: pass e.g. `waveformColor: ['#fafafa', '#71717a']`.
12
- * A single-element array collapses to that one colour; a multi-element array
13
- * is spread evenly from top (y=0) to bottom (y=height).
10
+ * stops (rendered as a canvas gradient). Bundle-light gradient support: pass
11
+ * e.g. `waveformColor: ['#fafafa', '#71717a']`. A single-element array collapses
12
+ * to that one colour; a multi-element array is spread evenly along the axis set
13
+ * by `options.waveformGradient`:
14
+ * - `'vertical'` (default) a canvas-height gradient (colour keyed to
15
+ * absolute Y, so short bars occupy only the lower band).
16
+ * - `'horizontal'` left -> right across the whole waveform (a hue sweep).
17
+ * - `'diagonal'` top-left -> bottom-right.
14
18
  * @private
15
19
  * @param {CanvasRenderingContext2D} ctx - Canvas context used to build the gradient.
16
20
  * @param {string|string[]} value - A CSS colour string, or an array of colour stops.
17
- * @param {number} height - Canvas height in device pixels (gradient span).
18
- * @returns {string|CanvasGradient} The original string, or a vertical linear gradient.
21
+ * @param {HTMLCanvasElement} canvas - Canvas (provides the device-pixel span).
22
+ * @param {Object} [options] - Drawing options; reads `waveformGradient`.
23
+ * @returns {string|CanvasGradient} The original string, or a linear gradient.
19
24
  */
20
- function makeFill(ctx, value, height) {
25
+ function makeFill(ctx, value, canvas, options) {
21
26
  if (!Array.isArray(value)) return value;
22
- if (value.length === 1) return value[0];
23
- const grad = ctx.createLinearGradient(0, 0, 0, height);
24
- value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
25
- return grad;
27
+ if (value.length < 2) return value[0];
28
+ const w = canvas.width;
29
+ const h = canvas.height;
30
+ const dir = options && options.waveformGradient;
31
+ const [x0, y0, x1, y1] =
32
+ dir === 'horizontal' ? [0, 0, w, 0] :
33
+ dir === 'diagonal' ? [0, 0, w, h] :
34
+ [0, 0, 0, h];
35
+ try {
36
+ const grad = ctx.createLinearGradient(x0, y0, x1, y1);
37
+ value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
38
+ return grad;
39
+ } catch (e) {
40
+ return value[0]; // a bad stop shouldn't abort the whole render
41
+ }
26
42
  }
27
43
 
28
44
  /**
@@ -120,8 +136,8 @@ export function drawBars(ctx, canvas, peaks, progress, options) {
120
136
  const height = canvas.height;
121
137
  const progressWidth = progress * canvas.width;
122
138
  const radii = barRadii(options, dpr);
123
- const baseFill = makeFill(ctx, options.color, height);
124
- const progFill = makeFill(ctx, options.progressColor, height);
139
+ const baseFill = makeFill(ctx, options.color, canvas, options);
140
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
125
141
 
126
142
  ctx.clearRect(0, 0, canvas.width, canvas.height);
127
143
 
@@ -184,8 +200,8 @@ export function drawMirror(ctx, canvas, peaks, progress, options) {
184
200
  const r = barRadiusPx(options, dpr);
185
201
  const topRadii = [r, r, 0, 0]; // round the upper cap
186
202
  const botRadii = [0, 0, r, r]; // round the lower cap
187
- const baseFill = makeFill(ctx, options.color, height);
188
- const progFill = makeFill(ctx, options.progressColor, height);
203
+ const baseFill = makeFill(ctx, options.color, canvas, options);
204
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
189
205
 
190
206
  ctx.clearRect(0, 0, canvas.width, canvas.height);
191
207
 
@@ -252,12 +268,16 @@ export function drawLine(ctx, canvas, peaks, progress, options) {
252
268
  * @returns {void}
253
269
  */
254
270
  const drawCurve = (color, lineWidth, endProgress = 1, addGlow = false) => {
271
+ // strokeStyle accepts a gradient; shadowColor must be a solid string, so
272
+ // collapse a stop array to its last stop for the glow.
273
+ const stroke = makeFill(ctx, color, canvas, options);
274
+ const solid = Array.isArray(color) ? color[color.length - 1] : color;
255
275
  if (addGlow) {
256
276
  ctx.shadowBlur = 12;
257
- ctx.shadowColor = color;
277
+ ctx.shadowColor = solid;
258
278
  }
259
279
 
260
- ctx.strokeStyle = color;
280
+ ctx.strokeStyle = stroke;
261
281
  ctx.lineWidth = lineWidth;
262
282
  ctx.lineCap = 'round';
263
283
  ctx.lineJoin = 'round';
@@ -350,8 +370,8 @@ export function drawBlocks(ctx, canvas, peaks, progress, options) {
350
370
  const blockGap = 2 * dpr;
351
371
  const progressWidth = progress * canvas.width;
352
372
  const centerY = height / 2;
353
- const baseFill = makeFill(ctx, options.color, height);
354
- const progFill = makeFill(ctx, options.progressColor, height);
373
+ const baseFill = makeFill(ctx, options.color, canvas, options);
374
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
355
375
 
356
376
  ctx.clearRect(0, 0, canvas.width, canvas.height);
357
377
 
@@ -402,8 +422,8 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
402
422
  const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
403
423
  const progressWidth = progress * canvas.width;
404
424
  const centerY = height / 2;
405
- const baseFill = makeFill(ctx, options.color, height);
406
- const progFill = makeFill(ctx, options.progressColor, height);
425
+ const baseFill = makeFill(ctx, options.color, canvas, options);
426
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
407
427
 
408
428
  ctx.clearRect(0, 0, canvas.width, canvas.height);
409
429
 
@@ -429,9 +449,10 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
429
449
 
430
450
  /**
431
451
  * Draw seekbar style - a simple rounded progress bar with no waveform.
432
- * Renders a pill-shaped background track, a glowing pill-shaped filled portion
433
- * (clamped to at least one full pill width so it never collapses), and a draggable
434
- * circular handle/thumb at the playhead with a drop shadow and inner accent dot.
452
+ * Renders a pill-shaped background track, a clean pill-shaped filled portion
453
+ * (clamped to at least one full pill width so it never collapses), and a
454
+ * draggable circular handle/thumb at the playhead (clamped so it never clips
455
+ * at the track ends).
435
456
  * The `peaks` argument is accepted for signature parity but is unused by this style.
436
457
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
437
458
  * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
@@ -446,54 +467,34 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
446
467
  const centerY = height / 2;
447
468
  const barHeight = 4; // Height of the seekbar in pixels
448
469
  const borderRadius = barHeight / 2;
470
+ const active = !!options.seekActive; // hovering or dragging the seekbar
449
471
 
450
472
  ctx.clearRect(0, 0, width, height);
451
473
 
452
474
  // Draw background track
453
- ctx.fillStyle = options.color || 'rgba(255, 255, 255, 0.2)';
475
+ ctx.fillStyle = makeFill(ctx, options.color, canvas, options) || 'rgba(255, 255, 255, 0.2)';
454
476
 
455
477
  // Rounded background track
456
478
  capsulePath(ctx, borderRadius, width, centerY, barHeight);
457
479
  ctx.fill();
458
480
 
459
- // Draw progress
481
+ // Draw progress — slightly dimmed at rest, full-bright on hover / drag.
482
+ // With a monochrome palette there's no hue to swap (Spotify goes
483
+ // white→green), so the hover cue is a brightness lift plus the handle
484
+ // appearing. The draggable handle is a DOM element
485
+ // (`.waveform-seek-handle`), not drawn here — so it's always a perfect
486
+ // circle and can grow on direct hover via CSS.
460
487
  if (progress > 0) {
461
488
  const progressWidth = Math.max(borderRadius * 2, progress * width);
462
489
 
463
- // Add subtle glow effect
464
- ctx.shadowBlur = 8;
465
- ctx.shadowColor = options.progressColor;
466
-
467
- ctx.fillStyle = options.progressColor || 'rgba(255, 255, 255, 0.9)';
468
-
469
- // Rounded progress fill
490
+ // Brightness lift on hover/drag is only meaningful when the handle is
491
+ // enabled (the bar); a standalone seekbar stays at full progress.
492
+ ctx.save();
493
+ ctx.globalAlpha = options.seekHandle && !active ? 0.7 : 1;
494
+ ctx.fillStyle = makeFill(ctx, options.progressColor, canvas, options) || 'rgba(255, 255, 255, 0.9)';
470
495
  capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
471
496
  ctx.fill();
472
-
473
- ctx.shadowBlur = 0;
474
-
475
- // Draw progress handle/thumb
476
- const handleRadius = 8;
477
- const handleX = progressWidth;
478
-
479
- // Handle shadow
480
- ctx.shadowBlur = 4;
481
- ctx.shadowColor = 'rgba(0, 0, 0, 0.3)';
482
- ctx.shadowOffsetY = 2;
483
-
484
- // Handle circle
485
- ctx.fillStyle = '#ffffff';
486
- ctx.beginPath();
487
- ctx.arc(handleX, centerY, handleRadius, 0, Math.PI * 2);
488
- ctx.fill();
489
-
490
- // Handle inner circle (for depth)
491
- ctx.shadowBlur = 0;
492
- ctx.shadowOffsetY = 0;
493
- ctx.fillStyle = options.progressColor || 'rgba(255, 255, 255, 0.9)';
494
- ctx.beginPath();
495
- ctx.arc(handleX, centerY, handleRadius * 0.4, 0, Math.PI * 2);
496
- ctx.fill();
497
+ ctx.restore();
497
498
  }
498
499
  }
499
500
 
package/src/js/themes.js CHANGED
@@ -3,7 +3,7 @@
3
3
  * @description Color presets and default options for WaveformPlayer
4
4
  */
5
5
 
6
- import {perceivedBrightness} from './utils.js';
6
+ import {perceivedBrightness, DEFAULT_SAMPLES} from './utils.js';
7
7
 
8
8
  /**
9
9
  * Does `<html>` or `<body>` explicitly signal the given colour scheme via a
@@ -93,23 +93,11 @@ export function detectColorScheme() {
93
93
  export const COLOR_PRESETS = {
94
94
  dark: {
95
95
  waveformColor: 'rgba(255, 255, 255, 0.3)',
96
- progressColor: 'rgba(255, 255, 255, 0.9)',
97
- buttonColor: 'rgba(255, 255, 255, 0.9)',
98
- buttonHoverColor: 'rgba(255, 255, 255, 1)',
99
- textColor: '#ffffff',
100
- textSecondaryColor: 'rgba(255, 255, 255, 0.6)',
101
- backgroundColor: 'rgba(255, 255, 255, 0.03)',
102
- borderColor: 'rgba(255, 255, 255, 0.1)'
96
+ progressColor: 'rgba(255, 255, 255, 0.9)'
103
97
  },
104
98
  light: {
105
99
  waveformColor: 'rgba(0, 0, 0, 0.2)',
106
- progressColor: 'rgba(0, 0, 0, 0.8)',
107
- buttonColor: 'rgba(0, 0, 0, 0.8)',
108
- buttonHoverColor: 'rgba(0, 0, 0, 0.9)',
109
- textColor: '#333333',
110
- textSecondaryColor: 'rgba(0, 0, 0, 0.6)',
111
- backgroundColor: 'rgba(0, 0, 0, 0.02)',
112
- borderColor: 'rgba(0, 0, 0, 0.1)'
100
+ progressColor: 'rgba(0, 0, 0, 0.8)'
113
101
  }
114
102
  };
115
103
 
@@ -157,7 +145,7 @@ export const DEFAULT_OPTIONS = {
157
145
  // bars, so this is fidelity headroom, not the visible bar count. 1800 (the
158
146
  // SoundCloud/WaveformGen figure) keeps wide / high-DPI waveforms crisp; the
159
147
  // every-frame scan means a higher value costs no extra extraction time.
160
- samples: 1800,
148
+ samples: DEFAULT_SAMPLES,
161
149
  preload: 'metadata',
162
150
 
163
151
  // Audio mode — 'self' = player owns the <audio> element (default, current
@@ -196,18 +184,20 @@ export const DEFAULT_OPTIONS = {
196
184
  // Rounded bar caps (px). 0 = square; 1 = soft caps (default). Applies to bars/mirror.
197
185
  barRadius: 1,
198
186
 
187
+ // Gradient axis when waveformColor/progressColor is an array of stops:
188
+ // 'vertical' (top->bottom canvas gradient), 'horizontal' (hue sweep across the
189
+ // waveform) or 'diagonal'. Ignored for single colours.
190
+ waveformGradient: 'vertical',
191
+
199
192
  // Color preset: null = auto-detect, 'dark' = force dark, 'light' = force light
200
193
  colorPreset: null,
201
194
 
202
- // Individual color overrides (null means use preset)
195
+ // Canvas colours (null = inherit the resolved preset; arrays = gradient
196
+ // stops, see waveformGradient). The DOM chrome (button, title, meta) is
197
+ // themed via CSS variables (--wfp-button-color / --wfp-text-color /
198
+ // --wfp-text-secondary-color), not JS options.
203
199
  waveformColor: null,
204
200
  progressColor: null,
205
- buttonColor: null,
206
- buttonHoverColor: null,
207
- textColor: null,
208
- textSecondaryColor: null,
209
- backgroundColor: null,
210
- borderColor: null,
211
201
 
212
202
  // Features
213
203
  autoplay: false,
@@ -215,6 +205,11 @@ export const DEFAULT_OPTIONS = {
215
205
  showInfo: true,
216
206
  showTime: true,
217
207
  showHoverTime: false,
208
+ // Show a draggable circle handle + hover brightness-lift on the SEEKBAR
209
+ // style only (it's meaningless on a waveform, where the fill-edge is the
210
+ // playhead). Off by default; the bar turns it on. Drag-to-scrub works
211
+ // regardless of this.
212
+ seekHandle: false,
218
213
  showBPM: false,
219
214
  // Known BPM to display in the badge (with showBPM). Wins over auto-detection
220
215
  // — set it when peaks are pre-generated so the tempo still shows. null = auto.
@@ -236,7 +231,7 @@ export const DEFAULT_OPTIONS = {
236
231
 
237
232
  // Content
238
233
  title: null,
239
- subtitle: null,
234
+ artist: null,
240
235
  artwork: null,
241
236
  album: '',
242
237
 
package/src/js/utils.js CHANGED
@@ -3,6 +3,30 @@
3
3
  * @description Utility functions for WaveformPlayer
4
4
  */
5
5
 
6
+ /**
7
+ * Default number of peak windows extracted per track. Shared by the runtime
8
+ * peak extraction and `DEFAULT_OPTIONS.samples` so they can't silently drift,
9
+ * and matched to @arraypress/waveform-gen's offline default (1800) for parity.
10
+ * @type {number}
11
+ */
12
+ export const DEFAULT_SAMPLES = 1800;
13
+
14
+ /**
15
+ * Largest value in an array, via a loop — NOT `Math.max(...arr)`, whose
16
+ * argument spread throws `RangeError: Maximum call stack size exceeded` for
17
+ * very large arrays (~1e5+ entries). Returns `-Infinity` for an empty array,
18
+ * matching `Math.max()`.
19
+ * @param {number[]} values - Numbers to scan.
20
+ * @returns {number} The maximum value (`-Infinity` if empty).
21
+ */
22
+ export function maxOf(values) {
23
+ let max = -Infinity;
24
+ for (let i = 0; i < values.length; i++) {
25
+ if (values[i] > max) max = values[i];
26
+ }
27
+ return max;
28
+ }
29
+
6
30
  /**
7
31
  * Escape a string for safe interpolation into HTML, preventing injection when
8
32
  * building markup with template strings. `null`/`undefined` become `''`.
@@ -133,6 +157,7 @@ export function parseDataAttributes(element) {
133
157
  // `data-waveform-style`; the canonical long form wins if both are set.
134
158
  if (element.dataset.style) options.waveformStyle = element.dataset.style;
135
159
  if (element.dataset.waveformStyle) options.waveformStyle = element.dataset.waveformStyle;
160
+ if (element.dataset.waveformGradient) options.waveformGradient = element.dataset.waveformGradient;
136
161
  setNum('barWidth');
137
162
  setNum('barSpacing');
138
163
  setNum('barRadius');
@@ -152,12 +177,6 @@ export function parseDataAttributes(element) {
152
177
  // Individual color customization
153
178
  if (element.dataset.waveformColor) options.waveformColor = parseColorValue(element.dataset.waveformColor);
154
179
  if (element.dataset.progressColor) options.progressColor = parseColorValue(element.dataset.progressColor);
155
- if (element.dataset.buttonColor) options.buttonColor = element.dataset.buttonColor;
156
- if (element.dataset.buttonHoverColor) options.buttonHoverColor = element.dataset.buttonHoverColor;
157
- if (element.dataset.textColor) options.textColor = element.dataset.textColor;
158
- if (element.dataset.textSecondaryColor) options.textSecondaryColor = element.dataset.textSecondaryColor;
159
- if (element.dataset.backgroundColor) options.backgroundColor = element.dataset.backgroundColor;
160
- if (element.dataset.borderColor) options.borderColor = element.dataset.borderColor;
161
180
 
162
181
  // Legacy support for old attribute names
163
182
  if (element.dataset.color) options.waveformColor = element.dataset.color;
@@ -169,6 +188,7 @@ export function parseDataAttributes(element) {
169
188
  setBool('showInfo');
170
189
  setBool('showTime');
171
190
  setBool('showHoverTime');
191
+ setBool('seekHandle');
172
192
  setBool('showBPM', 'showBpm');
173
193
  setNum('bpm');
174
194
  setBool('singlePlay');
@@ -176,7 +196,7 @@ export function parseDataAttributes(element) {
176
196
 
177
197
  // Content and metadata
178
198
  if (element.dataset.title) options.title = element.dataset.title;
179
- if (element.dataset.subtitle) options.subtitle = element.dataset.subtitle;
199
+ if (element.dataset.artist) options.artist = element.dataset.artist;
180
200
  if (element.dataset.album) options.album = element.dataset.album;
181
201
  if (element.dataset.artwork) options.artwork = element.dataset.artwork;
182
202