react-native-queue-player 1.2.0 → 2.0.1

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerEventsTest.kt

@@ -41,7 +41,9 @@ class TrackPlayerEventsTest {
   private fun track(id: String) = TrackItem(
     id = id, url = "https://example.com/$id.m4a",
     title = null, artist = null, album = null,
-    duration = null, artworkUrl = null, extras = null
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null
   )
 
   private lateinit var serviceHandle: PlaybackServiceTestHandle
@@ -51,7 +53,7 @@ class TrackPlayerEventsTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 
@@ -100,44 +102,118 @@ class TrackPlayerEventsTest {
     assertEquals(0.0, snap.buffered, 0.001)
   }
 
+  // --- onStateChange / onError / onQueueEnd registration
+
   @Test
-  fun `emitProgressTick is a no-op when no subscriber exists`() {
-    // Just verify it does not throw.
-    player.emitProgressTick()
-  }
+  fun `onStateChange delivers to a subscriber and stops after unsubscribe`() {
+    var fired = 0
+    val unsubscribe = player.onStateChange { _, _ -> fired += 1 }
 
-  // --- onStateChange / onError / onQueueEnd registration
+    player.emitRemoteState(PlayerState.PAUSED, StateChangeReason.SYSTEM)
+    assertEquals(1, fired)
+
+    unsubscribe()
+    // A different state, so the only thing between it and the listener is
+    // the unsubscribe — a repeat of the same one would be deduped.
+    player.emitRemoteState(PlayerState.PLAYING, StateChangeReason.SYSTEM)
+    assertEquals("nothing reaches a removed subscriber", 1, fired)
+  }
 
   @Test
-  fun `onStateChange registration stores and unsubscribe clears the callback`() {
-    var fireCount = 0
-    val unsubscribe = player.onStateChange { _, _ -> fireCount += 1 }
+  fun `onError delivers to a subscriber and stops after unsubscribe`() {
+    player.setQueueInternal((1..2).map { track("t$it") })
+    player.currentTrackIndex = 1
+    var fired = 0
+    val unsubscribe = player.onError { fired += 1 }
+
+    // A failure on a track that is not playing is reported straight away.
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    assertEquals(1, fired)
 
-    // No way to force the Player.Listener onto READY without a
-    // real media pipeline, but we can unregister + verify no
-    // leftover reference causes a crash when destroyInternal runs.
     unsubscribe()
-    assertEquals(0, fireCount)
+    // A different failure, so the only thing between it and the listener
+    // is the unsubscribe — a repeat of the same one would be deduped.
+    player.onError(serviceHandle.engine, decodingFailure(), 0)
+    assertEquals("nothing reaches a removed subscriber", 1, fired)
   }
 
   @Test
-  fun `onError registration stores and unsubscribe clears the callback`() {
-    val unsubscribe = player.onError { }
+  fun `onQueueEnd delivers to a subscriber and stops after unsubscribe`() {
+    player.setQueueInternal((1..2).map { track("t$it") })
+    var fired = 0
+    val unsubscribe = player.onQueueEnd { fired += 1 }
+
+    player.maybeEmitQueueEnd(androidx.media3.common.Player.STATE_ENDED)
+    assertEquals(1, fired)
+
     unsubscribe()
-    // No-op sanity — callback slot is cleared; destroy must not
-    // fire a spurious error call.
+    player.maybeEmitQueueEnd(androidx.media3.common.Player.STATE_ENDED)
+    assertEquals("nothing reaches a removed subscriber", 1, fired)
   }
 
+  /** Queue end is announced as ENDED / QUEUE_END, and the pause that parks the
+   *  engine afterwards leaves no reason behind for the next emit. */
   @Test
-  fun `onQueueEnd registration stores and unsubscribe clears the callback`() {
-    val unsubscribe = player.onQueueEnd { }
+  fun `queue end announces ENDED with the queue-end reason and stamps nothing after`() {
+    player.setQueueInternal((1..2).map { track("t$it") })
+    val emits = mutableListOf<Pair<PlayerState, StateChangeReason>>()
+    val unsubscribe = player.onStateChange { state, reason -> emits.add(state to reason) }
+
+    player.maybeEmitQueueEnd(androidx.media3.common.Player.STATE_ENDED)
     unsubscribe()
+
+    assertEquals(PlayerState.ENDED to StateChangeReason.QUEUE_END, emits.last())
+    assertEquals("the parking pause's USER stamp must not survive", null, player.pendingStateChangeReason)
   }
 
   @Test
-  fun `onTrackChange registration stores and unsubscribe clears the callback`() {
-    val unsubscribe = player.onTrackChange { _, _, _, _ -> }
+  fun `onTrackChange delivers to a subscriber and stops after unsubscribe`() {
+    player.setQueueInternal((1..3).map { track("t$it") })
+    var fired = 0
+    val unsubscribe = player.onTrackChange { _, _, _, _ -> fired += 1 }
+
+    player.emitRemoteTrackChange(1)
+    assertEquals(1, fired)
+
     unsubscribe()
+    // A different index, so the only thing between it and the listener is
+    // the unsubscribe — a repeat of the current index returns early.
+    player.emitRemoteTrackChange(2)
+    assertEquals("nothing reaches a removed subscriber", 1, fired)
+  }
+
+  /**
+   * A source that answered with something that is not media is a format
+   * problem, not a reachability one: it was reached, and a retry cannot change
+   * what it sends. Classing it transient would spend an automatic attempt on a
+   * body that can never become audio.
+   */
+  @Test
+  fun aNonMediaResponseClassifiesAsAFormatFailureAndIsFatal() {
+    val invalidContentType = PlaybackException(
+      "msg", null,
+      PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE
+    )
+    assertEquals(
+      PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED,
+      PlaybackErrorMapping.classify(invalidContentType)
+    )
+    assertFalse(
+      PlaybackErrorMapping.isTransient(PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED)
+    )
+  }
+
+  /** A source that is genuinely missing stays a reachability failure. */
+  @Test
+  fun aMissingFileStillClassifiesAsUnreachable() {
+    val notFound = PlaybackException(
+      "msg", null,
+      PlaybackException.ERROR_CODE_IO_FILE_NOT_FOUND
+    )
+    assertEquals(
+      PlaybackErrorCode.SOURCE_UNREACHABLE,
+      PlaybackErrorMapping.classify(notFound)
+    )
   }
 
   // --- PlaybackErrorMapping.isTransient classification
@@ -230,7 +306,7 @@ class TrackPlayerEventsTest {
     // the public effects — a new configure + getStateInternal
     // should return NONE.
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     assertEquals(PlayerState.NONE, player.getStateInternal())
   }
@@ -246,8 +322,8 @@ class TrackPlayerEventsTest {
     //   - listener must NOT clobber the logical -1 from the Kotlin
     //     side with the ExoPlayer-derived 0
     player.tracks = listOf(
-      TrackItem("a", "https://example.com/a.m4a", null, null, null, null, null, null),
-      TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null)
+      TrackItem("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+      TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null)
     )
     player.currentTrackIndex = -1
 
@@ -267,7 +343,7 @@ class TrackPlayerEventsTest {
     // before issuing player.seekTo — the subsequent REASON_SEEK
     // listener fire must not reset it from the player.
     player.tracks = (1..5).map {
-      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null)
+      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null, null, null, null, null)
     }
     player.currentTrackIndex = 3
 
@@ -281,7 +357,7 @@ class TrackPlayerEventsTest {
   @Test
   fun `handleMediaItemTransition REASON_SEEK consumes the pending track change reason`() {
     player.tracks = (1..5).map {
-      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null)
+      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null, null, null, null, null)
     }
     player.currentTrackIndex = 2
 
@@ -305,7 +381,7 @@ class TrackPlayerEventsTest {
   @Test
   fun `handleMediaItemTransition REASON_SEEK without stashed reason falls back to SEEK`() {
     player.tracks = (1..5).map {
-      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null)
+      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null, null, null, null, null)
     }
     player.currentTrackIndex = 2
 
@@ -321,11 +397,11 @@ class TrackPlayerEventsTest {
 
   @Test
   fun `handleMediaItemTransition fires callback with current track snapshot`() {
-    val t2 = TrackItem("t2", "https://example.com/t2.m4a", null, null, null, null, null, null)
+    val t2 = TrackItem("t2", "https://example.com/t2.m4a", null, null, null, null, null, null, null, null, null, null)
     player.tracks = listOf(
-      TrackItem("t1", "https://example.com/t1.m4a", null, null, null, null, null, null),
+      TrackItem("t1", "https://example.com/t1.m4a", null, null, null, null, null, null, null, null, null, null),
       t2,
-      TrackItem("t3", "https://example.com/t3.m4a", null, null, null, null, null, null)
+      TrackItem("t3", "https://example.com/t3.m4a", null, null, null, null, null, null, null, null, null, null)
     )
     player.currentTrackIndex = 1
 
@@ -353,8 +429,8 @@ class TrackPlayerEventsTest {
   @Test
   fun `handleMediaItemTransition PLAYLIST_CHANGED reports null transitionGapMs`() {
     player.tracks = listOf(
-      TrackItem("t1", "https://example.com/t1.m4a", null, null, null, null, null, null),
-      TrackItem("t2", "https://example.com/t2.m4a", null, null, null, null, null, null)
+      TrackItem("t1", "https://example.com/t1.m4a", null, null, null, null, null, null, null, null, null, null),
+      TrackItem("t2", "https://example.com/t2.m4a", null, null, null, null, null, null, null, null, null, null)
     )
     player.currentTrackIndex = 0
 
@@ -376,7 +452,7 @@ class TrackPlayerEventsTest {
   @Test
   fun `handleMediaItemTransition SEEK reports null transitionGapMs`() {
     player.tracks = (1..3).map {
-      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null)
+      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null, null, null, null, null)
     }
     player.currentTrackIndex = 1
 
@@ -395,7 +471,7 @@ class TrackPlayerEventsTest {
   @Test
   fun `maybeEmitQueueEnd does nothing on non-ENDED states`() {
     player.tracks = listOf(
-      TrackItem("t1", "https://example.com/t1.m4a", null, null, null, null, null, null)
+      TrackItem("t1", "https://example.com/t1.m4a", null, null, null, null, null, null, null, null, null, null)
     )
     var queueEndFires = 0
     player.onQueueEnd { queueEndFires += 1 }
@@ -425,7 +501,7 @@ class TrackPlayerEventsTest {
   @Test
   fun `maybeEmitQueueEnd fires queueEnd and ENDED state on STATE_ENDED with tracks`() {
     player.tracks = (1..3).map {
-      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null)
+      TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null, null, null, null, null)
     }
 
     var queueEndFires = 0
@@ -450,7 +526,7 @@ class TrackPlayerEventsTest {
   fun `emitStateIfChanged defaults pending reason to SYSTEM on terminal state`() {
     player.setQueueInternal(
       (1..1).map {
-        TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null)
+        TrackItem("t$it", "https://example.com/t$it.m4a", null, null, null, null, null, null, null, null, null, null)
       }
     )
     // Manually reset dedup so the next call emits
@@ -479,7 +555,7 @@ class TrackPlayerEventsTest {
     serviceHandle.destroy()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     // No listener is bound to the new ExoPlayer's actual STATE_ENDED
     // path in a Robolectric test, but the callback slot itself is
@@ -493,4 +569,12 @@ class TrackPlayerEventsTest {
     unsubscribe()
     assertFalse(fired)
   }
+
+  private fun networkFailure() = androidx.media3.common.PlaybackException(
+    "boom", null,
+    androidx.media3.common.PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED)
+
+  private fun decodingFailure() = androidx.media3.common.PlaybackException(
+    "bad frame", null,
+    androidx.media3.common.PlaybackException.ERROR_CODE_DECODING_FAILED)
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerLifecycleTest.kt

@@ -4,6 +4,7 @@ import androidx.media3.common.util.UnstableApi
 import androidx.test.core.app.ApplicationProvider
 import org.junit.After
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNotEquals
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertNull
@@ -58,18 +59,293 @@ class TrackPlayerLifecycleTest {
     serviceHandle.destroy()
   }
 
+  @Test
+  fun `a failure on a track that is not playing is reported, not swallowed`() {
+    seedThreeTrackQueue()
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    val states = mutableListOf<PlayerState>()
+    val disposeState = player.onStateChange { state, _ -> states.add(state) }
+    // Index 2 is not the current track — the shape a standby preroll failure
+    // arrives in. The engine argument is not read by the handler.
+    player.onError(
+      serviceHandle.engine,
+      androidx.media3.common.PlaybackException(
+        "boom", null,
+        androidx.media3.common.PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED),
+      2)
+    dispose()
+    disposeState()
+
+    assertEquals("the failure is surfaced rather than swallowed", 1, reported)
+    assertFalse(
+      "the state is the current track's, which is still playing",
+      states.contains(PlayerState.ERROR))
+  }
+
+  /**
+   * A repeat of the same failure while the attempt is pending stays inside the
+   * library.
+   */
+  @Test
+  fun `an echo of the pending failure is not reported`() {
+    seedThreeTrackQueue()
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    dispose()
+
+    assertEquals("the pending attempt owns both fires", 0, reported)
+  }
+
+  /** A failure after the attempt has run is the consumer's to see. */
+  @Test
+  fun `a failure after the attempt is reported`() {
+    seedThreeTrackQueue()
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    player.retryFailedItem(0)
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    dispose()
+
+    assertEquals("the attempt was spent and the track is still broken", 1, reported)
+  }
+
+  /**
+   * Inserting ahead of a track moves it, and its retry budget moves with it.
+   * A budget of two with one attempt spent is the one value that tells the
+   * moved track apart from both a fresh entry (two left) and a dropped one
+   * (none left) at its new index.
+   */
+  @Test
+  fun `a track keeps its retry budget when a track is inserted before it`() {
+    seedThreeTrackQueue(autoRetries = 2.0)
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    player.retryFailedItem(0)
+
+    player.addToQueueInternal(listOf(track("https://example.com/new.mp3")), insertBefore = 0)
+    assertEquals("the playing track moved to index 1", 1, player.currentTrackIndex)
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, networkFailure(), 1)
+    assertEquals(
+      "one attempt is left at the new index, so the failure is retried silently; "
+        + "a dropped budget would have reported it",
+      0, reported)
+    player.retryFailedItem(1)
+    player.onError(serviceHandle.engine, networkFailure(), 1)
+    dispose()
+
+    assertEquals(
+      "the second attempt was spent, so this failure is reported; "
+        + "a fresh budget of two would still be silent",
+      1, reported)
+  }
+
+  /**
+   * A user's retry withdraws the automatic attempt scheduled for the same
+   * track: left posted, it would fire after the backoff and rebuild the track
+   * a second time.
+   */
+  @Test
+  fun `a retry withdraws the scheduled automatic attempt`() {
+    player.configureInternal(config(retryBackoffMs = 500.0), context())
+    player.setQueueInternal((0 until 3).map { track("https://example.com/$it.mp3") })
+    player.currentTrackIndex = 0
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+
+    player.retryFailedItem(0)
+    val looper = org.robolectric.Shadows.shadowOf(android.os.Looper.getMainLooper())
+    looper.idle()
+    // The retry rebuilt the item once (a remove and an add on the playlist);
+    // whatever the looper still holds for the backoff must not rebuild again.
+    // Only playlist changes count: the playback thread reports its own
+    // source refresh after the prepare, on its own schedule.
+    var timelineChanges = 0
+    val listener = object : androidx.media3.common.Player.Listener {
+      override fun onTimelineChanged(timeline: androidx.media3.common.Timeline, reason: Int) {
+        if (reason == androidx.media3.common.Player.TIMELINE_CHANGE_REASON_PLAYLIST_CHANGED) {
+          timelineChanges += 1
+        }
+      }
+    }
+    player.player!!.addListener(listener)
+    looper.idleFor(java.time.Duration.ofMillis(1_000))
+    player.player!!.removeListener(listener)
+
+    assertEquals(
+      "the automatic attempt fired after the user's retry and rebuilt the track again",
+      0, timelineChanges)
+  }
+
+  /**
+   * The track that ends up at a position after a queue change reports its own
+   * failure instead of being taken for an echo of the old queue's attempt.
+   */
+  @Test
+  fun `a failure on the replacement queue is not taken for an echo of the old one`() {
+    seedThreeTrackQueue()
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+
+    // The replacement queue gets no automatic attempt, so a failure on it can
+    // only be suppressed by a marker left over from the queue before it.
+    player.config = config(autoRetries = 0.0)
+    player.setQueueInternal((0 until 2).map {
+      track("https://example.com/next-$it.mp3")
+    })
+    player.currentTrackIndex = 0
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, networkFailure(), 0)
+    dispose()
+
+    assertEquals("the attempt belonged to a queue that is gone", 1, reported)
+  }
+
+  private fun config(
+    httpHeaders: Map<String, String>? = null,
+    userAgent: String? = null,
+    autoRetries: Double? = null,
+    retryBackoffMs: Double? = null,
+  ) = PlayerConfig(
+    httpHeaders = httpHeaders, userAgent = userAgent, autoRetries = autoRetries,
+    retryBackoffMs = retryBackoffMs, networkTimeoutMs = null, audioContentType = null,
+    audioCategoryOptions = null, voiceVocabularyDonationEnabled = null,
+    visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null,
+    lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null,
+    backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null,
+    skipToPreviousBehavior = null)
+
+  private fun track(url: String) = TrackItem(
+    id = null, url = url, title = null, artist = null, album = null, duration = null,
+    artworkUrl = null, extras = null, replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null)
+
+  private fun networkFailure() = androidx.media3.common.PlaybackException(
+    "boom", null,
+    androidx.media3.common.PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED)
+
+  /**
+   * Under crossfade the standby leg prerolls the next track, so a broken one
+   * fails while the leading track is still playing and is surfaced there. The
+   * engine then seats it and it fails again as the current track — the listener
+   * asked for one thing and must be told once.
+   */
+  @Test
+  fun `a track reported while it was prerolling does not report again when it is seated`() {
+    seedThreeTrackQueue(autoRetries = 0.0)
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+
+    // The standby leg prerolling track 1 fails while track 0 is playing.
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    assertEquals("the listener is told their next track is broken", 1, reported)
+
+    // The fade begins, so track 1 is the one being heard, and it fails again as
+    // the current track.
+    player.onCrossfadeBegin(serviceHandle.engine, 1)
+    assertEquals("the fade seats the track that was prerolling", 1, player.currentTrackIndex)
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    dispose()
+
+    assertEquals("and not told a second time about the same track", 1, reported)
+  }
+
+  /**
+   * A shuffle renumbers every position, so a record against the pre-shuffle
+   * current index names a different track afterwards. Nothing is carried.
+   */
+  @Test
+  fun `a shuffle leaves no track marked as stopped`() {
+    seedThreeTrackQueue(autoRetries = 0.0)
+    player.onError(serviceHandle.engine, fatalFailure(), 0)
+
+    player.shuffleQueueInternal()
+
+    assertEquals("a shuffle seats position 0", 0, player.currentTrackIndex)
+    // A stop standing against the current track silences every other track's
+    // failure, so a report for one of them is what shows the set is empty.
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    dispose()
+
+    assertEquals("no track is holding the queue after a shuffle", 1, reported)
+  }
+
+  /**
+   * `-1` means "no track", so a failure that carries no index — an engine that
+   * reports without one, or a queue that has been cleared — must not enter the
+   * set. A member equal to `currentTrackIndex` is what "stopped" means, and at
+   * `-1` that would read as stopped and silence every later failure.
+   */
+  @Test
+  fun `a failure with no track does not mark the queue as stopped`() {
+    player.configureInternal(config(autoRetries = 0.0), context())
+    player.setQueueInternal(emptyList())
+    assertEquals("an empty queue seats no track", -1, player.currentTrackIndex)
+
+    // An engine that reports without an index — AirPlay does — while the queue
+    // is empty. There is no position to record.
+    player.onError(serviceHandle.engine, fatalFailure())
+
+    // The add empties the set and restores the current track's entry, so with
+    // -1 a member that restore is what carries it forward. It leaves the index
+    // at -1 by design, which is what keeps it a member.
+    player.addToQueueInternal(
+      (0 until 2).map { track("https://example.com/$it.mp3") }, insertBefore = 0)
+    assertEquals("an add into an empty queue seats nothing", -1, player.currentTrackIndex)
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    dispose()
+
+    assertEquals(
+      "a track's failure still reaches the listener — nothing is holding the queue",
+      1, reported)
+  }
+
+  private fun fatalFailure() = androidx.media3.common.PlaybackException(
+    "boom", null,
+    androidx.media3.common.PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE)
+
+  private fun seedThreeTrackQueue(autoRetries: Double? = null) {
+    player.configureInternal(config(autoRetries = autoRetries), context())
+    player.setQueueInternal((0 until 3).map { track("https://example.com/$it.mp3") })
+    player.currentTrackIndex = 0
+  }
+
+  @Test
+  fun `the automatic retry budget is one attempt by default`() {
+    assertEquals(1, player.effectiveAutoRetries())
+  }
+
+  @Test
+  fun `the consumer can ask for none or more`() {
+    player.config = config(autoRetries = 0.0)
+    assertEquals(0, player.effectiveAutoRetries())
+    player.config = config(autoRetries = 4.0)
+    assertEquals(4, player.effectiveAutoRetries())
+    player.config = config(autoRetries = 99.0)
+    assertEquals(5, player.effectiveAutoRetries())
+    player.config = config()
+    assertEquals(1, player.effectiveAutoRetries())
+  }
+
   @Test
   fun `configureInternal builds an ExoPlayer and stores config`() {
     assertNull("player not yet built before configure", player.player)
 
-    val config = PlayerConfig(
-      httpHeaders = mapOf("X-Foo" to "bar"),
-      userAgent = "rnqp-test/0.0",
-      autoRetries = null,
-      retryBackoffMs = null,
-      networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
-    )
+    val config = config(httpHeaders = mapOf("X-Foo" to "bar"), userAgent = "rnqp-test/0.0")
     player.configureInternal(config, context())
 
     assertNotNull("configure must build ExoPlayer", player.player)
@@ -87,12 +363,12 @@ class TrackPlayerLifecycleTest {
   fun `configure destroys then rebuilds — second call yields a fresh ExoPlayer`() {
     // Universal `configure()` auto-destroy contract: every call to
     // the public configure tears down any prior state before
-    // reinitialising. The internal `configureInternal` seam is
+    // reinitialising. The internal `configureInternal` entry point is
     // purely constructive (assumes `player == null` on entry); the
     // public path owns the destroy step. This test drives the
     // destroy + reconstruct shape directly to mirror what
     // `configure()` does end-to-end.
-    val empty = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
+    val empty = config()
 
     player.configureInternal(empty, context())
     val firstInstance = player.player
@@ -122,16 +398,8 @@ class TrackPlayerLifecycleTest {
 
   @Test
   fun `configureInternal stores the latest config on repeat call`() {
-    val first = PlayerConfig(
-      httpHeaders = mapOf("A" to "1"), userAgent = "ua-1",
-      autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
-    )
-    val second = PlayerConfig(
-      httpHeaders = mapOf("B" to "2"), userAgent = "ua-2",
-      autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
-    )
+    val first = config(httpHeaders = mapOf("A" to "1"), userAgent = "ua-1")
+    val second = config(httpHeaders = mapOf("B" to "2"), userAgent = "ua-2")
 
     player.configureInternal(first, context())
     player.configureInternal(second, context())
@@ -141,11 +409,7 @@ class TrackPlayerLifecycleTest {
 
   @Test
   fun `destroyInternal releases ExoPlayer + cache, persists user config`() {
-    val configured = PlayerConfig(
-      httpHeaders = mapOf("h" to "v"), userAgent = "ua",
-      autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
-    )
+    val configured = config(httpHeaders = mapOf("h" to "v"), userAgent = "ua")
     player.configureInternal(configured, context())
     // Non-default playback state the consumer set post-configure.
     player.repeatModeState = RepeatMode.QUEUE
@@ -180,7 +444,7 @@ class TrackPlayerLifecycleTest {
   @Test
   fun `destroyInternal is safe to call twice`() {
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      config(), context()
     )
     player.destroyInternal()
     player.destroyInternal()
@@ -189,7 +453,7 @@ class TrackPlayerLifecycleTest {
 
   @Test
   fun `configureInternal after destroyInternal rebuilds the ExoPlayer`() {
-    val cfg = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
+    val cfg = config()
 
     player.configureInternal(cfg, context())
     val first = player.player