react-native-nitro-player 1.5.0 → 1.6.0-alpha.0

package/ios/HybridTrackPlayer.swift

@@ -25,40 +25,63 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
     super.init()
   }
 
+  // MARK: - Ordered dispatch
+  //
+  // `Promise.async` starts an unordered Task, so the hop onto the player queue used
+  // to happen at an arbitrary later point: two calls made in order from JS could
+  // reach the player in reverse order (play-then-pause landing as pause-then-play).
+  // Enqueueing synchronously here — on the JS thread, at call time — makes the serial
+  // queue's FIFO order equal the JS call order.
+
+  private func enqueue<T>(_ block: @escaping () -> T) -> Promise<T> {
+    let promise = Promise<T>()
+    core.playerQueue.async { promise.resolve(withResult: block()) }
+    return promise
+  }
+
+  private func enqueueThrowing<T>(_ block: @escaping () throws -> T) -> Promise<T> {
+    let promise = Promise<T>()
+    core.playerQueue.async {
+      do { promise.resolve(withResult: try block()) }
+      catch { promise.reject(withError: error) }
+    }
+    return promise
+  }
+
   // MARK: - Playback Control (async Promise<Void>)
 
   func play() throws -> Promise<Void> {
-    Promise.async { await self.core.play() }
+    enqueue { self.core.playOnQueue() }
   }
 
   func pause() throws -> Promise<Void> {
-    Promise.async { await self.core.pause() }
+    enqueue { self.core.pauseOnQueue() }
   }
 
   func seek(position: Double) throws -> Promise<Void> {
-    Promise.async { await self.core.seek(position: position) }
+    enqueue { self.core.seekOnQueue(position: position) }
   }
 
   func skipToNext() throws -> Promise<Void> {
-    Promise.async { await self.core.skipToNext() }
+    enqueue { self.core.skipToNextOnQueue() }
   }
 
   func skipToPrevious() throws -> Promise<Void> {
-    Promise.async { await self.core.skipToPrevious() }
+    enqueue { self.core.skipToPreviousOnQueue() }
   }
 
   func playSong(songId: String, fromPlaylist: String?) throws -> Promise<Void> {
-    Promise.async { await self.core.playSong(songId: songId, fromPlaylist: fromPlaylist) }
+    enqueue { self.core.playSongInternal(songId: songId, fromPlaylist: fromPlaylist) }
   }
 
   func skipToIndex(index: Double) throws -> Promise<Bool> {
-    Promise.async { await self.core.skipToIndex(index: Int(index)) }
+    enqueue { self.core.skipToIndexOnQueue(index: Int(index)) }
   }
 
   // MARK: - Repeat / Volume / Config
 
   func setRepeatMode(mode: RepeatMode) throws -> Promise<Void> {
-    Promise.async { await self.core.setRepeatMode(mode: mode) }
+    enqueue { self.core.setRepeatModeOnQueue(mode: mode) }
   }
 
   func getRepeatMode() throws -> RepeatMode {
@@ -66,12 +89,12 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
   }
 
   func setVolume(volume: Double) throws -> Promise<Void> {
-    Promise.async { await self.core.setVolume(volume: volume) }
+    enqueue { self.core.setVolumeOnQueue(volume: volume) }
   }
 
   func configure(config: PlayerConfig) throws -> Promise<Void> {
-    Promise.async {
-      await self.core.configure(
+    enqueue {
+      self.core.configureOnQueue(
         androidAutoEnabled: config.androidAutoEnabled,
         carPlayEnabled: config.carPlayEnabled,
         showInNotification: config.showInNotification,
@@ -83,80 +106,80 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
   // MARK: - Queue / State reads
 
   func getActualQueue() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getActualQueue() }
+    enqueue { self.core.getActualQueueInternal() }
   }
 
   func getState() throws -> Promise<PlayerState> {
-    Promise.async { await self.core.getState() }
+    enqueue { self.core.getStateInternal() }
   }
 
   func getCurrentTrackIndex() throws -> Promise<Double> {
-    Promise.async { Double(await self.core.getCurrentTrackIndex()) }
+    enqueue { Double(self.core.currentTrackIndex) }
   }
 
   // MARK: - URL updates / lazy loading
 
   func updateTracks(tracks: [TrackItem]) throws -> Promise<Void> {
-    Promise.async { await self.core.updateTracks(tracks: tracks) }
+    enqueue { self.core.updateTracksInternal(tracks: tracks) }
   }
 
   func getTracksById(trackIds: [String]) throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getTracksById(trackIds: trackIds) }
+    enqueue { self.core.getPlaylistManager().getTracksById(trackIds: trackIds) }
   }
 
   func getTracksNeedingUrls() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getTracksNeedingUrls() }
