gapless 4.3.0 → 4.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gapless",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "Gapless audio playback javascript plugin",
   "type": "module",
   "main": "dist/index.mjs",
@@ -20,16 +20,6 @@
   },
   "sideEffects": false,
   "private": false,
-  "scripts": {
-    "test": "vitest run",
-    "build": "tsup",
-    "build:demo": "pnpm --dir demo build",
-    "dev": "pnpm --dir demo dev",
-    "types": "tsc --noEmit",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "pnpm run build"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/RelistenNet/gapless.js.git"
@@ -47,8 +37,16 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   },
-  "packageManager": "pnpm@10.30.2",
   "dependencies": {
     "xstate": "^5.32.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup",
+    "build:demo": "pnpm --dir demo build",
+    "dev": "pnpm --dir demo dev",
+    "types": "tsc --noEmit",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
 }

package/src/Queue.ts

@@ -198,8 +198,9 @@ export class Queue implements TrackQueueRef {
           const e = event as { type: 'SEEK'; time: number };
           this._trackAt(context.currentTrackIndex)?.seek(e.time);
         },
-        seekCurrentToZero: ({ context }) => {
-          this._trackAt(context.currentTrackIndex)?.seek(0);
+        seekCurrentToStartTime: ({ context, event }) => {
+          const e = event as { type: 'GOTO'; startTime?: number };
+          this._trackAt(context.currentTrackIndex)?.seek(e.startTime ?? 0);
         },
         scheduleGapless: ({ context }) => {
           this._tryScheduleGapless(context.currentTrackIndex);
@@ -271,20 +272,19 @@ export class Queue implements TrackQueueRef {
   previous(): void {
     const ct = this._currentTrack;
     if (ct && ct.currentTime > 8) {
-      ct.seek(0);
-      ct.play();
+      this._actor.send({ type: 'SEEK', time: 0 });
       return;
     }
 
     this._actor.send({ type: 'PREVIOUS' });
   }
 
-  gotoTrack(index: number, playImmediately = false): void {
+  gotoTrack(index: number, playImmediately = false, startTime?: number): void {
     if (index < 0 || index >= this._tracks.length) return;
     this.onDebug(
-      `gotoTrack(${index}, playImmediately=${playImmediately}) queueState=${this._actor.getSnapshot().value} curIdx=${this._actor.getSnapshot().context.currentTrackIndex}`
+      `gotoTrack(${index}, playImmediately=${playImmediately}, startTime=${startTime}) queueState=${this._actor.getSnapshot().value} curIdx=${this._actor.getSnapshot().context.currentTrackIndex}`
     );
-    this._actor.send({ type: 'GOTO', index, playImmediately });
+    this._actor.send({ type: 'GOTO', index, playImmediately, startTime });
   }
 
   seek(time: number): void {
@@ -530,6 +530,11 @@ export class Queue implements TrackQueueRef {
       track.cancelGaplessStart();
       this.onDebug(`_cancelScheduledGapless: cancelled track ${this._scheduledNextIndex}`);
     }
+    // Cancel any HTML5 gain mute that was scheduled on the current track,
+    // but only if it's still in HTML5 state. After crossover the gain node
+    // is managed by the crossfade ramp — cancelScheduledValues would wipe it.
+    const cur = this._trackAt(this._actor.getSnapshot().context.currentTrackIndex);
+    if (cur && cur.playbackType === 'HTML5') cur.cancelHtml5Mute();
     this._scheduledNextIndex = null;
   }
 
@@ -564,7 +569,18 @@ export class Queue implements TrackQueueRef {
       return;
     }
 
-    next.scheduleGaplessStart(endTime);
+    if (!next.scheduleGaplessStart(endTime)) {
+      this.onDebug(
+        `_tryScheduleGapless: track ${nextIndex} rejected SCHEDULE_GAPLESS (state=${next.machineState})`
+      );
+      return;
+    }
+    // When scheduling from an HTML5-clock prediction, mute the HTML5 gain
+    // at endTime so a stalled/late HTML5 element is silenced rather than
+    // overlapping the next track.
+    if (current.playbackType === 'HTML5') {
+      current.scheduleHtml5Mute(endTime);
+    }
     this.onDebug(
       `_tryScheduleGapless: scheduled track ${nextIndex} at endTime=${endTime.toFixed(3)} (in ${(endTime - ctx.currentTime).toFixed(1)}s) curPlaybackType=${current.playbackType}`
     );

package/src/Track.ts

@@ -273,6 +273,11 @@ export class Track {
           // half a second of silence/garbage. _bufferStartPaddingSec is
           // computed at decode time via _ensureBufferAlignment.
           this.sourceNode.start(when, this._bufferStartPaddingSec);
+          const bufRemaining = this.audioBuffer.duration - this._bufferStartPaddingSec;
+          const schedRate = this.sourceNode.playbackRate.value || 1;
+          if (bufRemaining > 0) {
+            this.sourceNode.stop(when + bufRemaining / schedRate);
+          }
           this._waRefCtxTime = when;
           this._waRefTrackTime = 0;
           this.queueRef.onDebug(
@@ -353,14 +358,33 @@ export class Track {
   }
 
   setPlaybackRate(rate: number): void {
-    // Freeze current track position at the old rate before switching
-    if (this.ctx && this.sourceNode && this._actor.getSnapshot().context.isPlaying) {
+    // Freeze current track position at the old rate before switching.
+    // Skip the anchor rewrite during the scheduling lead (when the source
+    // is scheduled but ctx.currentTime hasn't reached _waRefCtxTime yet) —
+    // the source hasn't started producing audio, so the anchors are still
+    // correct for the future start. Rewriting them with a negative elapsed
+    // time would corrupt playbackEndContextTime and cause overlap/gap.
+    if (this.ctx && this.sourceNode && this._actor.getSnapshot().context.isPlaying
+        && this.ctx.currentTime >= this._waRefCtxTime) {
       const oldRate = this.sourceNode.playbackRate.value;
       this._waRefTrackTime = this._waRefTrackTime + (this.ctx.currentTime - this._waRefCtxTime) * oldRate;
       this._waRefCtxTime = this.ctx.currentTime;
     }
     this.audio.playbackRate = rate;
-    if (this.sourceNode) this.sourceNode.playbackRate.value = rate;
+    if (this.sourceNode) {
+      this.sourceNode.playbackRate.value = rate;
+      // Re-issue the hard stop ceiling at the new end time. The spec
+      // allows repeated stop() calls (latest wins), so this overwrites
+      // the stale stop scheduled at the old rate.
+      if (this.audioBuffer && this.ctx) {
+        const remaining = this.audioBuffer.duration - this._bufferStartPaddingSec - this._waRefTrackTime;
+        if (remaining > 0) {
+          try {
+            this.sourceNode.stop(this._waRefCtxTime + remaining / rate);
+          } catch { /* already stopped */ }
+        }
+      }
+    }
   }
 
   preload(): void {
@@ -411,15 +435,34 @@ export class Track {
   // Gapless scheduling (called by Queue)
   // --------------------------------------------------------------------------
 
+  /** Schedule the HTML5 gain node to mute at `when` — safety valve so an
+   *  HTML5 element that runs past the predicted end is silenced instead of
+   *  overlapping the next track. No-op if the HTML5 gain path isn't active. */
+  scheduleHtml5Mute(when: number): void {
+    if (!this._html5GainNode || !this.ctx) return;
+    this._html5GainNode.gain.setValueAtTime(1, when - 0.005);
+    this._html5GainNode.gain.linearRampToValueAtTime(0, when);
+  }
+
+  /** Cancel any scheduled HTML5 gain mute (called when gapless is cancelled). */
+  cancelHtml5Mute(): void {
+    if (!this._html5GainNode || !this.ctx) return;
+    this._html5GainNode.gain.cancelScheduledValues(this.ctx.currentTime);
+    this._html5GainNode.gain.setValueAtTime(1, this.ctx.currentTime);
+  }
+
   cancelGaplessStart(): void {
     const snap = this._actor.getSnapshot();
     if (snap.context.scheduledStartContextTime === null) return;
     this._actor.send({ type: 'CANCEL_GAPLESS' });
   }
 
-  scheduleGaplessStart(when: number): void {
-    if (!this.ctx || !this.audioBuffer || !this.gainNode) return;
+  scheduleGaplessStart(when: number): boolean {
+    if (!this.ctx || !this.audioBuffer || !this.gainNode) return false;
+    const state = this._actor.getSnapshot().value;
+    if (state !== 'idle' && state !== 'loading') return false;
     this._actor.send({ type: 'SCHEDULE_GAPLESS', when });
+    return true;
   }
 
   // --------------------------------------------------------------------------
@@ -605,51 +648,46 @@ export class Track {
       return;
     }
 
-    // Sample-accurate crossfade. Both sides live on the AudioContext clock:
-    //   • HTML5 path:    mediaElementSource → _html5GainNode → gainNode → destination
-    //   • WebAudio path: source → fadeGain → gainNode → destination
-    //
-    // We schedule a 1→0 ramp on _html5GainNode and a 0→1 ramp on the WebAudio
-    // fadeGain, both over CROSSOVER_FADE_SEC and both starting at the same
-    // ctx-clock time. The two streams overlap with constant-summed gain
-    // through the fade window, smoothing out the sample-level discontinuity
-    // that an instant cut would otherwise leave audible as a "blip".
-    //
-    // If _html5GainNode wasn't created (createMediaElementSource fell back —
-    // e.g. CORS blocked or legacy browser), we degrade to immediate pause +
-    // WebAudio fade-in only.
-    const t0 = this.ctx.currentTime;
-    const t1 = t0 + CROSSOVER_FADE_SEC;
-
-    if (this._html5GainNode) {
-      this._html5GainNode.gain.cancelScheduledValues(t0);
-      this._html5GainNode.gain.setValueAtTime(1, t0);
-      this._html5GainNode.gain.linearRampToValueAtTime(0, t1);
-      // Pause the HTML5 element after the fade completes — it stops consuming
-      // network/decoder resources and the gain is back to silent regardless.
-      // Reset the gain to 1 afterwards so future plays through this element
-      // (post-deactivate/reactivate) start at full level.
+    // Start the WebAudio source first to learn the exact context-clock time
+    // it will begin producing audio (the "when" returned by _startSourceNode).
+    // Then align the HTML5 fade-out to that same instant so both crossfade
+    // halves overlap at constant-summed gain.
+    const when = this._startSourceNode(this.pausedAtTrackTime, CROSSOVER_FADE_SEC);
+
+    if (when !== null && this._html5GainNode) {
+      this._html5GainNode.gain.cancelScheduledValues(when);
+      this._html5GainNode.gain.setValueAtTime(1, when);
+      this._html5GainNode.gain.linearRampToValueAtTime(0, when + CROSSOVER_FADE_SEC);
       const ctxRef = this.ctx;
       const html5GainRef = this._html5GainNode;
+      const delayMs = (when - this.ctx.currentTime + CROSSOVER_FADE_SEC) * 1000 + 5;
       setTimeout(() => {
         this.audio.pause();
         if (ctxRef && html5GainRef) {
           html5GainRef.gain.cancelScheduledValues(ctxRef.currentTime);
           html5GainRef.gain.setValueAtTime(1, ctxRef.currentTime);
         }
-      }, CROSSOVER_FADE_SEC * 1000 + 5);
-    } else {
-      // Fallback: no MediaElementSource path. Silence HTML5 immediately.
-      const savedVolume = this.audio.volume;
-      this.audio.volume = 0;
-      this.audio.pause();
-      this.audio.volume = savedVolume;
+      }, delayMs);
+    } else if (!this._html5GainNode) {
+      // No MediaElementSource path (CORS blocked or legacy browser).
+      // Delay the HTML5 pause until the WebAudio source actually starts
+      // at `when` so there's no silence gap during the scheduling lead.
+      if (when !== null && this.ctx) {
+        const delayMs = (when - this.ctx.currentTime) * 1000;
+        setTimeout(() => {
+          this.audio.volume = 0;
+          this.audio.pause();
+          this.audio.volume = 1;
+        }, Math.max(0, delayMs));
+      } else {
+        this.audio.volume = 0;
+        this.audio.pause();
+        this.audio.volume = 1;
+      }
     }
 
-    this._startSourceNode(this.pausedAtTrackTime, CROSSOVER_FADE_SEC);
-
     this.queueRef.onDebug(
-      `crossoverHtml5ToWebAudio track=${this.index} offset=${this.pausedAtTrackTime.toFixed(3)} wasPlaying=true fade=${CROSSOVER_FADE_SEC}s mediaSource=${!!this._html5GainNode}`
+      `crossoverHtml5ToWebAudio track=${this.index} offset=${this.pausedAtTrackTime.toFixed(3)} wasPlaying=true fade=${CROSSOVER_FADE_SEC}s mediaSource=${!!this._html5GainNode} when=${when?.toFixed(3) ?? 'null'}`
     );
   }
 
@@ -671,16 +709,13 @@ export class Track {
     );
   }
 
-  private _startSourceNode(offset: number, fadeInSec = 0): void {
-    if (!this.ctx || !this.audioBuffer || !this.gainNode) return;
-    // Re-check alignment in case audio.duration became available since the
-    // last computation (e.g., preloaded track whose metadata load completed).
+  private _startSourceNode(offset: number, fadeInSec = 0): number | null {
+    if (!this.ctx || !this.audioBuffer || !this.gainNode) return null;
     this._maybeComputeBufferAlignment();
     this._stopSourceNode();
 
-    // Ensure the AudioContext is running (it may have been suspended after
-    // the previous track's source was disconnected).
-    if (this.ctx.state === 'suspended') {
+    const wasSuspended = this.ctx.state === 'suspended';
+    if (wasSuspended) {
       this.ctx.resume();
     }
 
@@ -688,30 +723,53 @@ export class Track {
     this.sourceNode.buffer = this.audioBuffer;
     this.sourceNode.playbackRate.value = this.queueRef.playbackRate;
 
-    // When fadeInSec > 0 (crossover path), insert a per-source fade gain
-    // between the source and the master gainNode. This gain ramps 0 → 1 over
-    // fadeInSec so the new Web Audio output rises in step with the HTML5
-    // element's audio-pipeline tail decaying. The master gainNode (which
-    // represents user volume) is unaffected.
+    // Schedule the source at an explicit future time rather than start(0).
+    // start(0) dispatches to the audio render thread asynchronously — the
+    // actual start lags the main-thread currentTime read by up to one
+    // hardware callback period (5-100 ms depending on device). That δ makes
+    // playbackEndContextTime compute an end time δ too early, causing the
+    // next gapless track to overlap briefly. Using start(when) with an
+    // explicit when that matches _waRefCtxTime eliminates the mismatch.
+    const lead = wasSuspended
+      ? 0.15
+      : Math.max(0.02, 2 * ((this.ctx as unknown as { baseLatency?: number }).baseLatency || 0) + 0.01);
+    const when = this.ctx.currentTime + lead;
+
+    // Advance the buffer start position by the lead so the source begins
+    // from where playback will actually be at `when`, not where it was at
+    // the moment we read currentTime. This keeps the currentTime formula
+    // (waRefTrackTime + (ctx.currentTime - waRefCtxTime) * rate) equal to
+    // `offset` immediately after the call without accumulating drift across
+    // pause/resume cycles. During crossover it also aligns the WebAudio
+    // source to where the HTML5 element will be at the fade point.
+    // The skipped interval (≤20 ms at 1× rate) is below audible threshold.
+    const rate = this.queueRef.playbackRate;
+    const maxOffset = this.audioBuffer.duration - this._bufferStartPaddingSec;
+    const effectiveOffset = Math.min(offset + lead * rate, maxOffset);
+
     if (fadeInSec > 0) {
       const fadeNode = this.ctx.createGain();
-      const t0 = this.ctx.currentTime;
-      fadeNode.gain.setValueAtTime(0, t0);
-      fadeNode.gain.linearRampToValueAtTime(1, t0 + fadeInSec);
+      fadeNode.gain.setValueAtTime(0, when);
+      fadeNode.gain.linearRampToValueAtTime(1, when + fadeInSec);
       this.sourceNode.connect(fadeNode);
       fadeNode.connect(this.gainNode);
     } else {
       this.sourceNode.connect(this.gainNode);
     }
-    // gainNode → destination connected once at ctx setup; do not re-connect.
     this.sourceNode.onended = this._handleWebAudioEnded;
 
-    this._waRefCtxTime = this.ctx.currentTime;
-    this._waRefTrackTime = offset;
-    // Buffer-internal offset = music-time offset + decoded-buffer start padding.
-    // See _bufferStartPaddingSec docs for why this is necessary on MP3 files
-    // with ID3v2 tags or encoder priming samples.
-    this.sourceNode.start(0, offset + this._bufferStartPaddingSec);
+    this._waRefCtxTime = when;
+    this._waRefTrackTime = effectiveOffset;
+    this.sourceNode.start(when, effectiveOffset + this._bufferStartPaddingSec);
+
+    // Hard ceiling: stop the source at its computed end time so any
+    // platform-level late start (render thread couldn't honor `when`)
+    // produces an inaudible truncation instead of overlap with the next track.
+    const bufRemaining = this.audioBuffer.duration - this._bufferStartPaddingSec - effectiveOffset;
+    if (bufRemaining > 0) {
+      this.sourceNode.stop(when + bufRemaining / rate);
+    }
+    return when;
   }
 
   private _stopSourceNode(): void {

package/src/machines/queue.machine.ts

@@ -33,7 +33,7 @@ export type QueueEvent =
   | { type: 'TOGGLE' }
   | { type: 'NEXT' }
   | { type: 'PREVIOUS' }
-  | { type: 'GOTO'; index: number; playImmediately?: boolean }
+  | { type: 'GOTO'; index: number; playImmediately?: boolean; startTime?: number }
   | { type: 'SEEK'; time: number }
   | { type: 'SET_VOLUME'; volume: number }
   | { type: 'ADD_TRACK' }
@@ -113,7 +113,7 @@ export function createQueueMachine(initialContext: QueueContext) {
       playCurrent: () => {},
       pauseCurrent: () => {},
       seekCurrent: () => {},
-      seekCurrentToZero: () => {},
+      seekCurrentToStartTime: () => {},
       scheduleGapless: () => {},
       cancelScheduledGapless: () => {},
       cancelAndRescheduleGapless: () => {},
@@ -151,6 +151,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
+                'seekCurrentToStartTime',
                 'activateAndPlayCurrent',
                 'notifyStartNewTrack',
                 'updateMediaSessionMetadata',
@@ -163,7 +164,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
-                'seekCurrentToZero',
+                'seekCurrentToStartTime',
                 'preloadAhead',
               ],
             },
@@ -239,6 +240,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
+                'seekCurrentToStartTime',
                 'activateAndPlayCurrent',
                 'notifyStartNewTrack',
                 'updateMediaSessionMetadata',
@@ -250,7 +252,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
-                'seekCurrentToZero',
+                'seekCurrentToStartTime',
                 'preloadAhead',
               ],
             },
@@ -353,6 +355,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
+                'seekCurrentToStartTime',
                 'activateAndPlayCurrent',
                 'notifyStartNewTrack',
                 'updateMediaSessionMetadata',
@@ -364,7 +367,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
-                'seekCurrentToZero',
+                'seekCurrentToStartTime',
                 'preloadAhead',
               ],
             },
@@ -421,6 +424,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
+                'seekCurrentToStartTime',
                 'activateAndPlayCurrent',
                 'notifyStartNewTrack',
                 'updateMediaSessionMetadata',
@@ -433,7 +437,7 @@ export function createQueueMachine(initialContext: QueueContext) {
                 'deactivateCurrent',
                 'cancelAllGapless',
                 'gotoTrackIndex',
-                'seekCurrentToZero',
+                'seekCurrentToStartTime',
                 'preloadAhead',
               ],
             },

package/src/machines/track.machine.ts

@@ -187,6 +187,7 @@ export function createTrackMachine(initialContext: TrackContext) {
               'resetTiming',
               'stopProgressLoop',
               'clearScheduleAndLookahead',
+              'clearPendingPlay',
             ],
           },
           ACTIVATE: {
@@ -194,6 +195,7 @@ export function createTrackMachine(initialContext: TrackContext) {
               'resetTiming',
               'resetHtml5Element',
               'clearScheduleAndLookahead',
+              'clearPendingPlay',
             ],
           },
           PLAY: [
@@ -400,13 +402,14 @@ export function createTrackMachine(initialContext: TrackContext) {
             target: 'idle',
             actions: [
               'clearPlayingAndSchedule',
+              'clearPendingPlay',
               'resetTiming',
               'resetHtml5Element',
             ],
           },
           DEACTIVATE: {
             target: 'idle',
-            actions: ['clearIsPlaying', 'resetTiming'],
+            actions: ['clearIsPlaying', 'clearPendingPlay', 'resetTiming'],
           },
           URL_RESOLVED: {
             actions: 'setResolvedUrl',