react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

package/src/web/TrackPlayer/PlaybackStateMachine.ts

@@ -15,6 +15,12 @@ import type { PlaybackState } from '../../features'
  * | `paused`             | element `pause`                 |
  * | `trackEndedNaturally`| element `ended`                 |
  *
+ * `trackLoading` is left to Shaka rather than also dispatched when `load()` is
+ * called. Dispatching it up front would give the URL-resolution window a state
+ * to report, but it would put `loading` ahead of
+ * `onPlaybackActiveTrackChanged`, and native emits those the other way round —
+ * see the note in `NativeAudioBrowser.load`.
+ *
  * 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
@@ -24,11 +30,11 @@ import type { PlaybackState } from '../../features'
 export type PlaybackEvent =
   | { type: 'trackLoading' }
   | { type: 'trackEndedNaturally' }
-  | { type: 'loadSeekCompleted' }
+  | { type: 'loadSeekCompleted'; playWhenReady: boolean }
   | { type: 'paused'; hasAsset: boolean }
   | { type: 'waiting' }
   | { type: 'playing' }
-  | { type: 'bufferingSufficient' }
+  | { type: 'bufferingSufficient'; playWhenReady: boolean }
 
 /**
  * The next playback state for an event from the current state, or `null` to
@@ -56,7 +62,12 @@ export function nextPlaybackState(
       return 'playing'
     case 'loadSeekCompleted':
       // The settle after a load; meaningless from anything but a fresh load.
-      return current === 'loading' ? 'ready' : null
+      // `buffering` counts as one: a load now always passes through it.
+      if (current !== 'loading' && current !== 'buffering') return null
+      // Suppressed while the intent is to play, as Android suppresses
+      // STATE_READY there — it is a transient before `playing`, and emitting it
+      // flashes a settled, non-loading state mid-startup.
+      return event.playWhenReady ? null : 'ready'
     case 'paused':
       // A stopped player owns its state; a stray pause must not disturb it.
       if (current === 'stopped') return null
@@ -72,11 +83,16 @@ export function nextPlaybackState(
       // 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' ||
+      if (
+        current === 'playing' ||
         current === 'ended' ||
         current === 'stopped' ||
         current === 'error'
-        ? null
-        : 'ready'
+      ) {
+        return null
+      }
+      // Same suppression as `loadSeekCompleted`: while the intent is to play,
+      // `playing` is the next state worth reporting.
+      return event.playWhenReady ? null : 'ready'
   }
 }

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

@@ -23,8 +23,10 @@ class TestPlayer extends Player {
 
 class TestQueuePlayer extends QueuePlayer {
   endedCount = 0
-  protected onTrackEnded(): void {
+  /** Stands in for a handler that advances, so `ended` stays suppressed. */
+  protected onTrackEnded(): boolean {
     this.endedCount++
+    return true
   }
   forceStopped(stopped: boolean): void {
     this._isStopped = stopped
@@ -61,7 +63,7 @@ describe('Player.dispatch', () => {
     const player = new TestPlayer()
     player.forceState('playing')
 
-    player.emit({ type: 'bufferingSufficient' })
+    player.emit({ type: 'bufferingSufficient', playWhenReady: false })
 
     expect(player.read().state).toBe('playing')
   })
@@ -70,7 +72,7 @@ describe('Player.dispatch', () => {
     const player = new TestPlayer()
     player.forceState('loading')
 
-    player.emit({ type: 'loadSeekCompleted' })
+    player.emit({ type: 'loadSeekCompleted', playWhenReady: false })
 
     expect(player.read().state).toBe('ready')
   })

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

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import type { Playback } from '../../features'
 import type { Track } from '../../types'
 import { Player } from './Player'
@@ -84,3 +84,139 @@ describe('Player.load rejection staleness', () => {
     expect(player.read().state).toBe('error')
   })
 })
