react-native-nitro-player 1.3.0 → 1.4.1-alpha.0

package/android/build.gradle

@@ -140,11 +140,14 @@ dependencies {
   implementation project(":react-native-nitro-modules")
 
   implementation "androidx.media3:media3-exoplayer:$media3_version"
+  implementation "androidx.media3:media3-exoplayer-hls:$media3_version" //for .m3u8
+  implementation "androidx.media3:media3-exoplayer-dash:$media3_version"
+  implementation "androidx.media3:media3-exoplayer-smoothstreaming:$media3_version"
   implementation "androidx.media3:media3-session:$media3_version"
   implementation "androidx.media3:media3-common:$media3_version"
   implementation "androidx.media:media:1.7.0"
-  
-  // WorkManager for background downloads
-  implementation "androidx.work:work-runtime-ktx:2.9.0"
+
+  // WorkManager for background downloads.
+  implementation "androidx.work:work-runtime-ktx:2.10.5" // Latest version of 2.10
 }
 

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerCore.kt

@@ -125,6 +125,7 @@ class TrackPlayerCore private constructor(
 
     // ── Service binding ────────────────────────────────────────────────────
     private var serviceBound = false
+    private var rebindAttempts = 0
 
     private val serviceConnection =
         object : ServiceConnection {
@@ -132,7 +133,35 @@ class TrackPlayerCore private constructor(
                 name: ComponentName?,
                 service: IBinder?,
             ) {
-                val binder = service as NitroPlayerPlaybackService.LocalBinder
+                // Android can redeliver the MediaSessionService binder instead of
+                // our LocalBinder (e.g. after the service is restarted). Guard the
+                // cast and rebind explicitly with ACTION_LOCAL_BIND instead of crashing.
+                val binder = service as? NitroPlayerPlaybackService.LocalBinder
+                if (binder == null) {
+                    NitroPlayerLogger.log("TrackPlayerCore") {
+                        "onServiceConnected received unexpected binder: $service"
+                    }
+                    try {
+                        context.unbindService(this)
+                    } catch (_: Exception) {}
+                    serviceBound = false
+                    if (rebindAttempts < 3) {
+                        rebindAttempts++
+                        handler.post {
+                            val bindIntent =
+                                Intent(context, NitroPlayerPlaybackService::class.java).apply {
+                                    action = NitroPlayerPlaybackService.ACTION_LOCAL_BIND
+                                }
+                            context.bindService(
+                                bindIntent,
+                                this,
+                                Context.BIND_AUTO_CREATE,
+                            )
+                        }
+                    }
+                    return
+                }
+                rebindAttempts = 0
                 playerHandler = binder.handler
                 binder.service.trackPlayerCore = this@TrackPlayerCore
                 serviceBound = true

package/android/src/main/java/com/margelo/nitro/nitroplayer/download/DownloadWorker.kt

@@ -11,7 +11,9 @@ import androidx.work.ForegroundInfo
 import androidx.work.WorkerParameters
 import com.margelo.nitro.nitroplayer.*
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.withContext
+import kotlinx.coroutines.withTimeout
 import java.io.BufferedInputStream
 import java.io.FileOutputStream
 import java.net.HttpURLConnection
@@ -35,6 +37,14 @@ class DownloadWorker(
         private const val NOTIFICATION_CHANNEL_ID = "nitro_player_downloads"
         private const val BASE_NOTIFICATION_ID = 2001
         private const val BUFFER_SIZE = 8192
+
+        /**
+         * Hard upper bound on a single download. Bounds runaway/trickling
+         * downloads so the dataSync foreground service is always released
+         * well within the Android 14+ FGS timeout window — otherwise the
+         * system kills the app with ForegroundServiceDidNotStopInTimeException.
+         */
+        private const val MAX_DOWNLOAD_DURATION_MS = 30L * 60L * 1000L
         private val CONTENT_DISPOSITION_REGEX = Regex("filename=\"?([^\";]+)\"?")
     }
 
@@ -72,8 +82,12 @@ class DownloadWorker(
                     // Download continues in background.
                 }
 
-                // Perform download
-                val localPath = downloadFile(downloadId, trackId, trackTitle, urlString, storageLocation)
+                // Perform download, bounded so the foreground service is
+                // always released within the Android 14+ FGS timeout window.
+                val localPath =
+                    withTimeout(MAX_DOWNLOAD_DURATION_MS) {
+                        downloadFile(downloadId, trackId, trackTitle, urlString, storageLocation)
+                    }
 
                 if (localPath != null) {
                     downloadManager.onComplete(downloadId, trackId, localPath)
@@ -91,6 +105,17 @@ class DownloadWorker(
                     showErrorNotification(trackTitle)
                     Result.retry()
                 }
+            } catch (e: TimeoutCancellationException) {
+                val error =
+                    DownloadError(
+                        code = "DOWNLOAD_TIMEOUT",
+                        message = "Download exceeded maximum allowed duration",
+                        reason = DownloadErrorReason.TIMEOUT,
+                        isRetryable = true,
+                    )
+                downloadManager.onError(downloadId, trackId, error)
+                showErrorNotification(trackTitle)
+                Result.retry()
             } catch (e: Exception) {
                 val errorReason =
                     when {

package/ios/core/TrackPlayerCore.swift

@@ -7,6 +7,7 @@
 import AVFoundation
 import Foundation
 import MediaPlayer
+import Network
 import NitroModules
 import ObjectiveC
 
@@ -25,6 +26,9 @@ class TrackPlayerCore: NSObject {
     static let preferredForwardBufferDuration: Double = 30.0
     static let preloadAssetKeys: [String] = ["playable", "duration", "tracks", "preferredTransform"]
     static let gaplessPreloadCount: Int = 3
+    // Stall & failure recovery
+    static let maxFailedItemRetries: Int = 3
+    static let failedItemRetryDelay: TimeInterval = 2.0
   }
 
   // MARK: - Thread infrastructure
@@ -53,6 +57,32 @@ class TrackPlayerCore: NSObject {
   internal let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
   internal var didRequestUrlsForCurrentItem = false
 
+  // MARK: - Stall & network recovery
+  // Whether the user/app wants playback ongoing (true after play(), false after pause()).
+  internal var intendedToPlay = false
+  // Set when AVPlayer stalls on a buffer underrun; cleared once the buffer refills.
+  // Needed because automaticallyWaitsToMinimizeStalling == false means AVPlayer
+  // will NOT auto-resume after a stall — we must re-issue play() ourselves.
+  internal var isRecoveringFromStall = false
+  // True while an audio-session interruption (phone call, Siri, other app) is active.
+  // Recovery must NOT resume playback during this window even though `intendedToPlay`
+  // may still be true — the system decides whether to resume when the interruption ends.
+  internal var isInterrupted = false
+  // Set right before `recoverFailedItem` swaps the current item in place. Tells the
+  // resulting `currentItemDidChange` that this is an in-place recovery of the SAME
+  // track, not a real track change — so it must not emit onChangeTrack or reset
+  // per-track state. Consumed (cleared) by the next `currentItemDidChange`.
+  internal var suppressTrackChangeEmit = false
+  // Last observed playback position, used to resume after recreating a failed item.
+  internal var lastKnownPosition: Double = 0
+  // Per-track retry budget for recreating AVPlayerItems that hit status == .failed.
+  internal var failedItemRetryCounts: [String: Int] = [:]
+  // Monitors network path changes (VPN toggle, Wi-Fi band switch) to drive recovery.
+  internal var pathMonitor: NWPathMonitor?
+  // Starts unsatisfied so the first genuine `.satisfied` update is treated as a
+  // transition (and so a network that starts down is not mistaken for "up").
+  internal var lastPathStatus: NWPath.Status = .unsatisfied
+
   // MARK: - Temporary queue
   internal var playNextStack: [TrackItem] = []
   internal var upNextQueue: [TrackItem] = []
@@ -182,7 +212,10 @@ class TrackPlayerCore: NSObject {
         p.removeObserver(self, forKeyPath: "currentItem")
       }
       NotificationCenter.default.removeObserver(self)
+      self.pathMonitor?.cancel()
+      self.pathMonitor = nil
       self.preloadedAssets.removeAll()
+      self.failedItemRetryCounts.removeAll()
     }
   }
 

package/ios/core/TrackPlayerListener.swift

@@ -49,6 +49,8 @@ extension TrackPlayerCore {
     }
 
     setupPlayerObservers()
+    setupAudioSessionObservers()
+    startNetworkMonitoring()
   }
 
   func setupPlayerObservers() {
@@ -67,6 +69,8 @@ extension TrackPlayerCore {
       name: .AVPlayerItemNewErrorLogEntry, object: nil)
     NotificationCenter.default.addObserver(self, selector: #selector(playerItemTimeJumped(_:)),
       name: .AVPlayerItemTimeJumped, object: nil)
+    NotificationCenter.default.addObserver(self, selector: #selector(playerItemPlaybackStalled(_:)),
+      name: .AVPlayerItemPlaybackStalled, object: nil)
   }
 
   func setupBoundaryTimeObserver() {
@@ -109,6 +113,9 @@ extension TrackPlayerCore {
     let rawDuration = currentItem.duration.seconds
     let duration = (rawDuration > 0 && !rawDuration.isNaN && !rawDuration.isInfinite) ? rawDuration : 0.0
 
+    // Remember the position so we can resume here if the item has to be recreated.
+    if position.isFinite && position >= 0 { lastKnownPosition = position }
+
     NitroPlayerLogger.log("TrackPlayerCore", "⏱️ Boundary crossed - position: \(Int(position))s / duration: \(duration)s")
 
     notifyPlaybackProgress(position, duration, isManuallySeeked ? true : nil)
@@ -222,6 +229,37 @@ extension TrackPlayerCore {
     }
   }
 
+  /// Fires when playback stalls because media did not arrive in time (buffer underrun).
+  /// AVQueuePlayer runs with `automaticallyWaitsToMinimizeStalling = false` during playback
+  /// (see `setupCurrentItemObservers`) so it will NOT resume on its own — we mark a recovery
+  /// flag and re-issue play() once `isPlaybackLikelyToKeepUp` flips back to true.
+  @objc func playerItemPlaybackStalled(_ notification: Notification) {
+    playerQueue.async { [weak self] in
+      guard let self, let player = self.player, let currentItem = player.currentItem else { return }
+      guard (notification.object as? AVPlayerItem) === currentItem else { return }
+      // A stall only matters if we actually want playback ongoing. If the user has
+      // paused (or a stall notification is racing a pause), do NOT arm the recovery
+      // flag — the `isPlaybackLikelyToKeepUp` observer fires only on change, so a flag
+      // set here while paused could never be cleared and would wedge state on .buffering.
+      guard self.intendedToPlay else { return }
+      self.isRecoveringFromStall = true
+      // The buffer may have already refilled before this notification was
+      // processed. `isPlaybackLikelyToKeepUp` fires only on change, so its
+      // observer would not fire again — resume here instead of waiting forever.
+      if currentItem.isPlaybackLikelyToKeepUp,
+        self.intendedToPlay, player.timeControlStatus != .playing {
+        NitroPlayerLogger.log("TrackPlayerCore",
+          "⚠️ Playback stalled but buffer already refilled — resuming now")
+        self.isRecoveringFromStall = false
+        player.playImmediately(atRate: Float(self.currentPlaybackSpeed))
+      } else {
+        NitroPlayerLogger.log("TrackPlayerCore",
+          "⚠️ Playback stalled (buffer underrun) — will auto-resume once the buffer refills")
+      }
+      self.emitStateChange()
+    }
+  }
+
   func currentItemDidChange() {
     // Clear old item observers
     currentItemObservers.removeAll()
@@ -229,6 +267,22 @@ extension TrackPlayerCore {
     // Reset proactive URL check debounce for the new track
     didRequestUrlsForCurrentItem = false
 
+    // A recovery replace (recoverFailedItem) swaps the current item in place for the
+    // SAME track. It must not look like a track change: don't emit onChangeTrack and
+    // don't reset per-track state that recovery still depends on.
+    let isRecoveryReplace = suppressTrackChangeEmit
+    suppressTrackChangeEmit = false
+
+    if !isRecoveryReplace {
+      // Genuine new track — reset per-track state.
+      // Resume position is per-track; recovery captured what it needs before the swap.
+      lastKnownPosition = 0
+      // A new track is not a stall recovery — drop any stale flag from the old item.
+      isRecoveringFromStall = false
+      // Fresh failure-retry budget for the new track.
+      failedItemRetryCounts.removeAll()
+    }
+
     guard let player, let currentItem = player.currentItem else {
       NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Current item changed to nil")
       // Queue exhausted — handle PLAYLIST repeat
@@ -304,9 +358,14 @@ extension TrackPlayerCore {
         if currentTemporaryType == .playNext { tempTrack = playNextStack.first(where: { $0.id == trackId }) }
         else if currentTemporaryType == .upNext { tempTrack = upNextQueue.first(where: { $0.id == trackId }) }
         if let track = tempTrack {
-          NitroPlayerLogger.log("TrackPlayerCore", "   🎵 Temporary track: \(track.title) - \(track.artist)")
-          NitroPlayerLogger.log("TrackPlayerCore", "   📢 Emitting onChangeTrack for temporary track")
-          notifyTrackChange(track, .skip)
+          if isRecoveryReplace {
+            NitroPlayerLogger.log("TrackPlayerCore",
+              "   ♻️ Recovery replace of temporary track '\(track.title)' — suppressing onChangeTrack")
+          } else {
+            NitroPlayerLogger.log("TrackPlayerCore", "   🎵 Temporary track: \(track.title) - \(track.artist)")
+            NitroPlayerLogger.log("TrackPlayerCore", "   📢 Emitting onChangeTrack for temporary track")
+            notifyTrackChange(track, .skip)
+          }
         }
       } else if let index = currentTracks.firstIndex(where: { $0.id == trackId }) {
         NitroPlayerLogger.log("TrackPlayerCore", "   ✅ Found track at index: \(index)")
@@ -352,6 +411,11 @@ extension TrackPlayerCore {
       self?.playerQueue.async {
         if item.status == .readyToPlay {
           NitroPlayerLogger.log("TrackPlayerCore", "✅ Item ready, setting up boundaries")
+          // Note: the failure-retry budget is intentionally NOT cleared here. Reaching
+          // .readyToPlay momentarily must not refund retries — otherwise an item that
+          // flaps ready↔failed would bypass `maxFailedItemRetries`. The budget is reset
+          // only on a genuine track change (currentItemDidChange) or a real network
+          // restore (handleNetworkRestored).
           self?.setupBoundaryTimeObserver()
           // First item is buffered and ready — disable stall waiting for gapless inter-track transitions
           self?.player?.automaticallyWaitsToMinimizeStalling = false
@@ -365,8 +429,9 @@ extension TrackPlayerCore {
             }
           }
         } else if item.status == .failed {
-          NitroPlayerLogger.log("TrackPlayerCore", "❌ Item failed")
-          self?.notifyPlaybackStateChange(.stopped, .error)
+          NitroPlayerLogger.log("TrackPlayerCore",
+            "❌ Item failed — \(item.error?.localizedDescription ?? "unknown error")")
+          self?.recoverFailedItem(item)
         }
       }
     }
@@ -381,9 +446,21 @@ extension TrackPlayerCore {
     currentItemObservers.append(bufferEmptyObserver)
 
     let bufferKeepUpObserver = item.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
-      if item.isPlaybackLikelyToKeepUp {
+      guard item.isPlaybackLikelyToKeepUp else { return }
+      self?.playerQueue.async {
+        guard let self, let player = self.player else { return }
+        guard player.currentItem === item else { return }
         NitroPlayerLogger.log("TrackPlayerCore", "▶️ Buffer likely to keep up")
-        self?.emitStateChange()
+        // Recover from a stall: AVPlayer will NOT auto-resume because
+        // automaticallyWaitsToMinimizeStalling is false — re-issue play() ourselves.
+        if self.isRecoveringFromStall {
+          self.isRecoveringFromStall = false
+          if self.intendedToPlay && player.timeControlStatus != .playing {
+            NitroPlayerLogger.log("TrackPlayerCore", "🔁 Buffer refilled — resuming playback after stall")
+            player.playImmediately(atRate: Float(self.currentPlaybackSpeed))
+          }
+        }
+        self.emitStateChange()
       }
     }
     currentItemObservers.append(bufferKeepUpObserver)
@@ -396,6 +473,10 @@ extension TrackPlayerCore {
       state = .playing
     } else if player.timeControlStatus == .waitingToPlayAtSpecifiedRate {
       state = .buffering
+    } else if isRecoveringFromStall {
+      // Stalled with automaticallyWaitsToMinimizeStalling == false: timeControlStatus
+      // reads .paused, but we are buffering, not user-paused — report it as such.
+      state = .buffering
     } else if player.rate == 0 {
       state = .paused
     } else {

package/ios/core/TrackPlayerPlayback.swift

@@ -86,6 +86,11 @@ extension TrackPlayerCore {
 
   func playInternal() {
     NitroPlayerLogger.log("TrackPlayerCore", "▶️ play() called")
+    self.intendedToPlay = true
+    // An explicit play() is the ground truth for intent — clear any stale
+    // interruption flag so a missed AVAudioSession `.ended` can't permanently
+    // wedge recovery off.
+    self.isInterrupted = false
     if let player = self.player {
       NitroPlayerLogger.log("TrackPlayerCore", "▶️ Player status: \(player.status.rawValue)")
       if let currentItem = player.currentItem {
@@ -105,6 +110,9 @@ extension TrackPlayerCore {
 
   func pauseInternal() {
     NitroPlayerLogger.log("TrackPlayerCore", "⏸️ pause() called")
+    // User-initiated pause — cancel any pending stall auto-resume.
+    self.intendedToPlay = false
+    self.isRecoveringFromStall = false
     self.player?.pause()
     playerQueue.asyncAfter(deadline: .now() + Constants.stateChangeDelay) { [weak self] in
       self?.emitStateChange()
@@ -164,6 +172,8 @@ extension TrackPlayerCore {
       queuePlayer.advanceToNextItem()
     } else {
       queuePlayer.pause()
+      self.intendedToPlay = false
+      self.isRecoveringFromStall = false
       self.notifyPlaybackStateChange(.stopped, .end)
     }
 

package/ios/core/TrackPlayerRecovery.swift

@@ -0,0 +1,220 @@
+//
+//  TrackPlayerRecovery.swift
+//  NitroPlayer
+//
+//  Created by Ritesh Shukla on 22/05/26.
+//
+
+import AVFoundation
+import Foundation
+import Network
+
+extension TrackPlayerCore {
+
+  // MARK: - Failed-item recovery
+
+  /// Recreates a current AVPlayerItem that reached `status == .failed`.
+  /// A failed item cannot be revived, so we build a fresh one from the same
+  /// track URL, seek back to the last known position and resume if intended.
+  /// Must be called on `playerQueue`.
+  func recoverFailedItem(_ item: AVPlayerItem) {
+    guard let player else { return }
+    guard player.currentItem === item else {
+      NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Failed item is not the current item — ignoring")
+      return
+    }
+    guard let trackId = item.trackId, let track = findTrackById(trackId) else {
+      NitroPlayerLogger.log("TrackPlayerCore", "❌ Failed item has no recoverable track — stopping")
+      isRecoveringFromStall = false
+      // Nothing left to recover — playback is not happening; drop the intent so a
+      // later network restore doesn't try to resume a track we can't rebuild.
+      intendedToPlay = false
+      notifyPlaybackStateChange(.stopped, .error)
+      return
+    }
+
+    let attempts = (failedItemRetryCounts[trackId] ?? 0) + 1
+    guard attempts <= Constants.maxFailedItemRetries else {
+      NitroPlayerLogger.log("TrackPlayerCore",
+        "❌ '\(track.title)' failed \(attempts - 1)x — giving up")
+      failedItemRetryCounts.removeValue(forKey: trackId)
+      isRecoveringFromStall = false
+      // Don't silently resurrect a track the user already saw fail: clear the play
+      // intent so a later network-restore path doesn't auto-resume it.
+      intendedToPlay = false
+      notifyPlaybackStateChange(.stopped, .error)
+      return
+    }
+    failedItemRetryCounts[trackId] = attempts
+
+    // Resume from the furthest-known position: the failed item's own playhead is
+    // usually more current than the last periodic boundary-observer tick.
+    let itemTime = item.currentTime().seconds
+    let resumePosition = (itemTime.isFinite && itemTime > lastKnownPosition) ? itemTime : lastKnownPosition
+    // Keep lastKnownPosition aligned so a re-failure during recovery resumes here too.
+    lastKnownPosition = resumePosition
+
+    NitroPlayerLogger.log("TrackPlayerCore",
+      "🔁 Recreating failed item '\(track.title)' "
+        + "(attempt \(attempts)/\(Constants.maxFailedItemRetries), resume @ \(Int(resumePosition))s)")
+
+    // The failure may be a stale/expired streaming URL. Ask the JS layer for a fresh
+    // one; if it arrives before the retry fires, updateTracks replaces the item
+    // directly and the retry below aborts on the currentItem identity check.
+    notifyTracksNeedUpdate(tracks: [track], lookahead: lookaheadCount)
+
+    // A preloaded asset for this track shares the same dead connection state.
+    preloadedAssets.removeValue(forKey: trackId)
+    // Surface a buffering state while the retry is pending.
+    isRecoveringFromStall = true
+    emitStateChange()
+
+    playerQueue.asyncAfter(deadline: .now() + Constants.failedItemRetryDelay) { [weak self] in
+      guard let self, let player = self.player else { return }
+      // Bail if the user moved to a different track — or updateTracks already
+      // swapped in a fresh-URL item — while we waited.
+      guard player.currentItem === item else {
+        NitroPlayerLogger.log("TrackPlayerCore", "⏭️ Current item changed before retry — aborting recovery")
+        return
+      }
+      // Re-resolve the track so we pick up any URL refreshed during the wait.
+      guard let track = self.findTrackById(trackId),
+        let newItem = self.createGaplessPlayerItem(for: track, isPreload: false)
+      else {
+        NitroPlayerLogger.log("TrackPlayerCore", "❌ Could not rebuild item for track '\(trackId)'")
+        self.isRecoveringFromStall = false
+        self.intendedToPlay = false
+        self.notifyPlaybackStateChange(.stopped, .error)
+        return
+      }
+      // Mark the imminent currentItem change as an in-place recovery so the
+      // resulting currentItemDidChange does not emit a spurious onChangeTrack
+      // or reset per-track state (resume position, retry budget).
+      self.suppressTrackChangeEmit = true
+      player.replaceCurrentItem(with: newItem)
+
+      if resumePosition > 1 {
+        let time = CMTime(seconds: resumePosition, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+        player.seek(to: time)
+      }
+      if self.intendedToPlay {
+        player.playImmediately(atRate: Float(self.currentPlaybackSpeed))
+      }
+    }
+  }
+
+  // MARK: - Network path monitoring
+
+  /// Starts watching the network path. VPN toggles and Wi-Fi band switches
+  /// produce a path update we use to recover a player left stuck by the change.
+  func startNetworkMonitoring() {
+    guard pathMonitor == nil else { return }
+    let monitor = NWPathMonitor()
+    monitor.pathUpdateHandler = { [weak self] path in
+      // Handler is delivered on `playerQueue` (passed to start(queue:)).
+      guard let self else { return }
+      let previous = self.lastPathStatus
+      self.lastPathStatus = path.status
+      NitroPlayerLogger.log("TrackPlayerCore",
+        "🌐 Network path update — status: \(path.status) (was: \(previous))")
+      // React only to a real down→up transition. A satisfied→satisfied update
+      // (e.g. Wi-Fi↔cellular handoff) is not an outage recovery.
+      if previous != .satisfied && path.status == .satisfied {
+        self.handleNetworkRestored()
+      }
+    }
+    monitor.start(queue: playerQueue)
+    pathMonitor = monitor
+    NitroPlayerLogger.log("TrackPlayerCore", "🌐 Network monitoring started")
+  }
+
+  /// Called on `playerQueue` on a genuine down→up network transition.
+  /// Heavily guarded so it is a no-op during healthy playback and never fights an
+  /// intentional pause (user pause, audio-session interruption, route loss).
+  func handleNetworkRestored() {
+    // `intendedToPlay` alone is not enough: an audio interruption pauses playback
+    // while leaving the intent set. Never resume into an active interruption.
+    guard intendedToPlay, !isInterrupted, let player, let currentItem = player.currentItem else { return }
+
+    // The connection died completely — the item is dead, recreate it.
+    if currentItem.status == .failed {
+      NitroPlayerLogger.log("TrackPlayerCore", "🌐 Network restored — recreating failed item")
+      // A genuine outage→restore earns the current track one fresh retry budget
+      // (only this track's count — not a blanket reset, which would let a flapping
+      // network defeat `maxFailedItemRetries`).
+      if let tid = currentItem.trackId { failedItemRetryCounts.removeValue(forKey: tid) }
+      recoverFailedItem(currentItem)
+      return
+    }
+
+    // The item survived but playback stalled — nudge it back to life.
+    if player.timeControlStatus != .playing {
+      NitroPlayerLogger.log("TrackPlayerCore", "🌐 Network restored — resuming stalled playback")
+      isRecoveringFromStall = true
+      player.playImmediately(atRate: Float(currentPlaybackSpeed))
+    }
+  }
+
+  // MARK: - Audio session handling
+
+  func setupAudioSessionObservers() {
+    let nc = NotificationCenter.default
+    nc.addObserver(self, selector: #selector(handleAudioSessionInterruption(_:)),
+      name: AVAudioSession.interruptionNotification, object: nil)
+    nc.addObserver(self, selector: #selector(handleAudioRouteChange(_:)),
+      name: AVAudioSession.routeChangeNotification, object: nil)
+  }
+
+  /// Phone calls, Siri, other apps, etc. interrupt the audio session. When the
+  /// interruption ends the session may be inactive — reactivate it and resume.
+  @objc func handleAudioSessionInterruption(_ notification: Notification) {
+    guard let info = notification.userInfo,
+      let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
+      let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { return }
+
+    switch type {
+    case .began:
+      NitroPlayerLogger.log("TrackPlayerCore", "🔇 Audio session interruption began")
+      // The system has paused playback. Flag the interruption so network/stall
+      // recovery does not fight it by resuming mid-interruption.
+      playerQueue.async { [weak self] in self?.isInterrupted = true }
+    case .ended:
+      let options: AVAudioSession.InterruptionOptions =
+        (info[AVAudioSessionInterruptionOptionKey] as? UInt).map { .init(rawValue: $0) } ?? []
+      let shouldResume = options.contains(.shouldResume)
+      NitroPlayerLogger.log("TrackPlayerCore",
+        "🔊 Audio session interruption ended (shouldResume: \(shouldResume))")
+      playerQueue.async { [weak self] in
+        guard let self else { return }
+        self.isInterrupted = false
+        do {
+          try AVAudioSession.sharedInstance().setActive(true)
+        } catch {
+          NitroPlayerLogger.log("TrackPlayerCore", "❌ Failed to reactivate audio session — \(error)")
+        }
+        if shouldResume && self.intendedToPlay {
+          self.player?.playImmediately(atRate: Float(self.currentPlaybackSpeed))
+        } else if !shouldResume {
+          // System says do not resume — treat playback as no longer intended so
+          // recovery won't silently restart it. The user must press play again.
+          self.intendedToPlay = false
+        }
+      }
+    @unknown default:
+      break
+    }
+  }
+
+  /// Pauses when the current output device disappears (e.g. headphones unplugged),
+  /// matching standard iOS playback behaviour.
+  @objc func handleAudioRouteChange(_ notification: Notification) {
+    guard let info = notification.userInfo,
+      let reasonValue = info[AVAudioSessionRouteChangeReasonKey] as? UInt,
+      let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else { return }
+
+    NitroPlayerLogger.log("TrackPlayerCore", "🎧 Audio route changed — reason: \(reason.rawValue)")
+    if reason == .oldDeviceUnavailable {
+      playerQueue.async { [weak self] in self?.pauseInternal() }
+    }
+  }
+}

package/ios/core/TrackPlayerTempQueue.swift

@@ -174,6 +174,10 @@ extension TrackPlayerCore {
 
   func findTrackById(_ trackId: String) -> TrackItem? {
     if let t = currentTracks.first(where: { $0.id == trackId }) { return t }
+    // Temporary-queue tracks need not exist in any playlist — search the temp
+    // stacks too so a failed playNext/upNext track is still recoverable.
+    if let t = playNextStack.first(where: { $0.id == trackId }) { return t }
+    if let t = upNextQueue.first(where: { $0.id == trackId }) { return t }
     for playlist in playlistManager.getAllPlaylists() {
       if let t = playlist.tracks.first(where: { $0.id == trackId }) { return t }
     }

package/ios/core/TrackPlayerUrlLoader.swift

@@ -37,17 +37,22 @@ extension TrackPlayerCore {
     let currentTrackIsEmpty = currentTrack.map {
       $0.url.isEmpty && !DownloadManagerCore.shared.isTrackDownloaded(trackId: $0.id)
     } ?? false
+    // The current track's player item has failed (e.g. an expired streaming URL).
+    // Unlike a healthy current track, a failed one MUST accept a fresh URL so that
+    // recoverFailedItem can rebuild it from updated track data.
+    let currentItemFailed = self.player?.currentItem?.status == .failed
+      && self.player?.currentItem?.trackId == currentTrackId
 
     let safeTracks = tracks.filter { track in
       switch true {
-      case track.id == currentTrackId && !currentTrackIsEmpty:
+      case track.id == currentTrackId && (currentTrackIsEmpty || currentItemFailed):
+        NitroPlayerLogger.log("TrackPlayerCore",
+          "🔄 Updating current track (\(currentItemFailed ? "failed item" : "no URL")): \(track.id)")
+        return !track.url.isEmpty
+      case track.id == currentTrackId:
         NitroPlayerLogger.log("TrackPlayerCore",
           "⚠️ Skipping update for currently playing track: \(track.id) (preserves gapless)")
         return false
-      case track.id == currentTrackId && currentTrackIsEmpty:
-        NitroPlayerLogger.log("TrackPlayerCore",
-          "🔄 Updating current track with no URL: \(track.id)")
-        return !track.url.isEmpty
       case track.url.isEmpty:
         NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Skipping track with empty URL: \(track.id)")
         return false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "1.3.0",
+  "version": "1.4.1-alpha.0",
   "description": "A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay",
   "main": "lib/index",
   "module": "lib/index",