react-native-audio-browser 0.2.0-next.18 → 0.2.0-next.19

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,35 @@ 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
+  /** 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 +78,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 +161,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 +184,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 +212,10 @@ export class Player {
       this.dispatch(
         bufferingEvent.detail.buffering === true
           ? { type: 'waiting' }
-          : { type: 'bufferingSufficient' }
+          : {
+              type: 'bufferingSufficient',
+              playWhenReady: this.playWhenReady
+            }
       )
     })
 
@@ -208,6 +270,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 +316,57 @@ 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
+    // 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 +382,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 +400,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 +410,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 +433,132 @@ 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.
+   */
+  private _resume: { track: Track; position: number } | undefined
+
+  /**
+   * 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. 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') 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.load(
+      track,
+      resumePosition === undefined
+        ? undefined
+        : () => this.seekTo(resumePosition)
+    )
   }
 
+  /**
+   * 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 {

package/src/web/TrackPlayer/QueuePlayer.ts

@@ -22,18 +22,33 @@ export class QueuePlayer extends Player {
     // was a silent pause) and armed load()'s auto-play with phantom intent.
     // Cleared before the state lands so consumers observe the native order
     // (intent → state → queueEnded), independent of onQueueEnded overrides.
-    // Per-track ends that advance the queue keep the intent.
-    if (state === State.Ended && this.endsQueue()) {
-      this.playWhenReady = false
+    if (state !== State.Ended) {
+      super.applyState(state)
+      return
     }
 
-    super.applyState(state)
-
-    // dispatch() already gates on _isStopped before reaching applyState, so a
-    // natural end while stopped never advances the queue.
-    if (state === State.Ended) {
+    // A track ending mid-queue is not an `ended` playback state: ExoPlayer
+    // reaches STATE_ENDED only at the end of the *playlist*, and an advance
+    // between items stays READY/BUFFERING. Web loads one track at a time, so
+    // the element's own `ended` arrives every time — reporting it flashed a
+    // terminal state, and dropped `PlayingState.playing` to false, between
+    // every pair of tracks. Repeat-one counts as mid-queue for the same
+    // reason: native reports nothing there either.
+    if (this.endsQueue()) {
+      // The real end: the intent goes with it, and the state is genuinely ended.
+      this.playWhenReady = false
+      super.applyState(state)
+      // dispatch() already gates on _isStopped before reaching applyState, so a
+      // natural end while stopped never advances the queue.
       this.onTrackEnded()
+      return
     }
+
+    // Suppressing `ended` is only safe when something takes over the state. A
+    // handler that declines to advance — the sleep timer set to end-of-track —
+    // leaves nothing to move it, and the player would sit reporting `playing`
+    // with nothing playing. Report the end in that case, as before.
+    if (!this.onTrackEnded()) super.applyState(state)
   }
 
   /** True when a natural end has nowhere to go: not repeating, no next track. */
@@ -45,18 +60,22 @@ export class QueuePlayer extends Player {
     )
   }
 
-  protected onTrackEnded() {
+  /**
+   * @returns whether it started another load, and so owns the playback state
+   *   from here. `false` means the caller still has to report the end itself.
+   */
+  protected onTrackEnded(): boolean {
     if (this.queue.repeatMode === RepeatMode.Track) {
-      if (this.queue.currentIndex !== undefined) {
-        this.goToIndex(this.queue.currentIndex)
-      }
-      return
+      if (this.queue.currentIndex === undefined) return false
+      this.goToIndex(this.queue.currentIndex)
+      return true
     }
     if (this.endsQueue()) {
       this.onQueueEnded()
-      return
+      return false
     }
     this.skipToNext()
+    return true
   }
 
   /**