+    enqueue { self.core.getTracksNeedingUrlsInternal() }
   }
 
   func getNextTracks(count: Double) throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getNextTracks(count: Int(count)) }
+    enqueue { self.core.getNextTracksInternal(count: Int(count)) }
   }
 
   // MARK: - Playback speed
   func setPlaybackSpeed(speed: Double) throws -> Promise<Void> {
-    Promise.async { await self.core.setPlaybackSpeed(speed) }
+    enqueue { self.core.setPlaybackSpeedOnQueue(speed) }
   }
 
   func getPlaybackSpeed() throws -> Promise<Double> {
-    Promise.async { await self.core.getPlaybackSpeed() }
+    enqueue { self.core.currentPlaybackSpeed }
   }
 
   // MARK: - Temporary queue v2
 
   func addToUpNext(trackId: String) throws -> Promise<Void> {
-    Promise.async { try await self.core.addToUpNext(trackId: trackId) }
+    enqueueThrowing { try self.core.addToUpNextOnQueue(trackId: trackId) }
   }
 
   func playNext(trackId: String) throws -> Promise<Void> {
-    Promise.async { try await self.core.playNext(trackId: trackId) }
+    enqueueThrowing { try self.core.playNextOnQueue(trackId: trackId) }
   }
 
   func removeFromPlayNext(trackId: String) throws -> Promise<Bool> {
-    Promise.async { await self.core.removeFromPlayNext(trackId: trackId) }
+    enqueue { self.core.removeFromPlayNextOnQueue(trackId: trackId) }
   }
 
   func removeFromUpNext(trackId: String) throws -> Promise<Bool> {
-    Promise.async { await self.core.removeFromUpNext(trackId: trackId) }
+    enqueue { self.core.removeFromUpNextOnQueue(trackId: trackId) }
   }
 
   func clearPlayNext() throws -> Promise<Void> {
-    Promise.async { await self.core.clearPlayNext() }
+    enqueue { self.core.clearPlayNextOnQueue() }
   }
 
   func clearUpNext() throws -> Promise<Void> {
-    Promise.async { await self.core.clearUpNext() }
+    enqueue { self.core.clearUpNextOnQueue() }
   }
 
   func reorderTemporaryTrack(trackId: String, newIndex: Double) throws -> Promise<Bool> {
-    Promise.async { await self.core.reorderTemporaryTrack(trackId: trackId, newIndex: Int(newIndex)) }
+    enqueue { self.core.reorderTemporaryTrackOnQueue(trackId: trackId, newIndex: Int(newIndex)) }
   }
 
   func getPlayNextQueue() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getPlayNextQueue() }
+    enqueue { self.core.playNextStack }
   }
 
   func getUpNextQueue() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getUpNextQueue() }
+    enqueue { self.core.upNextQueue }
   }
 
   // MARK: - Android Auto (iOS no-op)
@@ -196,6 +219,11 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
     listenerIds.append(("onTracksNeedUpdate", id))
   }
 
+  func onTimedMetadata(callback: @escaping (_ metadata: TimedMetadata) -> Void) throws {
+    let id = core.addOnTimedMetadataListener(callback)
+    listenerIds.append(("onTimedMetadata", id))
+  }
+
   func onTemporaryQueueChange(callback: @escaping (_ playNextQueue: [TrackItem], _ upNextQueue: [TrackItem]) -> Void) throws {
     let id = core.addOnTemporaryQueueChangeListener(callback)
     listenerIds.append(("onTemporaryQueueChange", id))
@@ -212,6 +240,7 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
       case "onPlaybackProgressChange":_ = core.removeOnProgressListener(id: id)
       case "onTracksNeedUpdate":      _ = core.removeOnTracksNeedUpdateListener(id: id)
       case "onTemporaryQueueChange":  _ = core.removeOnTemporaryQueueChangeListener(id: id)
+      case "onTimedMetadata":         _ = core.removeOnTimedMetadataListener(id: id)
       default: break
       }
     }

