react-native-queue-player 1.2.0 → 2.0.1

package/ios/TrackPlayer+Transport.swift

@@ -0,0 +1,272 @@
+import AVFoundation
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Transport — pass-through to AVQueuePlayer.
+
+  func play() throws -> Promise<Void> {
+    return enqueue {
+      if CastTransportRouter.routePlay() { return }
+      // 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)
+          }
+        }
+      }
+      // At the end of the queue there is nothing to play: the engine is
+      // parked on the finished track (or drained), and writing a rate onto
+      // it would report `.playing` for a moment or, on some OS versions,
+      // re-post the item's end. A skip, a seek or a fresh queue leaves this
+      // state; play() alone restarts nothing.
+      if self.reachedQueueEnd, self.currentTrackIndex >= 0 { return }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = true
+      // An explicit play ends an interruption from the user's side: the
+      // system does not always deliver `.ended` (an app suspended mid-call
+      // never sees it), and the flag would otherwise keep retries, window
+      // refills and network recovery disabled for the rest of the session.
+      self.isInterrupted = false
+      self.beginPlayback()
+      self.recomputeBufferState()
+    }
+  }
+
+  func retry() throws -> Promise<Void> {
+    return enqueue {
+      // During cast the receiver owns playback — forward a play so a failed
+      // receiver item re-attempts.
+      if CastTransportRouter.routePlay() { return }
+      // A user asking for a retry has a reason, and the library is not the one
+      // to judge it. This is the manual attempt once the automatic one is
+      // spent, so gating it on the player's state would gate recovery on the
+      // state of a player that has already failed to recover — and a wedged
+      // decoder still reporting `playing` is exactly when someone reaches for
+      // the button.
+      //
+      // Only the bounds remain: no current track is genuinely nothing to
+      // retry, which is not second-guessing the request.
+      guard self.currentTrackIndex >= 0,
+            self.currentTrackIndex < self.queueItemIds.count else { return }
+      let qid = self.queueItemIds[self.currentTrackIndex]
+      // Capture the pre-failure position so a mid-track failure resumes where
+      // it stopped (the rebuild below reloads the item from 0). Matches
+      // Android's retryFailedItem position-restore.
+      let resumePos = self.engine?.currentPositionSeconds ?? 0
+      // Asking for this track to play is incompatible with the queue being over,
+      // and a queue whose only track failed to load has already drained: without
+      // this the rebuild seats an item into a queue that believes it is finished.
+      self.reachedQueueEnd = false
+      // The configured budget, not a hard-coded 1: this restores the track's
+      // automatic allowance for whatever fails *next*, and a consumer who set
+      // `autoRetries: 0` asked for none.
+      self.retryAttemptsRemaining[qid] = self.effectiveAutoRetries()
+      // A scheduled attempt for this item is superseded by the rebuild below;
+      // leaving it set would suppress the rebuilt item's own failure until the
+      // earlier attempt fired.
+      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
+      // 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)
+        }
+      }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = true
+      self.beginPlayback()
+      if resumePos.isFinite, resumePos > 0 {
+        _ = try? self.seekTo(position: resumePos)
+      }
+      self.recomputeBufferState()
+    }
+  }
+
+  func pause() throws -> Promise<Void> {
+    return enqueue {
+      if CastTransportRouter.routePause() { return }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = false
+      // An explicit pause outranks a pending stall recovery: without this the
+      // buffer refilling afterwards would restart audio the user just stopped.
+      self.isRecoveringFromStall = false
+      self.engine?.pause()
+      self.recomputeBufferState()
+    }
+  }
+
+  /// "Stop" = pause + seek to start of current item. Does NOT clear
+  /// the queue — consumers wanting a full reset call clearQueue().
+  func stop() throws -> Promise<Void> {
+    return enqueue {
+      if CastTransportRouter.routeStop() { return }
+      guard let engine = self.engine else { return }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = false
+      self.hasStartedPlaying = false
+      engine.stop()
+      self.recomputeBufferState()
+    }
+  }
+
+  /// Seek within the current track. Position in seconds; negative
+  /// values clamp to 0, values past the duration clamp to duration.
+  func seekTo(position: Double) throws -> Promise<Void> {
+    // Enqueued at call time, like every other transport method, so a seek
+    // reaches the player in the order JS issued it. The promise resolves once
+    // the seek's own completion has landed, which is why this builds the
+    // promise by hand rather than using `enqueue`.
+    let promise = Promise<Void>()
+    playerQueue.async {
+      // Match Android (`TrackPlayer.kt` seekToInternal): non-finite
+      // (NaN / ±Infinity) inputs are silent no-ops. See
+      // `InputGuards.sanitisedSeekPosition` for the rationale.
+      guard let position = InputGuards.sanitisedSeekPosition(position) else {
+        promise.resolve()
+        return
+      }
+      if CastTransportRouter.routeSeekTo(positionMs: Int64(position * 1000.0)) {
+        promise.resolve()
+        return
+      }
+
+      // Every player + queue read and the seek itself run on this one hop, so
+      // the player never crosses a concurrency boundary. The return value
+      // carries whether a seek was issued: the crossfade branch and the
+      // drained-gapless branch complete in place and yield false.
+      //
+      // Named rather than inlined so the two early-return branches and the
+      // seek branch share one exit.
+      let issueSeek: () -> Bool = {
+        // Engine-aware seek: under CrossfadeEngine `self.player` is
+        // nil. Without this branch every seek call would silently
+        // no-op once crossfade mode is active, breaking transport
+        // controls + auto-advance test coverage.
+        if self.player == nil {
+          guard let engine = self.engine else { return false }
+          // Seeking replays from a position — no longer at the end of the
+          // queue. (Gapless no-ops at end-of-queue with no current item below.)
+          self.reachedQueueEnd = false
+          let duration = engine.currentDurationSeconds
+          let clamped: Double
+          if position < 0 {
+            clamped = 0
+          } else {
+            clamped = (duration > 0 && position > duration) ? duration : position
+          }
+          let seekTarget = self.clampToBufferedIfEnabled(clamped)
+          self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+          let engineIdx: Int
+          if let installed = self.engineIndex(forQueuePosition: self.currentTrackIndex) {
+            engineIdx = installed
+          } else {
+            // Active track absent from the engine — reinstall it, then seek
+            // within the reinstalled run so the position is applied rather
+            // than dropped with a resolved promise.
+            self.performingMutation { self.fullRebuildPlayerQueue() }
+            guard let reinstalled = self.engineIndex(forQueuePosition: self.currentTrackIndex)
+            else { return false }
+            engineIdx = reinstalled
+          }
+          engine.seek(toIndex: engineIdx, position: seekTarget)
+          self.milestoneTracker.seek(
+            durationSec: self.effectiveMilestoneDuration(playerDuration: duration),
+            positionSec: seekTarget)
+          self.nowPlayingInfo.refreshPositionAndRate(self.nowPlayingSnapshot())
+          return false
+        }
+
+        guard let player = self.player else { return false }
+        // A gapless player drained at the end of the queue has no item to
+        // seek in: reinstall the finished track first, as a same-index skip
+        // does, so a seek after the end replays it on every engine. Seeking
+        // is what leaves the ended state, so the flag clears here.
+        if player.currentItem == nil, self.reachedQueueEnd,
+           self.currentTrackIndex >= 0, self.currentTrackIndex < self.tracks.count {
+          self.reachedQueueEnd = false
+          self.performingMutation { self.fullRebuildPlayerQueue() }
+        }
+        guard let item = player.currentItem else { return false }
+        let itemDuration = CMTimeGetSeconds(item.duration)
+        let clamped: Double
+        if position < 0 {
+          clamped = 0
+        } else {
+          clamped = (itemDuration.isFinite && position > itemDuration) ? itemDuration : position
+        }
+        // Apply the opt-in buffered clamp on top of the 0/duration clamp — caps
+        // the target at the buffered edge when the seek is past what's downloaded.
+        let seekTarget = self.clampToBufferedIfEnabled(clamped)
+        // Consume jumped-over milestones BEFORE issuing the (async) seek so a
+        // time-jump progress tick that fires during the seek can't emit the
+        // thresholds the seek skips over.
+        self.milestoneTracker.seek(
+          durationSec: self.effectiveMilestoneDuration(
+            playerDuration: (itemDuration.isFinite && itemDuration > 0) ? itemDuration : 0),
+          positionSec: seekTarget)
+        // Stash `.user` reason BEFORE the seek so any state transition
+        // the seek triggers (e.g. playable → buffering on a long jump)
+        // gets the correct origin. Matches the play / pause / stop pattern.
+        self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+        player.seek(
+          to: CMTime(seconds: seekTarget, preferredTimescale: CMTimeScale(NSEC_PER_SEC)),
+          toleranceBefore: .zero,
+          toleranceAfter: .zero
+        ) { _ in
+          // This closure captures `player`, so a teardown that drops every
+          // other reference cannot deallocate it with the seek still pending.
+          // AVFoundation invokes the handler when the seek completes or is
+          // interrupted, and the capture is released with it.
+          _ = player
+          self.playerQueue.async {
+            // Surface the new scrubber position to the lock-screen /
+            // control-center immediately. The KVO state-change emit covers
+            // transitions (e.g. paused → buffering on a long jump) but a
+            // same-state seek won't trigger an emit; without this the
+            // lock-screen scrubber sits at the pre-seek position until the
+            // next 10s periodic tick.
+            self.nowPlayingInfo.refreshPositionAndRate(self.nowPlayingSnapshot())
+            promise.resolve()
+          }
+        }
+        return true
+      }
+      // A branch that completed in place has nothing pending, so the promise
+      // resolves here; the seek branch resolves from its completion instead.
+      if !issueSeek() { promise.resolve() }
+    }
+    return promise
+  }
+}

