react-native-queue-player 2.0.0 → 2.0.1

package/ios/Tests/RetryRecoveryTests.swift

@@ -234,6 +234,121 @@ final class RetryRecoveryTests: XCTestCase {
     XCTAssertTrue(engine.seeks.isEmpty)
   }
 
+  // MARK: - The queue stops on a track whose failure was reported
+
+  /// A failure dispatched as its item is seated survives the first
+  /// announcement of that position, which happens in the same block.
+  func testAFailureAtSeatTimeStillHoldsTheQueueAfterTheTrackIsAnnounced() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    let item = AVPlayerItem(url: URL(string: "https://example.com/0.m4a")!)
+    item.queueItemId = qid
+
+    player.dispatchErrorOrRetry(
+      item: item,
+      underlying: NSError(domain: AVFoundationErrorDomain, code: -11828, userInfo: nil))
+    player.handleCurrentItemDidChange()
+
+    XCTAssertEqual(
+      player.reportedFailureOnCurrentTrack, qid,
+      "the track change announcing the failed track must not clear its report")
+  }
+
+  /// Announcing a different track clears a report the queue has moved past.
+  func testAnnouncingADifferentTrackClearsTheReport() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reportedFailureQueueItemIds = [player.queueItemIds[0]]
+    player.currentTrackIndex = 1
+
+    player.dispatchTrackChange(reason: .userSkipNext)
+
+    XCTAssertTrue(player.reportedFailureQueueItemIds.isEmpty)
+  }
+
+  /// A forced reinstall builds the current position from scratch, so what was
+  /// reported against it no longer describes what is installed.
+  func testAForcedReinstallClearsTheReport() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reportedFailureQueueItemIds = [player.queueItemIds[0]]
+
+    player.performingMutation { player.fullRebuildPlayerQueue(forcingReinstall: true) }
+
+    XCTAssertTrue(player.reportedFailureQueueItemIds.isEmpty)
+  }
+
+  /// A reconcile that is not rebuilding the position leaves the report alone —
+  /// the track it names is still the one that failed.
+  func testAPlainRebuildLeavesTheReportAlone() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    player.reportedFailureQueueItemIds = [qid]
+
+    player.performingMutation { player.fullRebuildPlayerQueue() }
+
+    XCTAssertEqual(player.reportedFailureQueueItemIds, [qid])
+  }
+
+  /// One `play()`, one error. Several tracks of an installed run fail at once —
+  /// a window of unplayable sources does exactly that — and only the track the
+  /// listener is on is theirs to act on; it reports once however many times it
+  /// or its neighbours fire. The record is a set so a repeat cannot be reopened
+  /// by a different track replacing it in a one-slot key.
+  func testOnlyTheCurrentTrackReportsAndOnlyOnce() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    var reported: [PlaybackError] = []
+    _ = player.errorListeners.add { reported.append($0) }
+    let fatal = NSError(domain: AVFoundationErrorDomain, code: -11828, userInfo: nil)
+    func item(at index: Int) -> AVPlayerItem {
+      let made = AVPlayerItem(url: URL(string: "https://example.com/\(index).m4a")!)
+      made.queueItemId = player.queueItemIds[index]
+      return made
+    }
+
+    // Two tracks failing, each reported twice, in the order that defeats a
+    // one-slot key: every fire names a different track than the one before it.
+    player.dispatchErrorOrRetry(item: item(at: 0), underlying: fatal)
+    player.dispatchErrorOrRetry(item: item(at: 1), underlying: fatal)
+    player.dispatchErrorOrRetry(item: item(at: 0), underlying: fatal)
+    player.dispatchErrorOrRetry(item: item(at: 1), underlying: fatal)
+
+    XCTAssertEqual(
+      reported.count, 1,
+      "one play(), one error: the track being played, once, whatever else fails")
+    XCTAssertEqual(
+      reported.first?.queueItemId, player.queueItemIds[0],
+      "the error names the track the listener is on")
+    XCTAssertEqual(
+      player.reportedFailureQueueItemIds, Set([player.queueItemIds[0]]),
+      "and only that track holds the queue")
+  }
+
+  /// Seating a position is an attempt at it, so a skip onto a track that
+  /// reported earlier clears its report. Without this the track is wedged:
+  /// it never reports again, its run is never extended, and it never reaches
+  /// an end verdict — silently, until play().
+  func testSkippingOntoAReportedTrackClearsItsReport() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reportedFailureQueueItemIds = [player.queueItemIds[1]]
+
+    player.applyNewCurrentIndex(newIndex: 1, reason: .userSkipToIndex)
+
+    XCTAssertTrue(
+      player.reportedFailureQueueItemIds.isEmpty,
+      "the track being skipped onto is being tried again")
+  }
+
   private func seed(_ player: TrackPlayer, engine: RetryEngineStub) {
     _ = player.queueState.replaceAll((0 ..< 2).map {
       TrackItem(

package/ios/Tests/TopUpWindowGateTests.swift

@@ -279,6 +279,53 @@ final class TopUpWindowGateTests: XCTestCase {
     XCTAssertEqual(engine.seatedAtPosition, 0)
   }
 
+  /// The same run, the same owed top-up: only the current track's reported
+  /// failure differs.
+  func testAReportedFailureOnTheCurrentTrackIsWhatHoldsTheTopUpBack() async throws {
+    let engine = WindowEngineStub(count: 3)
+    try await seed(engine: engine, trackCount: 20)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[$0.currentTrackIndex]] }
+
+    await onQueue { $0.topUpWindow() }
+    XCTAssertTrue(
+      engine.inserted.isEmpty,
+      "the track whose failure was reported is not installed again")
+
+    await onQueue { $0.reportedFailureQueueItemIds.removeAll() }
+    await onQueue { $0.topUpWindow() }
+    XCTAssertFalse(
+      engine.inserted.isEmpty,
+      "the same run extends once the track is no longer the reported failure")
+  }
+
+  /// The same run, the same owed top-up: only the scheduled attempt differs.
+  func testAScheduledAttemptForTheCurrentTrackAlsoHoldsTheTopUpBack() async throws {
+    let engine = WindowEngineStub(count: 3)
+    try await seed(engine: engine, trackCount: 20)
+    await onQueue { $0.pendingRetryQueueItemId = $0.queueItemIds[$0.currentTrackIndex] }
+
+    await onQueue { $0.topUpWindow() }
+    XCTAssertTrue(
+      engine.inserted.isEmpty,
+      "the attempt re-seats the track itself; rebuilding first fails it again")
+
+    await onQueue { $0.pendingRetryQueueItemId = nil }
+    await onQueue { $0.topUpWindow() }
+    XCTAssertFalse(engine.inserted.isEmpty)
+  }
+
+  /// A failure against a track the playhead has left does not stop the run
+  /// being extended.
+  func testATopUpRunsWhenTheReportedFailureIsADifferentTrack() async throws {
+    let engine = WindowEngineStub(count: 3)
+    try await seed(engine: engine, trackCount: 20)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[7]] }
+
+    await onQueue { $0.topUpWindow() }
+
+    XCTAssertFalse(engine.inserted.isEmpty)
+  }
+
   // MARK: - Helpers
 
   private func seed(engine: WindowEngineStub, trackCount: Int) async throws {

package/ios/Tests/TrackPlayerEndVerdictTests.swift

@@ -134,6 +134,47 @@ final class TrackPlayerEndVerdictTests: XCTestCase {
     XCTAssertFalse(state.ended)
   }
 
+  // MARK: - A drain that is really a failure
+
+  /// A drain that follows the current track's reported failure stays where it
+  /// is rather than wrapping.
+  func testADrainAfterTheCurrentTrackFailedDoesNotAdvanceTheQueue() async throws {
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[2]] }
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 2, "the queue stays on the track whose failure was reported")
+    XCTAssertFalse(state.ended, "a reported failure is not the end of the queue either")
+  }
+
+  /// The crossfade engine's own end signal reaches the same decision.
+  func testAnEngineEndReportAfterTheCurrentTrackFailedDoesNotAdvanceTheQueue() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[2]] }
+    let engine = try await read { $0.engine }
+    let reporting = try XCTUnwrap(engine)
+
+    await onQueue { $0.enginePlaybackEnded(reporting) }
+
+    let index = try await read { $0.currentTrackIndex }
+    XCTAssertEqual(index, 2)
+  }
+
+  /// A report against a track the playhead has left does not hold a genuine
+  /// end of queue open.
+  func testADrainAfterADifferentTrackFailedStillEndsTheQueue() async throws {
+    try await seedQueue(count: 3, at: 2, repeatMode: .off)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[0]] }
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let ended = try await read { $0.reachedQueueEnd }
+    XCTAssertTrue(ended)
+  }
+
   // MARK: - Helpers
 
   private func installCrossfade() async throws {

package/ios/TrackPlayer+EventsDispatch.swift

@@ -87,14 +87,77 @@ extension TrackPlayer {
     self.pendingTrackChangeReason = nil
     let endFired = self.didPlayToEndPending
     self.didPlayToEndPending = false
-    if endFired && !pendingUserMutation {
+    // A queue stopped on a reported failure does not re-derive its index from
+    // the player. `removeAllItems` fires `AVPlayerItemDidPlayToEndTime` for an
+    // item that never played (FB9221518), and the re-seat below issues one, so
+    // without this a later pass would resync off the parked position onto the
+    // track behind it — the move the stop exists to prevent. The report does
+    // not exist yet on the pass that files it, so that pass still runs.
+    if endFired && !pendingUserMutation && self.reportedFailureOnCurrentTrack == nil {
       if let derived = matchTrackIndex(forCurrentItem: self.player?.currentItem) {
-        self.currentTrackIndex = derived
+        // One natural advance that lands more than one position on means the
+        // player dropped what it skipped: `AVQueuePlayer` discards an item that
+        // cannot be played, and a track that failed while the previous one was
+        // still playing is never seated, so nothing ever observes its failure —
+        // the current-item status observer is the only load-failure path and it
+        // never sees that item. Carrying the queue past it would skip a track
+        // the listener never heard and was never told about.
+        if derived > self.currentTrackIndex + 1 {
+          self.stopOnDroppedTrack(at: self.currentTrackIndex + 1)
+        } else {
+          self.currentTrackIndex = derived
+        }
       }
     }
     return reason
   }
 
+
+  /// Stop on a track the player dropped mid-advance, report it, and park.
+  ///
+  /// Nothing has observed this track fail — `AVQueuePlayer` removed it rather
+  /// than seating it — so the report is raised here, against the position.
+  /// `fileFormatNotRecognized` is chosen for being fatal, which is what the
+  /// stop needs: the same function drops the play intent, and doing that under
+  /// a transient code would contradict `dispatchErrorOrRetry`, which refuses to.
+  /// The library does not know *why* the player dropped it — a 404, a DNS
+  /// failure and a non-media body all land here — so the code is a statement
+  /// about recoverability, not about the body.
+  private func stopOnDroppedTrack(at index: Int) {
+    guard let qid = self.queueItemIds[safe: index] else { return }
+    self.currentTrackIndex = index
+    self.engine?.pause()
+    self.wantsToPlay = false
+    // The player discarded this position's item and is sitting on one further
+    // on, so every read that answers from the seated item — duration,
+    // seekability, the progress payload's position — would describe a track the
+    // listener is not on. Re-seat the failed position so the index and the item
+    // agree. Forced, because the item keeps its `queueItemId` and an identity
+    // comparison would find the slice already correct.
+    //
+    // Read before the rebuild, which empties the set: a track the status
+    // observer already reported is one the consumer has been told about, and
+    // the drop is the same failure arriving by a second route.
+    let alreadyReported = self.reportedFailureQueueItemIds.contains(qid)
+    // The report is filed after: a forced rebuild clears the set, and the
+    // re-seated item failing again is then suppressed by this entry, so one
+    // dropped track still reports once.
+    self.performingMutation { self.fullRebuildPlayerQueue(forcingReinstall: true) }
+    self.reportedFailureQueueItemIds.insert(qid)
+    // The queue still parks — index, pause, intent and the re-seat above all
+    // stand — it just does not say so twice.
+    if alreadyReported { return }
+    let err = self.buildPlaybackError(
+      nil,
+      mapped: .fileFormatNotRecognized,
+      queueItemId: qid,
+      url: self.tracks[safe: index]?.url ?? "",
+      nativeDomainOverride: "PLAYER_ITEM_DROPPED"
+    )
+    self.errorListeners.forEach { $0(err) }
+    self.emitState(.error, reason: .error)
+  }
+
   /// Debug-only log of the classifier's verdict for the current item next to
   /// the URL its asset is bound to and its `sourceURL`.
   ///
@@ -162,6 +225,13 @@ extension TrackPlayer {
       self.lastEmittedQueueItemId = currentItemId
       self.lastErrorQueueItemId = nil
       self.lastErrorCode = nil
+      // A report against some OTHER track says nothing about the one now being
+      // announced, so it goes. A report against the track being announced
+      // stands: an item that is already failed when it is seated has its error
+      // dispatched before this, the first announcement of its position, and
+      // clearing here would leave the queue with nothing to hold on.
+      self.reportedFailureQueueItemIds = self.reportedFailureQueueItemIds
+        .intersection(currentItemId.map { [$0] } ?? [])
       // A real track (re)loaded => no longer at the end of the queue. At true
       // end-of-queue this block is skipped entirely — the last-track id still
       // matches `lastEmittedQueueItemId` — so `reachedQueueEnd` stays set; the
@@ -453,7 +523,11 @@ extension TrackPlayer {
     // The buffer has recovered and the user still wants playback: nothing else
     // will restart it. Not while the session is interrupted — the refill can
     // land mid-call, and the interruption's `.ended` is what resumes then.
-    if self.isRecoveringFromStall, computed == .full, self.wantsToPlay, !self.isInterrupted {
+    // Not while the queue is stopped on a reported failure either: the player
+    // has already moved onto the track behind it, and a refill is not the
+    // listener asking for that track.
+    if self.isRecoveringFromStall, computed == .full, self.wantsToPlay,
+       !self.isInterrupted, self.reportedFailureOnCurrentTrack == nil {
       self.isRecoveringFromStall = false
       self.beginPlayback()
     }

package/ios/TrackPlayer+Lifecycle.swift

@@ -249,7 +249,13 @@ extension TrackPlayer {
               for: self.config.audioCategoryOptions,
               contentType: self.config.audioContentType
             ))
-          self.beginPlayback()
+          // Not when the queue is stopped on a reported failure: the player is
+          // parked on a track the consumer was told failed, and `beginPlayback`
+          // writes a rate without consulting the transport intent, so resuming
+          // here would start it — or the track behind it — unasked.
+          if self.reportedFailureOnCurrentTrack == nil {
+            self.beginPlayback()
+          }
         case .endedShouldNotResume:
           // Interruption ended but user resolved it in a way that
           // shouldn't restart music. The player is already paused
@@ -602,6 +608,7 @@ extension TrackPlayer {
     // (the dedup is per-item).
     self.lastErrorQueueItemId = nil
     self.lastErrorCode = nil
+    self.reportedFailureQueueItemIds.removeAll()
     self.pendingRetryQueueItemId = nil
     self.retryAttemptsRemaining.removeAll()
     self.lastReportedState = .none
@@ -859,6 +866,33 @@ extension TrackPlayer {
     // An echo of a failure whose attempt has not run yet belongs to that
     // attempt, not to the consumer.
     if let qidReal = item?.queueItemId, self.pendingRetryQueueItemId == qidReal { return }
+    // Already reported and not yet recovered. The `(item, code)` dedup below
+    // cannot carry this on its own: a source the player keeps re-attempting —
+    // a server answering a ranged request with a whole body makes AVFoundation
+    // do exactly that — fails under more than one code, and codes that
+    // alternate defeat a one-slot key. Every recovery path clears the field, so
+    // the next thing the consumer asks for reports again.
+    if let qidReal = item?.queueItemId, self.reportedFailureQueueItemIds.contains(qidReal) { return }
+    // Once the queue has stopped on the current track, the tracks behind it go
+    // quiet. The `AVPlayerItemFailedToPlayToEndTime` observer is registered
+    // against every item, so a window of unplayable sources reports each of
+    // them — turning one `play()` into one error per broken track, which is the
+    // flicker the listener sees. They have already been told the track they are
+    // on failed; the rest is noise they cannot act on.
+    //
+    // While playback is healthy this does not fire, so a standby leg failing to
+    // preroll under crossfade is still surfaced — the leading leg is playing,
+    // nothing has been reported against it, and that failure is news.
+    //
+    // Nothing is lost either way: a suppressed track reports when the player
+    // seats it and it fails as the current one, or when the player drops it and
+    // `stopOnDroppedTrack` reports it against the position it skipped.
+    if let failedQid = item?.queueItemId,
+       let currentQid = self.queueItemIds[safe: self.currentTrackIndex],
+       failedQid != currentQid,
+       self.reportedFailureQueueItemIds.contains(currentQid) {
+      return
+    }
     if self.lastErrorQueueItemId == qid && self.lastErrorCode == mapped { return }
     self.lastErrorQueueItemId = qid
     self.lastErrorCode = mapped
@@ -896,6 +930,24 @@ extension TrackPlayer {
       url: failedUrl,
       nativeDomainOverride: nativeDomainOverride
     )
+    if let failedQid = item?.queueItemId {
+      // The consumer now knows this track failed, so the queue holds on it
+      // until something asks for playback again.
+      self.reportedFailureQueueItemIds.insert(failedQid)
+      // `AVQueuePlayer` consumes a failed item, so by now its current item is
+      // whatever was installed behind the failure. The gapless status path
+      // pauses before it gets here; the crossfade path has no queue player to
+      // pause, and neither covers a mid-playback failure.
+      self.engine?.pause()
+      // A failure that will not recover on its own ends the intent to play, the
+      // way reaching the end of the queue does. Left set for a transient
+      // failure whose attempts are merely spent, because that is what
+      // `handleNetworkRestored` reads through `NetworkRecoveryPolicy` when the
+      // network comes back. The resumes that do not consult this flag — a
+      // stall recovery, an interruption ending — are held off by the entry
+      // above instead, so neither case starts the track behind the failure.
+      if !PlaybackErrorMapping.isTransient(mapped) { self.wantsToPlay = false }
+    }
     self.errorListeners.forEach { $0(err) }
     self.emitState(.error, reason: .error)
   }

package/ios/TrackPlayer+Queue.swift

@@ -80,6 +80,7 @@ extension TrackPlayer {
         // coded error on the new queue's first item.
         self.lastErrorQueueItemId = nil
         self.lastErrorCode = nil
+        self.reportedFailureQueueItemIds.removeAll()
         // Reset auto-retry counters: new queueItemIds → new budget
         // entries. The retry budget is per-queue-position; old
         // entries from the prior queue are gone with the prior
@@ -509,6 +510,7 @@ extension TrackPlayer {
       self.lastEmittedQueueItemId = nil
       self.lastErrorQueueItemId = nil
       self.lastErrorCode = nil
+      self.reportedFailureQueueItemIds.removeAll()
       self.retryAttemptsRemaining.removeAll()
       // Fire queue-change BEFORE the synthetic track-change so a
       // `useQueue()` consumer sees the empty queue + index -1 together,
@@ -682,6 +684,15 @@ extension TrackPlayer {
   /// terminally. A failed item keeps its `queueItemId`, so identity cannot
   /// tell a dead item from a live one and the caller has to say.
   internal func fullRebuildPlayerQueue(forcingReinstall: Bool = false) {
+    // A forced reinstall builds the current position from scratch, so whatever
+    // was reported against it no longer describes what is installed. Its
+    // callers — `play()`, `retry()` and `retryFailedItem` — drop the position
+    // they attempt themselves too; this covers the case where the rebuild below
+    // bails at its own guards, and a skip that seats without rebuilding clears
+    // its target in `applyNewCurrentIndex`. `stopOnDroppedTrack` also forces a
+    // reinstall and files its report after this line, so the clear does not
+    // reach it.
+    if forcingReinstall { self.reportedFailureQueueItemIds.removeAll() }
     assertQueueIdsInvariant("fullRebuildPlayerQueue")
     guard let engine = self.engine else { return }
     guard self.currentTrackIndex >= 0,

package/ios/TrackPlayer+Recovery.swift

@@ -105,6 +105,22 @@ extension TrackPlayer {
     appLifecycleObservers.removeAll()
   }
 
+  /// The current position's `queueItemId` when its failure has been reported
+  /// and not yet recovered; nil otherwise.
+  ///
+  /// The position matters because the queue only holds where it is for *this*
+  /// track's failure. A report against a track the playhead has since left says
+  /// nothing about whether the current one can play.
+  ///
+  /// Nil when the failing item carried no `queueItemId` — nothing can be
+  /// correlated to a position then, so the queue behaves as it did before the
+  /// failure. `AVQueueBuilder.makeItem` always sets one; raw items do not.
+  internal var reportedFailureOnCurrentTrack: String? {
+    guard let currentId = self.queueItemIds[safe: self.currentTrackIndex],
+          self.reportedFailureQueueItemIds.contains(currentId) else { return nil }
+    return currentId
+  }
+
   /// Retry the current item when the network comes back after an outage.
   ///
   /// The common real-world case is a tunnel, a lift, or airplane mode: the
@@ -157,6 +173,7 @@ extension TrackPlayer {
     // The attempt has arrived, so whatever fails next is a new failure rather
     // than an echo of the one being retried.
     if self.pendingRetryQueueItemId == qid { self.pendingRetryQueueItemId = nil }
+    self.reportedFailureQueueItemIds.remove(qid)
     guard let engine = self.engine else { return }
     // Verify the failed item is still the current one. A subsequent
     // user skip / queue mutation could have moved past it; in that

package/ios/TrackPlayer+Skip.swift

@@ -274,6 +274,16 @@ extension TrackPlayer {
     guard newIndex >= 0, newIndex < self.tracks.count else { return }
 
     let oldIndex = self.currentTrackIndex
+    // Seating a position is an attempt at it, so whatever was reported against
+    // it no longer describes what is about to play. This is the clear point for
+    // every skip, including the ones that seat without rebuilding — a crossfade
+    // skip onto a position the engine still holds, and a forward skip that
+    // trims the installed run — which would otherwise leave the report standing
+    // and the track silently wedged: no report, no run extension, no end
+    // verdict, until play().
+    if let seated = self.queueItemIds[safe: newIndex] {
+      self.reportedFailureQueueItemIds.remove(seated)
+    }
     if newIndex == oldIndex {
       // A same-index skip is an explicit "restart this track" — no longer at
       // the end of the queue. Clear `reachedQueueEnd` here because this branch returns

package/ios/TrackPlayer+Transport.swift

@@ -7,32 +7,35 @@ extension TrackPlayer {
   func play() throws -> Promise<Void> {
     return enqueue {
       if CastTransportRouter.routePlay() { return }
-      // Stuck-recovery: a user re-tapping play after an exhausted-retries error
-      // is asking for this track again, so it gets the allowance the consumer
-      // configured back and a rebuild. Not a hard-coded 1: `autoRetries: 0`
-      // asked for none.
-      if self.lastReportedState == .error,
-         self.currentTrackIndex >= 0,
-         self.currentTrackIndex < self.queueItemIds.count {
-        let qid = self.queueItemIds[self.currentTrackIndex]
-        if (self.retryAttemptsRemaining[qid] ?? 0) == 0 {
-          // Asking for this track to play is incompatible with the queue being
-          // over, so `reachedQueueEnd` cannot survive it.
-          self.reachedQueueEnd = false
-          self.retryAttemptsRemaining[qid] = self.effectiveAutoRetries()
-          // A scheduled attempt for this item is superseded by the rebuild below.
-          if self.pendingRetryQueueItemId == qid { self.pendingRetryQueueItemId = nil }
-          self.lastErrorQueueItemId = nil
-          self.lastErrorCode = nil
-          // Rebuild whenever an engine is live — the rebuild is
-          // engine-agnostic, and the failed item has to be
-          // reconstructed on either engine for the retry to reach it.
-          // Forced: the failed item keeps its `queueItemId`, so a rebuild
-          // that compares identity would find nothing to do.
-          if self.engine != nil {
-            self.performingMutation {
-              self.fullRebuildPlayerQueue(forcingReinstall: true)
-            }
+      // Stuck-recovery: the queue holds on a track whose failure was reported,
+      // and pressing play is asking for that track again — so it gets the
+      // allowance the consumer configured back and a rebuild. Not a hard-coded
+      // 1: `autoRetries: 0` asked for none.
+      if let qid = self.reportedFailureOnCurrentTrack {
+        // Asking for this track to play is incompatible with the queue being
+        // over, so `reachedQueueEnd` cannot survive it.
+        self.reachedQueueEnd = false
+        self.retryAttemptsRemaining[qid] = self.effectiveAutoRetries()
+        // This track only. A standby leg's report is a different track's, and
+        // discarding it here would hand the listener that failure a second
+        // time when the engine seats it.
+        self.reportedFailureQueueItemIds.remove(qid)
+        // A scheduled attempt for this item is superseded by the rebuild below.
+        // Reachable because the two are set by different errors on the same
+        // item: a reported failure leaves the report standing, and a later
+        // failure carrying a different code is transient enough to schedule an
+        // attempt. Leaving it would fire a second rebuild behind this one.
+        if self.pendingRetryQueueItemId == qid { self.pendingRetryQueueItemId = nil }
+        self.lastErrorQueueItemId = nil
+        self.lastErrorCode = nil
+        // Rebuild whenever an engine is live — the rebuild is
+        // engine-agnostic, and the failed item has to be
+        // reconstructed on either engine for the retry to reach it.
+        // Forced: the failed item keeps its `queueItemId`, so a rebuild
+        // that compares identity would find nothing to do.
+        if self.engine != nil {
+          self.performingMutation {
+            self.fullRebuildPlayerQueue(forcingReinstall: true)
           }
         }
       }
@@ -89,6 +92,8 @@ extension TrackPlayer {
       if self.pendingRetryQueueItemId == qid { self.pendingRetryQueueItemId = nil }
       self.lastErrorQueueItemId = nil
       self.lastErrorCode = nil
+      // This track only, for the reason `play()` gives above.
+      self.reportedFailureQueueItemIds.remove(qid)
       // Rebuild whenever an engine is live — the rebuild is
       // engine-agnostic, and the failed item has to be reconstructed
       // on either engine for the retry to reach it. Forced: the failed

package/ios/TrackPlayer+Window.swift

@@ -17,6 +17,21 @@ extension TrackPlayer {
     // installing into it here would put the finished track back and let the
     // rate the engine restores carry it on playing.
     guard !engine.allMediaItems.isEmpty, !self.reachedQueueEnd else { return }
+    // A current position that has failed is not put back, whether its failure
+    // has been reported or an attempt for it is still scheduled. `AVQueuePlayer`
+    // consumes a failed item, and when the run holds something behind it the
+    // player advances there instead of draining — so the end verdict never runs
+    // and this reconcile is what rebuilds. It rebuilds from `currentTrackIndex`,
+    // still the failed position because the resync needs a play-to-end and a
+    // failure fires `AVPlayerItemFailedToPlayToEndTime` instead, and a reinstall
+    // is exactly what a missing current position asks for. The rebuilt item
+    // fails the same way and its error is swallowed — as a repeat, or as an echo
+    // of the pending attempt — so the rebuild would repeat unannounced.
+    guard self.reportedFailureOnCurrentTrack == nil else { return }
+    if let currentId = self.queueItemIds[safe: self.currentTrackIndex],
+       self.pendingRetryQueueItemId == currentId {
+      return
+    }
     self.performingMutation { self.fullRebuildPlayerQueue() }
   }
 
@@ -92,6 +107,23 @@ extension TrackPlayer {
        self.pendingRetryQueueItemId == currentId {
       return
     }
+    // A drain that follows the current item's reported failure is that failure,
+    // not the end of the queue. The same `.advance` walks a failed item out of
+    // the player, and with nothing installed behind it the queue drains to
+    // `currentItem == nil` and lands here. Deciding a verdict would move past a
+    // track the consumer has just been told failed — and when the tracks behind
+    // it fail the same way, the advance, rebuild and resume repeat with nothing
+    // counting them, wrapping forever under repeat-all. The queue stays where it
+    // is, in `.error`, until `play()` or `retry()` asks for the track again.
+    if self.reportedFailureOnCurrentTrack != nil {
+      // Park the engine, as the queue-end branch below does and for the same
+      // reason: neither engine drops its rate when it runs out of items, so a
+      // leg left running would start whatever lands on it next. The gapless
+      // failure path pauses the `AVQueuePlayer` itself, but the crossfade one
+      // has no `AVQueuePlayer` to pause.
+      self.engine?.pause()
+      return
+    }
     var verdict = QueueWindowArithmetic.verdict(
       drained: true,
       atLogicalTail: QueueWindowArithmetic.isAtLogicalTail(

package/ios/TrackPlayer.swift

@@ -405,6 +405,32 @@ class TrackPlayer: HybridTrackPlayerSpec {
   internal var lastErrorQueueItemId: String?
   internal var lastErrorCode: PlaybackErrorCode?
 
+  /// `queueItemId` of every track whose playback error has been reported to
+  /// the consumer and not yet recovered.
+  ///
+  /// A set, not one slot: several tracks of an installed run can be failing at
+  /// once — a window of unplayable sources does exactly that — and a single
+  /// slot cannot hold them. Each fire replaces the last, so a later fire for a
+  /// track already reported passes the check and reports again — one broken
+  /// queue then hands the listener an unbounded stream of `onError`.
+  ///
+  /// Written where `dispatchErrorOrRetry` hands an `onError` out and where
+  /// `stopOnDroppedTrack` reports a track the player discarded, so it names a
+  /// track the consumer has been told about and nothing has recovered. The
+  /// queue neither advances past that track nor puts it back until the track's
+  /// entry is cleared, which `play()`, `retry()`, `retryFailedItem`, a track
+  /// change to a different track, a skip that seats the position, `setQueue`,
+  /// `clearQueue`, `destroy` and a forced `fullRebuildPlayerQueue` all do.
+  /// Deliberately NOT a state emit of `.playing`: a source the player keeps
+  /// re-attempting flips to playing between attempts, so clearing there would
+  /// reopen the report for a track already reported.
+  ///
+  /// Separate from `lastErrorQueueItemId` even though both name a failing
+  /// track: that one exists to dedup repeat reports and is cleared whenever a
+  /// repeat would be wanted again, which is not the same question as whether
+  /// the queue is still stopped.
+  internal var reportedFailureQueueItemIds: Set<String> = []
+
   /// `queueItemId` of the item whose automatic attempt is scheduled but has
   /// not run yet.
   ///