@arraypress/waveform-player 1.16.1 → 1.17.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/index.d.ts CHANGED
@@ -155,6 +155,8 @@ export interface WaveformPlayerOptions {
155
155
  showTime?: boolean;
156
156
  /** Show a time tooltip on hover. @default false */
157
157
  showHoverTime?: boolean;
158
+ /** Show a draggable circle handle + hover brightness on the seekbar style (hover/drag); the bar enables it. Drag-to-scrub works regardless. @default false */
159
+ seekHandle?: boolean;
158
160
  /** Show detected BPM. @default false */
159
161
  showBPM?: boolean;
160
162
  /** Known BPM shown in the badge (with `showBPM`); wins over auto-detection. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.16.1",
3
+ "version": "1.17.0",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
@@ -296,6 +296,32 @@
296
296
  z-index: 1000;
297
297
  }
298
298
 
299
+ /* Draggable seek handle — a DOM circle over the playhead, shown only on
300
+ hover / drag, that grows on direct hover / while dragging. A DOM element
301
+ (not canvas-drawn) so it's always a perfect circle and animates smoothly. */
302
+ .waveform-seek-handle {
303
+ position: absolute;
304
+ top: 50%;
305
+ left: 0;
306
+ width: 11px;
307
+ height: 11px;
308
+ border-radius: 50%;
309
+ background: #fff;
310
+ box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35);
311
+ transform: translate(-50%, -50%) scale(0);
312
+ opacity: 0;
313
+ transition: opacity 0.12s ease, transform 0.12s ease;
314
+ pointer-events: none;
315
+ z-index: 6;
316
+ }
317
+ .waveform-seek-handle.is-visible {
318
+ opacity: 1;
319
+ transform: translate(-50%, -50%) scale(1);
320
+ }
321
+ .waveform-seek-handle.is-active {
322
+ transform: translate(-50%, -50%) scale(1.25);
323
+ }
324
+
299
325
  /* Focus styles for accessibility */
