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

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

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+import type { PlaybackState } from '../../features'
+import { nextPlaybackState } from './PlaybackStateMachine'
+
+// Ported from the native truth tables (ios/Tests/PlaybackStateMachineTests.swift,
+// android/.../PlaybackStateMachineTest.kt) so web stays behaviourally in sync.
+const ALL_STATES: PlaybackState[] = [
+  'none',
+  'ready',
+  'playing',
+  'paused',
+  'stopped',
+  'loading',
+  'buffering',
+  'error',
+  'ended'
+]
+
+describe('nextPlaybackState', () => {
+  describe('unconditional events — always produce their target state', () => {
+    it('trackLoading → loading from any state', () => {
+      for (const state of ALL_STATES) {
+        expect(nextPlaybackState(state, { type: 'trackLoading' })).toBe(
+          'loading'
+        )
+      }
+    })
+
+    it('trackEndedNaturally → ended from any state', () => {
+      for (const state of ALL_STATES) {
+        expect(nextPlaybackState(state, { type: 'trackEndedNaturally' })).toBe(
+          'ended'
+        )
+      }
+    })
+
+    it('waiting → buffering from any state', () => {
+      for (const state of ALL_STATES) {
+        expect(nextPlaybackState(state, { type: 'waiting' })).toBe('buffering')
+      }
+    })
+
+    it('playing → playing from any state', () => {
+      for (const state of ALL_STATES) {
+        expect(nextPlaybackState(state, { type: 'playing' })).toBe('playing')
+      }
+    })
+  })
+
+  describe('loadSeekCompleted — only transitions from loading', () => {
+    it('from loading → ready', () => {
+      expect(nextPlaybackState('loading', { type: 'loadSeekCompleted' })).toBe(
+        'ready'
+      )
+    })
+
+    it('from any other state → suppressed', () => {
+      for (const state of ALL_STATES.filter((s) => s !== 'loading')) {
+        expect(
+          nextPlaybackState(state, { type: 'loadSeekCompleted' })
+        ).toBeNull()
+      }
+    })
+  })
+
+  describe('paused — conditional on current state and hasAsset', () => {
+    it('from stopped → suppressed', () => {
+      expect(
+        nextPlaybackState('stopped', { type: 'paused', hasAsset: true })
+      ).toBeNull()
+      expect(
+        nextPlaybackState('stopped', { type: 'paused', hasAsset: false })
+      ).toBeNull()
+    })
+
+    it('from error with an asset → suppressed (preserves the error)', () => {
+      expect(
+        nextPlaybackState('error', { type: 'paused', hasAsset: true })
+      ).toBeNull()
+    })
+
+    it('without an asset → none from any non-stopped state', () => {
+      for (const state of ALL_STATES.filter((s) => s !== 'stopped')) {
+        expect(
+          nextPlaybackState(state, { type: 'paused', hasAsset: false })
+        ).toBe('none')
+      }
+    })
+
+    it('with an asset → paused from states other than stopped/error', () => {
+      for (const state of ALL_STATES.filter(
+        (s) => s !== 'stopped' && s !== 'error'
+      )) {
+        expect(
+          nextPlaybackState(state, { type: 'paused', hasAsset: true })
+        ).toBe('paused')
+      }
+    })
+  })
+
+  describe('bufferingSufficient — suppressed from terminal states and playing', () => {
+    const suppressed: PlaybackState[] = ['playing', 'ended', 'stopped', 'error']
+
+    it('from playing → suppressed', () => {
+      expect(
+        nextPlaybackState('playing', { type: 'bufferingSufficient' })
+      ).toBeNull()
+    })
+
+    // Shaka's post-error unload emits buffering events without the stopped
+    // dispatch gate; drifting error → ready would silently clear the error
+    // the UI is rendering with nothing recovered. Same guard as iOS/Android.
+    it('from error → suppressed (preserves the error)', () => {
+      expect(
+        nextPlaybackState('error', { type: 'bufferingSufficient' })
+      ).toBeNull()
+    })
+
+    it('from ended → suppressed', () => {
+      expect(
+        nextPlaybackState('ended', { type: 'bufferingSufficient' })
+      ).toBeNull()
+    })
+
+    it('from stopped → suppressed', () => {
+      expect(
+        nextPlaybackState('stopped', { type: 'bufferingSufficient' })
+      ).toBeNull()
+    })
+
+    it('from any other state → ready', () => {
+      for (const state of ALL_STATES.filter((s) => !suppressed.includes(s))) {
+        expect(nextPlaybackState(state, { type: 'bufferingSufficient' })).toBe(
+          'ready'
+        )
+      }
+    })
+  })
+})

