@arraypress/waveform-player 1.18.0 → 1.19.1

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
@@ -201,6 +201,10 @@ export interface WaveformPlayerOptions {
201
201
  onEnd?: WaveformPlayerHandler | null;
202
202
  onError?: WaveformErrorHandler | null;
203
203
  onTimeUpdate?: WaveformTimeUpdateHandler | null;
204
+ /** Called when the Media Session "next track" control is used. Registering it shows the lock-screen skip-forward button. */
205
+ onNextTrack?: WaveformPlayerHandler | null;
206
+ /** Called when the Media Session "previous track" control is used. */
207
+ onPreviousTrack?: WaveformPlayerHandler | null;
204
208
  }
205
209
 
206
210
  /** `detail` of `waveformplayer:play | pause | ready | destroy`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.18.0",
3
+ "version": "1.19.1",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
package/src/js/core.js CHANGED
@@ -295,12 +295,12 @@ export class WaveformPlayer {
295
295
  ` : ''}
296
296
  ${this.options.showPlaybackSpeed ? `
297
297
  <div class="waveform-speed">
298
- <button class="speed-btn" aria-label="Playback speed" aria-haspopup="true" aria-expanded="false">
298
+ <button class="speed-btn" aria-label="Playback speed" aria-haspopup="menu" aria-expanded="false">
299
299
  <span class="speed-value">1x</span>
300
300
  </button>
301
- <div class="speed-menu" style="display: none;">
301
+ <div class="speed-menu" role="menu" aria-label="Playback speed" style="display: none;">
302
302
  ${this.options.playbackRates.map(rate =>
303
- `<button class="speed-option" data-rate="${rate}">${rate}x</button>`
303
+ `<button class="speed-option" role="menuitemradio" tabindex="-1" aria-checked="false" data-rate="${rate}">${rate}x</button>`
304
304
  ).join('')}
305
305
  </div>
306
306
  </div>
@@ -427,40 +427,68 @@ export class WaveformPlayer {
427
427
 
428
428
  if (!speedBtn || !speedMenu) return;
429
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.
430
+ const options = () => Array.from(speedMenu.querySelectorAll('.speed-option'));
431
+ const isOpen = () => speedMenu.style.display !== 'none';
432
+
433
+ // Open/close the menu (a proper role="menu"): keep aria-expanded in sync
434
+ // and, on open, move focus into the menu — the checked rate, else the
435
+ // first option — so arrow keys drive it.
433
436
  const setSpeedMenu = (open) => {
434
437
  speedMenu.style.display = open ? 'block' : 'none';
435
438
  speedBtn.setAttribute('aria-expanded', open ? 'true' : 'false');
439
+ if (open) {
440
+ const opts = options();
441
+ (opts.find((o) => o.getAttribute('aria-checked') === 'true') || opts[0])?.focus();
442
+ }
443
+ };
444
+
445
+ const focusOption = (i) => {
446
+ const opts = options();
447
+ if (opts.length) opts[(i + opts.length) % opts.length].focus();
436
448
  };
437
449
 
438
- // Toggle menu
450
+ const selectOption = (opt) => {
451
+ this.setPlaybackRate(parseFloat(opt.dataset.rate));
452
+ setSpeedMenu(false);
453
+ speedBtn.focus();
454
+ };
455
+
456
+ // Toggle from the trigger.
439
457
  speedBtn.addEventListener('click', (e) => {
440
458
  e.stopPropagation();
441
- setSpeedMenu(speedMenu.style.display === 'none');
459
+ setSpeedMenu(!isOpen());
442
460
  }, {signal: this._ac.signal});
443
461
 
444
- // Close menu when clicking outside
462
+ // Close when clicking outside.
445
463
  document.addEventListener('click', () => setSpeedMenu(false), {signal: this._ac.signal});
446
464
 
447
- // Handle speed selection — apply the rate, close, and return focus to
448
- // the trigger.
465
+ // Pointer + native-button (Enter/Space on an option) selection.
449
466
  speedMenu.addEventListener('click', (e) => {
450
467
  e.stopPropagation();
451
- if (e.target.classList.contains('speed-option')) {
452
- this.setPlaybackRate(parseFloat(e.target.dataset.rate));
453
- setSpeedMenu(false);
454
- speedBtn.focus();
455
- }
468
+ const opt = e.target.closest('.speed-option');
469
+ if (opt) selectOption(opt);
456
470
  }, {signal: this._ac.signal});
457
471
 
458
- // Escape closes the menu and restores focus to the trigger, whether
459
- // focus is on the button or one of the options.
472
+ // Keyboard menu: arrows/Home/End roam, Enter/Space select (via the
473
+ // native button click above), Escape/Tab close. ArrowDown/Up on the
474
+ // trigger opens and focuses the first/checked option.
460
475
  speedBtn.closest('.waveform-speed')?.addEventListener('keydown', (e) => {
461
- if (e.key === 'Escape' && speedMenu.style.display !== 'none') {
462
- setSpeedMenu(false);
463
- speedBtn.focus();
476
+ const opts = options();
477
+ const i = opts.indexOf(document.activeElement);
478
+ if (!isOpen()) {
479
+ if ((e.key === 'ArrowDown' || e.key === 'ArrowUp') && document.activeElement === speedBtn) {
480
+ e.preventDefault();
481
+ setSpeedMenu(true);
482
+ }
483
+ return;
484
+ }
485
+ switch (e.key) {
486
+ case 'ArrowDown': e.preventDefault(); focusOption(i < 0 ? 0 : i + 1); break;
487
+ case 'ArrowUp': e.preventDefault(); focusOption(i < 0 ? opts.length - 1 : i - 1); break;
488
+ case 'Home': e.preventDefault(); focusOption(0); break;
489
+ case 'End': e.preventDefault(); focusOption(opts.length - 1); break;
490
+ case 'Escape': e.preventDefault(); setSpeedMenu(false); speedBtn.focus(); break;
491
+ case 'Tab': setSpeedMenu(false); break;
464
492
  }
465
493
  }, {signal: this._ac.signal});
466
494
 
@@ -561,6 +589,17 @@ export class WaveformPlayer {
561
589
  this.updateSeekAccessibility();
562
590
 
563
591
  this.seekEl.addEventListener('keydown', (e) => {
592
+ // Space toggles play/pause even while the waveform slider is focused —
593
+ // it's a media control, so play/pause should work here too, not only
594
+ // when the player root is the active element (restores the pre-a11y
595
+ // Space path reported in #10).
596
+ if (e.key === ' ' || e.key === 'Spacebar') {
597
+ e.preventDefault();
598
+ e.stopPropagation();
599
+ this.togglePlay();
600
+ return;
601
+ }
602
+
564
603
  const duration = this.getSeekDuration();
565
604
  if (!duration) return;
566
605
 
@@ -698,15 +737,7 @@ export class WaveformPlayer {
698
737
  // Session handlers; ours would conflict with its.
699
738
  if (!this.audio) return;
700
739
 
701
- // Set metadata
702
- navigator.mediaSession.metadata = new MediaMetadata({
703
- title: this.options.title || 'Unknown Track',
704
- artist: this.options.artist || '',
705
- album: this.options.album || '',
706
- artwork: this.options.artwork ? [
707
- {src: this.options.artwork, sizes: '512x512', type: 'image/jpeg'}
708
- ] : []
709
- });
740
+ this._applyMediaMetadata();
710
741
 
711
742
  // Set up action handlers
712
743
  navigator.mediaSession.setActionHandler('play', () => this.play());
@@ -722,6 +753,56 @@ export class WaveformPlayer {
722
753
  this.seekTo(details.seekTime);
723
754
  }
724
755
  });
756
+
757
+ // Optional queue navigation — lights up the lock-screen skip-track
758
+ // buttons. Registered only when a host (bar / playlist) supplies a
759
+ // callback; a null handler hides the button.
760
+ const onNext = this.options.onNextTrack, onPrev = this.options.onPreviousTrack;
761
+ try { navigator.mediaSession.setActionHandler('nexttrack', typeof onNext === 'function' ? () => onNext(this) : null); } catch (e) { /* unsupported */ }
762
+ try { navigator.mediaSession.setActionHandler('previoustrack', typeof onPrev === 'function' ? () => onPrev(this) : null); } catch (e) { /* unsupported */ }
763
+ }
764
+
765
+ /**
766
+ * Publish the current track's Media Session metadata (lock-screen /
767
+ * Now-Playing title, artist, album, artwork). Idempotent — safe to re-call.
768
+ * @private
769
+ */
770
+ _applyMediaMetadata() {
771
+ if (!('mediaSession' in navigator) || !this.options.enableMediaSession) return;
772
+ navigator.mediaSession.metadata = new MediaMetadata({
773
+ title: this.options.title || 'Unknown Track',
774
+ artist: this.options.artist || '',
775
+ album: this.options.album || '',
776
+ artwork: this.options.artwork ? [
777
+ {src: this.options.artwork, sizes: '512x512', type: 'image/jpeg'}
778
+ ] : []
779
+ });
780
+ }
781
+
782
+ /**
783
+ * Sync Media Session playback state + scrubber position on play/pause. iOS
784
+ * ignores metadata set before the media is active, so we re-assert it on
785
+ * play — that's what fixes the blank lock-screen card on mobile.
786
+ * @param {'playing'|'paused'} state
787
+ * @private
788
+ */
789
+ _updateMediaSession(state) {
790
+ if (!('mediaSession' in navigator) || !this.options.enableMediaSession || !this.audio) return;
791
+ try {
792
+ // Claim the (global, singleton) Media Session for THIS player on play —
793
+ // (re)register our action handlers + metadata so the lock-screen controls
794
+ // drive the player you're actually listening to, not the last one loaded.
795
+ if (state === 'playing') this.initMediaSession();
796
+ navigator.mediaSession.playbackState = state;
797
+ const d = this.audio.duration;
798
+ if (navigator.mediaSession.setPositionState && d && isFinite(d)) {
799
+ navigator.mediaSession.setPositionState({
800
+ duration: d,
801
+ playbackRate: this.audio.playbackRate || 1,
802
+ position: clamp(this.audio.currentTime, 0, d),
803
+ });
804
+ }
805
+ } catch (e) { /* Media Session is best-effort */ }
725
806
  }
