gapless 4.0.5

package/src/machines/fetchDecode.machine.ts

@@ -0,0 +1,130 @@
+// ---------------------------------------------------------------------------
+// FetchDecodeMachine — child actor for the fetch + decode pipeline
+//
+// States:  resolvingUrl → fetching → decoding → done | error
+//
+// Spawned by TrackMachine via START_FETCH. Sends BUFFER_READY, BUFFER_ERROR,
+// and URL_RESOLVED back to the parent — the same events TrackMachine already
+// handles. Promise implementations are no-op defaults, provided by Track.ts
+// via .provide().
+//
+// xstate v5 automatically passes an AbortSignal to fromPromise actors, so
+// when the parent stops (destroy), in-flight fetches are aborted for free.
+// ---------------------------------------------------------------------------
+
+import { setup, assign, sendParent, fromPromise } from 'xstate';
+
+// ---- Context ---------------------------------------------------------------
+
+export interface FetchDecodeContext {
+  trackUrl: string;
+  resolvedUrl: string;
+  skipHEAD: boolean;
+}
+
+// ---- Machine ---------------------------------------------------------------
+
+export const fetchDecodeMachine = setup({
+  types: {
+    context: {} as FetchDecodeContext,
+    input: {} as FetchDecodeContext,
+  },
+  actors: {
+    resolveUrl: fromPromise<string | null, { trackUrl: string }>(async () => null),
+    fetchAudio: fromPromise<void, { resolvedUrl: string }>(async () => {}),
+    decodeAudio: fromPromise<void, void>(async () => {}),
+  },
+  guards: {
+    shouldSkipHEAD: ({ context }) => context.skipHEAD,
+  },
+}).createMachine({
+  id: 'fetchDecode',
+  initial: 'resolvingUrl',
+  // Note: xstate v5 internally calls assign() when initialising a child
+  // actor with a context function, which produces a false-positive
+  // "Custom actions should not call assign()" warning when this machine
+  // is spawned from a parent. This is harmless and cannot be avoided.
+  context: ({ input }) => ({
+    trackUrl: input.trackUrl,
+    resolvedUrl: input.resolvedUrl,
+    skipHEAD: input.skipHEAD,
+  }),
+
+  states: {
+    // -----------------------------------------------------------------
+    // resolvingUrl: HEAD request to resolve redirects
+    // -----------------------------------------------------------------
+    resolvingUrl: {
+      always: {
+        guard: 'shouldSkipHEAD',
+        target: 'fetching',
+      },
+      invoke: {
+        id: 'resolveUrl',
+        src: 'resolveUrl',
+        input: ({ context }) => ({ trackUrl: context.trackUrl }),
+        onDone: {
+          target: 'fetching',
+          actions: [
+            assign({
+              resolvedUrl: ({ event, context }) => event.output ?? context.resolvedUrl,
+              skipHEAD: () => true,
+            }),
+            sendParent(({ event, context }) => {
+              const url = event.output;
+              return { type: 'URL_RESOLVED' as const, url: url ?? context.resolvedUrl };
+            }),
+          ],
+        },
+        onError: {
+          // HEAD failed — non-fatal, fall back to original URL
+          target: 'fetching',
+          actions: assign({ skipHEAD: () => true }),
+        },
+      },
+    },
+
+    // -----------------------------------------------------------------
+    // fetching: GET the audio data
+    // -----------------------------------------------------------------
+    fetching: {
+      invoke: {
+        id: 'fetchAudio',
+        src: 'fetchAudio',
+        input: ({ context }) => ({ resolvedUrl: context.resolvedUrl }),
+        onDone: 'decoding',
+        onError: {
+          target: 'error',
+          actions: sendParent({ type: 'BUFFER_ERROR' }),
+        },
+      },
+    },
+
+    // -----------------------------------------------------------------
+    // decoding: decodeAudioData on the ArrayBuffer
+    // -----------------------------------------------------------------
+    decoding: {
+      invoke: {
+        id: 'decodeAudio',
+        src: 'decodeAudio',
+        input: () => {},
+        onDone: {
+          target: 'done',
+          actions: sendParent({ type: 'BUFFER_READY' }),
+        },
+        onError: {
+          target: 'error',
+          actions: sendParent({ type: 'BUFFER_ERROR' }),
+        },
+      },
+    },
+
+    // -----------------------------------------------------------------
+    // Terminal states
+    // -----------------------------------------------------------------
+    done: { type: 'final' },
+    error: { type: 'final' },
+  },
+});
+
+export type FetchDecodeMachine = typeof fetchDecodeMachine;