package/src/web/TrackPlayer/PlaybackStateMachine.ts

@@ -0,0 +1,82 @@
+import type { PlaybackState } from '../../features'
+
+/**
+ * Every racy observation that can move the playback state — the web analog of
+ * iOS's `PlaybackEvent` / Android's `PlaybackEvent`. Each is produced by an
+ * HTML5 `<audio>` or Shaka event:
+ *
+ * | event                | source                          |
+ * |----------------------|---------------------------------|
+ * | `trackLoading`       | Shaka `loading`                 |
+ * | `loadSeekCompleted`  | Shaka `loaded`                  |
+ * | `waiting`            | Shaka `buffering` (`true`)      |
+ * | `bufferingSufficient`| Shaka `buffering` (`false`)     |
+ * | `playing`            | element `playing`               |
+ * | `paused`             | element `pause`                 |
+ * | `trackEndedNaturally`| element `ended`                 |
+ *
+ * Deliberate *commands* (stop, error) set their terminal state directly rather
+ * than flowing through here — they are intentions, not observations. The two
+ * iOS-only events `trackUnloaded` and `audioFrameDecoded` are omitted: web has
+ * no unload-to-none source, and a decoded frame is indistinguishable from
+ * `playing` in the browser.
+ */
+export type PlaybackEvent =
+  | { type: 'trackLoading' }
+  | { type: 'trackEndedNaturally' }
+  | { type: 'loadSeekCompleted' }
+  | { type: 'paused'; hasAsset: boolean }
+  | { type: 'waiting' }
+  | { type: 'playing' }
+  | { type: 'bufferingSufficient' }
+
+/**
+ * The next playback state for an event from the current state, or `null` to
+ * suppress the transition. A faithful port of iOS's `nextPlaybackState(from:on:)`.
+ *
+ * Guards here are **state-related** (e.g. "only from loading"). Context-related
+ * guards (does an asset exist, near track end, playWhenReady) are decided at the
+ * call site and arrive as event fields / whether the event fires at all.
+ *
+ * Pure: side effects (event emission, now-playing sync, timers, error payloads)
+ * stay with the caller.
+ */
+export function nextPlaybackState(
+  current: PlaybackState,
+  event: PlaybackEvent
+): PlaybackState | null {
+  switch (event.type) {
+    case 'trackLoading':
+      return 'loading'
+    case 'trackEndedNaturally':
+      return 'ended'
+    case 'waiting':
+      return 'buffering'
+    case 'playing':
+      return 'playing'
+    case 'loadSeekCompleted':
+      // The settle after a load; meaningless from anything but a fresh load.
+      return current === 'loading' ? 'ready' : null
+    case 'paused':
+      // A stopped player owns its state; a stray pause must not disturb it.
+      if (current === 'stopped') return null
+      // No asset means the element paused because it was emptied → nothing loaded.
+      if (!event.hasAsset) return 'none'
+      // Preserve a terminal error: the unload that follows an error pauses the
+      // element, and that pause must not clear the error the UI is rendering.
+      if (current === 'error') return null
+      return 'paused'
+    case 'bufferingSufficient':
+      // A rebuffer that finishes mid-playback should stay playing, not flash
+      // ready. Terminal states must not drift back to ready either: from error
+      // it would silently clear the error the UI is rendering (Shaka's
+      // post-error unload emits buffering events without the stopped dispatch
+      // gate); ended/stopped own their state until an explicit load or play.
+      return current === 'playing' ||
+        current === 'ended' ||
+        current === 'stopped' ||
+        current === 'error'
+        ? null
+        : 'ready'
+  }
+}

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

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { PlaybackTimer } from './PlaybackTimer'
+
+describe('PlaybackTimer', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('ticks every interval while the gate is open', () => {
+    const timer = new PlaybackTimer()
+    const onTick = vi.fn()
+    timer.start(1000, () => true, onTick)
+
+    vi.advanceTimersByTime(3000)
+
+    expect(onTick).toHaveBeenCalledTimes(3)
+  })
+
+  it('skips ticks while the gate is closed but keeps running', () => {
+    const timer = new PlaybackTimer()
+    const onTick = vi.fn()
+    let open = false
+    timer.start(1000, () => open, onTick)
+
+    vi.advanceTimersByTime(2000)
+    expect(onTick).not.toHaveBeenCalled()
+
+    open = true
+    vi.advanceTimersByTime(2000)
+    expect(onTick).toHaveBeenCalledTimes(2)
+  })
+
+  it('stops ticking after stop()', () => {
+    const timer = new PlaybackTimer()
+    const onTick = vi.fn()
+    timer.start(1000, () => true, onTick)
+
+    vi.advanceTimersByTime(1000)
+    timer.stop()
+    vi.advanceTimersByTime(5000)
+
+    expect(onTick).toHaveBeenCalledTimes(1)
+  })
+
+  it('restarts cleanly when start() is called again', () => {
+    const timer = new PlaybackTimer()
+    const first = vi.fn()
+    const second = vi.fn()
+    timer.start(1000, () => true, first)
+    timer.start(500, () => true, second)
+
+    vi.advanceTimersByTime(1000)
+
+    // The first timer must have been cleared — only the second ticks.
+    expect(first).not.toHaveBeenCalled()
+    expect(second).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not tick for a non-positive interval (acts as stopped)', () => {
+    const timer = new PlaybackTimer()
+    const onTick = vi.fn()
+    timer.start(0, () => true, onTick)
+
+    vi.advanceTimersByTime(5000)
+
+    expect(onTick).not.toHaveBeenCalled()
+  })
+})

