gapless.js 4.0.0 → 4.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gapless.js",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Gapless audio playback javascript plugin",
   "type": "module",
   "main": "dist/index.mjs",

package/src/Queue.ts

@@ -8,10 +8,12 @@ import {
   setupMediaSession,
   updateMediaSessionMetadata,
   updateMediaSessionPlaybackState,
+  updateMediaSessionPositionState,
 } from './utils/mediaSession';
 import { createQueueMachine } from './machines/queue.machine';
 import { Track } from './Track';
 import type { TrackQueueRef } from './Track';
+import { throttle } from './utils/throttle';
 import type { GaplessOptions, AddTrackOptions, TrackInfo, TrackMetadata } from './types';
 
 /** Maximum number of tracks to preload ahead of the current track. */
@@ -37,6 +39,12 @@ export class Queue implements TrackQueueRef {
   /** Track indices for which a gapless start has been pre-scheduled. */
   private _scheduledIndices = new Set<number>();
 
+  private _throttledUpdatePositionState = throttle(
+    (duration: number, currentTime: number) =>
+      updateMediaSessionPositionState(duration, currentTime),
+    1000,
+  );
+
   constructor(options: GaplessOptions = {}) {
     const {
       tracks = [],
@@ -337,6 +345,9 @@ export class Queue implements TrackQueueRef {
 
   onProgress(info: TrackInfo): void {
     if (info.index !== this._actor.getSnapshot().context.currentTrackIndex) return;
+    if (!isNaN(info.duration)) {
+      this._throttledUpdatePositionState(info.duration, info.currentTime);
+    }
     this._onProgress?.(info);
   }
 

package/src/Track.ts

@@ -227,9 +227,10 @@ export class Track {
 
   activate(): void {
     const state = this._actor.getSnapshot().value;
-    // If the track was in webaudio state (e.g. from gapless scheduling or
-    // preload BUFFER_READY), reset it so play() can start from a clean state.
-    if (state === 'webaudio') {
+    // If the track was in webaudio or loading state (e.g. from gapless scheduling,
+    // preload BUFFER_READY, or stuck in loading), reset it so play() can start
+    // from a clean state.
+    if (state === 'webaudio' || state === 'loading') {
       this._stopSourceNode();
       this._disconnectGain();
       this.scheduledStartContextTime = null;

package/src/machines/track.machine.ts

@@ -7,6 +7,16 @@
 //   loading     Track is preloaded (not yet playing). Decode in progress.
 //   webaudio    AudioBufferSourceNode is the active output.
 //
+// Design invariant — "Web Audio always wins eventually":
+//   When a track's buffer finishes decoding (BUFFER_READY), webAudioLoadingState
+//   is set to 'LOADED' regardless of what state the machine is in (html5, loading,
+//   or idle). We intentionally do NOT switch mid-stream — the track stays in html5
+//   until the next play(). But every state handles BUFFER_READY, so the flag is
+//   never lost, and the next play() will see the buffer and use Web Audio.
+//
+//   All DEACTIVATE transitions land in idle (not loading), so a deactivated track
+//   with a loaded buffer is always in idle+LOADED — ready for Web Audio on re-play.
+//
 // Bug fixes in this rewrite:
 //   #2: BUFFER_READY in html5 stays in html5 (no longer auto-transitions to webaudio)
 //   #3: DEACTIVATE from webaudio → idle (was staying in webaudio)
@@ -83,6 +93,12 @@ export function createTrackMachine(initialContext: TrackContext) {
           BUFFER_LOADING: {
             actions: assign({ webAudioLoadingState: () => 'LOADING' as WebAudioLoadingState }),
           },
+          BUFFER_READY: {
+            actions: assign({ webAudioLoadingState: () => 'LOADED' as WebAudioLoadingState }),
+          },
+          BUFFER_ERROR: {
+            actions: assign({ webAudioLoadingState: () => 'ERROR' as WebAudioLoadingState }),
+          },
           URL_RESOLVED: {
             actions: assign({
               resolvedUrl: ({ event }) => (event as { type: 'URL_RESOLVED'; url: string }).url,
@@ -140,7 +156,7 @@ export function createTrackMachine(initialContext: TrackContext) {
             }),
           },
           DEACTIVATE: {
-            target: 'loading',
+            target: 'idle',
             actions: assign({ isPlaying: () => false }),
           },
         },
@@ -178,6 +194,10 @@ export function createTrackMachine(initialContext: TrackContext) {
               playbackType: () => 'WEBAUDIO' as PlaybackType,
             }),
           },
+          DEACTIVATE: {
+            target: 'idle',
+            actions: assign({ isPlaying: () => false }),
+          },
           URL_RESOLVED: {
             actions: assign({
               resolvedUrl: ({ event }) => (event as { type: 'URL_RESOLVED'; url: string }).url,

package/src/utils/mediaSession.ts

@@ -53,3 +53,17 @@ export function updateMediaSessionPlaybackState(
   if (!hasMediaSession) return;
   navigator.mediaSession.playbackState = isPlaying ? 'playing' : 'paused';
 }
+
+/** Update the OS position/duration display (lock screen scrubber). */
+export function updateMediaSessionPositionState(
+  duration: number,
+  position: number,
+  playbackRate = 1,
+): void {
+  if (!hasMediaSession) return;
+  try {
+    navigator.mediaSession.setPositionState({ duration, position, playbackRate });
+  } catch {
+    // Some browsers throw on invalid values (e.g. NaN duration)
+  }
+}

package/src/utils/throttle.ts

@@ -0,0 +1,14 @@
+/** Returns a throttled version of `fn` that fires at most once per `ms`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function throttle<T extends (...args: any[]) => void>(
+  fn: T,
+  ms: number,
+): (...args: Parameters<T>) => void {
+  let last = 0;
+  return (...args: Parameters<T>) => {
+    const now = performance.now();
+    if (now - last < ms) return;
+    last = now;
+    fn(...args);
+  };
+}