726
807
 
727
808
  // ============================================
@@ -809,6 +890,10 @@ export class WaveformPlayer {
809
890
  const endDrag = (e) => {
810
891
  if (!this._dragging) return;
811
892
  this._dragging = false;
893
+ // The browser fires a click after pointerup on a tap/short drag —
894
+ // flag it so handleCanvasClick ignores it (a second seek from the
895
+ // synthetic click's coordinate can snap the playhead, e.g. to 0).
896
+ this._suppressClick = true;
812
897
  try { this.canvas.releasePointerCapture(e.pointerId); } catch (err) { /* ignore */ }
813
898
  this._seekFromPointer(e.clientX); // commit the seek now — audio jumps once
814
899
  // Hide the drag tooltip on release, unless hover-time keeps it (or
@@ -928,7 +1013,6 @@ export class WaveformPlayer {
928
1013
 
929
1014
  this.drawWaveform();
930
1015
  this.renderMarkers();
931
- this.initMediaSession();
932
1016
 
933
1017
  // Fire callback
934
1018
  if (this.options.onLoad) {
@@ -1364,6 +1448,8 @@ export class WaveformPlayer {
1364
1448
  * @fires WaveformPlayer#waveformplayer:request-seek
1365
1449
  */
1366
1450
  handleCanvasClick(event) {
1451
+ // Ignore the synthetic click that trails a pointer drag (see endDrag).
1452
+ if (this._suppressClick) { this._suppressClick = false; return; }
1367
1453
  this._seekFromPointer(event.clientX);
1368
1454
  }
1369
1455
 
@@ -1464,6 +1550,10 @@ export class WaveformPlayer {
1464
1550
 
1465
1551
  this.startSmoothUpdate();
1466
1552
 
1553
+ // iOS drops Media Session metadata set before playback begins — re-assert
1554
+ // metadata + playback state now that we're actually playing.
1555
+ this._updateMediaSession('playing');
1556
+
1467
1557
  // Dispatch play event
1468
1558
  this._emit('waveformplayer:play', {player: this, url: this.options.url});
1469
1559
 
@@ -1490,6 +1580,8 @@ export class WaveformPlayer {
1490
1580
 
1491
1581
  this.stopSmoothUpdate();
1492
1582
 
1583
+ this._updateMediaSession('paused');
1584
+
1493
1585
  // Dispatch pause event
1494
1586
  this._emit('waveformplayer:pause', {player: this, url: this.options.url});
1495
1587
 
@@ -1744,7 +1836,9 @@ export class WaveformPlayer {
1744
1836
 
1745
1837
  // Update active state in menu
1746
1838
  this.container.querySelectorAll('.speed-option').forEach(btn => {
1747
- btn.classList.toggle('active', parseFloat(btn.dataset.rate) === this.audio.playbackRate);
1839
+ const on = parseFloat(btn.dataset.rate) === this.audio.playbackRate;
1840
+ btn.classList.toggle('active', on);
1841
+ btn.setAttribute('aria-checked', on ? 'true' : 'false');
1748
1842
  });
1749
1843
  }
1750
1844
 
package/src/js/themes.js CHANGED
@@ -248,7 +248,13 @@ export const DEFAULT_OPTIONS = {
248
248
  onPause: null,
249
249
  onEnd: null,
250
250
  onError: null,
251
- onTimeUpdate: null
251
+ onTimeUpdate: null,
252
+
253
+ // Optional queue navigation — when set, the player registers Media Session
254
+ // nexttrack/previoustrack handlers (lock-screen skip buttons). Called with
255
+ // the player instance; wired by waveform-bar / -playlist.
256
+ onNextTrack: null,
257
+ onPreviousTrack: null
252
258
  };
253
259
 
254
260
  /**