package/src/machines/queue.machine.ts

@@ -0,0 +1,387 @@
+// ---------------------------------------------------------------------------
+// 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.
+//
+// Named actions (no-op defaults here, real implementations via .provide()):
+//   Actions before assign() see the OLD context (e.g. deactivateCurrent
+//   sees the old currentTrackIndex). Actions after assign() see the NEW
+//   context (e.g. activateAndPlayCurrent sees the incremented index).
+//   Implementations MUST use the ({ context }) parameter, NOT getSnapshot().
+// ---------------------------------------------------------------------------
+
+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,
+    },
+    actions: {
+      // --- named assign actions (avoids mixing inline assign with custom actions) ---
+      incrementTrackCount: assign({
+        trackCount: ({ context }) => context.trackCount + 1,
+      }),
+      decrementTrackCount: 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;
+        },
+      }),
+      gotoTrackIndex: assign({
+        currentTrackIndex: ({ event }) =>
+          (event as { type: 'GOTO'; index: number }).index,
+      }),
+      advanceToNextTrack: assign({
+        currentTrackIndex: ({ context }) => {
+          const next = context.currentTrackIndex + 1;
+          return next < context.trackCount ? next : context.currentTrackIndex;
+        },
+      }),
+      goToPreviousTrack: assign({
+        currentTrackIndex: ({ context }) => Math.max(0, context.currentTrackIndex - 1),
+      }),
+      advanceOnTrackEnd: assign({
+        currentTrackIndex: ({ context }) => context.currentTrackIndex + 1,
+      }),
+      resetToFirstTrack: assign({
+        currentTrackIndex: () => 0,
+      }),
+      // --- side-effect actions (no-op defaults, provided by Queue.ts) ---
+      deactivateCurrent: () => {},
+      deactivateEndedTrack: () => {},
+      activateAndPlayCurrent: () => {},
+      playOrContinueGapless: () => {},
+      cancelAllGapless: () => {},
+      notifyStartNewTrack: () => {},
+      notifyPlayNextTrack: () => {},
+      notifyPlayPreviousTrack: () => {},
+      notifyEnded: () => {},
+      updateMediaSessionMetadata: () => {},
+      preloadAhead: () => {},
+      playCurrent: () => {},
+      pauseCurrent: () => {},
+      seekCurrent: () => {},
+      seekCurrentToZero: () => {},
+      scheduleGapless: () => {},
+      cancelScheduledGapless: () => {},
+      cancelAndRescheduleGapless: () => {},
+    },
+  }).createMachine({
+    id: 'queue',
+    initial: 'idle',
+    context: initialContext,
+
+    // Global handlers — shared across all states
+    on: {
+      ADD_TRACK: {
+        actions: 'incrementTrackCount',
+      },
+      REMOVE_TRACK: {
+        actions: 'decrementTrackCount',
+      },
+    },
+
+    states: {
+      // -----------------------------------------------------------------
+      // idle
+      // -----------------------------------------------------------------
+      idle: {
+        on: {
+          PLAY: {
+            target: 'playing',
+            actions: ['playCurrent', 'updateMediaSessionMetadata', 'preloadAhead', 'scheduleGapless'],
+          },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              target: 'playing',
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'activateAndPlayCurrent',
+                'notifyStartNewTrack',
+                'updateMediaSessionMetadata',
+                'preloadAhead',
+              ],
+            },
+            {
+              target: 'paused',
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'seekCurrentToZero',
+                'preloadAhead',
+              ],
+            },
+          ],
+          TRACK_LOADED: {
+            actions: ['preloadAhead'],
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // playing
+      // -----------------------------------------------------------------
+      playing: {
+        on: {
+          PAUSE: {
+            target: 'paused',
+            actions: ['cancelScheduledGapless', 'pauseCurrent'],
+          },
+          TOGGLE: {
+            target: 'paused',
+            actions: ['cancelScheduledGapless', 'pauseCurrent'],
+          },
+          NEXT: {
+            actions: [
+              'deactivateCurrent',
+              'cancelAllGapless',
+              'advanceToNextTrack',
+              'activateAndPlayCurrent',
+              'notifyStartNewTrack',
+              'notifyPlayNextTrack',
+              'updateMediaSessionMetadata',
+              'preloadAhead',
+            ],
+          },
+          PREVIOUS: {
+            actions: [
+              'deactivateCurrent',
+              'cancelAllGapless',
+              'goToPreviousTrack',
+              'activateAndPlayCurrent',
+              'notifyStartNewTrack',
+              'notifyPlayPreviousTrack',
+              'updateMediaSessionMetadata',
+              'preloadAhead',
+            ],
+          },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'activateAndPlayCurrent',
+                'notifyStartNewTrack',
+                'updateMediaSessionMetadata',
+                'preloadAhead',
+              ],
+            },
+            {
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'seekCurrentToZero',
+                'preloadAhead',
+              ],
+            },
+          ],
+          SEEK: {
+            actions: ['seekCurrent', 'cancelAndRescheduleGapless'],
+          },
+          TRACK_ENDED: [
+            {
+              guard: 'hasNextTrack',
+              target: 'playing',
+              actions: [
+                'deactivateEndedTrack',
+                'advanceOnTrackEnd',
+                'playOrContinueGapless',
+                'notifyStartNewTrack',
+                'notifyPlayNextTrack',
+                'updateMediaSessionMetadata',
+                'preloadAhead',
+              ],
+            },
+            {
+              target: 'ended',
+              actions: ['deactivateEndedTrack', 'notifyEnded'],
+            },
+          ],
+          TRACK_LOADED: {
+            actions: ['scheduleGapless', 'preloadAhead'],
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // paused
+      // -----------------------------------------------------------------
+      paused: {
+        on: {
+          PLAY: {
+            target: 'playing',
+            actions: ['playCurrent', 'updateMediaSessionMetadata', 'preloadAhead', 'scheduleGapless'],
+          },
+          TOGGLE: {
+            target: 'playing',
+            actions: ['playCurrent', 'updateMediaSessionMetadata', 'preloadAhead', 'scheduleGapless'],
+          },
+          NEXT: {
+            actions: [
+              'deactivateCurrent',
+              'cancelAllGapless',
+              'advanceToNextTrack',
+              'activateAndPlayCurrent',
+              'notifyStartNewTrack',
+              'notifyPlayNextTrack',
+              'updateMediaSessionMetadata',
+              'preloadAhead',
+            ],
+          },
+          PREVIOUS: {
+            actions: [
+              'deactivateCurrent',
+              'cancelAllGapless',
+              'goToPreviousTrack',
+              'activateAndPlayCurrent',
+              'notifyStartNewTrack',
+              'notifyPlayPreviousTrack',
+              'updateMediaSessionMetadata',
+              'preloadAhead',
+            ],
+          },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              target: 'playing',
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'activateAndPlayCurrent',
+                'notifyStartNewTrack',
+                'updateMediaSessionMetadata',
+                'preloadAhead',
+              ],
+            },
+            {
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'seekCurrentToZero',
+                'preloadAhead',
+              ],
+            },
+          ],
+          SEEK: {
+            actions: ['seekCurrent'],
+          },
+          TRACK_ENDED: [
+            {
+              guard: 'hasNextTrack',
+              target: 'paused',
+              actions: [
+                'deactivateEndedTrack',
+                'advanceOnTrackEnd',
+                'notifyStartNewTrack',
+                'updateMediaSessionMetadata',
+              ],
+            },
+            {
+              target: 'ended',
+              actions: ['deactivateEndedTrack', 'notifyEnded'],
+            },
+          ],
+          TRACK_LOADED: {
+            actions: ['preloadAhead'],
+          },
+        },
+      },
+
+      // -----------------------------------------------------------------
+      // ended
+      // -----------------------------------------------------------------
+      ended: {
+        on: {
+          PLAY: {
+            target: 'playing',
+            actions: [
+              'resetToFirstTrack',
+              'playCurrent',
+              'updateMediaSessionMetadata',
+              'preloadAhead',
+              'scheduleGapless',
+            ],
+          },
+          GOTO: [
+            {
+              guard: 'playImmediately',
+              target: 'playing',
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'activateAndPlayCurrent',
+                'notifyStartNewTrack',
+                'updateMediaSessionMetadata',
+                'preloadAhead',
+              ],
+            },
+            {
+              target: 'paused',
+              actions: [
+                'deactivateCurrent',
+                'cancelAllGapless',
+                'gotoTrackIndex',
+                'seekCurrentToZero',
+                'preloadAhead',
+              ],
+            },
+          ],
+        },
+      },
+    },
+  });
+}
+
+export type QueueMachine = ReturnType<typeof createQueueMachine>;