gapless 4.0.12 → 4.1.1

package/src/Queue.ts

@@ -14,10 +14,9 @@ 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';
+import type { GaplessOptions, AddTrackOptions, TrackInfo, TrackMetadata, PlaybackMethod } from './types';
 
-/** Maximum number of tracks to preload ahead of the current track. */
-const PRELOAD_AHEAD = 2;
+const MAX_SCHEDULE_LOOKAHEAD = 5;
 
 export class Queue implements TrackQueueRef {
   private _tracks: Track[] = [];
@@ -32,16 +31,18 @@ export class Queue implements TrackQueueRef {
   private readonly _onPlayBlocked?: () => void;
   private readonly _onDebug?: (msg: string) => void;
 
-  readonly webAudioIsDisabled: boolean;
+  readonly playbackMethod: PlaybackMethod;
 
   private _volume: number;
+  private _preloadNumTracks: number;
+  private _playbackRate: number;
 
   /** Index of the next track with a pre-scheduled gapless start, or null. */
   private _scheduledNextIndex: number | null = null;
 
   private _throttledUpdatePositionState = throttle(
-    (duration: number, currentTime: number) =>
-      updateMediaSessionPositionState(duration, currentTime),
+    (duration: number, currentTime: number, playbackRate: number) =>
+      updateMediaSessionPositionState(duration, currentTime, playbackRate),
     1000,
   );
 
@@ -56,13 +57,17 @@ export class Queue implements TrackQueueRef {
       onError,
       onPlayBlocked,
       onDebug,
-      webAudioIsDisabled = false,
+      playbackMethod = 'HYBRID',
       trackMetadata = [],
       volume: initialVolume = 1,
+      preloadNumTracks = 2,
+      playbackRate: initialPlaybackRate = 1,
     } = options;
 
     this._volume = Math.min(1, Math.max(0, initialVolume));
-    this.webAudioIsDisabled = webAudioIsDisabled;
+    this._preloadNumTracks = Math.max(0, preloadNumTracks);
+    this._playbackRate = Math.min(4, Math.max(0.25, initialPlaybackRate));
+    this.playbackMethod = playbackMethod;
     this._onProgress = onProgress;
     this._onEnded = onEnded;
     this._onPlayNextTrack = onPlayNextTrack;
@@ -246,6 +251,17 @@ export class Queue implements TrackQueueRef {
     for (const track of this._tracks) track.setVolume(clamped);
   }
 
+  setPlaybackRate(rate: number): void {
+    const clamped = Math.min(4, Math.max(0.25, rate));
+    this._playbackRate = clamped;
+    this._currentTrack?.setPlaybackRate(clamped);
+    this._cancelScheduledGapless();
+    const snap = this._actor.getSnapshot();
+    if (snap.value === 'playing') {
+      this._tryScheduleGapless(snap.context.currentTrackIndex);
+    }
+  }
+
   addTrack(url: string, options: AddTrackOptions = {}): void {
     const index = this._tracks.length;
     const metadata = options.metadata ?? ({} as TrackMetadata);
@@ -314,6 +330,22 @@ export class Queue implements TrackQueueRef {
     return this._volume;
   }
 
+  get preloadNumTracks(): number {
+    return this._preloadNumTracks;
+  }
+
+  set preloadNumTracks(value: number) {
+    this._preloadNumTracks = Math.max(0, value);
+    const snap = this._actor.getSnapshot();
+    if (snap.value === 'playing') {
+      this._preloadAhead(snap.context.currentTrackIndex);
+    }
+  }
+
+  get playbackRate(): number {
+    return this._playbackRate;
+  }
+
   /** Snapshot of the queue state machine (state name + context). For debugging. */
   get queueSnapshot(): { state: string; context: { currentTrackIndex: number; trackCount: number } } {
     const snap = this._actor.getSnapshot();
@@ -347,7 +379,7 @@ 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._throttledUpdatePositionState(info.duration, info.currentTime, this._playbackRate);
     }
     this._onProgress?.(info);
   }
@@ -393,7 +425,7 @@ export class Queue implements TrackQueueRef {
         return;
       }
     }
-    const limit = fromIndex + PRELOAD_AHEAD + 1;
+    const limit = fromIndex + this._preloadNumTracks + 1;
     this.onDebug(`_preloadAhead(${fromIndex}) limit=${limit} trackCount=${this._tracks.length}`);
     for (let i = fromIndex + 1; i < this._tracks.length && i < limit; i++) {
       const t = this._tracks[i];
@@ -419,7 +451,7 @@ export class Queue implements TrackQueueRef {
 
   private _tryScheduleGapless(curIndex: number): void {
     const ctx = getAudioContext();
-    if (!ctx || this.webAudioIsDisabled) return;
+    if (!ctx || this.playbackMethod === 'HTML5_ONLY') return;
 
     const nextIndex = curIndex + 1;
     if (nextIndex >= this._tracks.length) return;
@@ -440,7 +472,18 @@ export class Queue implements TrackQueueRef {
 
     if (endTime < ctx.currentTime + 0.01) return;
 
+    const timeUntilEnd = endTime - ctx.currentTime;
+    if (current.playbackType === 'HTML5' && timeUntilEnd > MAX_SCHEDULE_LOOKAHEAD) {
+      this.onDebug(
+        `_tryScheduleGapless: deferring — HTML5 track ${curIndex} has ${timeUntilEnd.toFixed(1)}s remaining (max lookahead=${MAX_SCHEDULE_LOOKAHEAD}s)`
+      );
+      return;
+    }
+
     next.scheduleGaplessStart(endTime);
+    this.onDebug(
+      `_tryScheduleGapless: scheduled track ${nextIndex} at endTime=${endTime.toFixed(3)} (in ${(endTime - ctx.currentTime).toFixed(1)}s) curPlaybackType=${current.playbackType}`
+    );
     this._scheduledNextIndex = nextIndex;
   }
 
@@ -451,10 +494,10 @@ export class Queue implements TrackQueueRef {
     if (isNaN(duration)) return null;
 
     if (track.scheduledStartContextTime !== null) {
-      return track.scheduledStartContextTime + duration;
+      return track.scheduledStartContextTime + duration / this._playbackRate;
     }
 
-    const remaining = duration - track.currentTime;
+    const remaining = (duration - track.currentTime) / this._playbackRate;
     if (remaining <= 0) return null;
     return ctx.currentTime + remaining;
   }

package/src/Track.ts

@@ -7,7 +7,7 @@ import { getAudioContext, resumeAudioContext } from './utils/audioContext';
 import { createTrackMachine } from './machines/track.machine';
 import { fetchDecodeMachine } from './machines/fetchDecode.machine';
 import type { TrackContext } from './machines/track.machine';
-import type { TrackInfo, TrackMetadata, WebAudioLoadingState, PlaybackType } from './types';
+import type { TrackInfo, TrackMetadata, WebAudioLoadingState, PlaybackType, PlaybackMethod } from './types';
 
 export interface TrackQueueRef {
   onTrackEnded(track: Track): void;
@@ -18,7 +18,8 @@ export interface TrackQueueRef {
   onPlayBlocked(): void;
   onDebug(msg: string): void;
   readonly volume: number;
-  readonly webAudioIsDisabled: boolean;
+  readonly playbackMethod: PlaybackMethod;
+  readonly playbackRate: number;
   readonly currentTrackIndex: number;
 }
 
@@ -42,10 +43,10 @@ export class Track {
   readonly audio: HTMLAudioElement;
 
   // ---- Web Audio nodes -----------------------------------------------------
-  private readonly _webAudioDisabled: boolean;
+  private readonly _playbackMethod: PlaybackMethod;
 
   private get ctx(): AudioContext | null {
-    if (this._webAudioDisabled) return null;
+    if (this._playbackMethod === 'HTML5_ONLY') return null;
     const context = getAudioContext();
     if (context && !this.gainNode) {
       this.gainNode = context.createGain();
@@ -57,8 +58,10 @@ export class Track {
   private gainNode: GainNode | null = null;
   private sourceNode: AudioBufferSourceNode | null = null;
   audioBuffer: AudioBuffer | null = null;
-  /** AudioContext.currentTime when the current source node was started. */
-  private webAudioStartedAt = 0;
+  /** AudioContext.currentTime at the start of the current playback segment. */
+  private _waRefCtxTime = 0;
+  /** Track position (seconds) at the start of the current playback segment. */
+  private _waRefTrackTime = 0;
   /** Track-time (seconds) frozen at the moment of the most recent pause. */
   private pausedAtTrackTime = 0;
   // ---- FSM -----------------------------------------------------------------
@@ -104,7 +107,7 @@ export class Track {
       this._actor.send({ type: 'HTML5_ENDED' });
     };
 
-    this._webAudioDisabled = opts.queue.webAudioIsDisabled;
+    this._playbackMethod = opts.queue.playbackMethod;
 
     const initialContext: TrackContext = {
       trackUrl: this._trackUrl,
@@ -116,10 +119,12 @@ export class Track {
       scheduledStartContextTime: null,
       notifiedLookahead: false,
       fetchStarted: false,
+      pendingPlay: false,
     };
     const machine = createTrackMachine(initialContext).provide({
       guards: {
         canPlayWebAudio: () => !!(this.ctx && this.audioBuffer && this.gainNode),
+        isWebAudioOnly: () => this._playbackMethod === 'WEBAUDIO_ONLY',
       },
       actors: {
         fetchDecode: fetchDecodeMachine.provide({
@@ -150,6 +155,10 @@ export class Track {
         }),
       },
       actions: {
+        triggerFetchForPendingPlay: () => {
+          this.preload();
+          resumeAudioContext();
+        },
         playHtml5: () => this._playHtml5(),
         startSourceNode: () => {
           this._startSourceNode(this.pausedAtTrackTime);
@@ -160,11 +169,13 @@ export class Track {
           this._stopSourceNode();
           this.sourceNode = this.ctx.createBufferSource();
           this.sourceNode.buffer = this.audioBuffer;
+          this.sourceNode.playbackRate.value = this.queueRef.playbackRate;
           this.sourceNode.connect(this.gainNode);
           this.gainNode.connect(this.ctx.destination);
           this.sourceNode.onended = this._handleWebAudioEnded;
           this.sourceNode.start(when, 0);
-          this.webAudioStartedAt = when;
+          this._waRefCtxTime = when;
+          this._waRefTrackTime = 0;
           this.queueRef.onDebug(
             `startScheduledSourceNode track=${this.index} when=${when.toFixed(3)} ctxNow=${this.ctx.currentTime.toFixed(3)} delta=${(when - this.ctx.currentTime).toFixed(3)}s`
           );
@@ -187,7 +198,8 @@ export class Track {
           this.audio.currentTime = 0;
         },
         resetTiming: () => {
-          this.webAudioStartedAt = 0;
+          this._waRefCtxTime = 0;
+          this._waRefTrackTime = 0;
           this.pausedAtTrackTime = 0;
         },
         notifyTrackEnded: () => {
@@ -228,6 +240,17 @@ export class Track {
     this._actor.send({ type: 'SET_VOLUME', volume: vol });
   }
 
+  setPlaybackRate(rate: number): void {
+    // Freeze current track position at the old rate before switching
+    if (this.ctx && this.sourceNode && this._actor.getSnapshot().context.isPlaying) {
+      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;
+  }
+
   preload(): void {
     this.queueRef.onDebug(
       `preload() track=${this.index} state=${this._actor.getSnapshot().value} hasBuffer=${!!this.audioBuffer} hasCtx=${!!this.ctx}`
@@ -296,7 +319,7 @@ export class Track {
     if (snap.value === 'webaudio') {
       if (!snap.context.isPlaying) return this.pausedAtTrackTime;
       if (!this.ctx) return 0;
-      return Math.max(0, this.ctx.currentTime - this.webAudioStartedAt);
+      return Math.max(0, this._waRefTrackTime + (this.ctx.currentTime - this._waRefCtxTime) * this.queueRef.playbackRate);
     }
     return this.audio.currentTime;
   }
@@ -356,6 +379,7 @@ export class Track {
       playbackType: this.playbackType,
       webAudioLoadingState: this.webAudioLoadingState,
       metadata: this.metadata,
+      playbackRate: this.queueRef.playbackRate,
       machineState: this.machineState,
     };
   }
@@ -366,6 +390,7 @@ export class Track {
 
   private _playHtml5(): void {
     if (this.audio.preload !== 'auto') this.audio.preload = 'auto';
+    this.audio.playbackRate = this.queueRef.playbackRate;
     const promise = this.audio.play();
     if (promise) {
       promise.catch((err: unknown) => {
@@ -414,11 +439,13 @@ export class Track {
 
     this.sourceNode = this.ctx.createBufferSource();
     this.sourceNode.buffer = this.audioBuffer;
+    this.sourceNode.playbackRate.value = this.queueRef.playbackRate;
     this.sourceNode.connect(this.gainNode);
     this.gainNode.connect(this.ctx.destination);
     this.sourceNode.onended = this._handleWebAudioEnded;
 
-    this.webAudioStartedAt = this.ctx.currentTime - offset;
+    this._waRefCtxTime = this.ctx.currentTime;
+    this._waRefTrackTime = offset;
     this.sourceNode.start(0, offset);
   }
 

package/src/machines/track.machine.ts

@@ -39,6 +39,8 @@ export interface TrackContext {
   scheduledStartContextTime: number | null;
   notifiedLookahead: boolean;
   fetchStarted: boolean;
+  /** True when PLAY was received in webAudioOnly mode before buffer is ready. */
+  pendingPlay: boolean;
 }
 
 // ---- Events ----------------------------------------------------------------
@@ -76,6 +78,7 @@ export function createTrackMachine(initialContext: TrackContext) {
     },
     guards: {
       canPlayWebAudio: () => false,
+      isWebAudioOnly: () => false,
       canStartFetch: ({ context }) => context.webAudioLoadingState === 'NONE' && !context.fetchStarted,
     },
     actions: {
@@ -94,6 +97,9 @@ export function createTrackMachine(initialContext: TrackContext) {
       resetHtml5Element: () => {},
       resetTiming: () => {},
       notifyTrackEnded: () => {},
+      triggerFetchForPendingPlay: () => {},
+      setPendingPlay: assign({ pendingPlay: () => true }),
+      clearPendingPlay: assign({ pendingPlay: () => false }),
       setIsPlaying: assign({ isPlaying: () => true }),
       clearIsPlaying: assign({ isPlaying: () => false }),
       setLoadingState: assign({ webAudioLoadingState: () => 'LOADING' as WebAudioLoadingState }),
@@ -163,6 +169,7 @@ export function createTrackMachine(initialContext: TrackContext) {
           },
           DEACTIVATE: {
             actions: [
+              'pauseHtml5',
               'resetHtml5Element',
               'resetTiming',
               'stopProgressLoop',
@@ -186,6 +193,10 @@ export function createTrackMachine(initialContext: TrackContext) {
                 'startProgressLoop',
               ],
             },
+            {
+              guard: 'isWebAudioOnly',
+              actions: ['setPendingPlay', 'triggerFetchForPendingPlay'],
+            },
             {
               target: 'html5',
               actions: ['setIsPlaying', 'playHtml5', 'startProgressLoop'],
@@ -210,11 +221,18 @@ export function createTrackMachine(initialContext: TrackContext) {
           BUFFER_LOADING: {
             actions: 'setLoadingState',
           },
-          BUFFER_READY: {
-            actions: 'setLoadedState',
-          },
+          BUFFER_READY: [
+            {
+              guard: ({ context }: { context: TrackContext }) => context.pendingPlay,
+              target: 'webaudio',
+              actions: ['clearPendingPlay', 'setPlayingWebAudio', 'startSourceNode', 'startProgressLoop'],
+            },
+            {
+              actions: 'setLoadedState',
+            },
+          ],
           BUFFER_ERROR: {
-            actions: 'setErrorState',
+            actions: ['setErrorState', 'clearPendingPlay'],
           },
           URL_RESOLVED: {
             actions: 'setResolvedUrl',
@@ -289,13 +307,20 @@ export function createTrackMachine(initialContext: TrackContext) {
           BUFFER_LOADING: {
             actions: 'setLoadingState',
           },
-          BUFFER_READY: {
-            target: 'idle',
-            actions: 'setLoadedState',
-          },
+          BUFFER_READY: [
+            {
+              guard: ({ context }: { context: TrackContext }) => context.pendingPlay,
+              target: 'webaudio',
+              actions: ['clearPendingPlay', 'setPlayingWebAudio', 'startSourceNode', 'startProgressLoop'],
+            },
+            {
+              target: 'idle',
+              actions: 'setLoadedState',
+            },
+          ],
           BUFFER_ERROR: {
             target: 'idle',
-            actions: 'setErrorState',
+            actions: ['setErrorState', 'clearPendingPlay'],
           },
           PLAY: [
             {
@@ -307,6 +332,10 @@ export function createTrackMachine(initialContext: TrackContext) {
                 'startProgressLoop',
               ],
             },
+            {
+              guard: 'isWebAudioOnly',
+              actions: ['setPendingPlay', 'triggerFetchForPendingPlay'],
+            },
             {
               target: 'html5',
               actions: ['setIsPlaying', 'playHtml5', 'startProgressLoop'],

package/src/types.ts

@@ -4,6 +4,14 @@
 
 export type PlaybackType = 'HTML5' | 'WEBAUDIO';
 
+/**
+ * Controls how audio is rendered.
+ * - `'HYBRID'` (default): Starts with HTML5 audio, then switches to Web Audio after decode. Best for remote files.
+ * - `'HTML5_ONLY'`: Uses HTML5 audio exclusively. Gapless playback is not available.
+ * - `'WEBAUDIO_ONLY'`: Uses Web Audio API exclusively. Audio must fully buffer before playing — only use for very small or local files.
+ */
+export type PlaybackMethod = 'HYBRID' | 'HTML5_ONLY' | 'WEBAUDIO_ONLY';
+
 export type WebAudioLoadingState = 'NONE' | 'LOADING' | 'LOADED' | 'ERROR';
 
 /** Metadata attached to a track (arbitrary user data). */
@@ -36,14 +44,25 @@ export interface GaplessOptions {
   /** Called when autoplay is blocked by the browser. */
   onPlayBlocked?: () => void;
   /**
-   * Set true to disable Web Audio API entirely and use HTML5 audio only.
-   * Gapless playback will not be available in this mode.
+   * Controls how audio is rendered.
+   * - `'HYBRID'` (default): Starts with HTML5 audio, switches to Web Audio after decode. Best for remote files.
+   * - `'HTML5_ONLY'`: HTML5 audio only. Gapless playback is not available.
+   * - `'WEBAUDIO_ONLY'`: Web Audio API only. Audio must fully buffer before playing.
    */
-  webAudioIsDisabled?: boolean;
+  playbackMethod?: PlaybackMethod;
   /** Per-track metadata (aligned to the tracks array by index). */
   trackMetadata?: TrackMetadata[];
   /** Initial volume, 0.0–1.0. Defaults to 1. */
   volume?: number;
+  /**
+   * Number of tracks to preload ahead of the current track.
+   * Defaults to 2. Set to 0 to disable preloading.
+   */
+  preloadNumTracks?: number;
+  /**
+   * Initial playback rate, 0.25–4.0. Defaults to 1.
+   */
+  playbackRate?: number;
 }
 
 /** Options for dynamically adding a track. */
@@ -82,6 +101,8 @@ export interface TrackInfo {
   webAudioLoadingState: WebAudioLoadingState;
   /** Arbitrary metadata supplied when the track was added. */
   metadata?: TrackMetadata;
+  /** Current playback rate. */
+  playbackRate: number;
   /** Current xstate machine state for this track (e.g. 'idle', 'html5', 'webaudio'). */
   machineState: string;
 }