package/src/web/TrackPlayer/PlaybackTimer.ts

@@ -0,0 +1,33 @@
+/**
+ * A restartable interval timer that fires only while a gate predicate holds —
+ * the web analog of Android's playback-state-gated `PlaybackTimer`. The timer
+ * keeps running while the gate is closed; ticks are simply skipped, so it
+ * resumes the moment the gate reopens (e.g. buffering → playing) without being
+ * restarted.
+ */
+export class PlaybackTimer {
+  private handle: ReturnType<typeof setInterval> | undefined
+
+  /**
+   * (Re)starts the timer. Every `intervalMs` it calls `onTick`, but only when
+   * `shouldTick()` returns true. A non-positive interval leaves it stopped.
+   */
+  start(
+    intervalMs: number,
+    shouldTick: () => boolean,
+    onTick: () => void
+  ): void {
+    this.stop()
+    if (intervalMs <= 0) return
+    this.handle = setInterval(() => {
+      if (shouldTick()) onTick()
+    }, intervalMs)
+  }
+
+  stop(): void {
+    if (this.handle !== undefined) {
+      clearInterval(this.handle)
+      this.handle = undefined
+    }
+  }
+}

package/src/web/TrackPlayer/Player.dispatch.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, it } from 'vitest'
+import type { Playback, PlaybackState } from '../../features'
+import type { PlaybackEvent } from './PlaybackStateMachine'
+import { Player } from './Player'
+import { QueuePlayer } from './QueuePlayer'
+
+// Exercises the integration seam between the element/Shaka events and the state
+// machine — the web-specific behaviour the pure machine test doesn't cover.
+class TestPlayer extends Player {
+  forceState(state: PlaybackState): void {
+    this.state = { state }
+  }
+  forceStopped(stopped: boolean): void {
+    this._isStopped = stopped
+  }
+  emit(event: PlaybackEvent): void {
+    this.dispatch(event)
+  }
+  read(): Playback {
+    return this.state
+  }
+}
+
+class TestQueuePlayer extends QueuePlayer {
+  endedCount = 0
+  protected onTrackEnded(): void {
+    this.endedCount++
+  }
+  forceStopped(stopped: boolean): void {
+    this._isStopped = stopped
+  }
+  emit(event: PlaybackEvent): void {
+    this.dispatch(event)
+  }
+}
+
+describe('Player.dispatch', () => {
+  it('keeps the error when the post-unload pause arrives (the documented bug)', () => {
+    const player = new TestPlayer()
+    player.forceState('error')
+
+    // onError() unloads, which makes the element emit `pause` with the track
+    // still set. Pre-machine this clobbered the error with `paused`.
+    player.emit({ type: 'paused', hasAsset: true })
+
+    expect(player.read().state).toBe('error')
+  })
+
+  it('ignores element/Shaka events while stopped', () => {
+    const player = new TestPlayer()
+    player.forceState('stopped')
+    player.forceStopped(true)
+
+    player.emit({ type: 'playing' })
+    player.emit({ type: 'waiting' })
+
+    expect(player.read().state).toBe('stopped')
+  })
+
+  it('stays playing when a rebuffer finishes mid-playback (no ready flash)', () => {
+    const player = new TestPlayer()
+    player.forceState('playing')
+
+    player.emit({ type: 'bufferingSufficient' })
+
+    expect(player.read().state).toBe('playing')
+  })
+
+  it('settles to ready after a load completes', () => {
+    const player = new TestPlayer()
+    player.forceState('loading')
+
+    player.emit({ type: 'loadSeekCompleted' })
+
+    expect(player.read().state).toBe('ready')
+  })
+})
+
+// Uses the real onTrackEnded (unlike TestQueuePlayer) so the natural-end path
+// runs through to onQueueEnded.
+class TestQueueEndPlayer extends QueuePlayer {
+  emit(event: PlaybackEvent): void {
+    this.dispatch(event)
+  }
+}
+
+// Overrides onQueueEnded without calling super — the intent clear must not
+// depend on subclasses remembering to (NativeAudioBrowser overrides this hook).
+class OverridingQueueEndPlayer extends QueuePlayer {
+  queueEndedCount = 0
+  emit(event: PlaybackEvent): void {
+    this.dispatch(event)
+  }
+  protected onQueueEnded(): void {
+    this.queueEndedCount++
+  }
+}
+
+// Records the relative order of the intent drop, the state landing, and the
+// queue-ended hook — pinned to the native order (intent → state → queueEnded).
+class OrderRecordingPlayer extends QueuePlayer {
+  order: string[] = []
+  emit(event: PlaybackEvent): void {
+    this.dispatch(event)
+  }
+  protected get state(): Playback {
+    return super.state
+  }
+  protected set state(newState: Playback) {
+    super.state = newState
+    this.order.push(`state:${newState.state}`)
+  }
+  public get playWhenReady(): boolean {
+    return super.playWhenReady
+  }
+  public set playWhenReady(pwr: boolean) {
+    super.playWhenReady = pwr
+    this.order.push(`pwr:${pwr}`)
+  }
+  protected onQueueEnded(): void {
+    super.onQueueEnded()
+    this.order.push('queueEnded')
+  }
+}
+
+describe('QueuePlayer queue end', () => {
+  it('drops the play intent when the queue ends naturally', () => {
+    const player = new TestQueueEndPlayer()
+    player.playWhenReady = true
+
+    player.emit({ type: 'trackEndedNaturally' })
+
+    // A natural end exhausts the intent: keeping it set inverted
+    // togglePlayback (first press was a silent pause) and armed load()'s
+    // auto-play with phantom intent.
+    expect(player.playWhenReady).toBe(false)
+  })
+
+  it('drops the intent even when onQueueEnded overrides without super', () => {
+    const player = new OverridingQueueEndPlayer()
+    player.playWhenReady = true
+
+    player.emit({ type: 'trackEndedNaturally' })
+
+    expect(player.queueEndedCount).toBe(1)
+    expect(player.playWhenReady).toBe(false)
+  })
+
+  it('orders intent → state → queueEnded, matching native', () => {
+    const player = new OrderRecordingPlayer()
+    player.playWhenReady = true
+    player.order.length = 0
+
+    player.emit({ type: 'trackEndedNaturally' })
+
+    expect(player.order).toEqual(['pwr:false', 'state:ended', 'queueEnded'])
+  })
+})
+
+describe('QueuePlayer remove without a current track', () => {
+  it('keeps the shuffle order aligned with the post-remove layout', () => {
+    class ShuffleTestPlayer extends QueuePlayer {
+      seed(tracks: Array<{ src: string }>): void {
+        this.queue.setTracks(tracks as never)
+      }
+      setCurrent(index: number): void {
+        this.queue.currentIndex = index
+      }
+      neighbours(): [number | undefined, number | undefined] {
+        return [this.queue.previousIndex(), this.queue.nextIndex()]
+      }
+    }
+    const player = new ShuffleTestPlayer()
+    player.setShuffleEnabled(true)
+    player.seed([{ src: 'a' }, { src: 'b' }])
+
+    // 'no-current' outcome: tracks are still spliced, so a stale order would
+    // keep indexing the pre-remove layout.
+    player.remove([0])
+
+    // One track left: a stale two-entry order (either permutation) would give
+    // the survivor a neighbour that no longer exists.
+    player.setCurrent(0)
+    expect(player.neighbours()).toEqual([undefined, undefined])
+  })
+})
+
+describe('QueuePlayer skip while stopped', () => {
+  it('reloads instead of seeking the unloaded element', () => {
+    const loads: string[] = []
+    class SkipTestPlayer extends QueuePlayer {
+      load(track: { src?: string }): void {
+        loads.push(track.src ?? '')
+      }
+      seekTo(): void {}
+      forceStopped(): void {
+        this._isStopped = true
+      }
+    }
+    const player = new SkipTestPlayer()
+    player.add([{ src: 's0' } as never])
+    expect(loads).toEqual(['s0'])
+    player.forceStopped()
+
+    player.skip(0)
+
+    // Same-index skip took the seek branch, which is dead while stopped.
+    expect(loads).toEqual(['s0', 's0'])
+  })
+})
+
+describe('QueuePlayer queue advance', () => {
+  it('advances the queue when a track ends naturally', () => {
+    const player = new TestQueuePlayer()
+
+    player.emit({ type: 'trackEndedNaturally' })
+
+    expect(player.endedCount).toBe(1)
+  })
+
+  it('does not advance the queue on an end event while stopped', () => {
+    const player = new TestQueuePlayer()
+    player.forceStopped(true)
+
+    player.emit({ type: 'trackEndedNaturally' })
+
+    expect(player.endedCount).toBe(0)
+  })
+})

