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

package/src/web/NativeAudioBrowser.ts

@@ -42,7 +42,12 @@ import type {
   AudioBrowser as AudioBrowserSpec,
   Output
 } from '../specs/audio-browser.nitro'
-import type { ResolvedTrack, Track, TrackLoadEvent } from '../types'
+import type {
+  ResolvedTrack,
+  Track,
+  TrackLoadEvent,
+  TransformableRequestConfig
+} from '../types'
 import type { NativeBrowserConfiguration } from '../types/browser-native'
 import { getTrackIdentity } from '../utils/getTrackIdentity'
 import { BrowserManager } from './browser/BrowserManager'
@@ -50,8 +55,12 @@ import { classifyTrackNavigation } from './browser/classifyTrackNavigation'
 import { FavoriteManager } from './browser/FavoriteManager'
 import { NavigationErrorManager } from './browser/NavigationErrorManager'
 import { SearchManager } from './browser/SearchManager'
+import { followMediaRedirect } from './http/followMediaRedirect'
 import { HttpClient } from './http/HttpClient'
-import { RequestConfigBuilder } from './http/RequestConfigBuilder'
+import {
+  RequestConfigBuilder,
+  type ResolvedMediaRequest
+} from './http/RequestConfigBuilder'
 import { NowPlayingManager } from './player/NowPlayingManager'
 import { OptionsManager } from './player/OptionsManager'
 import { RemoteCommandController } from './player/RemoteCommandController'
@@ -96,7 +105,6 @@ export class NativeAudioBrowser
   private remoteCommands: RemoteCommandController
 
   // Player state
-  private currentLoadId = 0
   private progressTimer = new PlaybackTimer()
   private intervalTimer = new PlaybackTimer()
   private _online: boolean =
@@ -306,6 +314,11 @@ export class NativeAudioBrowser
 
     if (newState.state === 'error' && newState.error) {
       this.onPlaybackError({ error: newState.error })
+    } else if (oldState.state === 'error') {
+      // Leaving the error state clears it, as it does natively. The getter
+      // already reads undefined — consumers subscribe to the event, so without
+      // this a stale error outlives the next successful load.
+      this.onPlaybackError({ error: undefined })
     }
   }
 
@@ -610,71 +623,102 @@ export class NativeAudioBrowser
    * Supports the transform callback for URL manipulation.
    * Mirrors Android's MediaFactory.getMediaRequestConfig behavior.
    */
