@arraypress/waveform-player 1.16.0 → 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/dist/waveform-player.cjs +194 -50
- package/dist/waveform-player.cjs.map +2 -2
- package/dist/waveform-player.css +1 -1
- package/dist/waveform-player.esm.js +7 -7
- package/dist/waveform-player.esm.js.map +3 -3
- package/dist/waveform-player.js +194 -50
- package/dist/waveform-player.min.js +7 -7
- package/dist/waveform-player.min.js.map +3 -3
- package/index.d.ts +2 -0
- package/package.json +1 -1
- package/src/css/waveform-player.css +32 -2
- package/src/js/audio.js +9 -9
- package/src/js/core.js +218 -35
- package/src/js/drawing.js +16 -35
- package/src/js/themes.js +7 -2
- package/src/js/utils.js +25 -0
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
|
@@ -268,8 +268,12 @@
|
|
|
268
268
|
opacity: 1;
|
|
269
269
|
}
|
|
270
270
|
|
|
271
|
-
/*
|
|
272
|
-
|
|
271
|
+
/* Briefly reveal the marker's label when the playhead reaches it. The player
|
|
272
|
+
adds `.show-label` on activation and removes it after ~2.5s, so the label
|
|
273
|
+
flashes then fades while the `.active` highlight stays. Override to taste —
|
|
274
|
+
e.g. `.waveform-marker.active .waveform-marker-tooltip { opacity: 1 }` to keep
|
|
275
|
+
it on, or `{ opacity: 0 !important }` to disable. */
|
|
276
|
+
.waveform-marker.show-label .waveform-marker-tooltip {
|
|
273
277
|
opacity: 1;
|
|
274
278
|
}
|
|
275
279
|
|
|
@@ -292,6 +296,32 @@
|
|
|
292
296
|
z-index: 1000;
|
|
293
297
|
}
|
|
294
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
|
+
|
|
295
325
|
/* Focus styles for accessibility */
|
|
296
326
|
.waveform-btn:focus-visible {
|
|
297
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=
|
|
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 =
|
|
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 =
|
|
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=
|
|
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 =
|
|
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=
|
|
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 =
|
|
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 =
|
|
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
|
|
@@ -116,6 +123,7 @@ export class WaveformPlayer {
|
|
|
116
123
|
this.waveformData = [];
|
|
117
124
|
this.progress = 0;
|
|
118
125
|
this._activeMarkerIndex = -1;
|
|
126
|
+
this._markerLabelTimer = null;
|
|
119
127
|
this.isPlaying = false;
|
|
120
128
|
this.isLoading = false;
|
|
121
129
|
this.hasError = false;
|
|
@@ -287,7 +295,7 @@ export class WaveformPlayer {
|
|
|
287
295
|
` : ''}
|
|
288
296
|
${this.options.showPlaybackSpeed ? `
|
|
289
297
|
<div class="waveform-speed">
|
|
290
|
-
<button class="speed-btn" aria-label="Playback speed">
|
|
298
|
+
<button class="speed-btn" aria-label="Playback speed" aria-haspopup="true" aria-expanded="false">
|
|
291
299
|
<span class="speed-value">1x</span>
|
|
292
300
|
</button>
|
|
293
301
|
<div class="speed-menu" style="display: none;">
|
|
@@ -406,8 +414,9 @@ export class WaveformPlayer {
|
|
|
406
414
|
|
|
407
415
|
/**
|
|
408
416
|
* Wire up the playback-speed menu: toggle it open on the speed button,
|
|
409
|
-
* close it on
|
|
410
|
-
*
|
|
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
|
|
411
420
|
* instance `AbortController` signal so {@link WaveformPlayer#destroy} tears
|
|
412
421
|
* them down. No-op if the speed elements are absent.
|
|
413
422
|
* @private
|
|
@@ -418,24 +427,40 @@ export class WaveformPlayer {
|
|
|
418
427
|
|
|
419
428
|
if (!speedBtn || !speedMenu) return;
|
|
420
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
|
+
|
|
421
438
|
// Toggle menu
|
|
422
439
|
speedBtn.addEventListener('click', (e) => {
|
|
423
440
|
e.stopPropagation();
|
|
424
|
-
speedMenu.style.display
|
|
441
|
+
setSpeedMenu(speedMenu.style.display === 'none');
|
|
425
442
|
}, {signal: this._ac.signal});
|
|
426
443
|
|
|
427
444
|
// Close menu when clicking outside
|
|
428
|
-
document.addEventListener('click', () => {
|
|
429
|
-
speedMenu.style.display = 'none';
|
|
430
|
-
}, {signal: this._ac.signal});
|
|
445
|
+
document.addEventListener('click', () => setSpeedMenu(false), {signal: this._ac.signal});
|
|
431
446
|
|
|
432
|
-
// Handle speed selection
|
|
447
|
+
// Handle speed selection — apply the rate, close, and return focus to
|
|
448
|
+
// the trigger.
|
|
433
449
|
speedMenu.addEventListener('click', (e) => {
|
|
434
450
|
e.stopPropagation();
|
|
435
451
|
if (e.target.classList.contains('speed-option')) {
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
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();
|
|
439
464
|
}
|
|
440
465
|
}, {signal: this._ac.signal});
|
|
441
466
|
|
|
@@ -458,8 +483,12 @@ export class WaveformPlayer {
|
|
|
458
483
|
// Make container focusable but not in tab order by default
|
|
459
484
|
this.container.setAttribute('tabindex', '-1');
|
|
460
485
|
|
|
461
|
-
// Only activate keyboard controls when explicitly focused (clicked)
|
|
462
|
-
|
|
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;
|
|
463
492
|
// Remove focus from all other players
|
|
464
493
|
WaveformPlayer.getAllInstances().forEach(player => {
|
|
465
494
|
if (player !== this) {
|
|
@@ -728,13 +757,70 @@ export class WaveformPlayer {
|
|
|
728
757
|
this.audio.addEventListener('error', (e) => this.onError(e));
|
|
729
758
|
}
|
|
730
759
|
|
|
731
|
-
// Canvas interactions — seek
|
|
732
|
-
//
|
|
733
|
-
//
|
|
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.
|
|
734
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);
|
|
735
819
|
|
|
736
820
|
// Hover-time tooltip over the waveform (when showHoverTime is on).
|
|
737
821
|
this.setupHoverTime();
|
|
822
|
+
// Draggable seek handle (DOM circle, shown on hover / drag).
|
|
823
|
+
this.setupSeekHandle();
|
|
738
824
|
|
|
739
825
|
// Window resize - store handler for cleanup
|
|
740
826
|
this.resizeHandler = debounce(() => this.resizeCanvas(), 100);
|
|
@@ -1007,7 +1093,8 @@ export class WaveformPlayer {
|
|
|
1007
1093
|
...this.options,
|
|
1008
1094
|
waveformStyle: this.options.waveformStyle || 'bars',
|
|
1009
1095
|
color: this.options.waveformColor,
|
|
1010
|
-
progressColor: this.options.progressColor
|
|
1096
|
+
progressColor: this.options.progressColor,
|
|
1097
|
+
seekActive: this._seekHover || this._dragging
|
|
1011
1098
|
});
|
|
1012
1099
|
}
|
|
1013
1100
|
|
|
@@ -1052,6 +1139,7 @@ export class WaveformPlayer {
|
|
|
1052
1139
|
this.markersContainer.innerHTML = '';
|
|
1053
1140
|
// Re-sync the active marker on the next progress tick (the DOM was wiped).
|
|
1054
1141
|
this._activeMarkerIndex = -1;
|
|
1142
|
+
clearTimeout(this._markerLabelTimer);
|
|
1055
1143
|
|
|
1056
1144
|
if (!this.options.showMarkers || !this.options.markers?.length) return;
|
|
1057
1145
|
|
|
@@ -1137,6 +1225,17 @@ export class WaveformPlayer {
|
|
|
1137
1225
|
if (active !== this._activeMarkerIndex) {
|
|
1138
1226
|
this._activeMarkerIndex = active;
|
|
1139
1227
|
this.setActiveMarker(active);
|
|
1228
|
+
// Flash the newly-active marker's label, then let it fade — the
|
|
1229
|
+
// highlight stays. Override via `.waveform-marker.show-label` CSS.
|
|
1230
|
+
clearTimeout(this._markerLabelTimer);
|
|
1231
|
+
els.forEach((el, i) => el.classList.toggle('show-label', i === active));
|
|
1232
|
+
if (active >= 0) {
|
|
1233
|
+
this._markerLabelTimer = setTimeout(() => {
|
|
1234
|
+
this.markersContainer
|
|
1235
|
+
?.querySelectorAll('.waveform-marker')
|
|
1236
|
+
.forEach((el) => el.classList.remove('show-label'));
|
|
1237
|
+
}, 2500);
|
|
1238
|
+
}
|
|
1140
1239
|
}
|
|
1141
1240
|
}
|
|
1142
1241
|
|
|
@@ -1155,16 +1254,86 @@ export class WaveformPlayer {
|
|
|
1155
1254
|
this.seekEl.appendChild(tip);
|
|
1156
1255
|
this.hoverTimeEl = tip;
|
|
1157
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).
|
|
1158
1261
|
this.seekEl.addEventListener('pointermove', (e) => {
|
|
1159
|
-
|
|
1160
|
-
if (!dur) { tip.style.opacity = '0'; return; }
|
|
1161
|
-
const rect = this.canvas.getBoundingClientRect();
|
|
1162
|
-
const pct = clamp((e.clientX - rect.left) / rect.width);
|
|
1163
|
-
tip.textContent = formatTime(pct * dur);
|
|
1164
|
-
tip.style.left = (pct * 100) + '%';
|
|
1165
|
-
tip.style.opacity = '1';
|
|
1262
|
+
if (!this._dragging) this._updateHoverTip(e.clientX);
|
|
1166
1263
|
});
|
|
1167
|
-
this.seekEl.addEventListener('pointerleave', () => {
|
|
1264
|
+
this.seekEl.addEventListener('pointerleave', () => {
|
|
1265
|
+
if (!this._dragging) this._hideHoverTip();
|
|
1266
|
+
});
|
|
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);
|
|
1168
1337
|
}
|
|
1169
1338
|
|
|
1170
1339
|
// ============================================
|
|
@@ -1184,15 +1353,24 @@ export class WaveformPlayer {
|
|
|
1184
1353
|
* @fires WaveformPlayer#waveformplayer:request-seek
|
|
1185
1354
|
*/
|
|
1186
1355
|
handleCanvasClick(event) {
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
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) {
|
|
1193
1371
|
const rect = this.canvas.getBoundingClientRect();
|
|
1194
|
-
|
|
1195
|
-
const targetPercent = clamp(
|
|
1372
|
+
if (!rect.width) return;
|
|
1373
|
+
const targetPercent = clamp((clientX - rect.left) / rect.width);
|
|
1196
1374
|
|
|
1197
1375
|
if (this.options.audioMode === 'external') {
|
|
1198
1376
|
this._requestSeek(targetPercent);
|
|
@@ -1429,12 +1607,16 @@ export class WaveformPlayer {
|
|
|
1429
1607
|
// Self-mode only — external mode receives progress via
|
|
1430
1608
|
// setProgress() from the controller and never calls this.
|
|
1431
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;
|
|
1432
1613
|
|
|
1433
1614
|
const newProgress = this.audio.currentTime / this.audio.duration;
|
|
1434
1615
|
|
|
1435
1616
|
if (Math.abs(newProgress - this.progress) > 0.001) {
|
|
1436
1617
|
this.progress = newProgress;
|
|
1437
1618
|
this.drawWaveform();
|
|
1619
|
+
this._updateSeekHandle();
|
|
1438
1620
|
}
|
|
1439
1621
|
|
|
1440
1622
|
if (this.currentTimeEl) {
|
|
@@ -1831,6 +2013,7 @@ export class WaveformPlayer {
|
|
|
1831
2013
|
// Stop playback and animations
|
|
1832
2014
|
this.pause();
|
|
1833
2015
|
this.stopSmoothUpdate();
|
|
2016
|
+
clearTimeout(this._markerLabelTimer);
|
|
1834
2017
|
|
|
1835
2018
|
// Tear down every document/container/seek listener in one shot.
|
|
1836
2019
|
this._ac?.abort();
|
|
@@ -1923,7 +2106,7 @@ export class WaveformPlayer {
|
|
|
1923
2106
|
* @param {number} samples - Number of samples
|
|
1924
2107
|
* @returns {Promise<number[]>} Waveform peak data
|
|
1925
2108
|
*/
|
|
1926
|
-
static async generateWaveformData(url, samples =
|
|
2109
|
+
static async generateWaveformData(url, samples = DEFAULT_SAMPLES) {
|
|
1927
2110
|
try {
|
|
1928
2111
|
const result = await generateWaveform(url, samples);
|
|
1929
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
|
|
433
|
-
* (clamped to at least one full pill width so it never collapses), and a
|
|
434
|
-
* circular handle/thumb at the playhead
|
|
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
|
-
//
|
|
464
|
-
|
|
465
|
-
ctx.
|
|
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:
|
|
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');
|