package/ios/TrackPlayer+Window.swift

@@ -0,0 +1,227 @@
+extension TrackPlayer {
+  /// Bring the engine's installed run back in line as the playhead moves.
+  ///
+  /// Reconciling against `QueueWindowArithmetic.slice` rather than measuring
+  /// from an anchor: a run that wraps ends at a lower absolute position than
+  /// it starts, so any comparison of the two as integers reads it as
+  /// backwards. The reconcile keeps what is still wanted, drops what has
+  /// fallen off the trail, and builds the rest.
+  internal func topUpWindow() {
+    guard let engine = self.engine else { return }
+    // Every branch of the reconcile changes the installed items, and each of
+    // those cancels an in-flight fade. Extending the run can wait for the fade
+    // to finish; cutting a crossfade short to do it cannot be undone.
+    guard !engine.isFadePendingOrActive else { return }
+    // This extends a run; it never creates one. A drained engine is either a
+    // queue that has ended or one the caller is about to seat itself, and
+    // 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() }
+  }
+
+  /// Notices that the gapless player has auto-advanced past its last item,
+  /// and hands the decision to `applyEndVerdict`.
+  internal func detectQueueEnd() {
+    // Engine-aware "is the active item nil" check. With
+    // CrossfadeEngine `self.player` is nil by design — reading it
+    // alone would mis-detect every mid-play engine swap as
+    // queue-end and fire a spurious onQueueEnd + emitState(.ended).
+    let activeItemNil: Bool
+    if self.player != nil {
+      activeItemNil = self.player?.currentItem == nil
+    } else if let engine = self.engine {
+      activeItemNil = engine.currentMediaItem == nil
+    } else {
+      activeItemNil = true
+    }
+    guard activeItemNil else { return }
+    applyEndVerdict()
+  }
+
+  /// Play `currentTrackIndex` from its start and announce it.
+  ///
+  /// A rebuild replaces only the positions that differ, so it cannot be relied
+  /// on for either half of this: when the position being re-seated is already
+  /// the one installed, nothing is replaced, the seek is what restarts it, and
+  /// no `currentItem` change fires to carry the track change out. Dispatching
+  /// here is deduped against `lastEmittedQueueItemId`, so a rebuild that *did*
+  /// replace the item still emits exactly once.
+  private func restartCurrentPosition() {
+    if let engine = self.engine,
+       let engineIdx = engineIndex(forQueuePosition: self.currentTrackIndex) {
+      engine.seek(toIndex: engineIdx, position: 0)
+    }
+    dispatchTrackChange(reason: .autoAdvance)
+  }
+
+  /// Decide and apply what a drained engine means for the queue.
+  ///
+  /// Both ends funnel here — the gapless player's `currentItem` going nil, and
+  /// the crossfade engine reporting its last item played out — so the queue
+  /// reaches the same verdict whichever engine is installed. The engines
+  /// report that they drained; they do not decide whether the queue is over.
+  ///
+  /// A drained engine exposes no items, so the anchor cannot be derived from
+  /// them. `matchTrackIndex(forCurrentItem: nil)` is nil at a drain, which
+  /// leaves `currentTrackIndex` on the track that just finished — the furthest
+  /// position the queue actually reached.
+  internal func applyEndVerdict() {
+    // `verdict` is specified against a queue that has something to end.
+    guard !self.tracks.isEmpty else { return }
+    // A queue that has ended stays ended: a further drain report — a rate
+    // written onto a leg parked at its end re-posts the item's end — must
+    // not re-decide against a queue that has since grown and seat the added
+    // track. A skip, a seek or a fresh queue clears the flag first.
+    guard !self.reachedQueueEnd else { return }
+    // A drain whose current item failed to load with an auto-retry already
+    // scheduled is not the end of the queue — the pending retry rebuilds and
+    // resumes that item. `AVQueuePlayer` consumes a failed item (its
+    // `actionAtItemEnd` is `.advance`) and drains to `currentItem == nil`,
+    // which lands here; deciding a queue-end would clear the play intent the
+    // retry reads, leaving the recovered track paused. The scheduled retry
+    // clears `pendingRetryQueueItemId` and re-seats the item, so this only
+    // holds for the brief window between the failure and the attempt.
+    //
+    // Relies on the item's `.failed` status KVO — which stakes
+    // `pendingRetryQueueItemId` in `dispatchErrorOrRetry` — being delivered
+    // before the `currentItem`→nil drain KVO that reaches here. The status
+    // change is what causes the advance-to-nil, so it is observed first. The
+    // `retry-recovery` demo suite is the integration coverage for that order.
+    if let currentId = self.queueItemIds[safe: self.currentTrackIndex],
+       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(
+        anchorPosition: self.currentTrackIndex, trackCount: self.tracks.count),
+      repeatMode: repeatModeAsSkipMode())
+
+    // Re-decided in place when the position a verdict seats cannot be built:
+    // `.windowDrained` advances the anchor each time round, so it reaches the
+    // tail; `.refillCurrent` cannot advance (repeat-track re-seats the same
+    // position), so an unplayable current track ends the queue instead.
+    while true {
+      switch verdict {
+      case .notEnded:
+        return
+      case .wrapToStart:
+        self.currentTrackIndex = 0
+        self.pendingTrackChangeReason = .autoAdvance
+        // The queueItemId at index 0 is unchanged across a single-track wrap,
+        // so without this clear the next dispatch would dedup-swallow the
+        // re-emission and the consumer would see no track change.
+        self.lastEmittedQueueItemId = nil
+        self.performingMutation { self.fullRebuildPlayerQueue() }
+        // Restart position 0 explicitly: on a single-track queue the wrap target
+        // is the item already installed, so the rebuild replaces nothing.
+        restartCurrentPosition()
+        // Each engine restores its own rate across a rebuild only while its
+        // play intent stands, and a reconcile that removes the item the
+        // crossfade engine's leading leg held drops that intent with it — so
+        // the resume is asked for here. Gated on the transport intent because
+        // a rebuild cannot tell "was playing" from "was paused" by rate alone,
+        // and on the interruption flag because the system may not permit
+        // playback right now.
+        if self.wantsToPlay, !self.isInterrupted { self.beginPlayback() }
+        return
+      case .windowDrained, .refillCurrent:
+        // The engine ran out with queue left. `currentTrackIndex` still names
+        // the track that just finished, so `.windowDrained` moves past it while
+        // `.refillCurrent` re-seats it. Clearing `lastEmittedQueueItemId` keeps
+        // the refilled track from being dedup-swallowed, and the drained player
+        // has parked at rate 0, so it has to be told to resume.
+        if verdict == .windowDrained {
+          self.currentTrackIndex = min(self.currentTrackIndex + 1, self.tracks.count - 1)
+        }
+        self.pendingTrackChangeReason = .autoAdvance
+        self.lastEmittedQueueItemId = nil
+        self.performingMutation { self.fullRebuildPlayerQueue() }
+        self.rescheduleLookahead()
+        // A position whose item cannot be built is absent from the installed
+        // run, and no engine signal follows to re-enter on. Asking whether the
+        // run holds *this* position rather than whether the engine holds
+        // anything: the run reaches behind the playhead, so an unplayable
+        // current position still leaves the trail installed.
+        //
+        // Re-decide rather than parking mid-queue.
+        if engineIndex(forQueuePosition: self.currentTrackIndex) == nil {
+          if verdict == .refillCurrent {
+            verdict = .queueEnd
+          } else {
+            verdict = QueueWindowArithmetic.verdict(
+              drained: true,
+              atLogicalTail: QueueWindowArithmetic.isAtLogicalTail(
+                anchorPosition: self.currentTrackIndex, trackCount: self.tracks.count),
+              repeatMode: repeatModeAsSkipMode())
+          }
+          continue
+        }
+        // Both verdicts need the explicit restart the wrap does — after the
+        // guard above, so a position that could not be built is never announced
+        // as a track change. An engine that retains its run rebuilds by
+        // extending it, which never re-seats the leg: it would still hold the
+        // item that just ended, and the resume below would write a rate onto a
+        // track already at its end. On an engine that consumes its items the
+        // rebuild has reinstalled from the anchor already, and this seeks to a
+        // position it is on.
+        restartCurrentPosition()
+        // Playback is asked to resume for the same reason as the wrap above,
+        // and only if it was running: neither engine drops its rate when it
+        // runs out of items, so rate cannot tell "was playing" from "was
+        // paused" and the transport intent is what does. Not while the system
+        // has playback interrupted — the refill must not start audio during a
+        // call, nor after one the user declined to resume.
+        if self.wantsToPlay, !self.isInterrupted { self.beginPlayback() }
+        return
+      case .queueEnd:
+        // Park the engine. Draining is not the same as being stopped — neither
+        // engine drops its rate when it runs out of items, so a leg left running
+        // would start the next queue installed on it the moment an item lands.
+        // The other verdicts deliberately resume instead, just below.
+        self.engine?.pause()
+        // The intent to play ends with the queue: nothing that seats a track
+        // from here — a skip, a seek, a fresh queue, an engine swap — starts
+        // it until play() is called again.
+        self.wantsToPlay = false
+        self.reachedQueueEnd = true
+        queueEndListeners.forEach { $0() }
+        emitState(.ended, reason: .queueEnd)
+        return
+      }
+    }
+  }
+}