react-native-audio-browser 0.2.0-next.9 → 0.2.0

package/src/web/NativeAudioBrowser.playWhenReady.test.ts

@@ -1,301 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type { PlaybackState } from '../features'
-import type { Track } from '../types'
-import { NativeAudioBrowser } from './NativeAudioBrowser'
-
-// Transport calls must emit the intent change through the playWhenReady
-// accessor override — they previously wrote the raw base field, so JS
-// consumers never heard about play()/pause()/stop() intent changes (only
-// setPlayWhenReady()'s) and MediaSession never synced.
-class TestBrowser extends NativeAudioBrowser {
-  playCalls = 0
-  pauseCalls = 0
-
-  constructor() {
-    super()
-    // Minimal fakes so transport calls run without setupPlayer/DOM.
-    this.element = {
-      play: () => {
-        this.playCalls++
-        return Promise.resolve()
-      },
-      pause: () => {
-        this.pauseCalls++
-      }
-    } as unknown as HTMLMediaElement
-    this.player = {
-      load: () => Promise.resolve(),
-      unload: () => Promise.resolve()
-    } as unknown as typeof this.player
-  }
-
-  forceState(state: PlaybackState): void {
-    this.state = { state }
-  }
-}
-
-const track: Track = {
-  id: 't1',
-  src: 'https://example.com/audio.mp3',
-  title: 'Test Track'
-}
-
-function makeBrowser(): { browser: TestBrowser; emitted: boolean[] } {
-  const browser = new TestBrowser()
-  const emitted: boolean[] = []
-  browser.onPlaybackPlayWhenReadyChanged = (event) =>
-    emitted.push(event.playWhenReady)
-  return { browser, emitted }
-}
-
-describe('NativeAudioBrowser playWhenReady emission', () => {
-  it('play() emits the intent change', () => {
-    const { browser, emitted } = makeBrowser()
-    browser.play()
-    expect(emitted).toEqual([true])
-  })
-
-  it('pause() emits the intent change', () => {
-    const { browser, emitted } = makeBrowser()
-    browser.play()
-    browser.pause()
-    expect(emitted).toEqual([true, false])
-  })
-
-  it('stop() emits the intent change', () => {
-    const { browser, emitted } = makeBrowser()
-    browser.play()
-    browser.stop()
-    expect(emitted).toEqual([true, false])
-  })
-
-  it('does not emit when the value is unchanged', () => {
-    const { browser, emitted } = makeBrowser()
-    browser.play()
-    browser.play()
-    expect(emitted).toEqual([true])
-  })
-})
-
-// setPlayWhenReady must drive the engine like native, not just the flag:
-// audio kept playing after setPlayWhenReady(false) while every event and
-// MediaSession reported paused, and true from 'paused' never resumed.
-describe('NativeAudioBrowser setPlayWhenReady drives the engine', () => {
-  it('false pauses the element', () => {
-    const { browser } = makeBrowser()
-    browser.play()
-    browser.forceState('playing')
-
-    browser.setPlayWhenReady(false)
-
-    expect(browser.pauseCalls).toBe(1)
-    expect(browser.getPlayWhenReady()).toBe(false)
-  })
-
-  it('true from paused resumes the element', () => {
-    const { browser } = makeBrowser()
-    browser.current = track
-    browser.forceState('paused')
-
-    browser.setPlayWhenReady(true)
-
-    expect(browser.playCalls).toBe(1)
-  })
-
-  it('true while loading only sets the flag (load auto-plays)', () => {
-    const { browser } = makeBrowser()
-    browser.current = track
-    browser.forceState('loading')
-
-    browser.setPlayWhenReady(true)
-
-    expect(browser.playCalls).toBe(0)
-    expect(browser.getPlayWhenReady()).toBe(true)
-  })
-})
-
-// Intent-only changes alter the derived playing/buffering flags without a
-// state transition (e.g. pause during 'loading') — they must emit too, and
-// identical derivations must not double-emit (parity with Android's
-// refreshPlayingState dedupe).
-describe('NativeAudioBrowser playing-state emission', () => {
-  it('emits on an intent-only change', () => {
-    const { browser } = makeBrowser()
-    const states: Array<{ playing: boolean; buffering: boolean }> = []
-    browser.onPlaybackPlayingState = (s) =>
-      states.push({ playing: s.playing, buffering: s.buffering })
-    browser.forceState('loading')
-    browser.setPlayWhenReady(true)
-    states.length = 0
-
-    browser.setPlayWhenReady(false)
-
-    expect(states).toEqual([{ playing: false, buffering: false }])
-  })
-
-  it('does not re-emit an identical derivation across state changes', () => {
-    const { browser } = makeBrowser()
-    const states: Array<{ playing: boolean }> = []
-    browser.onPlaybackPlayingState = (s) => states.push({ playing: s.playing })
-
-    browser.forceState('paused')
-    browser.forceState('stopped')
-
-    // pwr is false throughout: both derive {playing:false,buffering:false}.
-    expect(states.length).toBe(1)
-  })
-})
-
-describe('NativeAudioBrowser stop vs in-flight load', () => {
-  it('stop() invalidates a load still resolving its URL', async () => {
-    const { browser } = makeBrowser()
-    browser.load(track)
-    browser.stop()
-
-    // Let the load's post-await continuation run.
-    await new Promise((resolve) => setTimeout(resolve, 0))
-
-    // The stale load must not revive the player: previously its continuation
-    // re-armed _isStopped = false and set the current track after stop().
-    expect(browser.current).toBeUndefined()
-    expect(browser.getPlayback().state).toBe('stopped')
-  })
-})
-
-// Queue mutations must emit onPlaybackQueueChanged (the JS contract documents
-// "added, removed, reordered"; Android emits via onTimelineChanged) — only
-// load/setQueue did on web, so useQueue() went stale after any mutation.
-describe('NativeAudioBrowser queue change events', () => {
-  function makeQueueBrowser(): {
-    browser: TestBrowser
-    lengths: number[]
-  } {
-    class QueueEventBrowser extends TestBrowser {
-      load(): void {}
-    }
-    const browser = new QueueEventBrowser()
-    const lengths: number[] = []
-    browser.onPlaybackQueueChanged = (queue) => lengths.push(queue.length)
-    browser.setQueue([track, { ...track, id: 't2' }], 0)
-    lengths.length = 0
-    return { browser, lengths }
-  }
-
-  it('add emits', () => {
-    const { browser, lengths } = makeQueueBrowser()
-    browser.add([{ ...track, id: 't3' }])
-    expect(lengths).toEqual([3])
-  })
-
-  it('remove emits', () => {
-    const { browser, lengths } = makeQueueBrowser()
-    browser.remove([1])
-    expect(lengths).toEqual([1])
-  })
-
-  it('move emits', () => {
-    const { browser, lengths } = makeQueueBrowser()
-    browser.move(0, 1)
-    expect(lengths).toEqual([2])
-  })
-
-  it('removeUpcomingTracks emits', () => {
-    const { browser, lengths } = makeQueueBrowser()
-    browser.removeUpcomingTracks()
-    expect(lengths).toEqual([1])
-  })
-
-  it('reset emits the emptied queue', () => {
-    const { browser, lengths } = makeQueueBrowser()
-    browser.reset()
-    expect(lengths).toEqual([0])
-  })
-})
-
-// The queue array must never leak by live reference: in-place mutations
-// (add/move) otherwise emit the same object React already holds, and the
-// useState Object.is bailout suppresses the re-render the event exists for.
-describe('NativeAudioBrowser queue reference freshness', () => {
-  it('emits a fresh array on each mutation', () => {
-    class QueueEventBrowser extends TestBrowser {
-      load(): void {}
-    }
-    const browser = new QueueEventBrowser()
-    const seen: object[] = []
-    browser.onPlaybackQueueChanged = (queue) => seen.push(queue)
-    browser.setQueue([track, { ...track, id: 't2' }], 0)
-
-    browser.add([{ ...track, id: 't3' }])
-    browser.move(0, 1)
-
-    expect(seen[1]).not.toBe(seen[0])
-    expect(seen[2]).not.toBe(seen[1])
-    expect(seen[2]).not.toBe(browser.getQueue())
-  })
-
-  it('getQueue returns a defensive copy', () => {
-    class QueueEventBrowser extends TestBrowser {
-      load(): void {}
-    }
-    const browser = new QueueEventBrowser()
-    browser.setQueue([track, { ...track, id: 't2' }], 0)
-
-    browser.getQueue().length = 0
-
-    expect(browser.getQueue().length).toBe(2)
-  })
-})
-
-// Halting must precede the fade-cancel volume restore — the reverse lets
-// full-volume audio slip out while the element is still playing.
-describe('NativeAudioBrowser sleep-fade halt order', () => {
-  it('setPlayWhenReady(false) pauses before restoring the fading volume', () => {
-    const order: string[] = []
-    class FadeBrowser extends NativeAudioBrowser {
-      constructor() {
-        super()
-        this.element = {
-          play: () => Promise.resolve(),
-          pause: () => {
-            order.push('pause')
-          },
-          get volume() {
-            return 1
-          },
-          set volume(_v: number) {
-            order.push('volume')
-          }
-        } as unknown as HTMLMediaElement
-        this.player = {
-          unload: () => Promise.resolve()
-        } as unknown as typeof this.player
-      }
-    }
-    const browser = new FadeBrowser()
-    ;(
-      browser as unknown as { sleepFader: { start(d: number): void } }
-    ).sleepFader.start(10)
-    order.length = 0
-
-    browser.setPlayWhenReady(false)
-
-    expect(order[0]).toBe('pause')
-    expect(order).toContain('volume')
-  })
-})
-
-describe('NativeAudioBrowser setQueue start position', () => {
-  it('passes startPosition through to skip() in seconds', () => {
-    const skips: Array<[number, number | undefined]> = []
-    class SkipRecordingBrowser extends TestBrowser {
-      skip(index: number, initialPosition?: number): void {
-        skips.push([index, initialPosition])
-      }
-    }
-    const browser = new SkipRecordingBrowser()
-
-    browser.setQueue([track], 0, 30)
-
-    expect(skips).toEqual([[0, 30]])
-  })
-})

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

@@ -1,139 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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

@@ -1,33 +0,0 @@
-/**
- * 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
-    }
-  }
-}