react-native-audio-browser 0.1.1 → 0.2.0-next.1

package/src/web/TrackPlayer/Player.ts

@@ -1,12 +1,15 @@
-import type shaka from 'shaka-player/dist/shaka-player.ui'
+import type shaka from 'shaka-player/dist/shaka-player.compiled'
 import type {
   Progress,
-  PartialSetupPlayerOptions,
+  NativeSetupPlayerOptions,
   Playback,
-  PlaybackError
+  PlaybackError,
+  PlaybackState
 } from '../../features'
 import type { Track } from '../../types'
-import type { State as StateType } from './State'
+import type { PlaybackEvent } from './PlaybackStateMachine'
+import { playbackErrorKind } from '../playbackErrorKind'
+import { nextPlaybackState } from './PlaybackStateMachine'
 import { SetupNotCalledError } from './SetupNotCalledError'
 import { State } from './State'
 
@@ -19,10 +22,14 @@ declare global {
 
 // Shaka event type definitions
 interface ShakaErrorEvent extends CustomEvent {
-  detail: {
-    code: number
-    message: string
-  }
+  detail: ShakaError
+}
+
+interface ShakaError {
+  code: number
+  message: string
+  /** Shaka's per-code payload; for BAD_HTTP_STATUS `data[1]` is the status. */
+  data?: unknown[]
 }
 
 interface ShakaBufferingEvent extends CustomEvent {
@@ -83,19 +90,15 @@ export class Player {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async setupPlayer(_options: PartialSetupPlayerOptions = {}): Promise<void> {
+  async setupPlayer(_options: NativeSetupPlayerOptions = {}): Promise<void> {
     // shaka only runs in a browser
     if (typeof window === 'undefined') return
-    if (this.hasInitialized === true) {
-      const error: PlaybackError = {
-        code: 'player_already_initialized',
-        message: 'The player has already been initialized via setupPlayer.'
-      }
-      // eslint-disable-next-line @typescript-eslint/only-throw-error
-      throw error
-    }
+    // Re-setup reconfigures: web has no construction-bound engine options, so
+    // there's nothing to rebuild — the caller re-applies options/state on top.
+    if (this.hasInitialized === true) return
 
-    const shaka = (await import('shaka-player/dist/shaka-player.ui')).default
+    const shaka = (await import('shaka-player/dist/shaka-player.compiled'))
+      .default
     // Install built-in polyfills to patch browser incompatibilities.
     shaka.polyfill.installAll()
     // Check to see if the browser supports the basic APIs Shaka needs.
@@ -104,6 +107,7 @@ export class Player {
       this.state = {
         state: State.Error,
         error: {
+          kind: 'unplayable',
           code: 'not_supported',
           message: 'Browser not supported...'
         }
@@ -127,20 +131,30 @@ export class Player {
       this.onError(errorEvent.detail)
     })
 
-    element.addEventListener('ended', () => this.onStateUpdate(State.Ended))
-    element.addEventListener('playing', () => this.onStateUpdate(State.Playing))
-    element.addEventListener('pause', () => this.onStateUpdate(State.Paused))
-
-    player.addEventListener('loading', () => this.onStateUpdate(State.Loading))
-    player.addEventListener('loaded', () => this.onStateUpdate(State.Ready))
+    element.addEventListener('ended', () =>
+      this.dispatch({ type: 'trackEndedNaturally' })
+    )
+    element.addEventListener('playing', () =>
+      this.dispatch({ type: 'playing' })
+    )
+    element.addEventListener('pause', () =>
+      this.dispatch({ type: 'paused', hasAsset: this.current !== undefined })
+    )
+
+    player.addEventListener('loading', () =>
+      this.dispatch({ type: 'trackLoading' })
+    )
+    player.addEventListener('loaded', () =>
+      this.dispatch({ type: 'loadSeekCompleted' })
+    )
 
     player.addEventListener('buffering', (event: Event) => {
       const bufferingEvent = event as ShakaBufferingEvent
-      if (bufferingEvent.detail.buffering === true) {
-        this.onStateUpdate(State.Buffering)
-      } else {
-        this.onStateUpdate(State.Ready)
-      }
+      this.dispatch(
+        bufferingEvent.detail.buffering === true
+          ? { type: 'waiting' }
+          : { type: 'bufferingSufficient' }
+      )
     })
 
     // Attach player to the window to make it easy to access in the JS console.
@@ -152,38 +166,65 @@ export class Player {
   }
 
   /**
-   * event handlers
+   * Routes a racy element/Shaka observation through the state machine. The
+   * machine decides the next state (or suppresses the transition); commands
+   * (stop, error) set their terminal state directly instead.
    */
-  protected onStateUpdate(state: Exclude<StateType, typeof State.Error>): void {
-    // Ignore Shaka/element events while stopped (e.g., from unload)
+  protected dispatch(event: PlaybackEvent): void {
+    // Ignore element/Shaka events while stopped. This is broader than the
+    // machine's own stopped guards on purpose: native engines are torn down on
+    // stop so they emit nothing, but Shaka's unload() emits spurious events
+    // (pause, buffering) that would otherwise clobber the stopped state.
     if (this._isStopped) return
+    const next = nextPlaybackState(this.state.state, event)
+    if (next !== null) this.applyState(next)
+  }
+
+  /**
+   * Applies a machine-decided state. Overridable so subclasses can react to
+   * specific transitions (e.g. QueuePlayer advancing the queue on `ended`).
+   */
+  protected applyState(state: PlaybackState): void {
     this.state = { state }
   }
 
-  private toNormalizedError(err: unknown): { code: number; message: string } {
+  private toNormalizedError(err: unknown): ShakaError {
     if (
       typeof err === 'object' &&
       err !== null &&
       'code' in err &&
       typeof (err as Record<string, unknown>).code === 'number'
     ) {
-      const e = err as { code: number; message?: string }
-      return { code: e.code, message: e.message ?? 'Unknown error' }
+      const e = err as ShakaError
+      return {
+        code: e.code,
+        message: e.message ?? 'Unknown error',
+        data: e.data
+      }
     }
 
     const message = err instanceof Error ? err.message : String(err)
     return { code: -1, message }
   }
 
-  protected onError(shakaError: { code: number; message: string }): void {
+  protected onError(shakaError: ShakaError): void {
     // unload the current track to allow for clean playback on other
     this.player?.unload().catch((err) => {
       console.error(`Error unloading player on 'onError'`, err)
     })
 
+    const status = shakaError.data?.[1]
+    const httpStatus = typeof status === 'number' ? status : undefined
     const error: PlaybackError = {
+      kind: playbackErrorKind(
+        shakaError.code,
+        httpStatus,
+        // `navigator` is absent when this runs outside a browser (SSR, tests).
+        typeof navigator === 'undefined' || navigator.onLine
+      ),
       code: shakaError.code.toString(),
-      message: shakaError.message
+      message: shakaError.message,
+      statusCode: httpStatus
     }
 
     this.state = {
@@ -195,15 +236,22 @@ export class Player {
     console.debug('Error code', shakaError.code, 'object', shakaError)
   }
 
+  /** Invalidates the .then/.catch of superseded loads — a Shaka load
+   * interrupted by stop() or a newer load() rejects, and only the active load
+   * may surface that (or run its onLoaded side effects). */
+  private _loadGeneration = 0
+
   public load(track: Track, onLoaded?: (track: Track) => void): void {
     const player = this.requirePlayer()
     this._isStopped = false
     this._loadInProgress = true
+    const generation = ++this._loadGeneration
 
     if (!track.src) {
       this._loadInProgress = false
       this._pendingSeek = undefined
       const error: PlaybackError = {
+        kind: 'unplayable',
         code: 'invalid_track',
         message: 'Track does not have a valid src URL'
       }
@@ -217,6 +265,7 @@ export class Player {
     player
       .load(track.src)
       .then(() => {
+        if (generation !== this._loadGeneration || this._isStopped) return
         this._loadInProgress = false
         this.current = track
         onLoaded?.(track)
@@ -233,6 +282,7 @@ export class Player {
         }
       })
       .catch((err: unknown) => {
+        if (generation !== this._loadGeneration || this._isStopped) return
         this._loadInProgress = false
         this._pendingSeek = undefined
         this.onError(this.toNormalizedError(err))
@@ -264,19 +314,29 @@ export class Player {
     this.playWhenReady = true
 
     if (this.state.state === State.Error && this.current) {
-      this.load(this.current)
+      this.reloadCurrent()
       return
     }
 
     // Match Android: play() after stop() re-prepares the current track
     if (this._isStopped && this.current) {
-      this.load(this.current)
+      this.reloadCurrent()
       return
     }
 
     element.play().catch((err: unknown) => console.error(err))
   }
 
+  /**
+   * Reloads the current track. `current` holds the *resolved* track, so
+   * subclasses that resolve media URLs override this to reload from the
+   * original source instead — re-feeding `current` into `load()` would
+   * re-resolve an already-resolved URL and leak it into the queue.
+   */
+  protected reloadCurrent(): void {
+    if (this.current) this.load(this.current)
+  }
+
   public retry(): void {
     const player = this.requirePlayer()
     player.retryStreaming()
@@ -326,6 +386,20 @@ export class Player {
     element.currentTime = seconds
   }
 
+  public seekToLiveEdge(): void {
+    if (this.current?.live !== true) return
+    const element = this.requireElement()
+    // Live with a seekable window (HLS): jump to the window end. Without one
+    // (non-seekable stream): reload to reconnect at the live edge.
+    const { seekable } = element
+    const end = seekable.length > 0 ? seekable.end(seekable.length - 1) : 0
+    if (end > 0) {
+      element.currentTime = end
+    } else {
+      this.reloadCurrent()
+    }
+  }
+
   public setVolume(volume: number): void {
     const element = this.requireElement()
     element.volume = volume

package/src/web/TrackPlayer/PlayingStateFactory.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import type { PlaybackState } from '../../features'
+import { derivePlayingState } from './PlayingStateFactory'
+
+// Ported from the native truth table (android PlayingStateFactoryTest.kt /
+// ios PlayingStateManager) so web derives PlayingState identically.
+const ALL_STATES: PlaybackState[] = [
+  'none',
+  'ready',
+  'playing',
+  'paused',
+  'stopped',
+  'loading',
+  'buffering',
+  'error',
+  'ended'
+]
+
+describe('derivePlayingState', () => {
+  it('playWhenReady false is never playing nor buffering', () => {
+    for (const state of ALL_STATES) {
+      expect(derivePlayingState(false, state)).toEqual({
+        playing: false,
+        buffering: false
+      })
+    }
+  })
+
+  it('playWhenReady true plays except in terminal or empty states', () => {
+    const notPlaying = new Set<PlaybackState>([
+      'error',
+      'ended',
+      'none',
+      'stopped'
+    ])
+    for (const state of ALL_STATES) {
+      expect(derivePlayingState(true, state).playing).toBe(
+        !notPlaying.has(state)
+      )
+    }
+  })
+
+  it('buffers only while loading or rebuffering with playWhenReady', () => {
+    const buffering = new Set<PlaybackState>(['loading', 'buffering'])
+    for (const state of ALL_STATES) {
+      expect(derivePlayingState(true, state).buffering).toBe(
+        buffering.has(state)
+      )
+    }
+  })
+})

package/src/web/TrackPlayer/PlayingStateFactory.ts

@@ -0,0 +1,24 @@
+import type { PlaybackState, PlayingState } from '../../features'
+
+/**
+ * Derives the two-flag {@link PlayingState} (playing / buffering) from the
+ * player's intent (`playWhenReady`) and its current {@link PlaybackState}.
+ *
+ * A faithful port of the native derivations (android `PlayingStateFactory.derive`,
+ * ios `PlayingStateManager.update`) so all platforms agree on what "playing" and
+ * "buffering" mean for the now-playing UI.
+ */
+export function derivePlayingState(
+  playWhenReady: boolean,
+  state: PlaybackState
+): PlayingState {
+  return {
+    playing:
+      playWhenReady &&
+      state !== 'error' &&
+      state !== 'ended' &&
+      state !== 'none' &&
+      state !== 'stopped',
+    buffering: playWhenReady && (state === 'loading' || state === 'buffering')
+  }
+}

package/src/web/TrackPlayer/QueueManager.test.ts

@@ -0,0 +1,289 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Track } from '../../types'
+import { QueueManager } from './QueueManager'
+import { RepeatMode } from './RepeatMode'
+
+// Make shuffle deterministic (identity) so the shuffle-order navigation path is
+// assertable: shuffleOrder becomes [0,1,2,…] before the current-first swap.
+vi.mock('../util/shuffle', () => ({
+  fisherYatesShuffle: () => {}
+}))
+
+const tracks = (n: number): Track[] =>
+  Array.from({ length: n }, (_, i) => ({ src: `s${i}` }) as Track)
+
+describe('QueueManager', () => {
+  let q: QueueManager
+
+  beforeEach(() => {
+    q = new QueueManager()
+  })
+
+  describe('current index', () => {
+    it('tracks the previous index as lastIndex on set', () => {
+      q.currentIndex = 2
+      expect(q.lastIndex).toBeUndefined()
+      q.currentIndex = 5
+      expect(q.lastIndex).toBe(2)
+      expect(q.currentIndex).toBe(5)
+    })
+  })
+
+  describe('insert', () => {
+    it('adjusts currentIndex when inserting before the current track', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+
+      q.insert([{ src: 'x' } as Track], 0)
+
+      // The pointer must stay on the same track (remove()/move() already do
+      // this; native adjusts automatically).
+      expect(q.currentIndex).toBe(2)
+      expect(q.getTrack(q.currentIndex!)?.src).toBe('s1')
+    })
+
+    it('keeps currentIndex when inserting after the current track', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+
+      q.insert([{ src: 'x' } as Track], 2)
+
+      expect(q.currentIndex).toBe(1)
+    })
+
+    it('keeps currentIndex when appending', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+
+      q.insert([{ src: 'x' } as Track])
+
+      expect(q.currentIndex).toBe(1)
+    })
+  })
+
+  describe('sequential navigation', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 0
+    })
+
+    it('advances and stops at the end (no wrap by default)', () => {
+      expect(q.nextIndex()).toBe(1)
+      q.currentIndex = 2
+      expect(q.nextIndex()).toBeUndefined()
+    })
+
+    it('goes back and stops at the start', () => {
+      q.currentIndex = 1
+      expect(q.previousIndex()).toBe(0)
+      q.currentIndex = 0
+      expect(q.previousIndex()).toBeUndefined()
+    })
+
+    it('returns undefined navigation when there is no current track', () => {
+      const empty = new QueueManager()
+      empty.setTracks(tracks(3))
+      expect(empty.nextIndex()).toBeUndefined()
+      expect(empty.previousIndex()).toBeUndefined()
+    })
+  })
+
+  describe('wrap-around (repeat playlist)', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 2
+    })
+
+    it('only wraps when repeat mode is playlist', () => {
+      expect(q.wrapAroundFirstIndex()).toBeUndefined()
+      expect(q.wrapAroundLastIndex()).toBeUndefined()
+      q.repeatMode = RepeatMode.Queue
+      expect(q.wrapAroundFirstIndex()).toBe(0)
+      expect(q.wrapAroundLastIndex()).toBe(2)
+    })
+  })
+
+  describe('shuffle navigation', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(4))
+      q.currentIndex = 0
+      q.setShuffleEnabled(true) // identity shuffle → order [0,1,2,3]
+    })
+
+    it('navigates along the shuffle order with the current track first', () => {
+      // current (0) is already at position 0, so order stays [0,1,2,3]
+      expect(q.nextIndex()).toBe(1)
+      q.currentIndex = 3
+      expect(q.nextIndex()).toBeUndefined()
+      expect(q.previousIndex()).toBe(2)
+    })
+
+    it('moves the current track to the front of the shuffle order on regen', () => {
+      q.currentIndex = 2
+      q.regenerateShuffleOrder()
+      // order was [0,1,2,3]; current (2) swapped to front → [2,1,0,3]
+      expect(q.previousIndex()).toBeUndefined()
+      expect(q.nextIndex()).toBe(1)
+    })
+
+    // Mutations maintain the shuffle order in place (matching iOS/ExoPlayer)
+    // instead of regenerating it — a regeneration erased the played history,
+    // leaving previous() dead after any add/remove/move.
+
+    it('keeps the shuffle history across an append', () => {
+      q.currentIndex = 2 // identity order [0,1,2,3], position 2
+      const random = vi.spyOn(Math, 'random').mockReturnValue(0.999)
+      try {
+        q.insert([{ src: 'x' } as Track]) // appended at the order's end
+      } finally {
+        random.mockRestore()
+      }
+      expect(q.previousIndex()).toBe(1)
+      expect(q.nextIndex()).toBe(3)
+    })
+
+    it('keeps the shuffle history across a remove of another track', () => {
+      q.currentIndex = 2
+      q.remove([0]) // order [0,1,2,3] → [0,1,2] with current now at index 1
+      expect(q.currentIndex).toBe(1)
+      expect(q.previousIndex()).toBe(0)
+      expect(q.nextIndex()).toBe(2)
+    })
+
+    it('does not let a stale order survive clear()', () => {
+      // Mutations no longer regenerate the order, so clear() must reset it —
+      // otherwise the first post-clear insert shifts a 4-entry ghost order.
+      q.clear()
+      q.insert(tracks(1))
+      q.currentIndex = 0
+      expect(q.previousIndex()).toBeUndefined()
+      expect(q.nextIndex()).toBeUndefined()
+    })
+
+    it('keeps every track at its shuffle position across a move', () => {
+      q.currentIndex = 1
+      q.move(1, 3) // tracks [s0,s2,s3,s1]; order remapped to [0,3,1,2]
+      expect(q.currentIndex).toBe(3)
+      expect(q.previousIndex()).toBe(0)
+      expect(q.nextIndex()).toBe(1)
+    })
+  })
+
+  describe('insert', () => {
+    it('appends when no insert index is given', () => {
+      q.setTracks(tracks(2))
+      q.insert(tracks(1))
+      expect(q.length).toBe(3)
+    })
+
+    it('splices at the given index', () => {
+      q.setTracks([{ src: 'a' }, { src: 'b' }] as Track[])
+      q.insert([{ src: 'x' }] as Track[], 1)
+      expect(q.tracks.map((t) => t.src)).toEqual(['a', 'x', 'b'])
+    })
+
+    it('throws on a negative index other than the -1 append sentinel', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+      // -2 used to splice from the end while still shifting the pointer,
+      // leaving currentIndex on a different track (native throws here).
+      expect(() => q.insert(tracks(1), -2)).toThrow('use -1 to append')
+      expect(q.currentIndex).toBe(1)
+      expect(q.length).toBe(3)
+    })
+
+    it('throws on a past-the-end index', () => {
+      q.setTracks(tracks(3))
+      expect(() => q.insert(tracks(1), 4)).toThrow('out of bounds')
+    })
+  })
+
+  describe('remove', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(5)) // s0..s4
+      q.currentIndex = 2
+    })
+
+    it('keeps the current track, shifting its index down for removals before it', () => {
+      const result = q.remove([0])
+      expect(result).toEqual({ kind: 'kept' })
+      expect(q.currentIndex).toBe(1)
+    })
+
+    it('reports the index to reload when the current track is removed', () => {
+      const result = q.remove([2])
+      // index clamped into the shrunken queue; current reset so caller reloads
+      expect(result).toEqual({ kind: 'reload', index: 2 })
+      expect(q.currentIndex).toBeUndefined()
+    })
+
+    it('wraps to the first track when the current track was the last', () => {
+      const result = q.remove([4])
+      expect(result).toEqual({ kind: 'kept' })
+      q.currentIndex = 3 // now the last track
+      // Documented contract (and iOS behavior): removing the last-and-current
+      // track activates the first, not the new last.
+      expect(q.remove([3])).toEqual({ kind: 'reload', index: 0 })
+    })
+
+    it('reports emptied when the last remaining track is removed', () => {
+      q.setTracks(tracks(1))
+      q.currentIndex = 0
+      expect(q.remove([0])).toEqual({ kind: 'emptied' })
+    })
+
+    it('reports no-current when nothing is playing', () => {
+      const idle = new QueueManager()
+      idle.setTracks(tracks(3))
+      expect(idle.remove([0])).toEqual({ kind: 'no-current' })
+      expect(idle.length).toBe(2) // filter still applied
+    })
+  })
+
+  describe('move', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(4)) // s0..s3
+    })
+
+    it('follows the current track to its new position', () => {
+      q.currentIndex = 1
+      q.move(1, 3)
+      expect(q.tracks.map((t) => t.src)).toEqual(['s0', 's2', 's3', 's1'])
+      expect(q.currentIndex).toBe(3)
+    })
+
+    it('shifts the current index when a track moves across it', () => {
+      q.currentIndex = 2
+      q.move(0, 3) // moving an earlier track past current shifts current down
+      expect(q.currentIndex).toBe(1)
+    })
+
+    it('throws on an out-of-bounds source index', () => {
+      expect(() => q.move(9, 0)).toThrow('index out of bounds')
+    })
+
+    it('throws on an out-of-bounds destination index', () => {
+      expect(() => q.move(0, 9)).toThrow('index out of bounds')
+      expect(() => q.move(0, -1)).toThrow('index out of bounds')
+    })
+  })
+
+  describe('removeUpcoming', () => {
+    it('drops everything after the current track', () => {
+      q.setTracks(tracks(5))
+      q.currentIndex = 1
+      q.removeUpcoming()
+      expect(q.tracks.map((t) => t.src)).toEqual(['s0', 's1'])
+    })
+  })
+
+  describe('clear', () => {
+    it('empties the queue and resets the index', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+      q.clear()
+      expect(q.length).toBe(0)
+      expect(q.currentIndex).toBeUndefined()
+    })
+  })
+})