+
+/**
+ * The URL handed to Shaka can differ from the one the caller queued — a
+ * followed redirect, or a `transform` that rewrites it. Callers address tracks
+ * by their own `src` (mapping it back to their own content id, say), so a load
+ * must not rewrite the track's identity to a transport detail.
+ */
+describe('Player.load track identity', () => {
+  class SrcCapturingPlayer extends Player {
+    loadedSrc?: string
+
+    constructor() {
+      super()
+      this.element = {
+        play: () => Promise.resolve(),
+        pause: () => {}
+      } as unknown as HTMLMediaElement
+      this.player = {
+        load: (src: string) => {
+          this.loadedSrc = src
+          return Promise.resolve()
+        },
+        unload: () => Promise.resolve()
+      } as unknown as typeof this.player
+    }
+
+    headers(): Record<string, string> | undefined {
+      return this.mediaHeaders
+    }
+  }
+
+  const queued = {
+    id: 't1',
+    src: 'https://api.example.com/stream/content/7',
+    title: 'T1'
+  } as Track
+  const resolved = 'https://cdn.example.com/track.mp3?sig=abc'
+
+  it('plays the resolved url but keeps the queued track as current', async () => {
+    const player = new SrcCapturingPlayer()
+
+    player.load(queued, undefined, { src: resolved })
+    await tick()
+
+    expect(player.loadedSrc).toBe(resolved)
+    expect(player.current?.src).toBe(queued.src)
+  })
+
+  it('reports the queued track to onLoaded', async () => {
+    const player = new SrcCapturingPlayer()
+    const onLoaded = vi.fn()
+
+    player.load(queued, onLoaded, { src: resolved })
+    await tick()
+
+    expect(onLoaded).toHaveBeenCalledWith(
+      expect.objectContaining({ src: queued.src })
+    )
+  })
+
+  it('falls back to the track src when no override is given', async () => {
+    const player = new SrcCapturingPlayer()
+
+    player.load(queued)
+    await tick()
+
+    expect(player.loadedSrc).toBe(queued.src)
+    expect(player.current?.src).toBe(queued.src)
+  })
+
+  it('stores headers for the request filter, ignoring an empty set', async () => {
+    const player = new SrcCapturingPlayer()
+
+    player.load(queued, undefined, { headers: { Authorization: 'Bearer t' } })
+    await tick()
+    expect(player.headers()).toEqual({ Authorization: 'Bearer t' })
+
+    player.load(queued, undefined, { headers: {} })
+    await tick()
+    expect(player.headers()).toBeUndefined()
+  })
+})
+
+/**
+ * A track that fails to load is still the active track. Native derives the
+ * active track from the queue, so an app always has something to attach a
+ * playback error to; web tying it to load success meant a failed track left
+ * `getActiveTrack()` undefined, and UIs keyed on it rendered nothing at all —
+ * the error had nowhere to appear.
+ */
+describe('Player.load active track on failure', () => {
+  const track = (n: number): Track =>
+    ({
+      id: `t${n}`,
+      src: `https://example.com/${n}.mp3`,
+      title: `T${n}`
+    }) as Track
+
+  it('keeps the failed track as current so an error has a home', async () => {
+    const player = new LoadTestPlayer()
+
+    player.load(track(1))
+    expect(player.current?.src).toBe(track(1).src)
+
+    player.rejectLoad(0, new Error('401'))
+    await tick()
+
+    expect(player.current?.src).toBe(track(1).src)
+    expect(player.read().state).toBe('error')
+  })
+
+  it('reflects the newest attempt when a load supersedes another', async () => {
+    const player = new LoadTestPlayer()
+
+    player.load(track(1))
+    player.load(track(2))
+
+    expect(player.current?.src).toBe(track(2).src)
+
+    // the superseded load rejecting must not resurrect the older track
+    player.rejectLoad(0, new Error('stale'))
+    await tick()
+
+    expect(player.current?.src).toBe(track(2).src)
+  })
+
+  it('is set for an unplayable track with no src', async () => {
+    const player = new LoadTestPlayer()
+
+    player.load({ id: 'x', title: 'No Src' } as Track)
+    await tick()
+
+    expect(player.current?.id).toBe('x')
+    expect(player.read().state).toBe('error')
+  })
+})