-  private async resolveMediaUrl(src: string): Promise<string> {
-    const { request, media } = this.browserManager.configuration
-    return RequestConfigBuilder.resolveMediaUrl(src, request, media)
+  private async resolveMediaRequest(
+    src: string,
+    track: Track
+  ): Promise<ResolvedMediaRequest> {
+    // The *resolved* request layer, not `configuration.request`: a
+    // resolver-only config would otherwise reach media with no baseUrl and no
+    // headers. Browse, search and browse artwork all read it this way too.
+    //
+    // Caught, because unlike those three this one cannot fail the load: a
+    // resolver hiccup — a token refresh timing out — would otherwise take down
+    // a track whose `src` is already absolute and public and needed no layer at
+    // all. Native degrades the same way, `getMediaRequestConfig` returning null
+    // and the original URL playing on.
+    let request: TransformableRequestConfig | undefined
+    try {
+      request = await this.browserManager.resolvedRequestConfig()
+    } catch (e) {
+      console.error('Failed to resolve the request layer for media', e)
+    }
+    const { media } = this.browserManager.configuration
+    return RequestConfigBuilder.resolveMediaRequest(src, request, media, track)
   }
 
   /**
-   * Reload from the queue's own entry, whose `src` is still unresolved —
-   * `current` holds the resolved track, and re-feeding it into `load()` would
-   * re-resolve the resolved URL (double-applying a `transform`) and replace
-   * the queue entry with it.
+   * The queue's own entry, so the queue stays the source of truth for what is
+   * playing. `current` preserves the track as queued — the resolved URL is
+   * passed to `load()` separately — so either is safe to re-feed.
    */
-  protected override reloadCurrent(): void {
+  protected override trackToReload(): Track | undefined {
     const index = this.queue.currentIndex
-    const sourceTrack =
-      index !== undefined ? this.queue.getTrack(index) : undefined
-    if (sourceTrack) {
-      this.load(sourceTrack)
-    } else {
-      super.reloadCurrent()
-    }
+    const queued = index !== undefined ? this.queue.getTrack(index) : undefined
+    // The queue entry wins, so it stays the source of truth for what is
+    // playing; `current` is the fallback for a player loaded without one.
+    return queued ?? super.trackToReload()
   }
 
-  load(track: Track, callback?: (track: Track) => void): void {
-    const element = this.requireElement()
-
-    // Clear now playing override when track changes (matches Android's PlayerListener.onMediaItemTransition)
-    this.nowPlayingManager.clearNowPlayingOverride()
-
-    // Match Android: load() modifies the queue.
-    // If queue is empty, add the track. If queue has items, replace at currentIndex.
+  /**
+   * Makes `track` the queue's current entry, emitting the change.
+   *
+   * Matches Android, where `load()` modifies the queue: an empty queue takes
+   * the track as its only entry, a populated one has its current entry
+   * replaced.
+   */
+  private syncQueueTo(track: Track): void {
     if (this.queue.length === 0) {
       this.queue.setTracks([track])
       this.queue.currentIndex = 0
       this.emitQueueChanged()
-    } else if (
+      return
+    }
+    if (
       this.queue.currentIndex !== undefined &&
       this.queue.getTrack(this.queue.currentIndex) !== track
     ) {
       this.queue.replaceTrack(this.queue.currentIndex, track)
       this.emitQueueChanged()
     }
+  }
 
+  /**
+   * Everything native does in its media-item transition, all of it before any
+   * network work: announce the new track, publish its now-playing metadata,
+   * cut the outgoing one, and report `loading`.
+   *
+   * Android's `onMediaItemTransition` fires at `prepare()` and does exactly
+   * this, with its LOADING following from `onEvents`; resolution happens later
+   * still, inside `TransformingDataSource.open()`. Doing it here rather than
+   * after the URL resolves is what gives the resolution window a state, and
+   * keeps `activeTrack` ahead of `loading` — the order a consumer that reads
+   * `getActiveTrack()` on the loading edge depends on.
+   */
+  private transitionTo(track: Track): void {
+    const element = this.requireElement()
     const lastTrack = this.current
     const lastPosition = element.currentTime
     const lastIndex = this.queue.lastIndex
     const currentIndex = this.queue.currentIndex
 
-    // Set loading flag early so seekTo() calls during async URL resolution
-    // are captured as pending seeks rather than silently dropped
-    this._loadInProgress = true
-    this._pendingSeek = undefined
-
-    // Resolve the media URL before loading (async but we don't await)
-    const loadId = ++this.currentLoadId
-    const doLoad = async () => {
-      const resolvedTrack: Track = track.src
-        ? { ...track, src: await this.resolveMediaUrl(track.src) }
-        : track
-
-      // A newer load() was called while resolving — discard this stale result
-      if (loadId !== this.currentLoadId) {
-        return
-      }
-
-      super.load(resolvedTrack, (loadedTrack) => {
+    // A re-prepare of the item already current is not a transition, and must
+    // not be announced as one: ExoPlayer's `prepare()` does not re-fire
+    // `onMediaItemTransition` for an unchanged media item, so a consumer that
+    // resets on a track change would have its UI wiped by every retry. The
+    // `lastTrack === track` payload was the tell.
+    const isTransition = this.current !== track
+
+    // `current` first, so `getActiveTrack()` already reads the new track inside
+    // a handler and so `getNowPlaying()` publishes the new track's metadata. It
+    // also stops `getActiveTrackIndex()` — which moved with the queue already,
+    // synchronously — from disagreeing with it for the length of the
+    // resolution.
+    this.current = track
+
+    // Separately guarded: a throwing consumer handler must not skip the
+    // publish, and neither may fail the load.
+    if (isTransition) {
+      try {
         this.onPlaybackActiveTrackChanged({
           lastTrack,
           lastPosition,
@@ -682,24 +726,113 @@ export class NativeAudioBrowser
           index: currentIndex,
           track
         })
+      } catch (error) {
+        console.error('Failed to announce the active track change:', error)
+      }
 
-        // Update now playing metadata
+      try {
+        // Once, here: duration reaches the media session through
+        // `updateProgress()` on each tick, so only metadata needs publishing.
+        // Android publishes from the same transition handler that announces.
         const nowPlaying = this.getNowPlaying()
         if (nowPlaying) {
           this.publishNowPlaying(nowPlaying)
         }
+      } catch (error) {
+        console.error('Failed to publish now-playing metadata:', error)
+      }
+    }
 
-        // Call the provided callback if any
-        if (callback) {
-          callback(loadedTrack)
-        }
-      })
+    // Stop the outgoing track now rather than when Shaka eventually gets a URL.
+    // Announcing the new track while the old one is still audible is worse than
+    // the silence, and native has no such window — prepare() cuts the old item
+    // at the moment it announces. This adds no teardown: `player.load()`
+    // already unloads first (shaka player.js:1757-1762). It only moves when.
+    // Verified in a real browser to emit no `pause`, so no state comes of it.
+    this.requirePlayer()
+      .unload()
+      .catch((error: unknown) =>
+        console.error('Failed to unload the previous track:', error)
+      )
+
+    // Loading covers the resolution too. Shaka dispatches its own `loading`
+    // once `player.load()` is called — after resolution — and the state setter
+    // drops that as a no-op. The `buffering` that follows is Shaka's to report.
+    this.dispatch({ type: 'trackLoading' })
+  }
+
+  load(track: Track, callback?: (track: Track) => void): void {
+    // Before the queue is touched, so a load before `setupPlayer()` throws
+    // rather than half-applying.
+    this.requireElement()
+
+    // Clear now playing override when track changes (matches Android's PlayerListener.onMediaItemTransition)
+    this.nowPlayingManager.clearNowPlayingOverride()
+
+    this.syncQueueTo(track)
+
+    // Begun here, at the call, so a newer load supersedes this one immediately
+    // rather than once its own URL has resolved. Both continuations below carry
+    // it, as does `super.load()`.
+    const attempt = this.beginLoadAttempt()
+
+    // Loading ends being stopped. `dispatch()` drops every event while
+    // `_isStopped`, to keep Shaka's teardown noise off the stopped state, so
+    // the `trackLoading` in `transitionTo` would be swallowed on the stop → play
+    // path and the resolution window would report nothing. `super.load()` clears
+    // this too, but only after the URL resolves.
+    this._isStopped = false
+
+    // Set loading flag early so seekTo() calls during async URL resolution
+    // are captured as pending seeks rather than silently dropped
+    this._loadInProgress = true
+    this._pendingSeek = undefined
+
+    this.transitionTo(track)
+
+    // Resolve the media URL before loading (async but we don't await)
+    const doLoad = async () => {
+      const resolvedRequest = track.src
+        ? await this.resolveMediaRequest(track.src, track)
+        : undefined
+      // Web-only, and forced: a progressive file plays via `mediaElement.src`,
+      // which cannot carry headers. Native sends them with the media request
+      // and follows the redirect inline, so it needs none of this.
+      const resolvedMedia = resolvedRequest
+        ? await followMediaRedirect(
+            resolvedRequest.path ?? track.src!,
+            resolvedRequest.headers,
+            { mediaLayerHeaders: resolvedRequest.mediaLayerHeaders }
+          )
+        : undefined
+
+      // Something took over while the URL was resolving — discard this result
+      if (!attempt.isCurrent) return
+
+      super.load(
+        track,
+        (loadedTrack) => {
+          // Call the provided callback if any
+          if (callback) {
+            callback(loadedTrack)
+          }
+        },
+        { headers: resolvedMedia?.headers, src: resolvedMedia?.src, attempt }
+      )
     }
 
     // Execute async load without blocking, with error handling
     doLoad().catch((error: unknown) => {
-      // Only the active load may surface a resolution failure.
-      if (loadId !== this.currentLoadId) return
+      // A backstop with no reachable trigger today, kept because an unhandled
+      // rejection would be worse than a dead branch. Every await inside
+      // `doLoad` catches internally; `shaka.Player.load` is `async`, so it
+      // rejects rather than throwing and its rejection is handled against the
+      // attempt inside `Player.load`; and `this.player` is only ever assigned,
+      // so `requirePlayer()` cannot start succeeding and then fail mid-load.
+      //
+      // No attempt check either, for the same reason it would be dead: nothing
+      // awaits between the guard above and `super.load()`, so the attempt
+      // cannot have changed. Add an await there and this needs the check back.
       this._loadInProgress = false
       this._pendingSeek = undefined
       console.error('Error loading track:', error)
@@ -879,10 +1012,8 @@ export class NativeAudioBrowser
   }
 
   override stop(): void {
-    // Invalidate any in-flight load: its post-await continuation would call
-    // super.load(), whose first line re-arms the player (_isStopped = false)
-    // and revives the state out of Stopped.
-    this.currentLoadId++
+    // `Player.stop()` cancels the load attempt, so an in-flight load's
+    // continuation cannot re-arm the player and revive it out of Stopped.
     super.stop()
     this.clearSleepTimerIfFading()
   }
@@ -903,18 +1034,20 @@ export class NativeAudioBrowser
   /**
    * Override to check for sleep timer when track ends
    */
-  protected onTrackEnded(): void {
+  protected onTrackEnded(): boolean {
     // Check if sleep timer is set to end on track completion
     if (this.sleepTimer.sleepWhenPlayedToEnd) {
       console.log('Sleep timer triggered on track end, pausing playback')
       this.sleepTimer.clear()
       this.pause()
       this.onSleepTimerChanged(null)
-      return
+      // Nothing is loading, so the caller must still report the end — the
+      // element has stopped and its own `pause` is swallowed as end-of-track.
+      return false
     }
 
     // Otherwise proceed with normal track end behavior
-    super.onTrackEnded()
+    return super.onTrackEnded()
   }
 
   // MARK: Queue management

package/src/web/TrackPlayer/LoadAttempt.ts

@@ -0,0 +1,29 @@
+/**
+ * One attempt at loading a track, from the call that asked for it through to
+ * the continuations that finish it.
+ *
+ * A load on web spans two async boundaries — resolving the URL, then Shaka's
+ * own `load()` — and each has a continuation that must do nothing if something
+ * else has taken over in the meantime. Handing every continuation the same
+ * token turns that into one question, asked the same way in each place.
+ *
+ * Supersession is registered where it happens: {@link Player.beginLoadAttempt}
+ * cancels the previous attempt the moment a new one starts, and `stop()`
+ * cancels without starting one. Two integer generations used to stand in for
+ * this, incremented at different depths — the outer one at the call, the inner
+ * one only once the URL had resolved — so a load superseded during that gap
+ * still ran its own success path.
+ */
+export class LoadAttempt {
+  private cancelled = false
+
+  /** Abandons this attempt; every continuation holding it will bail. */
+  cancel(): void {
+    this.cancelled = true
+  }
+
+  /** Whether this attempt still owns the player. */
+  get isCurrent(): boolean {
+    return !this.cancelled
+  }
+}

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

@@ -47,17 +47,49 @@ describe('nextPlaybackState', () => {
     })
   })
 
-  describe('loadSeekCompleted — only transitions from loading', () => {
+  describe('loadSeekCompleted — the settle after a load', () => {
     it('from loading → ready', () => {
-      expect(nextPlaybackState('loading', { type: 'loadSeekCompleted' })).toBe(
-        'ready'
-      )
+      expect(
+        nextPlaybackState('loading', {
+          type: 'loadSeekCompleted',
+          playWhenReady: false
+        })
+      ).toBe('ready')
+    })
+
+    it('from buffering → ready', () => {
+      // every load now passes through buffering, so that is where the settle
+      // usually arrives
+      expect(
+        nextPlaybackState('buffering', {
+          type: 'loadSeekCompleted',
+          playWhenReady: false
+        })
+      ).toBe('ready')
     })
 
     it('from any other state → suppressed', () => {
-      for (const state of ALL_STATES.filter((s) => s !== 'loading')) {
+      for (const state of ALL_STATES.filter(
+        (s) => s !== 'loading' && s !== 'buffering'
+      )) {
         expect(
-          nextPlaybackState(state, { type: 'loadSeekCompleted' })
+          nextPlaybackState(state, {
+            type: 'loadSeekCompleted',
+            playWhenReady: false
+          })
+        ).toBeNull()
+      }
+    })
+
+    it('suppressed while playWhenReady — ready is a transient before playing', () => {
+      // Android suppresses STATE_READY the same way; emitting it flashes a
+      // settled, non-loading state mid-startup
+      for (const state of ['loading', 'buffering'] as const) {
+        expect(
+          nextPlaybackState(state, {
+            type: 'loadSeekCompleted',
+            playWhenReady: true
+          })
         ).toBeNull()
       }
     })
@@ -103,7 +135,10 @@ describe('nextPlaybackState', () => {
 
     it('from playing → suppressed', () => {
       expect(
-        nextPlaybackState('playing', { type: 'bufferingSufficient' })
+        nextPlaybackState('playing', {
+          type: 'bufferingSufficient',
+          playWhenReady: false
+        })
       ).toBeNull()
     })
 
@@ -112,27 +147,39 @@ describe('nextPlaybackState', () => {
     // the UI is rendering with nothing recovered. Same guard as iOS/Android.
     it('from error → suppressed (preserves the error)', () => {
       expect(
-        nextPlaybackState('error', { type: 'bufferingSufficient' })
+        nextPlaybackState('error', {
+          type: 'bufferingSufficient',
+          playWhenReady: false
+        })
       ).toBeNull()
     })
 
     it('from ended → suppressed', () => {
       expect(
-        nextPlaybackState('ended', { type: 'bufferingSufficient' })
+        nextPlaybackState('ended', {
+          type: 'bufferingSufficient',
+          playWhenReady: false
+        })
       ).toBeNull()
     })
 
     it('from stopped → suppressed', () => {
       expect(
-        nextPlaybackState('stopped', { type: 'bufferingSufficient' })
+        nextPlaybackState('stopped', {
+          type: 'bufferingSufficient',
+          playWhenReady: false
+        })
       ).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'
-        )
+        expect(
+          nextPlaybackState(state, {
+            type: 'bufferingSufficient',
+            playWhenReady: false
+          })
+        ).toBe('ready')
       }
     })
   })

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')
   })