@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/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-container">
398
- <canvas></canvas>
399
- <div class="waveform-markers"></div>
400
- <div class="waveform-loading" style="display:none;"></div>
401
- <div class="waveform-error" style="display:none;" role="alert">
402
- <span class="waveform-error-text">${escapeHtml(this.options.errorText)}</span>
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
- if (this.isPlaying && Date.now() - this._frameAt > 500) this.updateProgress();
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
- markerEl.setAttribute('aria-label', marker.label);
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
- this.seekTo(marker.time);
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
- this.seekEl.addEventListener('pointermove', (e) => {
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
- this.seekEl.addEventListener('pointerleave', () => {
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
- if (this.isDestroying) return;
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
- const rate = this.audio.playbackRate;
2313
- speedValue.textContent = rate === 1 ? '1x' : `${rate}x`;
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.audio.currentTime = clamp(s, 0, this.audio.duration);
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.audio.currentTime = this.audio.duration * clamp(p);
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; artworkAlt is
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
+