@arraypress/waveform-player 1.18.0 → 1.19.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
@@ -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.0",
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
@@ -561,6 +561,17 @@ export class WaveformPlayer {
561
561
  this.updateSeekAccessibility();
562
562
 
563
563
  this.seekEl.addEventListener('keydown', (e) => {
564
+ // Space toggles play/pause even while the waveform slider is focused —
565
+ // it's a media control, so play/pause should work here too, not only
566
+ // when the player root is the active element (restores the pre-a11y
567
+ // Space path reported in #10).
568
+ if (e.key === ' ' || e.key === 'Spacebar') {
569
+ e.preventDefault();
570
+ e.stopPropagation();
571
+ this.togglePlay();
572
+ return;
573
+ }
574
+
564
575
  const duration = this.getSeekDuration();
565
576
  if (!duration) return;
566
577
 
@@ -698,15 +709,7 @@ export class WaveformPlayer {
698
709
  // Session handlers; ours would conflict with its.
699
710
  if (!this.audio) return;
700
711
 
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
- });
712
+ this._applyMediaMetadata();
710
713
 
711
714
  // Set up action handlers
712
715
  navigator.mediaSession.setActionHandler('play', () => this.play());
@@ -722,6 +725,53 @@ export class WaveformPlayer {
722
725
  this.seekTo(details.seekTime);
723
726
  }
724
727
  });
728
+
729
+ // Optional queue navigation — lights up the lock-screen skip-track
730
+ // buttons. Registered only when a host (bar / playlist) supplies a
731
+ // callback; a null handler hides the button.
732
+ const onNext = this.options.onNextTrack, onPrev = this.options.onPreviousTrack;
733
+ try { navigator.mediaSession.setActionHandler('nexttrack', typeof onNext === 'function' ? () => onNext(this) : null); } catch (e) { /* unsupported */ }
734
+ try { navigator.mediaSession.setActionHandler('previoustrack', typeof onPrev === 'function' ? () => onPrev(this) : null); } catch (e) { /* unsupported */ }
735
+ }
736
+
737
+ /**
738
+ * Publish the current track's Media Session metadata (lock-screen /
739
+ * Now-Playing title, artist, album, artwork). Idempotent — safe to re-call.
740
+ * @private
741
+ */
742
+ _applyMediaMetadata() {
743
+ if (!('mediaSession' in navigator) || !this.options.enableMediaSession) return;
744
+ navigator.mediaSession.metadata = new MediaMetadata({
745
+ title: this.options.title || 'Unknown Track',
746
+ artist: this.options.artist || '',
747
+ album: this.options.album || '',
748
+ artwork: this.options.artwork ? [
749
+ {src: this.options.artwork, sizes: '512x512', type: 'image/jpeg'}
750
+ ] : []
751
+ });
752
+ }
753
+
754
+ /**
755
+ * Sync Media Session playback state + scrubber position on play/pause. iOS
756
+ * ignores metadata set before the media is active, so we re-assert it on
757
+ * play — that's what fixes the blank lock-screen card on mobile.
758
+ * @param {'playing'|'paused'} state
759
+ * @private
760
+ */
761
+ _updateMediaSession(state) {
762
+ if (!('mediaSession' in navigator) || !this.options.enableMediaSession || !this.audio) return;
763
+ try {
764
+ if (state === 'playing') this._applyMediaMetadata();
765
+ navigator.mediaSession.playbackState = state;
766
+ const d = this.audio.duration;
767
+ if (navigator.mediaSession.setPositionState && d && isFinite(d)) {
768
+ navigator.mediaSession.setPositionState({
769
+ duration: d,
770
+ playbackRate: this.audio.playbackRate || 1,
771
+ position: clamp(this.audio.currentTime, 0, d),
772
+ });
773
+ }
774
+ } catch (e) { /* Media Session is best-effort */ }
725
775
  }
726
776
 
727
777
  // ============================================
@@ -809,6 +859,10 @@ export class WaveformPlayer {
809
859
  const endDrag = (e) => {
810
860
  if (!this._dragging) return;
811
861
  this._dragging = false;
862
+ // The browser fires a click after pointerup on a tap/short drag —
863
+ // flag it so handleCanvasClick ignores it (a second seek from the
864
+ // synthetic click's coordinate can snap the playhead, e.g. to 0).
865
+ this._suppressClick = true;
812
866
  try { this.canvas.releasePointerCapture(e.pointerId); } catch (err) { /* ignore */ }
813
867
  this._seekFromPointer(e.clientX); // commit the seek now — audio jumps once
814
868
  // Hide the drag tooltip on release, unless hover-time keeps it (or
@@ -1364,6 +1418,8 @@ export class WaveformPlayer {
1364
1418
  * @fires WaveformPlayer#waveformplayer:request-seek
1365
1419
  */
1366
1420
  handleCanvasClick(event) {
1421
+ // Ignore the synthetic click that trails a pointer drag (see endDrag).
1422
+ if (this._suppressClick) { this._suppressClick = false; return; }
1367
1423
  this._seekFromPointer(event.clientX);
1368
1424
  }
1369
1425
 
@@ -1464,6 +1520,10 @@ export class WaveformPlayer {
1464
1520
 
1465
1521
  this.startSmoothUpdate();
1466
1522
 
1523
+ // iOS drops Media Session metadata set before playback begins — re-assert
1524
+ // metadata + playback state now that we're actually playing.
1525
+ this._updateMediaSession('playing');
1526
+
1467
1527
  // Dispatch play event
1468
1528
  this._emit('waveformplayer:play', {player: this, url: this.options.url});
1469
1529
 
@@ -1490,6 +1550,8 @@ export class WaveformPlayer {
1490
1550
 
1491
1551
  this.stopSmoothUpdate();
1492
1552
 
1553
+ this._updateMediaSession('paused');
1554
+
1493
1555
  // Dispatch pause event
1494
1556
  this._emit('waveformplayer:pause', {player: this, url: this.options.url});
1495
1557
 
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
  /**