package/src/web/TrackPlayer/Player.ts

@@ -9,6 +9,7 @@ import type {
 import type { Track } from '../../types'
 import type { PlaybackEvent } from './PlaybackStateMachine'
 import { playbackErrorKind } from '../playbackErrorKind'
+import { LoadAttempt } from './LoadAttempt'
 import { nextPlaybackState } from './PlaybackStateMachine'
 import { SetupNotCalledError } from './SetupNotCalledError'
 import { State } from './State'
@@ -32,6 +33,41 @@ interface ShakaError {
   data?: unknown[]
 }
 
+/** Per-load overrides that don't belong on the track itself. */
+export interface LoadOptions {
+  /**
+   * The attempt this load belongs to, when a subclass began one before
+   * resolving the URL. Internal plumbing: without it a direct `load()` is the
+   * outermost call and starts its own, so two of them supersede each other.
+   */
+  attempt?: LoadAttempt
+  /**
+   * Whether this load is a re-prepare of the current item, when a subclass
+   * captured {@link Player._repreparing} before an async stage and calls
+   * `super.load()` after it, once the flag has been reset.
+   */
+  reprepare?: boolean
+  /** Headers resolved from the media configuration, applied to Shaka's requests. */
+  headers?: Record<string, string>
+  /**
+   * The URL to play, when it differs from `track.src` — a followed redirect,
+   * say. Kept here rather than rewritten onto the track so the caller's own
+   * identity for it survives the load.
+   */
+  src?: string
+}
+
+/** The mutable request Shaka hands to a networking-engine request filter. */
+interface ShakaRequest {
+  headers: Record<string, string>
+}
+
+/**
+ * `shaka.util.Error.Code.LOAD_INTERRUPTED`. Inlined because shaka is imported
+ * for types only here, as the codes in `playbackErrorKind.ts` are.
+ */
+const LOAD_INTERRUPTED = 7000
+
 interface ShakaBufferingEvent extends CustomEvent {
   detail: {
     buffering: boolean
@@ -48,6 +84,12 @@ export class Player {
   protected _isStopped = false
   protected _loadInProgress = false
   protected _pendingSeek: number | undefined
+  /**
+   * Headers for the track currently loaded, applied by the request filter
+   * installed in `setupPlayer`. On the instance rather than per request so the
+   * manifest, its segments and any key requests all carry them.
+   */
+  protected mediaHeaders?: Record<string, string>
 
   // current getter/setter
   public get current(): Track | undefined {
@@ -125,6 +167,17 @@ export class Player {
     await player.attach(element)
     this.player = player
 
+    // Apply the media config's headers to Shaka's requests, as native does to
+    // the AVURLAsset / ExoPlayer DataSpec. Without this they resolve and are
+    // then dropped, and authenticated media 401s on web alone.
+    player
+      .getNetworkingEngine()
+      ?.registerRequestFilter((_type: unknown, request: ShakaRequest) => {
+        const headers = this.mediaHeaders
+        if (!headers) return
+        request.headers = { ...request.headers, ...headers }
+      })
+
     // Listen for relevant events
     player.addEventListener('error', (event: Event) => {
       const errorEvent = event as ShakaErrorEvent
@@ -137,15 +190,27 @@ export class Player {
     element.addEventListener('playing', () =>
       this.dispatch({ type: 'playing' })
     )
-    element.addEventListener('pause', () =>
+    element.addEventListener('pause', () => {
+      // A track playing out fires `pause` and then `ended`. Only the `ended`
+      // is meaningful — reporting `paused` first flashes a state Android never
+      // reports, mid-queue or at the true end.
+      if (element.ended) return
       this.dispatch({ type: 'paused', hasAsset: this.current !== undefined })
-    )
+    })
 
-    player.addEventListener('loading', () =>
+    player.addEventListener('loading', () => {
       this.dispatch({ type: 'trackLoading' })
-    )
+      // Every load passes through `buffering`, as ExoPlayer's always does via
+      // STATE_BUFFERING. Shaka only fires its own `buffering` event when a load
+      // actually stalls, so a load served from cache would otherwise skip a
+      // state native always reports.
+      this.dispatch({ type: 'waiting' })
+    })
     player.addEventListener('loaded', () =>
-      this.dispatch({ type: 'loadSeekCompleted' })
+      this.dispatch({
+        type: 'loadSeekCompleted',
+        playWhenReady: this.playWhenReady
+      })
     )
 
     player.addEventListener('buffering', (event: Event) => {
@@ -153,7 +218,10 @@ export class Player {
       this.dispatch(
         bufferingEvent.detail.buffering === true
           ? { type: 'waiting' }
-          : { type: 'bufferingSufficient' }
+          : {
+              type: 'bufferingSufficient',
+              playWhenReady: this.playWhenReady
+            }
       )
     })
 
@@ -208,6 +276,24 @@ export class Player {
   }
 
   protected onError(shakaError: ShakaError): void {
+    // An interrupted load is not a failure. Shaka raises it when a `load()` is
+    // cut short by a newer `load()` or an `unload()` — always something we
+    // asked for — and names it accordingly: `createAbortLoadError_()`. Its own
+    // code skips its cleanup unload for this code too (player.js:2010).
+    //
+    // Recognising it here rather than pre-emptively invalidating the load keeps
+    // the two independent: any teardown, in any order, can abort a load without
+    // the abort reaching a consumer as an error. Eagerly unloading to stop the
+    // outgoing track used to flash an error banner on every fast track switch.
+    if (shakaError.code === LOAD_INTERRUPTED) {
+      console.debug('Load interrupted by a newer load or an unload')
+      return
+    }
+
+    // Before the unload below resets it: a retry resumes from where playback
+    // failed, as native does.
+    this.rememberResumePosition()
+
     // unload the current track to allow for clean playback on other
     this.player?.unload().catch((err) => {
       console.error(`Error unloading player on 'onError'`, err)
@@ -236,18 +322,60 @@ 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
+  /**
+   * The load attempt that owns the player, or none. See {@link LoadAttempt}.
+   */
+  private _attempt: LoadAttempt | undefined
+
+  /**
+   * Starts an attempt, superseding whatever was in flight.
+   *
+   * Called by the outermost `load()` so supersession is registered when the
+   * caller asks for it, not when some inner stage happens to reach it.
+   */
+  protected beginLoadAttempt(): LoadAttempt {
+    this._attempt?.cancel()
+    const attempt = new LoadAttempt()
+    this._attempt = attempt
+    return attempt
+  }
+
+  /** Abandons the attempt in flight without starting another — `stop()`. */
+  protected cancelLoadAttempt(): void {
+    this._attempt?.cancel()
+    this._attempt = undefined
+  }
 
-  public load(track: Track, onLoaded?: (track: Track) => void): void {
+  public load(
+    track: Track,
+    onLoaded?: (track: Track) => void,
+    options?: LoadOptions
+  ): void {
     const player = this.requirePlayer()
     this._isStopped = false
     this._loadInProgress = true
-    const generation = ++this._loadGeneration
-
-    if (!track.src) {
+    const headers = options?.headers
+    this.mediaHeaders =
+      headers && Object.keys(headers).length > 0 ? headers : undefined
+    // What Shaka plays may differ from what the caller queued; `track` is left
+    // alone so `current` and `getActiveTrack()` keep the caller's identity for
+    // it rather than a transport detail.
+    const playbackSrc = options?.src ?? track.src
+    // Current on the attempt, not on success — native derives the active track
+    // from the queue, so a failed load is still the active track there and its
+    // error has somewhere to show. `getActiveTrackIndex()` already reported the
+    // queue's index either way; this makes the pair agree.
+    this.current = track
+    // Only a re-prepare carries the remembered position, and `reprepare()`
+    // has already read it by now.
+    if (!(options?.reprepare ?? this._repreparing)) this._resume = undefined
+    // The attempt a subclass began before resolving the URL, so its resolution
+    // stage and both continuations below share one token. Passed rather than
+    // read off the instance: a direct `load()` is itself the outermost call and
+    // must start a fresh attempt, superseding whatever was in flight.
+    const attempt = options?.attempt ?? this.beginLoadAttempt()
+
+    if (!playbackSrc) {
       this._loadInProgress = false
       this._pendingSeek = undefined
       const error: PlaybackError = {
@@ -263,11 +391,10 @@ export class Player {
     }
 
     player
-      .load(track.src)
+      .load(playbackSrc)
       .then(() => {
-        if (generation !== this._loadGeneration || this._isStopped) return
+        if (!attempt.isCurrent) return
         this._loadInProgress = false
-        this.current = track
         onLoaded?.(track)
 
         // Execute any pending seek that arrived during loading
@@ -282,7 +409,7 @@ export class Player {
         }
       })
       .catch((err: unknown) => {
-        if (generation !== this._loadGeneration || this._isStopped) return
+        if (!attempt.isCurrent) return
         this._loadInProgress = false
         this._pendingSeek = undefined
         this.onError(this.toNormalizedError(err))
@@ -292,8 +419,14 @@ export class Player {
   public stop(onComplete?: () => void): void {
     const player = this.requirePlayer()
 
+    // Whatever was loading no longer owns the player: its continuations, at
+    // either boundary, must not revive it.
+    this.cancelLoadAttempt()
+
     // Match Android: stop sets playWhenReady=false and state=stopped,
-    // but keeps the current track so play() can resume.
+    // but keeps the current track so play() can resume — from where it
+    // stopped, which ExoPlayer preserves across its own stop/prepare pair.
+    this.rememberResumePosition()
     this._isStopped = true
     this._loadInProgress = false
     this._pendingSeek = undefined
@@ -309,37 +442,151 @@ export class Player {
       })
   }
 
+  /**
+   * Where playback was when it failed or was stopped, so a re-prepare can
+   * resume rather than restart.
+   *
+   * Kept against the track it belongs to rather than as a bare number, so it
+   * self-invalidates when a different track becomes current and cannot be
+   * applied to the wrong one. A fresh `load()` clears it; a re-prepare keeps
+   * it, so a retry that fails still knows where the next one resumes.
+   */
+  private _resume: { track: Track; position: number } | undefined
+
+  /**
+   * Whether the load in progress is a re-prepare of the current item rather
+   * than a new one — set by {@link reloadCurrent} for the duration of its
+   * `load()` call. A re-prepare keeps the remembered position; every other
+   * load resets it.
+   */
+  protected _repreparing = false
+
+  /**
+   * Records the current position, when there is one worth recording.
+   *
+   * A zero is never recorded: `onError` runs for a *load* failure too, where
+   * the element has just been torn down and reads 0, and overwriting a good
+   * position with that made a failed retry lose the place a successful one
+   * would have resumed from.
+   */
+  private rememberResumePosition(): void {
+    const position = this.element?.currentTime
+    const track = this.current
+    if (!track || typeof position !== 'number' || position <= 0) return
+    this._resume = { track, position }
+  }
+
+  /**
+   * Android's `prepare()`, which both `play()` and `retry()` call.
+   *
+   * It early-returns unless ExoPlayer is STATE_IDLE, so it reconnects after an
+   * error or a stop and never re-buffers a healthy stream; `error`/`_isStopped`
+   * is web's equivalent of idle. Re-preparing re-resolves the URL, which is the
+   * whole point — a signed URL or token may have expired since the failure, and
+   * replaying the cached one just fails again. iOS says the same thing in its
+   * own `retry()`: "Re-resolve rather than replay the cached URL".
+   *
+   * Returns whether it handled the call, so `play()` knows not to also poke the
+   * element.
+   */
+  protected reprepare(): boolean {
+    if (!this.current) return false
+    if (this.state.state !== State.Error && !this._isStopped) return false
+
+    // Not for live: `currentTime` there is elapsed time on a connection that no
+    // longer exists, and a fresh connection already *is* the live edge. Seeking
+    // to the old value asks for a point the new stream does not have. The
+    // track's own `live` declaration is the gate, as it is in `seekToLiveEdge`
+    // and on both native platforms.
+    const remembered =
+      this._resume?.track === this.current ? this._resume.position : undefined
+    const resume = this.current.live === true ? undefined : remembered
+
+    this.reloadCurrent(resume)
+    return true
+  }
+
   public play(): void {
     const element = this.requireElement()
     this.playWhenReady = true
 
-    if (this.state.state === State.Error && this.current) {
-      this.reloadCurrent()
-      return
-    }
+    // Matches Android's play(): set the intent, then prepare — which does
+    // something only when idle, i.e. after an error or a stop.
+    if (this.reprepare()) return
 
-    // Match Android: play() after stop() re-prepares the current track
-    if (this._isStopped && this.current) {
-      this.reloadCurrent()
-      return
-    }
+    element.play().catch((err: unknown) => this.onPlayRejected(err))
+  }
+
+  /**
+   * A rejected `element.play()`. Web-only: neither native platform can refuse
+   * a play intent, so there is no parity target here.
+   *
+   * `AbortError` means a newer load interrupted this one — that load owns the
+   * state and the intent stands. So does a rejection while a load is still in
+   * flight: `load()` then `play()` is the library's own sequence, and until
+   * Shaka has a source the element may refuse (Firefox rejects a source-less
+   * element with `NotSupportedError`; Chrome leaves it pending). The load
+   * calls `play()` again on success, and a real refusal repeats there.
+   * Anything else, autoplay policy above all, is the browser refusing: the
+   * intent cannot be honoured, so it is cleared and the state settles rather
+   * than stranding on `loading`/`buffering`, which is where suppressing
+   * `ready` under `playWhenReady` would otherwise leave it.
+   */
+  private onPlayRejected(err: unknown): void {
+    console.error(err)
+    const name =
+      typeof err === 'object' && err !== null && 'name' in err
+        ? (err as { name?: unknown }).name
+        : undefined
+    if (name === 'AbortError' || this._loadInProgress) return
 
-    element.play().catch((err: unknown) => console.error(err))
+    this.playWhenReady = false
+    this.dispatch({ type: 'paused', hasAsset: this.current !== undefined })
   }
 
   /**
-   * 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.
+   * The track a reload re-feeds. `current` holds it as the caller queued it —
+   * `load()` takes the resolved URL separately, via `LoadOptions.src` — so
+   * re-feeding it is safe.
+   *
+   * The overridable part of {@link reloadCurrent}, rather than the whole
+   * method: a subclass backed by a queue changes only where the track comes
+   * from, and the reload itself stays in one place.
    */
-  protected reloadCurrent(): void {
-    if (this.current) this.load(this.current)
+  protected trackToReload(): Track | undefined {
+    return this.current
+  }
+
+  /** Reloads the track {@link trackToReload} names, resuming if asked to. */
+  protected reloadCurrent(resumePosition?: number): void {
+    const track = this.trackToReload()
+    if (!track) return
+    this._repreparing = true
+    try {
+      this.load(
+        track,
+        resumePosition === undefined
+          ? undefined
+          : () => this.seekTo(resumePosition)
+      )
+    } finally {
+      this._repreparing = false
+    }
   }
 
+  /**
+   * Android's `retry()` is `player.prepare()` — the same call `play()` makes,
+   * without setting the intent. So this is `play()` minus the intent.
+   *
+   * It is emphatically not `shaka.Player.retryStreaming()`, which this used to
+   * call: that returns false and does nothing at all unless the load mode is
+   * MEDIA_SOURCE, so for a progressive file — the case a signed URL is for — it
+   * was a silent no-op, while the `play()` the same docs offer as the
+   * alternative recovered properly.
+   */
   public retry(): void {
-    const player = this.requirePlayer()
-    player.retryStreaming()
+    this.requirePlayer()
+    this.reprepare()
   }
 
   public pause(): void {