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

package/src/web/NativeAudioBrowser.ts

@@ -42,21 +42,32 @@ 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'
 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'
 import { QueuePlayer, SleepTimerManager, VolumeFader } from './TrackPlayer'
 import { PlaybackTimer } from './TrackPlayer/PlaybackTimer'
 import { derivePlayingState } from './TrackPlayer/PlayingStateFactory'
+import { BrowserPathHelper } from './util/BrowserPathHelper'
 
 /**
  * Web implementation of AudioBrowser (unified browser + player)
@@ -94,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 =
@@ -304,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 })
     }
   }
 
@@ -414,11 +429,13 @@ export class NativeAudioBrowser
    * Attempts to skip to a track already in the current queue.
    * Used as an optimization to avoid re-expanding the queue.
    *
-   * @param trackId The track's src identifier
+   * @param track The tapped track (its contextual path pins the exact copy)
+   * @param trackId The track's identity (id, falling back to src)
    * @param parentPath The parent path to check against queueSourcePath
    * @returns true if successfully skipped to existing track, false otherwise
    */
   private async trySkipToExistingQueueTrack(
+    track: Track,
     trackId: string,
     parentPath: string
   ): Promise<boolean> {
@@ -426,8 +443,21 @@ export class NativeAudioBrowser
       return false
     }
 
+    // Exact-surface match first: a contextual path carries the tapped page
+    // position (__index), so path equality pins the exact copy when the page
+    // holds the same identity more than once. The identity match remains for
+    // index-less paths (e.g. pre-stamp persisted state); an index-stamped path
+    // with no exact match falls through to expansion, which re-scopes the
+    // queue to the tapped section.
     const queue = this.getQueue()
-    const index = queue.findIndex((t) => t.src === trackId)
+    let index = queue.findIndex((t) => t.path != null && t.path === track.path)
+    if (
+      index < 0 &&
+      track.path != null &&
+      BrowserPathHelper.extractIndex(track.path) === undefined
+    ) {
+      index = queue.findIndex((t) => getTrackIdentity(t) === trackId)
+    }
 
     if (index < 0) {
       return false
@@ -474,6 +504,11 @@ export class NativeAudioBrowser
    */
   private async navigateTrackAsync(track: Track): Promise<void> {
     try {
+      // A disabled track is unavailable — it never plays, whichever surface
+      // or stale resume path delivered the selection (Track.disabled; mirrors
+      // iOS TrackSelector.select and Android navigateTrack).
+      if (track.disabled === true) return
+
       const nav = classifyTrackNavigation(track)
       switch (nav.kind) {
         case 'contextual':
@@ -481,6 +516,7 @@ export class NativeAudioBrowser
           if (
             nav.trackId &&
             (await this.trySkipToExistingQueueTrack(
+              track,
               nav.trackId,
               nav.parentPath
             ))
@@ -504,7 +540,7 @@ export class NativeAudioBrowser
           return
 
         case 'invalid':
-          throw new Error("Track must have either 'url' or 'src' property")
+          throw new Error("Track must have either 'path' or 'src' property")
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Unknown error'
@@ -520,7 +556,7 @@ export class NativeAudioBrowser
     })
   }
 
-  async onSearch(query: string): Promise<Track[]> {
+  async search(query: string): Promise<Track[]> {
     // Wrap query string in SearchParams (matches Android's search(query: String) overload)
     return this.searchManager.search({ query, reference: 'unknown' })
   }
@@ -587,71 +623,106 @@ 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) {
+      // As Android's onMediaItemTransition does: a new item is a clean slate,
+      // a retry of the same one keeps what the consumer set.
+      this.nowPlayingManager.clearNowPlayingOverride()
+
+      try {
         this.onPlaybackActiveTrackChanged({
           lastTrack,
           lastPosition,
@@ -659,24 +730,118 @@ 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)
+      }
+    }
+
+    // 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()
+
+    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()
+    // Read now: `reloadCurrent` holds the flag only for this synchronous call,
+    // and `super.load()` runs after the URL has resolved.
+    const reprepare = this._repreparing
+
+    // 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
 
-        // Call the provided callback if any
-        if (callback) {
-          callback(loadedTrack)
+    // 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,
+          reprepare
         }
-      })
+      )
     }
 
     // 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)
@@ -856,10 +1021,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()
   }
@@ -880,18 +1043,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
@@ -941,13 +1106,14 @@ export class NativeAudioBrowser
   setActiveTrackFavorited(favorited: boolean): void {
     const track = this.getActiveTrack()
     const index = this.getActiveTrackIndex()
-    if (!track || !track.src || index === undefined) return
+    if (!track || getTrackIdentity(track) === undefined || index === undefined)
+      return
 
-    // Update favorites set via manager
+    // Update favorites set via manager (keyed by track identity)
     if (favorited) {
-      this.favoriteManager.addFavorite(track.src)
+      this.favoriteManager.addFavorite(track)
     } else {
-      this.favoriteManager.removeFavorite(track.src)
+      this.favoriteManager.removeFavorite(track)
     }
 
     // Create updated track with new favorited state
@@ -959,27 +1125,18 @@ export class NativeAudioBrowser
     // Replace the track in the queue
     this.queue.replaceTrack(index, updatedTrack)
 
-    // Emit favorite changed event
+    // Emit favorite changed only. A favorite toggle is an in-place mutation of
+    // the active track, not a transition — onPlaybackActiveTrackChanged and
+    // onPlaybackQueueChanged stay transition-only, and the useActiveTrack /
+    // useQueue hooks subscribe to onFavoriteChanged themselves.
     this.onFavoriteChanged({ track: updatedTrack, favorited })
-
-    // Emit active track changed so useActiveTrack() hook updates
-    this.onPlaybackActiveTrackChanged({
-      lastIndex: index,
-      lastTrack: track,
-      lastPosition: this.element?.currentTime ?? 0,
-      index,
-      track: updatedTrack
-    })
-
-    // Emit queue changed so useQueue() hook updates
-    this.emitQueueChanged()
   }
 
   toggleActiveTrackFavorited(): void {
     const track = this.getActiveTrack()
-    if (!track || !track.src) return
+    if (!track || getTrackIdentity(track) === undefined) return
 
-    const isFavorited = this.favoriteManager.isFavorited(track.src)
+    const isFavorited = this.favoriteManager.isFavorited(track)
     this.setActiveTrackFavorited(!isFavorited)
   }
 

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