package/src/web/TrackPlayer/Player.load.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import type { Playback } from '../../features'
+import type { Track } from '../../types'
+import { Player } from './Player'
+
+// A Shaka load interrupted by stop() or a newer load() rejects; only the
+// active load may surface that rejection — otherwise the .catch clobbers the
+// Stopped state (or tears down the newer load via onError's unload).
+class LoadTestPlayer extends Player {
+  rejecters: Array<(err: unknown) => void> = []
+  resolvers: Array<() => void> = []
+  unloadCalls = 0
+
+  constructor() {
+    super()
+    this.element = {
+      play: () => Promise.resolve(),
+      pause: () => {}
+    } as unknown as HTMLMediaElement
+    this.player = {
+      load: () =>
+        new Promise<void>((resolve, reject) => {
+          this.resolvers.push(resolve)
+          this.rejecters.push(reject)
+        }),
+      unload: () => {
+        this.unloadCalls++
+        return Promise.resolve()
+      }
+    } as unknown as typeof this.player
+  }
+
+  read(): Playback {
+    return this.state
+  }
+
+  rejectLoad(index: number, err: unknown): void {
+    this.rejecters[index]?.(err)
+  }
+}
+
+const track = (n: number): Track =>
+  ({
+    id: `t${n}`,
+    src: `https://example.com/${n}.mp3`,
+    title: `T${n}`
+  }) as Track
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+describe('Player.load rejection staleness', () => {
+  it('a load rejected after stop() does not clobber the stopped state', async () => {
+    const player = new LoadTestPlayer()
+    player.load(track(1))
+    player.stop()
+
+    player.rejectLoad(0, new Error('LOAD_INTERRUPTED'))
+    await tick()
+
+    expect(player.read().state).toBe('stopped')
+  })
+
+  it('a load rejected after a newer load() stays silent', async () => {
+    const player = new LoadTestPlayer()
+    player.load(track(1))
+    player.load(track(2))
+    const unloadsBefore = player.unloadCalls
+
+    player.rejectLoad(0, new Error('LOAD_INTERRUPTED'))
+    await tick()
+
+    // The stale rejection must not set error state or unload the new load.
+    expect(player.read().state).not.toBe('error')
+    expect(player.unloadCalls).toBe(unloadsBefore)
+  })
+
+  it('the active load still surfaces its own failure', async () => {
+    const player = new LoadTestPlayer()
+    player.load(track(1))
+
+    player.rejectLoad(0, new Error('boom'))
+    await tick()
+
+    expect(player.read().state).toBe('error')
+  })
+})