gapless.js 2.2.3 → 4.0.0

package/src/machines/queue.machine.ts

@@ -0,0 +1,218 @@
+// ---------------------------------------------------------------------------
+// QueueMachine — top-level queue state (xstate v5)
+//
+// States:
+//   idle     No tracks, or not yet started.
+//   playing  A track is actively playing.
+//   paused   Explicitly paused by the user.
+//   ended    The last track in the queue has finished.
+//
+// Root-level `on:` eliminates the handler duplication that plagued v2.
+// ---------------------------------------------------------------------------
+
+import { setup, assign } from 'xstate';
+
+// ---- Context ---------------------------------------------------------------
+
+export interface QueueContext {
+  currentTrackIndex: number;
+  trackCount: number;
+}
+
+// ---- Events ----------------------------------------------------------------
+
+export type QueueEvent =
+  | { type: 'PLAY' }
+  | { type: 'PAUSE' }
+  | { type: 'TOGGLE' }
+  | { type: 'NEXT' }
+  | { type: 'PREVIOUS' }
+  | { type: 'GOTO'; index: number; playImmediately?: boolean }
+  | { type: 'SEEK'; time: number }
+  | { type: 'SET_VOLUME'; volume: number }
+  | { type: 'ADD_TRACK' }
+  | { type: 'REMOVE_TRACK'; index: number }
+  | { type: 'TRACK_ENDED' }
+  | { type: 'TRACK_LOADED'; index: number };
+
+// ---- Machine ---------------------------------------------------------------
+
+export function createQueueMachine(initialContext: QueueContext) {
+  return setup({
+    types: {
+      context: {} as QueueContext,
+      events: {} as QueueEvent,
+    },
+    guards: {
+      hasNextTrack: ({ context }) => context.currentTrackIndex + 1 < context.trackCount,
+      playImmediately: ({ event }) =>
+        !!(event as { type: 'GOTO'; playImmediately?: boolean }).playImmediately,
+    },
+  }).createMachine({
+    id: 'queue',
+    initial: 'idle',
+    context: initialContext,
+
+    // Global handlers — shared across all states
+    on: {
+      ADD_TRACK: {
+        actions: assign({ trackCount: ({ context }) => context.trackCount + 1 }),
+      },
+      REMOVE_TRACK: {
+        actions: assign({
+          trackCount: ({ context }) => Math.max(0, context.trackCount - 1),
+          currentTrackIndex: ({ context, event }) => {
+            const e = event as { type: 'REMOVE_TRACK'; index: number };
+            if (e.index < context.currentTrackIndex) {
+              return Math.max(0, context.currentTrackIndex - 1);
+            }
+            return context.currentTrackIndex;
+          },
+        }),
+      },
+    },
+
+    states: {
+      // -----------------------------------------------------------------
+      // idle
+      // -----------------------------------------------------------------
+      idle: {
+        on: {
+          PLAY: { target: 'playing' },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              target: 'playing',
+              actions: assign({
+                currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+              }),
+            },
+            {
+              target: 'paused',
+              actions: assign({
+                currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+              }),
+            },
+          ],
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // playing
+      // -----------------------------------------------------------------
+      playing: {
+        on: {
+          PAUSE: { target: 'paused' },
+          TOGGLE: { target: 'paused' },
+          NEXT: {
+            actions: assign({
+              currentTrackIndex: ({ context }) => {
+                const next = context.currentTrackIndex + 1;
+                return next < context.trackCount ? next : context.currentTrackIndex;
+              },
+            }),
+          },
+          PREVIOUS: {
+            actions: assign({
+              currentTrackIndex: ({ context }) => Math.max(0, context.currentTrackIndex - 1),
+            }),
+          },
+          GOTO: {
+            actions: assign({
+              currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+            }),
+          },
+          SEEK: {},
+          TRACK_ENDED: [
+            {
+              guard: 'hasNextTrack',
+              target: 'playing',
+              actions: assign({
+                currentTrackIndex: ({ context }) => context.currentTrackIndex + 1,
+              }),
+            },
+            { target: 'ended' },
+          ],
+          TRACK_LOADED: {},
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // paused
+      // -----------------------------------------------------------------
+      paused: {
+        on: {
+          PLAY: { target: 'playing' },
+          TOGGLE: { target: 'playing' },
+          NEXT: {
+            actions: assign({
+              currentTrackIndex: ({ context }) => {
+                const next = context.currentTrackIndex + 1;
+                return next < context.trackCount ? next : context.currentTrackIndex;
+              },
+            }),
+          },
+          PREVIOUS: {
+            actions: assign({
+              currentTrackIndex: ({ context }) => Math.max(0, context.currentTrackIndex - 1),
+            }),
+          },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              target: 'playing',
+              actions: assign({
+                currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+              }),
+            },
+            {
+              actions: assign({
+                currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+              }),
+            },
+          ],
+          SEEK: {},
+          TRACK_ENDED: [
+            {
+              guard: 'hasNextTrack',
+              target: 'paused',
+              actions: assign({
+                currentTrackIndex: ({ context }) => context.currentTrackIndex + 1,
+              }),
+            },
+            { target: 'ended' },
+          ],
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // ended
+      // -----------------------------------------------------------------
+      ended: {
+        on: {
+          PLAY: {
+            target: 'playing',
+            actions: assign({ currentTrackIndex: () => 0 }),
+          },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              target: 'playing',
+              actions: assign({
+                currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+              }),
+            },
+            {
+              target: 'paused',
+              actions: assign({
+                currentTrackIndex: ({ event }) => (event as { type: 'GOTO'; index: number }).index,
+              }),
+            },
+          ],
+        },
+      },
+    },
+  });
+}
+
+export type QueueMachine = ReturnType<typeof createQueueMachine>;