300
326
  .waveform-btn:focus-visible {
301
327
  outline: 2px solid currentColor;
package/src/js/audio.js CHANGED
@@ -4,7 +4,7 @@
4
4
  */
5
5
 
6
6
  import {detectBPM} from './bpm.js';
7
- import {clamp} from './utils.js';
7
+ import {clamp, maxOf, DEFAULT_SAMPLES} from './utils.js';
8
8
 
9
9
  /**
10
10
  * Extract peaks from a decoded audio buffer for waveform visualization.
@@ -18,10 +18,10 @@ import {clamp} from './utils.js';
18
18
  * returned unscaled).
19
19
  *
20
20
  * @param {AudioBuffer} buffer - Decoded audio buffer to analyse.
21
- * @param {number} [samples=200] - Number of peak windows (output array length).
21
+ * @param {number} [samples=1800] - Number of peak windows (output array length).
22
22
  * @returns {number[]} Array of `samples` normalized peak values in the 0-1 range.
23
23
  */
24
- export function extractPeaks(buffer, samples = 200) {
24
+ export function extractPeaks(buffer, samples = DEFAULT_SAMPLES) {
25
25
  const sampleSize = buffer.length / samples;
26
26
  const channels = buffer.numberOfChannels;
27
27
  const peaks = [];
@@ -56,7 +56,7 @@ export function extractPeaks(buffer, samples = 200) {
56
56
  }
57
57
 
58
58
  // Normalize peaks
59
- const maxPeak = Math.max(...peaks);
59
+ const maxPeak = maxOf(peaks);
60
60
  return maxPeak > 0 ? peaks.map(peak => peak / maxPeak) : peaks;
61
61
  }
62
62
 
@@ -71,13 +71,13 @@ export function extractPeaks(buffer, samples = 200) {
71
71
  * callers can fall back to a placeholder waveform.
72
72
  *
73
73
  * @param {string} url - Audio file URL to fetch and decode.
74
- * @param {number} [samples=200] - Number of peak windows to extract.
74
+ * @param {number} [samples=1800] - Number of peak windows to extract.
75
75
  * @param {boolean} [shouldDetectBPM=false] - Whether to run BPM detection on the decoded buffer.
76
76
  * @returns {Promise<{peaks: number[], bpm: (number|null)}>} Resolves with the
77
77
  * normalized peaks and the detected BPM (`null` when detection is disabled or fails).
78
78
  * @throws {Error} Re-throws any fetch/decode error after logging it.
79
79
  */
80
- export async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
80
+ export async function generateWaveform(url, samples = DEFAULT_SAMPLES, shouldDetectBPM = false) {
81
81
  // Created lazily so the finally block can always close it — browsers
82
82
  // hard-cap live AudioContexts (~6 in Chrome), so leaking one per failed
83
83
  // decode would break every subsequent player on the page.
@@ -115,10 +115,10 @@ export async function generateWaveform(url, samples = 200, shouldDetectBPM = fal
115
115
  * variation across the array, clamped to the 0.1-1 range so the result always
116
116
  * looks like a plausible waveform rather than pure noise.
117
117
  *
118
- * @param {number} [samples=200] - Number of bars (output array length).
118
+ * @param {number} [samples=1800] - Number of bars (output array length).
119
119
  * @returns {number[]} Array of `samples` pseudo-random peak values in the 0.1-1 range.
120
120
  */
121
- export function generatePlaceholderWaveform(samples = 200) {
121
+ export function generatePlaceholderWaveform(samples = DEFAULT_SAMPLES) {
122
122
  const data = [];
123
123
  for (let i = 0; i < samples; i++) {
124
124
  const base = Math.random() * 0.5 + 0.3;
@@ -142,7 +142,7 @@ export function generatePlaceholderWaveform(samples = 200) {
142
142
  * @private
143
143
  */
144
144
  function normalizePeaks(peaks, targetMax = 0.95) {
145
- const maxPeak = Math.max(...peaks);
145
+ const maxPeak = maxOf(peaks);
146
146
 
147
147
  // Don't normalize if already loud enough or silent
148
148
  if (maxPeak === 0 || maxPeak > targetMax) return peaks;
package/src/js/core.js CHANGED
@@ -13,7 +13,8 @@ import {
13
13
  mergeOptions,
14
14
  debounce,
15
15
  clamp,
16
- escapeHtml
16
+ escapeHtml,
17
+ DEFAULT_SAMPLES
17
18
  } from './utils.js';
18
19
 
19
20
  import {DEFAULT_OPTIONS, STYLE_DEFAULTS, getColorPreset, COLOR_PRESETS} from './themes.js';
@@ -31,6 +32,12 @@ const ARTWORK_FALLBACK = 'data:image/svg+xml,' + encodeURIComponent(
31
32
  const SEEK_STEP_SECONDS = 5;
32
33
  const SEEK_PAGE_SECONDS = 10;
33
34
 
35
+ // Controls that own their own focus. A click landing on one of these (or a
36
+ // descendant) must leave focus on the control, not pull it onto the player
37
+ // container — otherwise activating the play button/slider steals focus onto the
38
+ // wrapper, moving it off the control the user just operated.
39
+ const INTERACTIVE_ELEMENTS = 'button, a[href], input, [role="slider"]';
40
+
34
41
  /**
35
42
  * WaveformPlayer - Modern audio player with waveform visualization
36
43
  * @class
@@ -288,7 +295,7 @@ export class WaveformPlayer {
288
295
  ` : ''}
289
296
  ${this.options.showPlaybackSpeed ? `
290
297
  <div class="waveform-speed">
291
- <button class="speed-btn" aria-label="Playback speed">
298
+ <button class="speed-btn" aria-label="Playback speed" aria-haspopup="true" aria-expanded="false">
292
299
  <span class="speed-value">1x</span>
293
300
  </button>
294
301
  <div class="speed-menu" style="display: none;">
@@ -407,8 +414,9 @@ export class WaveformPlayer {
407
414
 
408
415
  /**
409
416
  * Wire up the playback-speed menu: toggle it open on the speed button,
410
- * close it on any outside click, and apply the chosen rate when a
411
- * `.speed-option` is clicked. All listeners are registered against the
417
+ * close it on outside click or Escape (keeping `aria-expanded` on the
418
+ * trigger in sync), and apply the chosen rate when a `.speed-option` is
419
+ * clicked, returning focus to the trigger. All listeners are registered against the
412
420
  * instance `AbortController` signal so {@link WaveformPlayer#destroy} tears
413
421
  * them down. No-op if the speed elements are absent.
414
422
  * @private
@@ -419,24 +427,40 @@ export class WaveformPlayer {
419
427
 
420
428
  if (!speedBtn || !speedMenu) return;
421
429
 
430
+ // Open/close the menu, keeping aria-expanded on the trigger in sync so
431
+ // assistive tech announces the state. This is a disclosure, not a full
432
+ // ARIA menu — the options stay plain buttons in the tab order.
433
+ const setSpeedMenu = (open) => {
434
+ speedMenu.style.display = open ? 'block' : 'none';
435
+ speedBtn.setAttribute('aria-expanded', open ? 'true' : 'false');
436
+ };
437
+
422
438
  // Toggle menu
423
439
  speedBtn.addEventListener('click', (e) => {
424
440
  e.stopPropagation();
425
- speedMenu.style.display = speedMenu.style.display === 'none' ? 'block' : 'none';
441
+ setSpeedMenu(speedMenu.style.display === 'none');
426
442
  }, {signal: this._ac.signal});
427
443
 
428
444
  // Close menu when clicking outside
429
- document.addEventListener('click', () => {
430
- speedMenu.style.display = 'none';
431
- }, {signal: this._ac.signal});
445
+ document.addEventListener('click', () => setSpeedMenu(false), {signal: this._ac.signal});
432
446
 
433
- // Handle speed selection
447
+ // Handle speed selection — apply the rate, close, and return focus to
448
+ // the trigger.
434
449
  speedMenu.addEventListener('click', (e) => {
435
450
  e.stopPropagation();
436
451
  if (e.target.classList.contains('speed-option')) {
437
- const rate = parseFloat(e.target.dataset.rate);
438
- this.setPlaybackRate(rate);
439
- speedMenu.style.display = 'none';
452
+ this.setPlaybackRate(parseFloat(e.target.dataset.rate));
453
+ setSpeedMenu(false);
454
+ speedBtn.focus();
455
+ }
456
+ }, {signal: this._ac.signal});
457
+
458
+ // Escape closes the menu and restores focus to the trigger, whether
459
+ // focus is on the button or one of the options.
460
+ speedBtn.closest('.waveform-speed')?.addEventListener('keydown', (e) => {
461
+ if (e.key === 'Escape' && speedMenu.style.display !== 'none') {
462
+ setSpeedMenu(false);
463
+ speedBtn.focus();
440
464
  }
441
465
  }, {signal: this._ac.signal});
442
466
 
@@ -459,8 +483,12 @@ export class WaveformPlayer {
459
483
  // Make container focusable but not in tab order by default
460
484
  this.container.setAttribute('tabindex', '-1');
461
485
 
462
- // Only activate keyboard controls when explicitly focused (clicked)
463
- this.container.addEventListener('click', () => {
486
+ // Only activate keyboard controls when explicitly focused (clicked).
487
+ // Skip when the click landed on an interactive control (play button,
488
+ // link, slider, input): those own their focus, so pulling it onto the
489
+ // container would move focus off the control the user just activated.
490
+ this.container.addEventListener('click', (e) => {
491
+ if (e.target.closest(INTERACTIVE_ELEMENTS)) return;
464
492
  // Remove focus from all other players
465
493
  WaveformPlayer.getAllInstances().forEach(player => {
466
494
  if (player !== this) {
@@ -729,13 +757,70 @@ export class WaveformPlayer {
729
757
  this.audio.addEventListener('error', (e) => this.onError(e));
730
758
  }
731
759
 
732
- // Canvas interactions — seek-on-click. In external mode the
733
- // canvas click dispatches a `waveformplayer:request-seek` event
734
- // so the controller can position its own audio element.
760
+ // Canvas interactions — click + drag to seek. pointerdown starts a
761
+ // scrub (with pointer capture so moves keep flowing if the cursor
762
+ // leaves the canvas), pointermove updates it while held, pointerup /
763
+ // pointercancel end it. The click handler stays for keyboard/synthetic
764
+ // compatibility. In external mode each seek dispatches a cancelable
765
+ // `waveformplayer:request-seek` so the controller positions its audio.
735
766
  this.canvas.addEventListener('click', (e) => this.handleCanvasClick(e));
767
+ this._dragging = false;
768
+ this._seekHover = false;
769
+ this._handleNear = false;
770
+
771
+ // Hover state — reveals the handle + lifts the seekbar brightness. A
772
+ // redraw is needed because the canvas has no CSS :hover of its own.
773
+ this.canvas.addEventListener('pointerenter', () => {
774
+ this._seekHover = true;
775
+ this.drawWaveform();
776
+ this._updateSeekHandle();
777
+ });
778
+ this.canvas.addEventListener('pointerleave', () => {
779
+ this._seekHover = false;
780
+ this._handleNear = false;
781
+ if (!this._dragging) this._hideHoverTip();
782
+ this.drawWaveform();
783
+ this._updateSeekHandle();
784
+ });
785
+
786
+ // Drag = a VISUAL scrub: the playhead previews the cursor while the
787
+ // audio keeps playing untouched (a per-move seek glitches the audio and
788
+ // fights the progress loop). The real seek is committed once, on
789
+ // release. updateProgress() bails while _dragging so playback can't drag
790
+ // the handle off the cursor.
791
+ this.canvas.addEventListener('pointerdown', (e) => {
792
+ if (e.pointerType === 'mouse' && e.button !== 0) return; // primary / touch only
793
+ this._dragging = true;
794
+ try { this.canvas.setPointerCapture(e.pointerId); } catch (err) { /* unsupported */ }
795
+ this._scrubTo(e.clientX);
796
+ });
797
+ this.canvas.addEventListener('pointermove', (e) => {
798
+ if (this._dragging) {
799
+ this._scrubTo(e.clientX);
800
+ return;
801
+ }
802
+ // Hover (not dragging): grow the handle when the cursor is over it.
803
+ const rect = this.canvas.getBoundingClientRect();
804
+ if (rect.width) {
805
+ this._handleNear = Math.abs((e.clientX - rect.left) - this.progress * rect.width) <= 10;
806
+ this._updateSeekHandle();
807
+ }
808
+ });
809
+ const endDrag = (e) => {
810
+ if (!this._dragging) return;
811
+ this._dragging = false;
812
+ try { this.canvas.releasePointerCapture(e.pointerId); } catch (err) { /* ignore */ }
813
+ this._seekFromPointer(e.clientX); // commit the seek now — audio jumps once
814
+ if (!this._seekHover) this._hideHoverTip();
815
+ this._updateSeekHandle();
816
+ };
817
+ this.canvas.addEventListener('pointerup', endDrag);
818
+ this.canvas.addEventListener('pointercancel', endDrag);
736
819
 
737
820
  // Hover-time tooltip over the waveform (when showHoverTime is on).
738
821
  this.setupHoverTime();
822
+ // Draggable seek handle (DOM circle, shown on hover / drag).
823
+ this.setupSeekHandle();
739
824
 
740
825
  // Window resize - store handler for cleanup
741
826
  this.resizeHandler = debounce(() => this.resizeCanvas(), 100);
@@ -1008,7 +1093,8 @@ export class WaveformPlayer {
1008
1093
  ...this.options,
1009
1094
  waveformStyle: this.options.waveformStyle || 'bars',
1010
1095
  color: this.options.waveformColor,
1011
- progressColor: this.options.progressColor
1096
+ progressColor: this.options.progressColor,
1097
+ seekActive: this._seekHover || this._dragging
1012
1098
  });
1013
1099
  }
1014
1100
 
@@ -1168,16 +1254,86 @@ export class WaveformPlayer {
1168
1254
  this.seekEl.appendChild(tip);
1169
1255
  this.hoverTimeEl = tip;
1170
1256
 
1257
+ // Hover updates the tip; the drag handlers also call _updateHoverTip so
1258
+ // the time follows the playhead while scrubbing (Spotify-style). The
1259
+ // guard avoids a double-update when a drag is in progress (the canvas
1260
+ // pointermove already drives it then).
1171
1261
  this.seekEl.addEventListener('pointermove', (e) => {
1172
- const dur = this.getSeekDuration();
1173
- if (!dur) { tip.style.opacity = '0'; return; }
1174
- const rect = this.canvas.getBoundingClientRect();
1175
- const pct = clamp((e.clientX - rect.left) / rect.width);
1176
- tip.textContent = formatTime(pct * dur);
1177
- tip.style.left = (pct * 100) + '%';
1178
- tip.style.opacity = '1';
1262
+ if (!this._dragging) this._updateHoverTip(e.clientX);
1263
+ });
1264
+ this.seekEl.addEventListener('pointerleave', () => {
1265
+ if (!this._dragging) this._hideHoverTip();
1179
1266
  });
1180
- this.seekEl.addEventListener('pointerleave', () => { tip.style.opacity = '0'; });
1267
+ }
1268
+
1269
+ /**
1270
+ * Position + fill the hover-time tooltip for a given client-X. Shared by
1271
+ * hover and drag-scrub. No-op when the tooltip isn't enabled
1272
+ * (`showHoverTime` off).
1273
+ * @param {number} clientX - Pointer client-X coordinate.
1274
+ * @private
1275
+ */
1276
+ _updateHoverTip(clientX) {
1277
+ const tip = this.hoverTimeEl;
1278
+ if (!tip) return;
1279
+ const dur = this.getSeekDuration();
1280
+ if (!dur) { tip.style.opacity = '0'; return; }
1281
+ const rect = this.canvas.getBoundingClientRect();
1282
+ const pct = clamp((clientX - rect.left) / rect.width);
1283
+ tip.textContent = formatTime(pct * dur);
1284
+ tip.style.left = (pct * 100) + '%';
1285
+ tip.style.opacity = '1';
1286
+ }
1287
+
1288
+ /** Hide the hover-time tooltip. @private */
1289
+ _hideHoverTip() {
1290
+ if (this.hoverTimeEl) this.hoverTimeEl.style.opacity = '0';
1291
+ }
1292
+
1293
+ /**
1294
+ * Visually preview a seek during a drag — moves the playhead + handle +
1295
+ * tooltip to the cursor WITHOUT touching the audio (playback continues; the
1296
+ * real seek is committed on release).
1297
+ * @param {number} clientX - Pointer client-X coordinate.
1298
+ * @private
1299
+ */
1300
+ _scrubTo(clientX) {
1301
+ const rect = this.canvas.getBoundingClientRect();
1302
+ if (!rect.width) return;
1303
+ this.progress = clamp((clientX - rect.left) / rect.width);
1304
+ this.drawWaveform();
1305
+ this._updateSeekHandle();
1306
+ this._updateHoverTip(clientX);
1307
+ }
1308
+
1309
+ /**
1310
+ * Create the draggable seek handle — a DOM circle over the playhead, shown
1311
+ * only on hover / drag (Spotify-style). Pointer-events are off so it never
1312
+ * blocks the canvas scrub; size + visibility are CSS.
1313
+ * @private
1314
+ */
1315
+ setupSeekHandle() {
1316
+ // Only the seekbar style — on a real waveform the fill-edge already is
1317
+ // the playhead, so a floating dot is just noise.
1318
+ if (!this.options.seekHandle || this.options.waveformStyle !== 'seekbar' || !this.seekEl) return;
1319
+ const h = document.createElement('div');
1320
+ h.className = 'waveform-seek-handle';
1321
+ h.setAttribute('aria-hidden', 'true');
1322
+ this.seekEl.appendChild(h);
1323
+ this.seekHandleEl = h;
1324
+ }
1325
+
1326
+ /**
1327
+ * Position the seek handle at the current progress and toggle its
1328
+ * visibility (hover / drag) + expanded (drag / direct-hover) classes.
1329
+ * @private
1330
+ */
1331
+ _updateSeekHandle() {
1332
+ const h = this.seekHandleEl;
1333
+ if (!h) return;
1334
+ h.style.left = (this.progress * 100) + '%';
1335
+ h.classList.toggle('is-visible', this._seekHover || this._dragging);
1336
+ h.classList.toggle('is-active', this._dragging || this._handleNear);
1181
1337
  }
1182
1338
 
1183
1339
  // ============================================
@@ -1197,15 +1353,24 @@ export class WaveformPlayer {
1197
1353
  * @fires WaveformPlayer#waveformplayer:request-seek
1198
1354
  */
1199
1355
  handleCanvasClick(event) {
1200
- // In external mode the player has no audio of its own —
1201
- // dispatch a cancelable `waveformplayer:request-seek` event
1202
- // with the target percentage so the controller can seek its
1203
- // own audio. Locally we just update the visual progress so
1204
- // the canvas paints the new position immediately (the
1205
- // controller's progress event will reconcile shortly after).
1356
+ this._seekFromPointer(event.clientX);
1357
+ }
1358
+
1359
+ /**
1360
+ * Seek to a horizontal client-X position over the canvas — shared by
1361
+ * click and drag. In external mode the player has no audio of its own,
1362
+ * so it dispatches a cancelable `waveformplayer:request-seek` with the
1363
+ * target percentage (updating the local visual optimistically); in self
1364
+ * mode it seeks the owned `<audio>` via
1365
+ * {@link WaveformPlayer#seekToPercent}.
1366
+ * @param {number} clientX - Pointer client-X coordinate.
1367
+ * @private
1368
+ * @fires WaveformPlayer#waveformplayer:request-seek
1369
+ */
1370
+ _seekFromPointer(clientX) {
1206
1371
  const rect = this.canvas.getBoundingClientRect();
1207
- const x = event.clientX - rect.left;
1208
- const targetPercent = clamp(x / rect.width);
1372
+ if (!rect.width) return;
1373
+ const targetPercent = clamp((clientX - rect.left) / rect.width);
1209
1374
 
1210
1375
  if (this.options.audioMode === 'external') {
1211
1376
  this._requestSeek(targetPercent);
@@ -1442,12 +1607,16 @@ export class WaveformPlayer {
1442
1607
  // Self-mode only — external mode receives progress via
1443
1608
  // setProgress() from the controller and never calls this.
1444
1609
  if (!this.audio || !this.audio.duration) return;
1610
+ // While dragging, the playhead previews the cursor — don't let playback
1611
+ // move it (the audio keeps playing; the seek commits on release).
1612
+ if (this._dragging) return;
1445
1613
 
1446
1614
  const newProgress = this.audio.currentTime / this.audio.duration;
1447
1615
 
1448
1616
  if (Math.abs(newProgress - this.progress) > 0.001) {
1449
1617
  this.progress = newProgress;
1450
1618
  this.drawWaveform();
1619
+ this._updateSeekHandle();
1451
1620
  }
1452
1621
 
1453
1622
  if (this.currentTimeEl) {
@@ -1937,7 +2106,7 @@ export class WaveformPlayer {
1937
2106
  * @param {number} samples - Number of samples
1938
2107
  * @returns {Promise<number[]>} Waveform peak data
1939
2108
  */
1940
- static async generateWaveformData(url, samples = 200) {
2109
+ static async generateWaveformData(url, samples = DEFAULT_SAMPLES) {
1941
2110
  try {
1942
2111
  const result = await generateWaveform(url, samples);
1943
2112
  return result.peaks;
package/src/js/drawing.js CHANGED
@@ -429,9 +429,10 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
429
429
 
430
430
  /**
431
431
  * 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.
432
+ * Renders a pill-shaped background track, a clean pill-shaped filled portion
433
+ * (clamped to at least one full pill width so it never collapses), and a
434
+ * draggable circular handle/thumb at the playhead (clamped so it never clips
435
+ * at the track ends).
435
436
  * The `peaks` argument is accepted for signature parity but is unused by this style.
436
437
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
437
438
  * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
@@ -446,6 +447,7 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
446
447
  const centerY = height / 2;
447
448
  const barHeight = 4; // Height of the seekbar in pixels
448
449
  const borderRadius = barHeight / 2;
450
+ const active = !!options.seekActive; // hovering or dragging the seekbar
449
451
 
450
452
  ctx.clearRect(0, 0, width, height);
451
453
 
@@ -456,44 +458,23 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
456
458
  capsulePath(ctx, borderRadius, width, centerY, barHeight);
457
459
  ctx.fill();
458
460
 
459
- // Draw progress
461
+ // Draw progress — slightly dimmed at rest, full-bright on hover / drag.
462
+ // With a monochrome palette there's no hue to swap (Spotify goes
463
+ // white→green), so the hover cue is a brightness lift plus the handle
464
+ // appearing. The draggable handle is a DOM element
465
+ // (`.waveform-seek-handle`), not drawn here — so it's always a perfect
466
+ // circle and can grow on direct hover via CSS.
460
467
  if (progress > 0) {
461
468
  const progressWidth = Math.max(borderRadius * 2, progress * width);
462
469
 
463
- // Add subtle glow effect
464
- ctx.shadowBlur = 8;
465
- ctx.shadowColor = options.progressColor;
466
-
470
+ // Brightness lift on hover/drag is only meaningful when the handle is
471
+ // enabled (the bar); a standalone seekbar stays at full progress.
472
+ ctx.save();
473
+ ctx.globalAlpha = options.seekHandle && !active ? 0.7 : 1;
467
474
  ctx.fillStyle = options.progressColor || 'rgba(255, 255, 255, 0.9)';
468
-
469
- // Rounded progress fill
470
475
  capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
471
476
  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();
477
+ ctx.restore();
497
478
  }
498
479
  }
499
480
 
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
@@ -157,7 +157,7 @@ export const DEFAULT_OPTIONS = {
157
157
  // bars, so this is fidelity headroom, not the visible bar count. 1800 (the
158
158
  // SoundCloud/WaveformGen figure) keeps wide / high-DPI waveforms crisp; the
159
159
  // every-frame scan means a higher value costs no extra extraction time.
160
- samples: 1800,
160
+ samples: DEFAULT_SAMPLES,
161
161
  preload: 'metadata',
162
162
 
163
163
  // Audio mode — 'self' = player owns the <audio> element (default, current
@@ -215,6 +215,11 @@ export const DEFAULT_OPTIONS = {
215
215
  showInfo: true,
216
216
  showTime: true,
217
217
  showHoverTime: false,
218
+ // Show a draggable circle handle + hover brightness-lift on the SEEKBAR
219
+ // style only (it's meaningless on a waveform, where the fill-edge is the
220
+ // playhead). Off by default; the bar turns it on. Drag-to-scrub works
221
+ // regardless of this.
222
+ seekHandle: false,
218
223
  showBPM: false,
219
224
  // Known BPM to display in the badge (with showBPM). Wins over auto-detection
220
225
  // — set it when peaks are pre-generated so the tempo still shows. null = auto.
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 `''`.
@@ -169,6 +193,7 @@ export function parseDataAttributes(element) {
169
193
  setBool('showInfo');
170
194
  setBool('showTime');
171
195
  setBool('showHoverTime');
196
+ setBool('seekHandle');
172
197
  setBool('showBPM', 'showBpm');
173
198
  setNum('bpm');
174
199
  setBool('singlePlay');