@arraypress/waveform-player 1.29.0 → 1.30.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-no-autoinit.cjs +153 -21
- package/dist/waveform-player-no-autoinit.esm.js +15 -13
- package/dist/waveform-player.cjs +153 -21
- package/dist/waveform-player.css +1 -1
- package/dist/waveform-player.esm.js +15 -13
- package/dist/waveform-player.js +153 -21
- package/dist/waveform-player.min.js +15 -13
- package/index.d.ts +7 -1
- package/package.json +1 -1
- package/src/css/waveform-player.css +12 -1
- package/src/js/core.js +184 -23
- package/src/js/themes.js +3 -1
- package/src/js/utils.js +33 -1
package/src/js/core.js
CHANGED
|
@@ -18,7 +18,9 @@ import {
|
|
|
18
18
|
formatCssLength,
|
|
19
19
|
toFiniteNumber,
|
|
20
20
|
toNumberArray,
|
|
21
|
-
DEFAULT_SAMPLES
|
|
21
|
+
DEFAULT_SAMPLES,
|
|
22
|
+
inTimeRanges,
|
|
23
|
+
coversDuration,
|
|
22
24
|
} from './utils.js';
|
|
23
25
|
|
|
24
26
|
import {
|
|
@@ -53,6 +55,18 @@ const SEEK_PAGE_SECONDS = 10;
|
|
|
53
55
|
// wrapper, moving it off the control the user just operated.
|
|
54
56
|
const INTERACTIVE_ELEMENTS = 'button, a[href], input, [role="slider"]';
|
|
55
57
|
|
|
58
|
+
/**
|
|
59
|
+
* Accessible name for the speed button: the visible rate first, then the
|
|
60
|
+
* `speedLabel` text — "1.5x Playback speed". A fixed label would hide the rate
|
|
61
|
+
* the button shows (WCAG 2.5.3 Label in Name, axe `label-content-name-mismatch`).
|
|
62
|
+
* @param {number} rate - Current playback rate.
|
|
63
|
+
* @param {string} [label] - The `speedLabel` option.
|
|
64
|
+
* @returns {string}
|
|
65
|
+
*/
|
|
66
|
+
function speedButtonLabel(rate, label) {
|
|
67
|
+
return label ? `${rate}x ${label}` : `${rate}x`;
|
|
68
|
+
}
|
|
69
|
+
|
|
56
70
|
/**
|
|
57
71
|
* WaveformPlayer - Modern audio player with waveform visualization
|
|
58
72
|
* @class
|
|
@@ -64,6 +78,9 @@ export class WaveformPlayer {
|
|
|
64
78
|
/** @type {WaveformPlayer|null} */
|
|
65
79
|
static currentlyPlaying = null;
|
|
66
80
|
|
|
81
|
+
/** Audio URLs already warned about lacking byte-range support. @private */
|
|
82
|
+
static _noRangeWarned = new Set();
|
|
83
|
+
|
|
67
84
|
/**
|
|
68
85
|
* Create a new WaveformPlayer instance.
|
|
69
86
|
*
|
|
@@ -368,7 +385,7 @@ export class WaveformPlayer {
|
|
|
368
385
|
` : ''}
|
|
369
386
|
${this.options.showPlaybackSpeed ? `
|
|
370
387
|
<div class="waveform-speed">
|
|
371
|
-
<button class="speed-btn" aria-label="${escapeHtml(this.options.speedLabel)}" aria-haspopup="menu" aria-expanded="false">
|
|
388
|
+
<button class="speed-btn" aria-label="${escapeHtml(speedButtonLabel(1, this.options.speedLabel))}" aria-haspopup="menu" aria-expanded="false">
|
|
372
389
|
<span class="speed-value">1x</span>
|
|
373
390
|
</button>
|
|
374
391
|
<div class="speed-menu" role="menu" aria-label="${escapeHtml(this.options.speedLabel)}" style="display: none;">
|
|
@@ -394,13 +411,15 @@ export class WaveformPlayer {
|
|
|
394
411
|
<div class="waveform-track waveform-align-${buttonAlign}">
|
|
395
412
|
${buttonHTML}
|
|
396
413
|
|
|
397
|
-
<div class="waveform-
|
|
398
|
-
<
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
414
|
+
<div class="waveform-surface">
|
|
415
|
+
<div class="waveform-container">
|
|
416
|
+
<canvas></canvas>
|
|
417
|
+
<div class="waveform-loading" style="display:none;"></div>
|
|
418
|
+
<div class="waveform-error" style="display:none;" role="alert">
|
|
419
|
+
<span class="waveform-error-text">${escapeHtml(this.options.errorText)}</span>
|
|
420
|
+
</div>
|
|
403
421
|
</div>
|
|
422
|
+
<div class="waveform-markers"></div>
|
|
404
423
|
</div>
|
|
405
424
|
</div>
|
|
406
425
|
|
|
@@ -426,6 +445,11 @@ export class WaveformPlayer {
|
|
|
426
445
|
this.bpmValueEl = this.container.querySelector('.bpm-value');
|
|
427
446
|
this.loadingEl = this.container.querySelector('.waveform-loading');
|
|
428
447
|
this.errorEl = this.container.querySelector('.waveform-error');
|
|
448
|
+
// Markers sit BESIDE the seek slider, not inside it: they're buttons,
|
|
449
|
+
// and a focusable control nested in role="slider" is unreachable to
|
|
450
|
+
// assistive tech (axe nested-interactive, WCAG 4.1.2). `.waveform-surface`
|
|
451
|
+
// is the shared positioned box that lays them over the waveform.
|
|
452
|
+
this.surfaceEl = this.container.querySelector('.waveform-surface');
|
|
429
453
|
this.markersContainer = this.container.querySelector('.waveform-markers');
|
|
430
454
|
this.speedBtn = this.container.querySelector('.speed-btn');
|
|
431
455
|
this.speedMenu = this.container.querySelector('.speed-menu');
|
|
@@ -1122,7 +1146,8 @@ export class WaveformPlayer {
|
|
|
1122
1146
|
this.audio.addEventListener('seeked', () => this._updatePositionState());
|
|
1123
1147
|
this.audio.addEventListener('ratechange', () => this._updatePositionState());
|
|
1124
1148
|
this.audio.addEventListener('timeupdate', () => {
|
|
1125
|
-
|
|
1149
|
+
// Not mid cache-reload: currentTime reads 0 until the seek lands.
|
|
1150
|
+
if (this.isPlaying && !this._seekReload && Date.now() - this._frameAt > 500) this.updateProgress();
|
|
1126
1151
|
});
|
|
1127
1152
|
}
|
|
1128
1153
|
|
|
@@ -1388,6 +1413,9 @@ export class WaveformPlayer {
|
|
|
1388
1413
|
* @private
|
|
1389
1414
|
*/
|
|
1390
1415
|
_resetTrack() {
|
|
1416
|
+
// A seek waiting on / reloading the previous file no longer applies.
|
|
1417
|
+
this._cancelCacheSeek?.();
|
|
1418
|
+
this._seekReload = null;
|
|
1391
1419
|
this.progress = 0;
|
|
1392
1420
|
this.waveformData = [];
|
|
1393
1421
|
this._extDuration = 0;
|
|
@@ -1697,10 +1725,15 @@ export class WaveformPlayer {
|
|
|
1697
1725
|
const position = (marker.time / duration) * 100;
|
|
1698
1726
|
|
|
1699
1727
|
const markerEl = document.createElement('button');
|
|
1728
|
+
markerEl.type = 'button';
|
|
1700
1729
|
markerEl.className = 'waveform-marker';
|
|
1701
1730
|
markerEl.style.left = `${position}%`;
|
|
1702
1731
|
markerEl.style.backgroundColor = marker.color || 'rgba(255, 255, 255, 0.5)';
|
|
1703
|
-
|
|
1732
|
+
// Label + time, so a screen reader hears where the jump lands — and
|
|
1733
|
+
// an unlabelled marker still has a name (the time) instead of none.
|
|
1734
|
+
markerEl.setAttribute('aria-label', marker.label
|
|
1735
|
+
? `${marker.label}, ${formatTime(marker.time)}`
|
|
1736
|
+
: formatTime(marker.time));
|
|
1704
1737
|
markerEl.setAttribute('data-time', marker.time);
|
|
1705
1738
|
|
|
1706
1739
|
// Tooltip
|
|
@@ -1712,7 +1745,10 @@ export class WaveformPlayer {
|
|
|
1712
1745
|
// Click to seek
|
|
1713
1746
|
markerEl.addEventListener('click', (e) => {
|
|
1714
1747
|
e.stopPropagation();
|
|
1715
|
-
|
|
1748
|
+
// Mode-agnostic: seekTo() needs an owned <audio>, so in external
|
|
1749
|
+
// mode a marker click used to do nothing. seekToSeconds() seeks
|
|
1750
|
+
// in self mode and emits request-seek in external mode.
|
|
1751
|
+
this.seekToSeconds(marker.time);
|
|
1716
1752
|
if (this.options.playOnSeek && !this.isPlaying) {
|
|
1717
1753
|
this.play();
|
|
1718
1754
|
}
|
|
@@ -1797,10 +1833,13 @@ export class WaveformPlayer {
|
|
|
1797
1833
|
// the time follows the playhead while scrubbing (Spotify-style). The
|
|
1798
1834
|
// guard avoids a double-update when a drag is in progress (the canvas
|
|
1799
1835
|
// pointermove already drives it then).
|
|
1800
|
-
|
|
1836
|
+
// Listen on the surface, not the slider: the markers are the slider's
|
|
1837
|
+
// siblings, so hovering one would otherwise read as leaving the waveform.
|
|
1838
|
+
const hoverEl = this.surfaceEl || this.seekEl;
|
|
1839
|
+
hoverEl.addEventListener('pointermove', (e) => {
|
|
1801
1840
|
if (!this._dragging) this._updateHoverTip(e.clientX);
|
|
1802
1841
|
});
|
|
1803
|
-
|
|
1842
|
+
hoverEl.addEventListener('pointerleave', () => {
|
|
1804
1843
|
if (!this._dragging) this._hideHoverTip();
|
|
1805
1844
|
});
|
|
1806
1845
|
}
|
|
@@ -2005,8 +2044,9 @@ export class WaveformPlayer {
|
|
|
2005
2044
|
* @fires WaveformPlayer#waveformplayer:play
|
|
2006
2045
|
*/
|
|
2007
2046
|
onPlay() {
|
|
2008
|
-
// Ignore during destruction
|
|
2009
|
-
|
|
2047
|
+
// Ignore during destruction, and during a seek's cache reload (an
|
|
2048
|
+
// internal pause/play pair consumers shouldn't see; see _reloadForSeek).
|
|
2049
|
+
if (this.isDestroying || this._seekReload) return;
|
|
2010
2050
|
|
|
2011
2051
|
this.isPlaying = true;
|
|
2012
2052
|
|
|
@@ -2035,8 +2075,8 @@ export class WaveformPlayer {
|
|
|
2035
2075
|
* @fires WaveformPlayer#waveformplayer:pause
|
|
2036
2076
|
*/
|
|
2037
2077
|
onPause() {
|
|
2038
|
-
// Ignore during destruction
|
|
2039
|
-
if (this.isDestroying) return;
|
|
2078
|
+
// Ignore during destruction, and during a seek's cache reload.
|
|
2079
|
+
if (this.isDestroying || this._seekReload) return;
|
|
2040
2080
|
|
|
2041
2081
|
this.isPlaying = false;
|
|
2042
2082
|
|
|
@@ -2307,11 +2347,12 @@ export class WaveformPlayer {
|
|
|
2307
2347
|
// this.audio.playbackRate here would throw during construction).
|
|
2308
2348
|
if (!this.audio) return;
|
|
2309
2349
|
|
|
2350
|
+
const rate = this.audio.playbackRate;
|
|
2310
2351
|
const speedValue = this.container.querySelector('.speed-value');
|
|
2311
|
-
if (speedValue) {
|
|
2312
|
-
|
|
2313
|
-
|
|
2314
|
-
|
|
2352
|
+
if (speedValue) speedValue.textContent = `${rate}x`;
|
|
2353
|
+
// The accessible name must contain the visible rate (WCAG 2.5.3 Label
|
|
2354
|
+
// in Name), so it's rebuilt with it: "1.5x Playback speed".
|
|
2355
|
+
this.speedBtn?.setAttribute('aria-label', speedButtonLabel(rate, this.options.speedLabel));
|
|
2315
2356
|
|
|
2316
2357
|
// Update active state in menu
|
|
2317
2358
|
this.container.querySelectorAll('.speed-option').forEach(btn => {
|
|
@@ -2512,6 +2553,126 @@ export class WaveformPlayer {
|
|
|
2512
2553
|
}
|
|
2513
2554
|
}
|
|
2514
2555
|
|
|
2556
|
+
/**
|
|
2557
|
+
* Move the owned `<audio>` to `time`. The single path every self-mode seek
|
|
2558
|
+
* takes ({@link WaveformPlayer#seekTo}, {@link WaveformPlayer#seekToPercent},
|
|
2559
|
+
* so clicks, drags, keys and the slider too).
|
|
2560
|
+
*
|
|
2561
|
+
* Some hosts ignore HTTP byte ranges: they answer a `Range` request with
|
|
2562
|
+
* `200` and the whole file (Cloudflare Pages and Workers static assets, and
|
|
2563
|
+
* plenty of plain servers). Chromium then can't seek the media at all —
|
|
2564
|
+
* `seekable` stays `0–0` even once every byte has arrived — which is the
|
|
2565
|
+
* "long tracks snap back to 0" symptom. The copy in the browser's HTTP
|
|
2566
|
+
* cache *is* seekable (why a page refresh "fixes" it), so when the target
|
|
2567
|
+
* isn't seekable this reloads the element from cache and seeks there; see
|
|
2568
|
+
* {@link WaveformPlayer#_seekViaCache}. Detection is by the element's own
|
|
2569
|
+
* `seekable`, not the browser, so engines that can already seek (WebKit,
|
|
2570
|
+
* Firefox) never take that path; it runs at most once per file.
|
|
2571
|
+
* @param {number} time - Target position in seconds.
|
|
2572
|
+
* @private
|
|
2573
|
+
*/
|
|
2574
|
+
_seekAudio(time) {
|
|
2575
|
+
const audio = this.audio;
|
|
2576
|
+
// Only divert when the element positively reports ranges that exclude
|
|
2577
|
+
// the target (Chromium's `0–0` on these hosts). No ranges at all means
|
|
2578
|
+
// "unknown" (no metadata yet, some engines, test DOMs): seek as always.
|
|
2579
|
+
const seekable = audio.seekable;
|
|
2580
|
+
if (!Number.isFinite(audio.duration)
|
|
2581
|
+
|| !seekable || seekable.length === 0
|
|
2582
|
+
|| inTimeRanges(seekable, time)
|
|
2583
|
+
|| this._seekReloadedUrl === this.options.url) {
|
|
2584
|
+
audio.currentTime = time;
|
|
2585
|
+
return;
|
|
2586
|
+
}
|
|
2587
|
+
this._seekViaCache(time);
|
|
2588
|
+
}
|
|
2589
|
+
|
|
2590
|
+
/**
|
|
2591
|
+
* Seek on a host without byte-range support: once the whole file is
|
|
2592
|
+
* downloaded (raising `preload` to `auto` until it is, then restoring it),
|
|
2593
|
+
* reload the element from the browser cache and seek there. Repeated seeks
|
|
2594
|
+
* while waiting just update the target. Warns once per URL, since the
|
|
2595
|
+
* real fix is serving audio from a range-capable host.
|
|
2596
|
+
* @param {number} time - Target position in seconds.
|
|
2597
|
+
* @private
|
|
2598
|
+
*/
|
|
2599
|
+
_seekViaCache(time) {
|
|
2600
|
+
const audio = this.audio;
|
|
2601
|
+
const url = this.options.url;
|
|
2602
|
+
this._cacheSeekTime = time;
|
|
2603
|
+
|
|
2604
|
+
if (!WaveformPlayer._noRangeWarned.has(url)) {
|
|
2605
|
+
WaveformPlayer._noRangeWarned.add(url);
|
|
2606
|
+
console.warn(`[WaveformPlayer] ${url}: the host ignores HTTP Range requests, so seeking waits for the download and reloads from cache. Serve audio with Range support for instant seeks.`);
|
|
2607
|
+
}
|
|
2608
|
+
|
|
2609
|
+
if (this._cancelCacheSeek) return; // Already waiting; the target is updated.
|
|
2610
|
+
if (coversDuration(audio.buffered, audio.duration)) {
|
|
2611
|
+
this._reloadForSeek(url);
|
|
2612
|
+
return;
|
|
2613
|
+
}
|
|
2614
|
+
|
|
2615
|
+
const preload = audio.preload;
|
|
2616
|
+
audio.preload = 'auto';
|
|
2617
|
+
this.setLoading(true);
|
|
2618
|
+
const stop = () => {
|
|
2619
|
+
audio.removeEventListener('progress', check);
|
|
2620
|
+
audio.removeEventListener('canplaythrough', check);
|
|
2621
|
+
audio.preload = preload;
|
|
2622
|
+
this._cancelCacheSeek = null;
|
|
2623
|
+
};
|
|
2624
|
+
const check = () => {
|
|
2625
|
+
if (this.audio !== audio || this.options.url !== url) return stop();
|
|
2626
|
+
if (!coversDuration(audio.buffered, audio.duration)) return;
|
|
2627
|
+
stop();
|
|
2628
|
+
this._reloadForSeek(url);
|
|
2629
|
+
};
|
|
2630
|
+
this._cancelCacheSeek = stop;
|
|
2631
|
+
audio.addEventListener('progress', check, {signal: this._ac.signal});
|
|
2632
|
+
audio.addEventListener('canplaythrough', check, {signal: this._ac.signal});
|
|
2633
|
+
}
|
|
2634
|
+
|
|
2635
|
+
/**
|
|
2636
|
+
* Reload the fully-downloaded file from cache, seek to the pending target
|
|
2637
|
+
* and resume. The element's own pause/play events during the reload are
|
|
2638
|
+
* internal plumbing, so onPause/onPlay ignore them while `_seekReload` is
|
|
2639
|
+
* set: consumers (the bar, waveform-tracker) see a seek, not a pause and a
|
|
2640
|
+
* new play, and the button doesn't flicker.
|
|
2641
|
+
* @param {string} url - The file being reloaded.
|
|
2642
|
+
* @private
|
|
2643
|
+
*/
|
|
2644
|
+
_reloadForSeek(url) {
|
|
2645
|
+
const audio = this.audio;
|
|
2646
|
+
const wasPlaying = !audio.paused && !audio.ended;
|
|
2647
|
+
const rate = audio.playbackRate;
|
|
2648
|
+
this._seekReloadedUrl = url;
|
|
2649
|
+
this._seekReload = {wasPlaying};
|
|
2650
|
+
|
|
2651
|
+
const finish = () => {
|
|
2652
|
+
this._seekReload = null;
|
|
2653
|
+
this.setLoading(false);
|
|
2654
|
+
this.updateProgress();
|
|
2655
|
+
};
|
|
2656
|
+
audio.addEventListener('loadedmetadata', () => {
|
|
2657
|
+
if (this.audio !== audio || this.options.url !== url) return;
|
|
2658
|
+
audio.playbackRate = rate; // load() resets it to the default
|
|
2659
|
+
audio.currentTime = this._cacheSeekTime;
|
|
2660
|
+
if (!wasPlaying) {
|
|
2661
|
+
finish();
|
|
2662
|
+
return;
|
|
2663
|
+
}
|
|
2664
|
+
audio.play().then(() => {
|
|
2665
|
+
finish();
|
|
2666
|
+
this.startSmoothUpdate();
|
|
2667
|
+
}, () => {
|
|
2668
|
+
// Playback refused after the reload: show the true state.
|
|
2669
|
+
finish();
|
|
2670
|
+
this.onPause();
|
|
2671
|
+
});
|
|
2672
|
+
}, {once: true, signal: this._ac.signal});
|
|
2673
|
+
audio.load();
|
|
2674
|
+
}
|
|
2675
|
+
|
|
2515
2676
|
/**
|
|
2516
2677
|
* Seek the owned `<audio>` element to an absolute time, clamped to
|
|
2517
2678
|
* `[0, duration]`, and refresh progress. Self mode only — a no-op when
|
|
@@ -2524,7 +2685,7 @@ export class WaveformPlayer {
|
|
|
2524
2685
|
// Coerce + guard like setVolume(): `audio.currentTime = NaN` throws.
|
|
2525
2686
|
const s = Number(seconds);
|
|
2526
2687
|
if (this.audio && this.audio.duration && Number.isFinite(s)) {
|
|
2527
|
-
this.
|
|
2688
|
+
this._seekAudio(clamp(s, 0, this.audio.duration));
|
|
2528
2689
|
this.updateProgress();
|
|
2529
2690
|
}
|
|
2530
2691
|
}
|
|
@@ -2538,7 +2699,7 @@ export class WaveformPlayer {
|
|
|
2538
2699
|
seekToPercent(percent) {
|
|
2539
2700
|
const p = Number(percent);
|
|
2540
2701
|
if (this.audio && this.audio.duration && Number.isFinite(p)) {
|
|
2541
|
-
this.
|
|
2702
|
+
this._seekAudio(this.audio.duration * clamp(p));
|
|
2542
2703
|
this.updateProgress();
|
|
2543
2704
|
}
|
|
2544
2705
|
}
|
package/src/js/themes.js
CHANGED
|
@@ -371,7 +371,9 @@ export const DEFAULT_OPTIONS = {
|
|
|
371
371
|
|
|
372
372
|
// Localizable UI strings (alongside seekLabel / seekValueText / errorText).
|
|
373
373
|
// These are screen-reader / assistive-tech facing, so translate them for
|
|
374
|
-
// non-English UIs. playPauseLabel/speedLabel are aria-labels
|
|
374
|
+
// non-English UIs. playPauseLabel/speedLabel are aria-labels (the speed
|
|
375
|
+
// button prefixes speedLabel with its visible rate, "1.5x Playback speed",
|
|
376
|
+
// for WCAG 2.5.3 Label in Name); artworkAlt is
|
|
375
377
|
// the cover image alt text; unknownTrackText is the Media Session (lock-
|
|
376
378
|
// screen) title fallback used when no track title is set.
|
|
377
379
|
playPauseLabel: 'Play/Pause',
|
package/src/js/utils.js
CHANGED
|
@@ -680,4 +680,36 @@ export function resampleData(data, targetLength) {
|
|
|
680
680
|
}
|
|
681
681
|
|
|
682
682
|
return result;
|
|
683
|
-
}
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
/**
|
|
686
|
+
* Whether a time falls inside a `TimeRanges` (e.g. `audio.seekable`), with a
|
|
687
|
+
* little slack for float rounding at the edges.
|
|
688
|
+
*
|
|
689
|
+
* @param {Pick<TimeRanges, 'length'|'start'|'end'>} ranges - The ranges.
|
|
690
|
+
* @param {number} time - Seconds.
|
|
691
|
+
* @returns {boolean}
|
|
692
|
+
*/
|
|
693
|
+
export function inTimeRanges(ranges, time) {
|
|
694
|
+
for (let i = 0; i < ranges.length; i++) {
|
|
695
|
+
if (ranges.start(i) - 0.05 <= time && time <= ranges.end(i) + 0.05) return true;
|
|
696
|
+
}
|
|
697
|
+
return false;
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
/**
|
|
701
|
+
* Whether one range of a `TimeRanges` (e.g. `audio.buffered`) spans the whole
|
|
702
|
+
* track: the file is fully downloaded, and so in the browser's HTTP cache.
|
|
703
|
+
*
|
|
704
|
+
* @param {Pick<TimeRanges, 'length'|'start'|'end'>} ranges - The ranges.
|
|
705
|
+
* @param {number} duration - Track length in seconds.
|
|
706
|
+
* @returns {boolean}
|
|
707
|
+
*/
|
|
708
|
+
export function coversDuration(ranges, duration) {
|
|
709
|
+
if (!Number.isFinite(duration) || duration <= 0) return false;
|
|
710
|
+
for (let i = 0; i < ranges.length; i++) {
|
|
711
|
+
if (ranges.start(i) <= 0.05 && ranges.end(i) >= duration - 0.1) return true;
|
|
712
|
+
}
|
|
713
|
+
return false;
|
|
714
|
+
}
|
|
715
|
+
|