package/src/machines/track.machine.ts

@@ -0,0 +1,227 @@
+// ---------------------------------------------------------------------------
+// TrackMachine — per-track audio state (xstate v5)
+//
+// States:
+//   idle        Initial state. Audio nodes not yet initialised.
+//   html5       HTML5 Audio is playing. Web Audio fetch+decode may be in progress.
+//   loading     Track is preloaded (not yet playing). Decode in progress.
+//   webaudio    AudioBufferSourceNode is the active output.
+//
+// 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)
+//   #4: Removed dead error state (webAudioLoadingState: 'ERROR' is sufficient)
+// ---------------------------------------------------------------------------
+
+import { setup, assign } from 'xstate';
+import type { WebAudioLoadingState, PlaybackType } from '../types';
+
+// ---- Context ---------------------------------------------------------------
+
+export interface TrackContext {
+  trackUrl: string;
+  resolvedUrl: string;
+  skipHEAD: boolean;
+  playbackType: PlaybackType;
+  webAudioLoadingState: WebAudioLoadingState;
+  webAudioStartedAt: number;
+  pausedAtTrackTime: number;
+  isPlaying: boolean;
+}
+
+// ---- Events ----------------------------------------------------------------
+
+export type TrackEvent =
+  | { type: 'ACTIVATE' }
+  | { type: 'DEACTIVATE' }
+  | { type: 'PRELOAD' }
+  | { type: 'BUFFER_LOADING' }
+  | { type: 'PLAY' }
+  | { type: 'PLAY_WEBAUDIO' }
+  | { type: 'PAUSE' }
+  | { type: 'SEEK'; time: number }
+  | { type: 'SET_VOLUME'; volume: number }
+  | { type: 'BUFFER_READY' }
+  | { type: 'BUFFER_ERROR' }
+  | { type: 'HTML5_ENDED' }
+  | { type: 'WEBAUDIO_ENDED' }
+  | { type: 'URL_RESOLVED'; url: string };
+
+// ---- Machine ---------------------------------------------------------------
+
+export function createTrackMachine(initialContext: TrackContext) {
+  return setup({
+    types: {
+      context: {} as TrackContext,
+      events: {} as TrackEvent,
+    },
+  }).createMachine({
+    id: 'track',
+    initial: 'idle',
+    context: initialContext,
+
+    states: {
+      // -----------------------------------------------------------------
+      // idle: constructed but not started
+      // -----------------------------------------------------------------
+      idle: {
+        on: {
+          HTML5_ENDED: {},
+          PLAY: {
+            target: 'html5',
+            actions: assign({ isPlaying: () => true }),
+          },
+          PLAY_WEBAUDIO: {
+            target: 'webaudio',
+            actions: assign({
+              isPlaying: () => true,
+              webAudioLoadingState: () => 'LOADED' as WebAudioLoadingState,
+              playbackType: () => 'WEBAUDIO' as PlaybackType,
+            }),
+          },
+          PRELOAD: { target: 'loading' },
+          BUFFER_LOADING: {
+            actions: assign({ webAudioLoadingState: () => 'LOADING' as WebAudioLoadingState }),
+          },
+          URL_RESOLVED: {
+            actions: assign({
+              resolvedUrl: ({ event }) => (event as { type: 'URL_RESOLVED'; url: string }).url,
+            }),
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // html5: HTML5 Audio is playing; WebAudio decode may be in progress
+      // -----------------------------------------------------------------
+      html5: {
+        on: {
+          PAUSE: {
+            actions: assign({ isPlaying: () => false }),
+          },
+          PLAY: {
+            actions: assign({ isPlaying: () => true }),
+          },
+          BUFFER_LOADING: {
+            actions: assign({ webAudioLoadingState: () => 'LOADING' as WebAudioLoadingState }),
+          },
+          PLAY_WEBAUDIO: {
+            target: 'webaudio',
+            actions: assign({
+              isPlaying: () => true,
+              webAudioLoadingState: () => 'LOADED' as WebAudioLoadingState,
+              playbackType: () => 'WEBAUDIO' as PlaybackType,
+            }),
+          },
+          // Bug #2 fix: BUFFER_READY in html5 stays in html5, only updates loading state.
+          // The actual switchover to webaudio only happens via explicit PLAY_WEBAUDIO.
+          BUFFER_READY: {
+            actions: assign({
+              webAudioLoadingState: () => 'LOADED' as WebAudioLoadingState,
+            }),
+          },
+          BUFFER_ERROR: {
+            actions: assign({
+              webAudioLoadingState: () => 'ERROR' as WebAudioLoadingState,
+            }),
+          },
+          SEEK: {
+            actions: assign({
+              pausedAtTrackTime: ({ event }) => (event as { type: 'SEEK'; time: number }).time,
+            }),
+          },
+          HTML5_ENDED: {
+            target: 'idle',
+            actions: assign({ isPlaying: () => false }),
+          },
+          URL_RESOLVED: {
+            actions: assign({
+              resolvedUrl: ({ event }) => (event as { type: 'URL_RESOLVED'; url: string }).url,
+            }),
+          },
+          DEACTIVATE: {
+            target: 'loading',
+            actions: assign({ isPlaying: () => false }),
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // loading: preloading in background (not the active track yet)
+      // -----------------------------------------------------------------
+      loading: {
+        on: {
+          BUFFER_LOADING: {
+            actions: assign({ webAudioLoadingState: () => 'LOADING' as WebAudioLoadingState }),
+          },
+          BUFFER_READY: {
+            target: 'idle',
+            actions: assign({
+              webAudioLoadingState: () => 'LOADED' as WebAudioLoadingState,
+            }),
+          },
+          BUFFER_ERROR: {
+            target: 'idle',
+            actions: assign({
+              webAudioLoadingState: () => 'ERROR' as WebAudioLoadingState,
+            }),
+          },
+          PLAY: {
+            target: 'html5',
+            actions: assign({ isPlaying: () => true }),
+          },
+          PLAY_WEBAUDIO: {
+            target: 'webaudio',
+            actions: assign({
+              isPlaying: () => true,
+              webAudioLoadingState: () => 'LOADED' as WebAudioLoadingState,
+              playbackType: () => 'WEBAUDIO' as PlaybackType,
+            }),
+          },
+          URL_RESOLVED: {
+            actions: assign({
+              resolvedUrl: ({ event }) => (event as { type: 'URL_RESOLVED'; url: string }).url,
+            }),
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // webaudio: AudioBufferSourceNode is driving output
+      // -----------------------------------------------------------------
+      webaudio: {
+        on: {
+          PAUSE: {
+            actions: assign({ isPlaying: () => false }),
+          },
+          PLAY: {
+            actions: assign({ isPlaying: () => true }),
+          },
+          PLAY_WEBAUDIO: {
+            actions: assign({
+              isPlaying: () => true,
+              playbackType: () => 'WEBAUDIO' as PlaybackType,
+            }),
+          },
+          SEEK: {
+            actions: assign({
+              pausedAtTrackTime: ({ event }) => (event as { type: 'SEEK'; time: number }).time,
+            }),
+          },
+          SET_VOLUME: {},
+          WEBAUDIO_ENDED: {
+            target: 'idle',
+            actions: assign({ isPlaying: () => false }),
+          },
+          // Bug #3 fix: DEACTIVATE from webaudio → idle (was staying in webaudio)
+          DEACTIVATE: {
+            target: 'idle',
+            actions: assign({ isPlaying: () => false }),
+          },
+        },
+      },
+    },
+  });
+}
+
+export type TrackMachine = ReturnType<typeof createTrackMachine>;

package/src/types.ts

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// Public types for gapless.js
+// ---------------------------------------------------------------------------
+
+export type PlaybackType = 'HTML5' | 'WEBAUDIO';
+
+export type WebAudioLoadingState = 'NONE' | 'LOADING' | 'LOADED' | 'ERROR';
+
+/** Metadata attached to a track (arbitrary user data). */
+export interface TrackMetadata {
+  title?: string;
+  artist?: string;
+  album?: string;
+  artwork?: MediaImage[];
+  [key: string]: unknown;
+}
+
+/** Options accepted by the Queue constructor. */
+export interface GaplessOptions {
+  /** Initial list of track URLs. */
+  tracks?: string[];
+  /** Called at ~60fps while playing. */
+  onProgress?: (info: TrackInfo) => void;
+  /** Called when the last track in the queue ends. */
+  onEnded?: () => void;
+  /** Called when the queue advances to the next track. */
+  onPlayNextTrack?: (info: TrackInfo) => void;
+  /** Called when the queue goes back to the previous track. */
+  onPlayPreviousTrack?: (info: TrackInfo) => void;
+  /** Called whenever a new track becomes the current track. */
+  onStartNewTrack?: (info: TrackInfo) => void;
+  /** Called on HTML5 audio errors. */
+  onError?: (error: Error) => void;
+  /** Called with internal debug messages. Only use for development. */
+  onDebug?: (msg: string) => void;
+  /** 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.
+   */
+  webAudioIsDisabled?: boolean;
+  /** Per-track metadata (aligned to the tracks array by index). */
+  trackMetadata?: TrackMetadata[];
+  /** Initial volume, 0.0–1.0. Defaults to 1. */
+  volume?: number;
+}
+
+/** Options for dynamically adding a track. */
+export interface AddTrackOptions {
+  /**
+   * Skip the HEAD request used to resolve redirects.
+   * Set true when the URL is already a direct, final URL.
+   */
+  skipHEAD?: boolean;
+  metadata?: TrackMetadata;
+}
+
+/**
+ * A plain-data snapshot of a track's current state.
+ * Returned by Queue getters and passed to callbacks.
+ * No methods — pure data.
+ */
+export interface TrackInfo {
+  /** Zero-based position of this track in the queue. */
+  index: number;
+  /** Current playback position in seconds. */
+  currentTime: number;
+  /** Total duration in seconds (NaN until loaded). */
+  duration: number;
+  /** True if currently playing. */
+  isPlaying: boolean;
+  /** True if explicitly paused. */
+  isPaused: boolean;
+  /** Current volume, 0.0–1.0. */
+  volume: number;
+  /** The resolved URL of the audio file. */
+  trackUrl: string;
+  /** Which backend is currently producing sound. */
+  playbackType: PlaybackType;
+  /** Whether the Web Audio buffer has been decoded. */
+  webAudioLoadingState: WebAudioLoadingState;
+  /** Arbitrary metadata supplied when the track was added. */
+  metadata?: TrackMetadata;
+  /** Current xstate machine state for this track (e.g. 'idle', 'html5', 'webaudio'). */
+  machineState: string;
+}

package/src/utils/audioContext.ts

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// Singleton AudioContext manager
+//
+// A single AudioContext is shared across all Track instances. This is
+// essential: all AudioBufferSourceNodes must share the same context so that
+// audioContext.currentTime is a common monotonic clock, enabling
+// sample-accurate scheduling of back-to-back tracks.
+// ---------------------------------------------------------------------------
+
+const isBrowser = typeof window !== 'undefined';
+
+let _audioContext: AudioContext | null | undefined = undefined;
+
+function createAudioContext(): AudioContext | null {
+  if (!isBrowser) return null;
+  const Ctor =
+    (window as unknown as { AudioContext?: typeof AudioContext; webkitAudioContext?: typeof AudioContext })
+      .AudioContext ??
+    (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+  if (!Ctor) return null;
+  return new Ctor();
+}
+
+/**
+ * Return the shared AudioContext if it has already been created, otherwise null.
+ *
+ * Does NOT create the context — call resumeAudioContext() from a user-gesture
+ * handler to create and resume it. This prevents the browser warning:
+ * "An AudioContext was prevented from starting automatically."
+ */
+export function getAudioContext(): AudioContext | null {
+  // undefined  = never initialised (return null without creating)
+  // null       = explicitly disabled or unavailable
+  // AudioContext = ready to use
+  if (_audioContext === undefined) return null;
+  return _audioContext;
+}
+
+/**
+ * Create (if needed) and resume the AudioContext.
+ * Must be called from a user-gesture handler (click, keydown, etc.).
+ * Safe to call multiple times — subsequent calls are cheap no-ops.
+ */
+export function resumeAudioContext(): Promise<void> {
+  if (_audioContext === undefined) {
+    _audioContext = createAudioContext();
+  }
+  const ctx = _audioContext;
+  if (ctx && ctx.state === 'suspended') {
+    return ctx.resume();
+  }
+  return Promise.resolve();
+}
+
+/**
+ * Reset the cached AudioContext — used in tests so each test gets a fresh mock.
+ * @internal
+ */
+export function _resetAudioContext(): void {
+  _audioContext = undefined;
+}
+
+/**
+ * Directly set the cached AudioContext — used in tests to inject a mock instance.
+ * @internal
+ */
+export function _setAudioContext(ctx: AudioContext | null): void {
+  _audioContext = ctx;
+}

package/src/utils/mediaSession.ts

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// Media Session API integration
+//
+// Provides OS-level media controls (lock screen, notification shade, keyboard
+// media keys). Gracefully no-ops when the API is unavailable.
+// ---------------------------------------------------------------------------
+
+import type { TrackMetadata } from '../types';
+
+const hasMediaSession =
+  typeof navigator !== 'undefined' && 'mediaSession' in navigator;
+
+export interface MediaSessionHandlers {
+  onPlay: () => void;
+  onPause: () => void;
+  onNext: () => void;
+  onPrevious: () => void;
+  onSeek: (time: number) => void;
+}
+
+/** Register Media Session action handlers. Call once after construction. */
+export function setupMediaSession(handlers: MediaSessionHandlers): void {
+  if (!hasMediaSession) return;
+  const { mediaSession } = navigator;
+  mediaSession.setActionHandler('play', handlers.onPlay);
+  mediaSession.setActionHandler('pause', handlers.onPause);
+  mediaSession.setActionHandler('nexttrack', handlers.onNext);
+  mediaSession.setActionHandler('previoustrack', handlers.onPrevious);
+  mediaSession.setActionHandler('seekto', (details) => {
+    if (details.seekTime != null) handlers.onSeek(details.seekTime);
+  });
+}
+
+/** Update the OS metadata display (title, artist, album, artwork). */
+export function updateMediaSessionMetadata(metadata?: TrackMetadata): void {
+  if (!hasMediaSession) return;
+  if (!metadata) {
+    navigator.mediaSession.metadata = null;
+    return;
+  }
+  navigator.mediaSession.metadata = new MediaMetadata({
+    title: metadata.title ?? '',
+    artist: metadata.artist ?? '',
+    album: metadata.album ?? '',
+    artwork: metadata.artwork ?? [],
+  });
+}
+
+/** Sync the OS playback state indicator (playing / paused). */
+export function updateMediaSessionPlaybackState(
+  isPlaying: boolean,
+): void {
+  if (!hasMediaSession) return;
+  navigator.mediaSession.playbackState = isPlaying ? 'playing' : 'paused';
+}

package/CHANGELOG.md

@@ -1,29 +0,0 @@
-### 2.2.3
-  * Add option to specify `mode` for `fetch()` operations
-
-### 2.2.2
-  * Allow currentTrack to be undefined
-
-### 2.2.1
-  * Use `globalThis` instead of `window` to access `AudioContext`
-
-### 2.2.0
-  * Remove `tracks` from Queue constructor
-  * Expose Queue.tracks as public
-  * Transpile as commonjs module
-
-### 2.1.0
-  Update dependencies and code style
-
-  * Format with prettier
-  * Order methods and properties based on accessor type
-  * Add explicit return types to functions
-  * Remove deprecated seekToEnd() function
-
-### 2.0.0
-  * Convert to typescript
-  * Fix a handful of bugs as part of the typescript conversion
-
-### 1.0.0
-
-  * Initial release - [Original source](https://github.com/RelistenNet/gapless.js)