package/ios/core/TrackPlayerCore.swift

@@ -26,6 +26,10 @@ class TrackPlayerCore: NSObject {
     static let preferredForwardBufferDuration: Double = 30.0
     static let preloadAssetKeys: [String] = ["playable", "duration", "tracks", "preferredTransform"]
     static let gaplessPreloadCount: Int = 3
+    /// Upcoming AVPlayerItems kept materialized behind the current one. The logical
+    /// queue (currentTracks + temp lists) stays complete; only the AVQueuePlayer is
+    /// windowed, and it is topped up on every item transition.
+    static let queueWindowSize: Int = 4
     // Stall & failure recovery
     static let maxFailedItemRetries: Int = 3
     static let failedItemRetryDelay: TimeInterval = 2.0
@@ -44,7 +48,10 @@ class TrackPlayerCore: NSObject {
   internal var currentPlaylistId: String?
   internal var currentTrackIndex: Int = -1
   internal var currentTracks: [TrackItem] = []
-  internal var pendingPlaylistUpdateWorkItem: DispatchWorkItem?
+  // Bumped on every updatePlaylist request (playerQueue-owned). A queued rebuild
+  // whose generation is stale was superseded by a later request and is dropped,
+  // so a burst of playlist mutations collapses into a single rebuild.
+  internal var playlistUpdateGeneration: UInt64 = 0
   internal var isManuallySeeked = false
   internal var currentRepeatMode: RepeatMode = .off
   internal var currentPlaybackSpeed: Double = 1.0
@@ -52,6 +59,10 @@ class TrackPlayerCore: NSObject {
   internal var boundaryTimeObserver: Any?
   internal var currentItemObservers: [NSKeyValueObservation] = []
 
+  // In-stream (timed) metadata output, attached to the current item only.
+  internal var metadataOutput: AVPlayerItemMetadataOutput?
+  internal weak var metadataOutputItem: AVPlayerItem?
+
   // Gapless playback
   internal var preloadedAssets: [String: AVURLAsset] = [:]
   internal let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
@@ -103,6 +114,7 @@ class TrackPlayerCore: NSObject {
   internal let onProgressListeners            = ListenerRegistry<(Double, Double, Bool?) -> Void>()
   internal let onTracksNeedUpdateListeners    = ListenerRegistry<([TrackItem], Int) -> Void>()
   internal let onTemporaryQueueChangeListeners = ListenerRegistry<([TrackItem], [TrackItem]) -> Void>()
+  internal let onTimedMetadataListeners       = ListenerRegistry<(TimedMetadata) -> Void>()
   internal let onCastStateChangeListeners     = ListenerRegistry<(CastState, String?) -> Void>()
 
   // MARK: - Google Cast
@@ -209,6 +221,13 @@ class TrackPlayerCore: NSObject {
     onTemporaryQueueChangeListeners.remove(id: id)
   }
 
+  @discardableResult func addOnTimedMetadataListener(_ cb: @escaping (TimedMetadata) -> Void) -> Int64 {
+    onTimedMetadataListeners.add(cb)
+  }
+  @discardableResult func removeOnTimedMetadataListener(id: Int64) -> Bool {
+    onTimedMetadataListeners.remove(id: id)
+  }
+
   @discardableResult func addOnCastStateChangeListener(_ cb: @escaping (CastState, String?) -> Void) -> Int64 {
     onCastStateChangeListeners.add(cb)
   }
@@ -230,6 +249,7 @@ class TrackPlayerCore: NSObject {
         p.removeTimeObserver(obs)
       }
       self.currentItemObservers.removeAll()
+      self.detachMetadataOutput()
       if let p = self.player {
         p.removeObserver(self, forKeyPath: "status")
         p.removeObserver(self, forKeyPath: "rate")
@@ -239,6 +259,7 @@ class TrackPlayerCore: NSObject {
       NotificationCenter.default.removeObserver(self)
       self.pathMonitor?.cancel()
       self.pathMonitor = nil
+      for asset in self.preloadedAssets.values { asset.cancelLoading() }
       self.preloadedAssets.removeAll()
       self.failedItemRetryCounts.removeAll()
       self.redirectResolver.clear()

package/ios/core/TrackPlayerListener.swift

@@ -285,6 +285,7 @@ extension TrackPlayerCore {
 
     guard let player, let currentItem = player.currentItem else {
       NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Current item changed to nil")
+      detachMetadataOutput()
       // Queue exhausted — handle PLAYLIST repeat
       if currentRepeatMode == .playlist && !currentTracks.isEmpty, let player = self.player {
         NitroPlayerLogger.log("TrackPlayerCore", "🔁 PLAYLIST repeat — rebuilding original queue and restarting")
@@ -292,7 +293,8 @@ extension TrackPlayerCore {
         upNextQueue.removeAll()
         currentTemporaryType = .none
 
-        let allItems = currentTracks.compactMap { createGaplessPlayerItem(for: $0, isPreload: false) }
+        let windowed = currentTracks.prefix(1 + Constants.queueWindowSize)
+        let allItems = windowed.compactMap { createGaplessPlayerItem(for: $0, isPreload: false) }
         var lastItem: AVPlayerItem? = nil
         for item in allItems {
           player.insert(item, after: lastItem)
@@ -399,14 +401,47 @@ extension TrackPlayerCore {
       setupBoundaryTimeObserver()
     }
 
+    // Top up the windowed AVQueuePlayer — the item we just consumed freed a slot.
+    // Only when it is actually short: rebuildAVQueueFromCurrentPosition can fall into
+    // rebuildQueueFromPlaylistIndex (current track no longer in the playlist), which
+    // replaces the current item and re-enters this callback. The length check makes any
+    // such re-entry a no-op and terminate.
+    if player.items().count - 1 < Constants.queueWindowSize {
+      rebuildAVQueueFromCurrentPosition()
+    }
+
     // Preload upcoming tracks for gapless playback
     preloadUpcomingTracks(from: currentTrackIndex + 1)
     cleanupPreloadedAssets(keepingFrom: currentTrackIndex)
   }
 
+  /// Attaches an `AVPlayerItemMetadataOutput` to the current item so ICY/ID3
+  /// metadata emitted mid-stream reaches JS. Detaches from the previous item first —
+  /// an output may only be attached to one item at a time.
+  func attachMetadataOutput(to item: AVPlayerItem) {
+    detachMetadataOutput()
+    let output = AVPlayerItemMetadataOutput(identifiers: nil)
+    output.setDelegate(self, queue: playerQueue)
+    item.add(output)
+    metadataOutput = output
+    metadataOutputItem = item
+  }
+
+  /// Clears the metadata output so a detached one can no longer pass the identity
+  /// check in the delegate and emit metadata for an item that is no longer playing.
+  func detachMetadataOutput() {
+    if let output = metadataOutput, let item = metadataOutputItem {
+      item.remove(output)
+    }
+    metadataOutput = nil
+    metadataOutputItem = nil
+  }
+
   func setupCurrentItemObservers(item: AVPlayerItem) {
     NitroPlayerLogger.log("TrackPlayerCore", "📱 Setting up item observers")
 
+    attachMetadataOutput(to: item)
+
     let statusObserver = item.observe(\.status, options: [.new]) { [weak self] item, _ in
       self?.playerQueue.async {
         if item.status == .readyToPlay {
@@ -421,11 +456,12 @@ extension TrackPlayerCore {
           self?.player?.automaticallyWaitsToMinimizeStalling = false
           // Update now playing info now that duration is available (capture on playerQueue first)
           let state = self?.getStateInternal()
-          let queue = self?.getActualQueueInternal() ?? []
+          let metrics = self?.actualQueueMetrics() ?? (count: 0, position: -1)
           let track = self?.getCurrentTrack()
           DispatchQueue.main.async {
             if let track = track, let state = state {
-              self?.mediaSessionManager?.updateFromPlayerQueue(track: track, state: state, queue: queue)
+              self?.mediaSessionManager?.updateFromPlayerQueue(
+                track: track, state: state, queueCount: metrics.count, positionInQueue: metrics.position)
             }
           }
         } else if item.status == .failed {
@@ -438,9 +474,13 @@ extension TrackPlayerCore {
     currentItemObservers.append(statusObserver)
 
     let bufferEmptyObserver = item.observe(\.isPlaybackBufferEmpty, options: [.new]) { [weak self] item, _ in
-      if item.isPlaybackBufferEmpty {
+      guard item.isPlaybackBufferEmpty else { return }
+      // KVO fires on an arbitrary thread — emitStateChange reads playerQueue-owned
+      // state (currentTracks, temp queues, isRecoveringFromStall), so hop first.
+      self?.playerQueue.async {
+        guard let self, self.player?.currentItem === item else { return }
         NitroPlayerLogger.log("TrackPlayerCore", "⏸️ Buffer empty (buffering)")
-        self?.emitStateChange()
+        self.emitStateChange()
       }
     }
     currentItemObservers.append(bufferEmptyObserver)
@@ -466,6 +506,31 @@ extension TrackPlayerCore {
     currentItemObservers.append(bufferKeepUpObserver)
   }
 
+  func handleTimedMetadataGroups(_ groups: [AVTimedMetadataGroup]) {
+    var title: String?
+    var artist: String?
+    var album: String?
+
+    for group in groups {
+      for item in group.items {
+        guard let value = item.stringValue, !value.isEmpty else { continue }
+        switch item.commonKey {
+        case .some(.commonKeyTitle): title = value
+        case .some(.commonKeyArtist): artist = value
+        case .some(.commonKeyAlbumName): album = value
+        default:
+          // ICY/Shoutcast streams carry no common keys — match on the identifier
+          if item.identifier == .icyMetadataStreamTitle { title = value }
+        }
+      }
+    }
+
+    guard title != nil || artist != nil || album != nil else { return }
+    NitroPlayerLogger.log("TrackPlayerCore", "🏷️ Timed metadata - \(title ?? "-") / \(artist ?? "-")")
+    // artworkUrl is Android-only: iOS delivers embedded art as raw data, not a URL
+    notifyTimedMetadata(TimedMetadata(title: title, artist: artist, album: album, artworkUrl: nil))
+  }
+
   func emitStateChange(reason: Reason? = nil) {
     guard let player else { return }
     let state: TrackPlayerState
@@ -486,3 +551,17 @@ extension TrackPlayerCore {
     notifyPlaybackStateChange(state, reason)
   }
 }
+
+extension TrackPlayerCore: AVPlayerItemMetadataOutputPushDelegate {
+  // Delivered on playerQueue (set in attachMetadataOutput)
+  func metadataOutput(
+    _ output: AVPlayerItemMetadataOutput,
+    didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup],
+    from track: AVPlayerItemTrack?
+  ) {
+    // A detached output can still flush metadata it had already buffered — ignore it,
+    // it belongs to an item that is no longer current.
+    guard output === metadataOutput else { return }
+    handleTimedMetadataGroups(groups)
+  }
+}

package/ios/core/TrackPlayerNotify.swift

@@ -13,22 +13,24 @@ extension TrackPlayerCore {
   // Called on playerQueue — invoke listeners directly (Nitro handles JS thread hop)
   func notifyTrackChange(_ track: TrackItem, _ reason: Reason?) {
     onChangeTrackListeners.forEach { $0(track, reason) }
-    // Capture state + queue now (on playerQueue), pass pre-computed values to main
+    // Capture state + queue metrics now (on playerQueue), pass pre-computed values to main.
+    // Metrics, not the queue itself — the media session only needs count and position.
     let state = getStateInternal()
-    let queue = getActualQueueInternal()
+    let metrics = actualQueueMetrics()
     DispatchQueue.main.async { [weak self] in
-      self?.mediaSessionManager?.updateFromPlayerQueue(track: track, state: state, queue: queue)
+      self?.mediaSessionManager?.updateFromPlayerQueue(
+        track: track, state: state, queueCount: metrics.count, positionInQueue: metrics.position)
     }
   }
 
   func notifyPlaybackStateChange(_ state: TrackPlayerState, _ reason: Reason?) {
     onPlaybackStateChangeListeners.forEach { $0(state, reason) }
+    guard let track = getCurrentTrack() else { return }
     let playerState = getStateInternal()
-    let queue = getActualQueueInternal()
-    let track = getCurrentTrack()
+    let metrics = actualQueueMetrics()
     DispatchQueue.main.async { [weak self] in
-      guard let track = track else { return }
-      self?.mediaSessionManager?.updateFromPlayerQueue(track: track, state: playerState, queue: queue)
+      self?.mediaSessionManager?.updateFromPlayerQueue(
+        track: track, state: playerState, queueCount: metrics.count, positionInQueue: metrics.position)
     }
   }
 
@@ -44,6 +46,10 @@ extension TrackPlayerCore {
     onTracksNeedUpdateListeners.forEach { $0(tracks, lookahead) }
   }
 
+  func notifyTimedMetadata(_ metadata: TimedMetadata) {
+    onTimedMetadataListeners.forEach { $0(metadata) }
+  }
+
   func notifyTemporaryQueueChange() {
     let pn = playNextStack
     let un = upNextQueue

package/ios/core/TrackPlayerPlayback.swift

@@ -11,78 +11,98 @@ import MediaPlayer
 
 extension TrackPlayerCore {
 
-  func play() async {
+  // MARK: - Public commands
+  //
+  // Each command has a `…OnQueue` form that MUST run on `playerQueue` and an `async`
+  // shim for callers that are not already there (media-session remote commands).
+  // HybridTrackPlayer dispatches the `…OnQueue` form directly from the JS thread so
+  // the serial queue's FIFO order equals the JS call order — see HybridTrackPlayer.
+  //
+  // Reading `isCasting` inside the queue block (not before it) keeps every cast-vs-local
+  // decision on the thread that owns that flag.
+
+  func playOnQueue() {
     if isCasting {
       intendedToPlay = true
       castManager?.play()
       return
     }
-    await withPlayerQueueNoThrow { self.playInternal() }
+    playInternal()
   }
+  func play() async { await withPlayerQueueNoThrow { self.playOnQueue() } }
 
-  func pause() async {
+  func pauseOnQueue() {
     if isCasting {
       intendedToPlay = false
       castManager?.pause()
       return
     }
-    await withPlayerQueueNoThrow { self.pauseInternal() }
+    pauseInternal()
   }
+  func pause() async { await withPlayerQueueNoThrow { self.pauseOnQueue() } }
 
-  func seek(position: Double) async {
+  func seekOnQueue(position: Double) {
     if isCasting {
       castManager?.seek(to: position)
       return
     }
-    await withPlayerQueueNoThrow { self.seekInternal(position: position) }
+    seekInternal(position: position)
+  }
+  func seek(position: Double) async {
+    await withPlayerQueueNoThrow { self.seekOnQueue(position: position) }
   }
 
-  func skipToNext() async {
+  func skipToNextOnQueue() {
     if isCasting {
       castManager?.skipToNext()
       return
     }
-    await withPlayerQueueNoThrow { self.skipToNextInternal() }
+    skipToNextInternal()
   }
+  func skipToNext() async { await withPlayerQueueNoThrow { self.skipToNextOnQueue() } }
 
-  func skipToPrevious() async {
+  func skipToPreviousOnQueue() {
     if isCasting {
       // The receiver queue starts at the current track, so queuePreviousItem has nothing behind it — use core state instead.
-      await withPlayerQueueNoThrow { self.skipToPreviousCastInternal() }
+      skipToPreviousCastInternal()
       return
     }
-    await withPlayerQueueNoThrow { self.skipToPreviousInternal() }
+    skipToPreviousInternal()
   }
+  func skipToPrevious() async { await withPlayerQueueNoThrow { self.skipToPreviousOnQueue() } }
 
+  func setRepeatModeOnQueue(mode: RepeatMode) {
+    currentRepeatMode = mode
+    player?.actionAtItemEnd = (mode == .track) ? .none : .advance
+    if isCasting { castManager?.setQueueRepeatMode(mode) }
+    NitroPlayerLogger.log("TrackPlayerCore", "🔁 setRepeatMode: \(mode)")
+  }
   func setRepeatMode(mode: RepeatMode) async {
-    await withPlayerQueueNoThrow {
-      self.currentRepeatMode = mode
-      self.player?.actionAtItemEnd = (mode == .track) ? .none : .advance
-      if self.isCasting { self.castManager?.setQueueRepeatMode(mode) }
-      NitroPlayerLogger.log("TrackPlayerCore", "🔁 setRepeatMode: \(mode)")
-    }
+    await withPlayerQueueNoThrow { self.setRepeatModeOnQueue(mode: mode) }
   }
 
-  func setVolume(volume: Double) async {
+  func setVolumeOnQueue(volume: Double) {
+    let clamped = max(0.0, min(100.0, volume))
     if isCasting {
-      let clamped = max(0.0, min(100.0, volume))
       castManager?.setVolume(Float(clamped / 100.0))
       return
     }
-    await withPlayerQueueNoThrow {
-      let clamped = max(0.0, min(100.0, volume))
-      let normalized = Float(clamped / 100.0)
-      self.player?.volume = normalized
-      NitroPlayerLogger.log("TrackPlayerCore", "🔊 Volume set to \(Int(clamped))% (normalized: \(normalized))")
-    }
+    let normalized = Float(clamped / 100.0)
+    player?.volume = normalized
+    NitroPlayerLogger.log(
+      "TrackPlayerCore", "🔊 Volume set to \(Int(clamped))% (normalized: \(normalized))")
+  }
+  func setVolume(volume: Double) async {
+    await withPlayerQueueNoThrow { self.setVolumeOnQueue(volume: volume) }
   }
 
-  func configure(androidAutoEnabled: Bool?, carPlayEnabled: Bool?, showInNotification: Bool?, lookaheadCount: Int?) async {
-    await withPlayerQueueNoThrow {
-      if let la = lookaheadCount {
-        self.lookaheadCount = la
-        NitroPlayerLogger.log("TrackPlayerCore", "🔄 Lookahead count set to: \(la)")
-      }
+  func configureOnQueue(
+    androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
+    showInNotification: Bool?, lookaheadCount: Int?
+  ) {
+    if let la = lookaheadCount {
+      self.lookaheadCount = la
+      NitroPlayerLogger.log("TrackPlayerCore", "🔄 Lookahead count set to: \(la)")
     }
     DispatchQueue.main.async { [weak self] in
       self?.mediaSessionManager?.configure(
@@ -92,21 +112,31 @@ extension TrackPlayerCore {
       )
     }
   }
+  func configure(
+    androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
+    showInNotification: Bool?, lookaheadCount: Int?
+  ) async {
+    await withPlayerQueueNoThrow {
+      self.configureOnQueue(
+        androidAutoEnabled: androidAutoEnabled, carPlayEnabled: carPlayEnabled,
+        showInNotification: showInNotification, lookaheadCount: lookaheadCount)
+    }
+  }
 
-  func setPlaybackSpeed(_ speed: Double) async {
+  func setPlaybackSpeedOnQueue(_ speed: Double) {
+    currentPlaybackSpeed = speed
     if isCasting {
-      currentPlaybackSpeed = speed
       castManager?.setPlaybackRate(Float(speed))
       return
     }
-    await withPlayerQueueNoThrow {
-      self.currentPlaybackSpeed = speed
-      // Only update rate if currently playing; pause keeps rate at 0 until play() is called
-      if let player = self.player, player.rate != 0 {
-        player.rate = Float(speed)
-      }
+    // Only update rate if currently playing; pause keeps rate at 0 until play() is called
+    if let player = self.player, player.rate != 0 {
+      player.rate = Float(speed)
     }
   }
+  func setPlaybackSpeed(_ speed: Double) async {
+    await withPlayerQueueNoThrow { self.setPlaybackSpeedOnQueue(speed) }
+  }
 
   func getPlaybackSpeed() async -> Double {
     await withPlayerQueueNoThrow { self.currentPlaybackSpeed }
@@ -202,6 +232,12 @@ extension TrackPlayerCore {
       }
     }
 
+    // The AVQueuePlayer is windowed, so items().count is not the logical queue length.
+    // Top up first so there is always something to advance to while tracks remain.
+    if hasUpcomingTrack() {
+      if queuePlayer.items().count <= 1 { rebuildAVQueueFromCurrentPosition() }
+    }
+
     if queuePlayer.items().count > 1 {
       queuePlayer.advanceToNextItem()
     } else {