react-native-nitro-player 1.5.0-alpha.1 → 1.5.0

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

@@ -80,6 +80,8 @@ class ExoPlayerCore(
         }
     val currentMediaItem: MediaItem? get() = player.currentMediaItem
     val currentMediaItemIndex: Int get() = player.currentMediaItemIndex
+
+    fun getMediaItemAt(index: Int): MediaItem = player.getMediaItemAt(index)
     val currentPosition: Long get() = player.currentPosition
     val duration: Long get() = player.duration
     val mediaItemCount: Int get() = player.mediaItemCount

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

@@ -3,9 +3,9 @@
 package com.margelo.nitro.nitroplayer.core
 
 import android.app.Activity
-import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
 import com.margelo.nitro.nitroplayer.CastState
+import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.media.NitroCastConfig
 
 /**
@@ -21,35 +21,91 @@ import com.margelo.nitro.nitroplayer.media.NitroCastConfig
  */
 
 // ── Backend switching ──────────────────────────────────────────────────────
+// The queue is rebuilt for the target backend (not item-copied): cast needs remote URLs, local prefers download paths.
 
 internal fun TrackPlayerCore.switchToCastPlayer() {
     val controller = castSessionController ?: return
-    switchToPlayer(controller.castPlayer)
-    isCastingField = true
+    if (!isExoInitialized) return
+    val local = exo.player
+    if (local === controller.castPlayer) return
+
+    // Capture context BEFORE swapping — the queue helpers read `exo`, and the cast timeline is still empty.
+    val currentId = local.currentMediaItem?.mediaId?.let { extractTrackId(it) }
+    val currentTrack = getCurrentTrack() ?: currentTracks.getOrNull(currentTrackIndex)
+    val upcoming = buildUpcomingQueueTracks(currentId)
+    val positionMs = local.currentPosition.coerceAtLeast(0L)
+    val wasPlaying = local.playWhenReady
+    val repeat = local.repeatMode
+
+    playerListener?.let { local.removeListener(it) }
+    local.playWhenReady = false // silence local output — audio now comes from the device
+
+    isCastingField = true // before building items so makeMediaItem picks remote URLs
+    exo = ExoPlayerCore(controller.castPlayer)
+    playerListener?.let { controller.castPlayer.addListener(it) }
+    setMediaSessionPlayer(controller.castPlayer)
+
+    val castList = ArrayList<TrackItem>()
+    currentTrack?.let { castList.add(it) }
+    castList.addAll(upcoming)
+    val playable = castableUpcoming(castList)
+
+    if (playable.isNotEmpty()) {
+        lastCastWaitTrackId = null
+        val items = playable.map { makeMediaItem(it, mediaIdFor(it)) }
+        // Resume mid-track only when the receiver starts on the locally playing track.
+        val resumeFromCurrent = currentTrack != null && playable.first().id == currentTrack.id
+        controller.castPlayer.setMediaItems(items, 0, if (resumeFromCurrent) positionMs else 0L)
+        controller.castPlayer.repeatMode = repeat
+        controller.castPlayer.playWhenReady = wasPlaying
+        controller.castPlayer.prepare()
+    } else {
+        // Nothing castable yet (lazy queue) — request URLs; updateTracks will load.
+        checkUpcomingTracksForUrls(lookaheadCount)
+    }
+
     notifyCastStateChange(CastState.CONNECTED, controller.currentDeviceName())
 }
 
 internal fun TrackPlayerCore.switchToLocalPlayer() {
     val controller = castSessionController ?: return
-    switchToPlayer(controller.localPlayer)
-    isCastingField = false
-    notifyCastStateChange(controller.getCastState(), controller.currentDeviceName())
-}
-
-private fun TrackPlayerCore.switchToPlayer(target: Player) {
     if (!isExoInitialized) return
-    val current = exo.player
-    if (current === target) return
-
-    // Move listener, queue and position from the current player to the target,
-    // then make the target authoritative for the MediaSession & notification.
-    playerListener?.let { current.removeListener(it) }
-    transferPlaybackState(current, target)
-    current.playWhenReady = false // silence the player we're leaving
+    val cast = exo.player
+    if (cast === controller.localPlayer) return
+
+    // Capture context before swapping (the cast timeline empties once the session ends).
+    val currentId = cast.currentMediaItem?.mediaId?.let { extractTrackId(it) }
+    val currentTrack = getCurrentTrack() ?: currentTracks.getOrNull(currentTrackIndex)
+    val upcoming = buildUpcomingQueueTracks(currentId)
+    val positionMs = cast.currentPosition.coerceAtLeast(0L)
+    val wasPlaying = cast.playWhenReady
+    val repeat = cast.repeatMode
+
+    playerListener?.let { cast.removeListener(it) }
+    cast.playWhenReady = false
+
+    isCastingField = false // before building items so makeMediaItem restores download paths
+    lastCastWaitTrackId = null
+    exo = ExoPlayerCore(controller.localPlayer)
+    playerListener?.let { controller.localPlayer.addListener(it) }
+    setMediaSessionPlayer(controller.localPlayer)
+
+    val localList = ArrayList<TrackItem>()
+    currentTrack?.let { localList.add(it) }
+    localList.addAll(upcoming)
+
+    if (localList.isNotEmpty()) {
+        val items = localList.map { makeMediaItem(it, mediaIdFor(it)) }
+        controller.localPlayer.setMediaItems(items, 0, positionMs)
+        controller.localPlayer.repeatMode = repeat
+        controller.localPlayer.playWhenReady = wasPlaying
+        controller.localPlayer.prepare()
+    }
 
-    exo = ExoPlayerCore(target)
-    playerListener?.let { target.addListener(it) }
+    notifyCastStateChange(controller.getCastState(), controller.currentDeviceName())
+}
 
+private fun TrackPlayerCore.setMediaSessionPlayer(target: Player) {
     try {
         castSessionController?.let { it.mediaSession.player = target }
     } catch (e: Exception) {
@@ -57,24 +113,6 @@ private fun TrackPlayerCore.switchToPlayer(target: Player) {
     }
 }
 
-/** Copy the queue, index, position, repeat mode and play-when-ready from one player to another. */
-private fun transferPlaybackState(
-    from: Player,
-    to: Player,
-) {
-    val count = from.mediaItemCount
-    if (count == 0) return
-    val items = ArrayList<MediaItem>(count)
-    for (i in 0 until count) items.add(from.getMediaItemAt(i))
-    val index = from.currentMediaItemIndex.coerceAtLeast(0)
-    val position = if (from.currentPosition >= 0) from.currentPosition else 0L
-
-    to.setMediaItems(items, index, position)
-    to.repeatMode = from.repeatMode
-    to.playWhenReady = from.playWhenReady
-    to.prepare()
-}
-
 // ── Notifications ──────────────────────────────────────────────────────────
 
 internal fun TrackPlayerCore.notifyCastStateChange(

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

@@ -100,6 +100,9 @@ class TrackPlayerCore private constructor(
     /** True while the active backend is the CastPlayer (audio routed to a remote device). */
     @Volatile internal var isCastingField: Boolean = false
 
+    /** Last track announced from a cast "waiting for URL" state — dedups onChangeTrack across updateTracks re-entries. */
+    internal var lastCastWaitTrackId: String? = null
+
     // ── Progress & playlist-update runnables ───────────────────────────────
     internal val progressUpdateRunnable =
         object : Runnable {

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

@@ -6,6 +6,7 @@ import android.net.Uri
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
 import androidx.media3.common.Player
+import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.TrackItem
 
 /**
@@ -15,17 +16,63 @@ import com.margelo.nitro.nitroplayer.TrackItem
  * when jumping to a specific index.
  */
 
+// ── Cast-safety helpers ────────────────────────────────────────────────────
+
+/** A track the Cast receiver can actually load: non-empty remote (non-local) URL. */
+internal fun TrackPlayerCore.isTrackCastable(track: TrackItem): Boolean =
+    track.url.isNotEmpty() &&
+        !track.url.startsWith("/") &&
+        !track.url.startsWith("file:")
+
+/** Receiver-safe run: keeps castable tracks, skips local-only ones, stops at the first lazy (empty-URL) track whose resolution is pending — receivers auto-skip failed loads instead of waiting like ExoPlayer. */
+internal fun TrackPlayerCore.castableUpcoming(tracks: List<TrackItem>): List<TrackItem> {
+    val result = ArrayList<TrackItem>(tracks.size)
+    for (track in tracks) {
+        when {
+            isTrackCastable(track) -> result.add(track)
+            track.url.isEmpty() -> break
+            // local-only → skip and keep scanning
+        }
+    }
+    return result
+}
+
+internal fun TrackPlayerCore.mediaIdFor(track: TrackItem): String {
+    val playlistId = currentPlaylistId ?: ""
+    return if (playlistId.isNotEmpty()) "$playlistId:${track.id}" else track.id
+}
+
 // ── Full rebuild (jump to index) ───────────────────────────────────────────
 
 internal fun TrackPlayerCore.rebuildQueueAndPlayFromIndex(index: Int) {
     if (!isExoInitialized) return
     if (index < 0 || index >= currentTracks.size) return
 
-    val playlistId = currentPlaylistId ?: ""
+    if (isCastingField) {
+        currentTrackIndex = index
+        val target = currentTracks[index]
+        val castTracks = castableUpcoming(currentTracks.subList(index, currentTracks.size))
+        if (castTracks.isEmpty()) {
+            // Lazy target — silence the receiver and wait for updateTracks to reload (dedup so re-entries don't spam JS).
+            if (exo.mediaItemCount > 0) exo.clearMediaItems()
+            if (lastCastWaitTrackId != target.id) {
+                lastCastWaitTrackId = target.id
+                notifyTrackChange(target, Reason.SKIP)
+            }
+            checkUpcomingTracksForUrls(lookaheadCount)
+            return
+        }
+        lastCastWaitTrackId = null
+        // Single atomic queueLoad — no separate clear (each queue op is a receiver RPC).
+        exo.setMediaItems(castTracks.map { makeMediaItem(it, mediaIdFor(it)) }, true)
+        exo.prepare()
+        checkUpcomingTracksForUrls(lookaheadCount)
+        return
+    }
+
     val mediaItems =
         currentTracks.subList(index, currentTracks.size).map { track ->
-            val mediaId = if (playlistId.isNotEmpty()) "$playlistId:${track.id}" else track.id
-            makeMediaItem(track, mediaId)
+            makeMediaItem(track, mediaIdFor(track))
         }
 
     currentTrackIndex = index
@@ -63,8 +110,38 @@ internal fun TrackPlayerCore.rebuildQueueFromCurrentPosition() {
         }
     }
 
-    val newQueueTracks = ArrayList<TrackItem>(playNextStack.size + upNextQueue.size + currentTracks.size)
     val currentId = exo.currentMediaItem?.mediaId?.let { extractTrackId(it) }
+    var newQueueTracks: List<TrackItem> = buildUpcomingQueueTracks(currentId)
+
+    if (isCastingField) {
+        newQueueTracks = castableUpcoming(newQueueTracks)
+
+        // Every queue edit is a receiver RPC — skip the rebuild when the remote queue already matches.
+        val itemCount = exo.mediaItemCount
+        if (itemCount - currentIndex - 1 == newQueueTracks.size) {
+            var inSync = true
+            for (i in newQueueTracks.indices) {
+                val existingId = extractTrackId(exo.getMediaItemAt(currentIndex + 1 + i).mediaId)
+                if (existingId != newQueueTracks[i].id) {
+                    inSync = false
+                    break
+                }
+            }
+            if (inSync) return
+        }
+    }
+
+    val newMediaItems = newQueueTracks.map { makeMediaItem(it, mediaIdFor(it)) }
+
+    if (exo.mediaItemCount > currentIndex + 1) {
+        exo.removeMediaItems(currentIndex + 1, exo.mediaItemCount)
+    }
+    exo.addMediaItems(newMediaItems)
+}
+
+/** Desired upcoming list after the current track: playNext + upNext + remaining originals, with the playing temp track ([currentId]) skipped. */
+internal fun TrackPlayerCore.buildUpcomingQueueTracks(currentId: String?): List<TrackItem> {
+    val newQueueTracks = ArrayList<TrackItem>(playNextStack.size + upNextQueue.size + currentTracks.size)
 
     // playNext stack — skip the currently playing track by ID (not position)
     if (currentTemporaryType == TrackPlayerCore.TemporaryType.PLAY_NEXT && currentId != null) {
@@ -94,34 +171,39 @@ internal fun TrackPlayerCore.rebuildQueueFromCurrentPosition() {
         newQueueTracks.addAll(upNextQueue)
     }
 
-    // Remaining original tracks (after currentTrackIndex, not after ExoPlayer's currentIndex)
+    // Remaining original tracks (after currentTrackIndex, not after the player's currentIndex)
     if (currentTrackIndex + 1 < currentTracks.size) {
         newQueueTracks.addAll(currentTracks.subList(currentTrackIndex + 1, currentTracks.size))
     }
-
-    val playlistId = currentPlaylistId ?: ""
-    val newMediaItems =
-        newQueueTracks.map { track ->
-            val mediaId = if (playlistId.isNotEmpty()) "$playlistId:${track.id}" else track.id
-            makeMediaItem(track, mediaId)
-        }
-
-    if (exo.mediaItemCount > currentIndex + 1) {
-        exo.removeMediaItems(currentIndex + 1, exo.mediaItemCount)
-    }
-    exo.addMediaItems(newMediaItems)
+    return newQueueTracks
 }
 
 // ── Full queue set (initial load or no active item) ───────────────────────
 
 internal fun TrackPlayerCore.updatePlayerQueue(tracks: List<TrackItem>) {
     currentTracks = tracks
-    val playlistId = currentPlaylistId ?: ""
-    val mediaItems =
-        tracks.map { track ->
-            val mediaId = if (playlistId.isNotEmpty()) "$playlistId:${track.id}" else track.id
-            makeMediaItem(track, mediaId)
+
+    if (isCastingField) {
+        currentTrackIndex = 0
+        val castTracks = castableUpcoming(tracks)
+        if (castTracks.isEmpty()) {
+            // Lazy first track — silence the receiver and wait for updateTracks to supply URLs.
+            if (exo.mediaItemCount > 0) exo.clearMediaItems()
+            val first = tracks.firstOrNull()
+            if (first != null && lastCastWaitTrackId != first.id) {
+                lastCastWaitTrackId = first.id
+                notifyTrackChange(first, null)
+            }
+            checkUpcomingTracksForUrls(lookaheadCount)
+            return
         }
+        lastCastWaitTrackId = null
+        exo.setMediaItems(castTracks.map { makeMediaItem(it, mediaIdFor(it)) }, true)
+        exo.prepare()
+        return
+    }
+
+    val mediaItems = tracks.map { makeMediaItem(it, mediaIdFor(it)) }
     exo.setMediaItems(mediaItems, true)
     if (exo.playbackState == Player.STATE_IDLE && mediaItems.isNotEmpty()) {
         exo.prepare()
@@ -148,7 +230,8 @@ internal fun TrackPlayerCore.makeMediaItem(
         }
     }
 
-    val effectiveUrl = downloadManager.getEffectiveUrl(track)
+    // The receiver fetches media itself, so local download paths are unplayable there — cast uses the remote URL.
+    val effectiveUrl = if (isCastingField) track.url else downloadManager.getEffectiveUrl(track)
 
     // Register custom HTTP headers (e.g. Authorization) from extraPayload.headers so they are
     // injected into the request for this URL. Applies to remote streams only — see ExoPlayerBuilder.

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

@@ -36,12 +36,13 @@ suspend fun TrackPlayerCore.updateTracks(tracks: List<TrackItem>) =
 
         val affectedPlaylists: Map<String, Int> = playlistManager.updateTracks(safeTracks)
 
-        // Replace current track's MediaItem if it was empty-URL and now has a URL
-        if (currentTrackUpdate != null && currentTrackIsEmpty && currentTrackUpdate.url.isNotEmpty()) {
+        // Replace the current MediaItem when its URL just resolved (local only — the cast branch below reloads instead).
+        val currentTrackResolvedNow = currentTrackUpdate != null && currentTrackIsEmpty && currentTrackUpdate.url.isNotEmpty()
+        if (!isCastingField && currentTrackResolvedNow) {
             val exoIndex = exo.currentMediaItemIndex
             if (exoIndex >= 0) {
                 val playlistId = currentPlaylistId ?: ""
-                val mediaId = if (playlistId.isNotEmpty()) "$playlistId:${currentTrackUpdate.id}" else currentTrackUpdate.id
+                val mediaId = if (playlistId.isNotEmpty()) "$playlistId:${currentTrackUpdate!!.id}" else currentTrackUpdate!!.id
                 exo.replaceMediaItem(exoIndex, makeMediaItem(currentTrackUpdate, mediaId))
                 if (exo.playbackState == Player.STATE_IDLE) exo.prepare()
             }
@@ -55,6 +56,17 @@ suspend fun TrackPlayerCore.updateTracks(tracks: List<TrackItem>) =
                 playNextStack.forEachIndexed { i, t -> updatedById[t.id]?.let { if (it !== t) playNextStack[i] = it } }
                 upNextQueue.forEachIndexed { i, t -> updatedById[t.id]?.let { if (it !== t) upNextQueue[i] = it } }
             }
+
+            if (isCastingField) {
+                // Resolved current track (or empty receiver) → atomic reload from the current index; otherwise resync only the upcoming items.
+                if (currentTrackResolvedNow || exo.mediaItemCount == 0) {
+                    rebuildQueueAndPlayFromIndex(currentTrackIndex)
+                } else {
+                    rebuildQueueFromCurrentPosition()
+                }
+                return@withPlayerContext
+            }
+
             rebuildQueueFromCurrentPosition()
         }
     }

package/ios/core/CastSessionManager.swift

@@ -7,6 +7,8 @@
 //  `#if canImport(GoogleCast)` so the library still builds when the SDK is not
 //  linked — in that case every method is an inert no-op and casting is disabled.
 //
+//  Threading: the SDK is main-thread-affine, so SDK calls hop to main and reads are served from lock-guarded caches.
+//
 
 import Foundation
 import MediaPlayer
@@ -19,15 +21,67 @@ final class CastSessionManager: NSObject {
   weak var core: TrackPlayerCore?
 
   private var isConfigured = false
-  private var loadedTracks: [TrackItem] = []
-  private var lastCurrentTrackId: String?
-  // GoogleCast reads are main-thread-affine; Nitro sync getters run off-main, so
-  // serve them from a cache refreshed on the main thread by the Cast callbacks.
+  private var progressTimer: Timer?
+
+  // MARK: - Lock-guarded caches (written on main, read from playerQueue / JS thread)
+
+  private let stateLock = NSLock()
+  private var _lastCurrentTrackId: String?
+  private var _loadedTracks: [TrackItem] = []
+  private var _hasLoadedMedia = false
+  private var _cachedPlaybackState: TrackPlayerState = .stopped
+  private var _lastEmittedPlaybackState: TrackPlayerState?
+  private var _lastKnownRemotePosition: Double = 0
+  private var _lastKnownRemoteDuration: Double = 0
   private var cachedState: CastState = .noDevicesAvailable
   private var cachedDeviceName: String?
+
+  /// Track ID playing on the receiver (or expected to, right after a locally-initiated jump).
+  var currentRemoteTrackId: String? {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return _lastCurrentTrackId
+  }
+
+  /// IDs of the tracks last sent to the receiver, in queue order.
+  var loadedTrackIds: [String] {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return _loadedTracks.map { $0.id }
+  }
+
+  /// Whether the receiver currently has media loaded.
+  var hasLoadedMedia: Bool {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return _hasLoadedMedia
+  }
+
   /// Last position reported by the receiver, used to resume locally on disconnect.
-  private(set) var lastKnownRemotePosition: Double = 0
-  private var progressTimer: Timer?
+  var lastKnownRemotePosition: Double {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return _lastKnownRemotePosition
+  }
+
+  /// Last duration reported by the receiver for the current item.
+  var lastKnownRemoteDuration: Double {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return _lastKnownRemoteDuration
+  }
+
+  /// Last playback state reported by the receiver.
+  var cachedPlaybackState: TrackPlayerState {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return _cachedPlaybackState
+  }
+
+  /// Pre-set the expected current track after a local jump so the receiver's status echo doesn't duplicate the track-change event.
+  func setExpectedCurrentTrack(_ trackId: String?) {
+    stateLock.lock(); defer { stateLock.unlock() }
+    _lastCurrentTrackId = trackId
+  }
+
+  private func withState<T>(_ body: () -> T) -> T {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return body()
+  }
 
   // MARK: - Configuration
 
@@ -66,17 +120,23 @@ final class CastSessionManager: NSObject {
 
   var isCasting: Bool {
     #if canImport(GoogleCast)
-    return isConfigured && GCKCastContext.sharedInstance().sessionManager.currentCastSession != nil
+    return currentCastState() == .connected
     #else
     return false
     #endif
   }
 
   /// Cached — safe to call from the JS thread.
-  func currentCastState() -> CastState { cachedState }
+  func currentCastState() -> CastState {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return cachedState
+  }
 
   /// Cached — safe to call from the JS thread.
-  func deviceName() -> String? { cachedDeviceName }
+  func deviceName() -> String? {
+    stateLock.lock(); defer { stateLock.unlock() }
+    return cachedDeviceName
+  }
 
   // MARK: - UI / session control
 
@@ -128,12 +188,6 @@ final class CastSessionManager: NSObject {
     #endif
   }
 
-  func skipToPrevious() {
-    #if canImport(GoogleCast)
-    onMain { self.remoteClient?.queuePreviousItem() }
-    #endif
-  }
-
   func setVolume(_ volume0to1: Float) {
     #if canImport(GoogleCast)
     onMain { self.remoteClient?.setStreamVolume(volume0to1) }
@@ -146,38 +200,81 @@ final class CastSessionManager: NSObject {
     #endif
   }
 
-  func jump(toQueueIndex index: Int) {
+  func setQueueRepeatMode(_ mode: RepeatMode) {
     #if canImport(GoogleCast)
     onMain {
-      guard let client = self.remoteClient,
-            let status = client.mediaStatus,
-            index >= 0, index < Int(status.queueItemCount) else { return }
-      if let item = status.queueItem(at: UInt(index)) {
-        client.queueJumpToItem(withID: item.itemID)
+      let gckMode: GCKMediaRepeatMode
+      switch mode {
+      case .track: gckMode = .single
+      case .playlist: gckMode = .all
+      default: gckMode = .off
       }
+      self.remoteClient?.queueSetRepeatMode(gckMode)
+    }
+    #endif
+  }
+
+  /// Stop and unload the receiver (used when jumping to a track whose URL hasn't resolved yet).
+  func stop() {
+    #if canImport(GoogleCast)
+    // No-op when nothing is loaded — avoids a pointless receiver RPC per updateTracks re-entry.
+    let hadMedia: Bool = withState {
+      let had = _hasLoadedMedia || !_loadedTracks.isEmpty
+      _hasLoadedMedia = false
+      _loadedTracks = []
+      return had
     }
+    guard hadMedia else { return }
+    onMain { self.remoteClient?.stop() }
     #endif
   }
 
   // MARK: - Queue loading
 
-  func loadQueue(tracks: [TrackItem], startIndex: Int, position: Double, autoplay: Bool) {
+  /// Atomically replace the receiver queue — `tracks` must be castable and start at the item that should play.
+  func loadQueue(tracks: [TrackItem], position: Double, autoplay: Bool, repeatMode: RepeatMode) {
     #if canImport(GoogleCast)
+    guard !tracks.isEmpty else { return }
+    withState {
+      _loadedTracks = tracks
+      _hasLoadedMedia = true // optimistic; corrected by the next media status
+      _lastCurrentTrackId = tracks.first?.id
+    }
     onMain {
-      guard let client = self.remoteClient, !tracks.isEmpty else { return }
-      self.loadedTracks = tracks
+      guard let client = self.remoteClient else { return }
       let items = tracks.compactMap { self.makeQueueItem(for: $0, autoplay: autoplay) }
       guard !items.isEmpty else { return }
 
       let options = GCKMediaQueueLoadOptions()
-      options.startIndex = UInt(max(0, min(startIndex, items.count - 1)))
-      options.playPosition = position.isFinite ? position : 0
-      options.repeatMode = .off
+      options.startIndex = 0
+      options.playPosition = position.isFinite ? max(0, position) : 0
+      switch repeatMode {
+      case .track: options.repeatMode = .single
+      case .playlist: options.repeatMode = .all
+      default: options.repeatMode = .off
+      }
       client.queueLoad(items, with: options)
     }
     #endif
   }
 
+  /// Append tracks to the END of the receiver queue without touching playback.
+  func appendToQueue(tracks: [TrackItem]) {
+    #if canImport(GoogleCast)
+    guard !tracks.isEmpty else { return }
+    withState {
+      let known = Set(_loadedTracks.map { $0.id })
+      _loadedTracks.append(contentsOf: tracks.filter { !known.contains($0.id) })
+    }
+    onMain {
+      guard let client = self.remoteClient else { return }
+      let items = tracks.compactMap { self.makeQueueItem(for: $0, autoplay: true) }
+      guard !items.isEmpty else { return }
+      client.queueInsert(items, beforeItemWithID: kGCKMediaQueueInvalidItemID)
+    }
+    #endif
+  }
+
   // MARK: - Private helpers
 
   private func onMain(_ block: @escaping () -> Void) {
@@ -191,8 +288,9 @@ final class CastSessionManager: NSObject {
   }
 
   private func makeQueueItem(for track: TrackItem, autoplay: Bool) -> GCKMediaQueueItem? {
-    let urlString = DownloadManagerCore.shared.getEffectiveUrl(track: track)
-    guard let contentURL = URL(string: urlString) else { return nil }
+    // The receiver fetches media itself — only remote URLs are playable (callers pre-filter with isTrackCastable).
+    let urlString = track.url
+    guard !urlString.isEmpty, let contentURL = URL(string: urlString) else { return nil }
 
     let metadata = GCKMediaMetadata(metadataType: .musicTrack)
     metadata.setString(track.title, forKey: kGCKMetadataKeyTitle)
@@ -249,7 +347,10 @@ final class CastSessionManager: NSObject {
     let position = client.approximateStreamPosition()
     let duration = client.mediaStatus?.mediaInformation?.streamDuration ?? 0
     let safeDuration = (duration.isFinite && duration > 0) ? duration : 0
-    if position.isFinite { lastKnownRemotePosition = position }
+    withState {
+      if position.isFinite { _lastKnownRemotePosition = position }
+      _lastKnownRemoteDuration = safeDuration
+    }
     core?.emitCastProgress(position.isFinite ? position : 0, safeDuration)
     updateNowPlaying(position: position, duration: safeDuration)
   }
@@ -259,14 +360,10 @@ final class CastSessionManager: NSObject {
     guard let status else { return nil }
     let item = status.queueItem(withItemID: status.currentItemID)
     let info = item?.mediaInformation ?? status.mediaInformation
-    if let customData = info?.customData as? [String: Any],
-       let trackId = customData["trackId"] as? String {
-      return loadedTracks.first { $0.id == trackId }
-    }
-    if let url = info?.contentURL?.absoluteString {
-      return loadedTracks.first { DownloadManagerCore.shared.getEffectiveUrl(track: $0) == url }
-    }
-    return nil
+    guard let customData = info?.customData as? [String: Any],
+          let trackId = customData["trackId"] as? String
+    else { return nil }
+    return withState { _loadedTracks.first { $0.id == trackId } }
   }
 
   private func mapPlayerState(_ state: GCKMediaPlayerState) -> TrackPlayerState {
@@ -280,7 +377,8 @@ final class CastSessionManager: NSObject {
   }
 
   private func updateNowPlaying(position: Double, duration: Double) {
-    guard let track = lastCurrentTrackId.flatMap({ id in loadedTracks.first { $0.id == id } }) else { return }
+    let track = withState { _lastCurrentTrackId.flatMap { id in _loadedTracks.first { $0.id == id } } }
+    guard let track else { return }
     var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
     info[MPMediaItemPropertyTitle] = track.title
     info[MPMediaItemPropertyArtist] = track.artist
@@ -299,25 +397,32 @@ final class CastSessionManager: NSObject {
   /// Refreshes the cache from live Cast state and notifies listeners. Callers must be on the main thread.
   private func emitCastState() {
     refreshCacheOnMain()
-    core?.notifyCastStateChangeListeners(cachedState, cachedDeviceName)
+    core?.notifyCastStateChangeListeners(currentCastState(), deviceName())
   }
 
   /// Re-read live Cast state into the cache. MUST be called on the main thread.
   private func refreshCacheOnMain() {
     #if canImport(GoogleCast)
     guard isConfigured else {
-      cachedState = .noDevicesAvailable
-      cachedDeviceName = nil
+      withState {
+        cachedState = .noDevicesAvailable
+        cachedDeviceName = nil
+      }
       return
     }
+    let newState: CastState
     switch GCKCastContext.sharedInstance().castState {
-    case .noDevicesAvailable: cachedState = .noDevicesAvailable
-    case .notConnected: cachedState = .notConnected
-    case .connecting: cachedState = .connecting
-    case .connected: cachedState = .connected
-    @unknown default: cachedState = .notConnected
+    case .noDevicesAvailable: newState = .noDevicesAvailable
+    case .notConnected: newState = .notConnected
+    case .connecting: newState = .connecting
+    case .connected: newState = .connected
+    @unknown default: newState = .notConnected
+    }
+    let name = GCKCastContext.sharedInstance().sessionManager.currentCastSession?.device.friendlyName
+    withState {
+      cachedState = newState
+      cachedDeviceName = name
     }
-    cachedDeviceName = GCKCastContext.sharedInstance().sessionManager.currentCastSession?.device.friendlyName
     #endif
   }
 }
@@ -340,7 +445,13 @@ extension CastSessionManager: GCKSessionManagerListener {
 
   func sessionManager(_ sessionManager: GCKSessionManager, didEnd session: GCKSession, withError error: Error?) {
     stopProgressTimer()
-    lastCurrentTrackId = nil
+    withState {
+      _lastCurrentTrackId = nil
+      _loadedTracks = []
+      _hasLoadedMedia = false
+      _cachedPlaybackState = .stopped
+      _lastEmittedPlaybackState = nil
+    }
     core?.handleCastDisconnected()
     emitCastState()
   }
@@ -359,15 +470,39 @@ extension CastSessionManager: GCKRemoteMediaClientListener {
   func remoteMediaClient(_ client: GCKRemoteMediaClient, didUpdate mediaStatus: GCKMediaStatus?) {
     guard let core else { return }
 
-    // Track change
-    if let track = currentRemoteTrack(mediaStatus), track.id != lastCurrentTrackId {
-      lastCurrentTrackId = track.id
-      core.emitCastTrackChange(track)
+    let hasMedia = mediaStatus?.mediaInformation != nil
+    let state = mapPlayerState(mediaStatus?.playerState ?? .unknown)
+
+    // Track change — core state mutations must run on the player queue.
+    if let track = currentRemoteTrack(mediaStatus) {
+      let previousId: String? = withState {
+        let prev = _lastCurrentTrackId
+        _lastCurrentTrackId = track.id
+        _hasLoadedMedia = hasMedia
+        _cachedPlaybackState = state
+        return prev
+      }
+      if previousId != track.id {
+        core.playerQueue.async {
+          core.emitCastTrackChange(track, previousTrackId: previousId)
+        }
+      }
+    } else {
+      withState {
+        _hasLoadedMedia = hasMedia
+        _cachedPlaybackState = state
+      }
     }
 
-    // Playback state
-    let state = mapPlayerState(mediaStatus?.playerState ?? .unknown)
-    core.emitCastPlaybackState(state)
+    // Playback state — only forward actual changes (status updates are frequent).
+    let stateChanged: Bool = withState {
+      guard _lastEmittedPlaybackState != state else { return false }
+      _lastEmittedPlaybackState = state
+      return true
+    }
+    if stateChanged {
+      core.emitCastPlaybackState(state)
+    }
   }
 }
 #endif

package/ios/core/TrackPlayerCast.swift

@@ -10,12 +10,40 @@
 //  to the receiver. The same queue model (currentTracks / temp queues) stays the
 //  single source of truth, so disconnect can restore local playback seamlessly.
 //
+//  Receivers auto-skip failed loads (AVPlayer waits), so only receiver-loadable tracks are ever enqueued remotely.
+//
 
 import AVFoundation
 import Foundation
 
 extension TrackPlayerCore {
 
+  // MARK: - Cast-safety helpers
+
+  /// A track the Cast receiver can actually load: non-empty remote (non-local) URL.
+  func isTrackCastable(_ track: TrackItem) -> Bool {
+    !track.url.isEmpty && !track.url.hasPrefix("/") && !track.url.hasPrefix("file:")
+  }
+
+  /// Receiver-safe run: keeps castable tracks, skips local-only ones, stops at the first lazy (empty-URL) track whose resolution is pending.
+  func castableUpcoming(_ tracks: [TrackItem]) -> [TrackItem] {
+    var result: [TrackItem] = []
+    for track in tracks {
+      if isTrackCastable(track) {
+        result.append(track)
+      } else if track.url.isEmpty {
+        break
+      }
+      // local-only → skip and keep scanning
+    }
+    return result
+  }
+
+  /// Track ID playing on the ACTIVE backend — receiver while casting, local AVQueuePlayer otherwise.
+  var activeCurrentTrackId: String? {
+    isCasting ? castManager?.currentRemoteTrackId : player?.currentItem?.trackId
+  }
+
   // MARK: - Session lifecycle (called by CastSessionManager)
 
   /// A Cast session became active — transfer current playback to the device.
@@ -38,9 +66,9 @@ extension TrackPlayerCore {
     playerQueue.async { [weak self] in
       guard let self else { return }
       guard self.isCasting else { return }
+      let resumePosition = self.castManager?.lastKnownRemotePosition ?? 0
       self.isCasting = false
 
-      let resumePosition = self.castManager?.lastKnownRemotePosition ?? 0
       let index = self.currentTrackIndex
       guard index >= 0 && index < self.currentTracks.count else { return }
 
@@ -55,27 +83,220 @@ extension TrackPlayerCore {
     }
   }
 
-  /// Mirror the current effective queue to the Cast device, starting at the current track.
-  /// Must be called on `playerQueue`.
+  // MARK: - Receiver queue loading (all on playerQueue)
+
+  /// Load the receiver queue starting at the current track.
   func loadCastQueue(autoplay: Bool, position: Double) {
     let queue = getActualQueueInternal()
     guard !queue.isEmpty else { return }
     let current = getCurrentTrack()
     let startIndex = current
       .flatMap { c in queue.firstIndex(where: { $0.id == c.id }) }
-      ?? max(0, currentTrackIndex)
-    castManager?.loadQueue(tracks: queue, startIndex: startIndex, position: position, autoplay: autoplay)
+      ?? max(0, min(currentTrackIndex, queue.count - 1))
+    loadCastQueue(fromActualIndex: startIndex, autoplay: autoplay, position: position)
+  }
+
+  /// Atomically (re)load the receiver queue from `index` in the actual queue (lazy targets stop the receiver and wait for updateTracks).
+  func loadCastQueue(fromActualIndex index: Int, autoplay: Bool, position: Double) {
+    let queue = getActualQueueInternal()
+    guard index >= 0, index < queue.count else { return }
+    let slice = Array(queue[index...])
+    let playable = castableUpcoming(slice)
+
+    guard !playable.isEmpty else {
+      // Lazy target — silence the receiver and wait for updateTracks to reload.
+      castManager?.stop()
+      checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+      return
+    }
+
+    // Resume mid-track only when the receiver starts on the requested track.
+    let effectivePosition = playable[0].id == slice[0].id ? position : 0
+
+    castManager?.setExpectedCurrentTrack(playable[0].id)
+    castManager?.loadQueue(
+      tracks: playable,
+      position: effectivePosition,
+      autoplay: autoplay,
+      repeatMode: currentRepeatMode
+    )
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+  }
+
+  /// Sync the receiver's upcoming items: append-only extensions don't interrupt playback; anything else reloads at the current position.
+  func syncCastQueueAfterCurrent() {
+    guard let cast = castManager else { return }
+    guard cast.hasLoadedMedia else {
+      // Nothing loaded remotely (e.g. the target was lazy) — full load from current.
+      loadCastQueue(autoplay: intendedToPlay, position: 0)
+      return
+    }
+
+    let queue = getActualQueueInternal()
+    guard let current = getCurrentTrack(),
+      let currentIdx = queue.firstIndex(where: { $0.id == current.id })
+    else { return }
+
+    let desired = castableUpcoming(Array(queue[(currentIdx + 1)...]))
+    let desiredIds = desired.map { $0.id }
+
+    let loaded = cast.loadedTrackIds
+    let existingUpcoming: [String]
+    if let ei = loaded.firstIndex(of: current.id) {
+      existingUpcoming = Array(loaded[(ei + 1)...])
+    } else {
+      existingUpcoming = []
+    }
+
+    if desiredIds == existingUpcoming { return } // already in sync
+
+    if desiredIds.count > existingUpcoming.count,
+      Array(desiredIds.prefix(existingUpcoming.count)) == existingUpcoming {
+      // Strict tail extension — append without touching current playback.
+      let toAppend = Array(desired.suffix(desiredIds.count - existingUpcoming.count))
+      castManager?.appendToQueue(tracks: toAppend)
+    } else {
+      // Order changed / items removed — atomic reload preserving position.
+      loadCastQueue(
+        fromActualIndex: currentIdx,
+        autoplay: intendedToPlay,
+        position: cast.lastKnownRemotePosition
+      )
+    }
   }
 
-  // MARK: - Emit (cast-derived events → JS listeners)
-  // These bypass getStateInternal()/notify* which read the (paused) local player.
+  // MARK: - Cast-mode navigation (mirrors the local skip logic, minus AVQueuePlayer)
 
-  func emitCastTrackChange(_ track: TrackItem) {
-    if let idx = currentTracks.firstIndex(where: { $0.id == track.id }) {
-      currentTrackIndex = idx
+  /// skipToIndex while casting: apply the local path's list/index mutations, then reload the receiver at the target.
+  func skipToIndexCastInternal(index: Int) -> Bool {
+    let actualQueue = getActualQueueInternal()
+    guard index >= 0 && index < actualQueue.count else { return false }
+
+    // Same section boundaries as the local skipToIndexInternal.
+    let currentPos = currentTemporaryType != .none ? currentTrackIndex + 1 : currentTrackIndex
+    let effectivePlayNextSize = currentTemporaryType == .playNext
+      ? max(0, playNextStack.count - 1) : playNextStack.count
+    let effectiveUpNextSize = currentTemporaryType == .upNext
+      ? max(0, upNextQueue.count - 1) : upNextQueue.count
+    let playNextStart = currentPos + 1
+    let playNextEnd = playNextStart + effectivePlayNextSize
+    let upNextEnd = playNextEnd + effectiveUpNextSize
+
+    if index == currentPos {
+      castManager?.seek(to: 0)
+      return true
+    }
+
+    let target = actualQueue[index]
+
+    // Skipping away from a playing temp track removes it from its list (mirrors the local handler).
+    if currentTemporaryType != .none, let currentId = activeCurrentTrackId {
+      if currentTemporaryType == .playNext,
+        let i = playNextStack.firstIndex(where: { $0.id == currentId }) {
+        playNextStack.remove(at: i)
+      } else if currentTemporaryType == .upNext,
+        let i = upNextQueue.firstIndex(where: { $0.id == currentId }) {
+        upNextQueue.remove(at: i)
+      }
+    }
+
+    if index < currentPos || index >= upNextEnd {
+      // Original-playlist target — temps are cleared, same as the local path.
+      guard let originalIndex = currentTracks.firstIndex(where: { $0.id == target.id }) else { return false }
+      playNextStack.removeAll()
+      upNextQueue.removeAll()
+      currentTemporaryType = .none
+      currentTrackIndex = originalIndex
+    } else if index < playNextEnd {
+      // playNext section: everything before the target is dropped.
+      if let t = playNextStack.firstIndex(where: { $0.id == target.id }), t > 0 {
+        playNextStack.removeSubrange(0..<t)
+      }
+      currentTemporaryType = .playNext
+    } else {
+      // upNext section: playNext is consumed, earlier upNext entries dropped.
+      playNextStack.removeAll()
+      if let t = upNextQueue.firstIndex(where: { $0.id == target.id }), t > 0 {
+        upNextQueue.removeSubrange(0..<t)
+      }
+      currentTemporaryType = .upNext
+    }
+
+    castManager?.setExpectedCurrentTrack(target.id)
+    notifyTemporaryQueueChange()
+    onChangeTrackListeners.forEach { $0(target, .skip) }
+
+    // Reload the receiver from the target's position in the refreshed queue.
+    let newQueue = getActualQueueInternal()
+    let newIndex = newQueue.firstIndex(where: { $0.id == target.id }) ?? 0
+    loadCastQueue(fromActualIndex: newIndex, autoplay: intendedToPlay, position: 0)
+    return true
+  }
+
+  /// skipToPrevious while casting: restart after the threshold, otherwise step back through temp/original tracks.
+  func skipToPreviousCastInternal() {
+    let position = castManager?.lastKnownRemotePosition ?? 0
+    if position > Constants.skipToPreviousThreshold {
+      castManager?.seek(to: 0)
+      return
+    }
+
+    if currentTemporaryType != .none {
+      // Leaving a temp track removes it, then return to the current original.
+      if let currentId = activeCurrentTrackId {
+        if currentTemporaryType == .playNext,
+          let i = playNextStack.firstIndex(where: { $0.id == currentId }) {
+          playNextStack.remove(at: i)
+        } else if currentTemporaryType == .upNext,
+          let i = upNextQueue.firstIndex(where: { $0.id == currentId }) {
+          upNextQueue.remove(at: i)
+        }
+      }
       currentTemporaryType = .none
+      notifyTemporaryQueueChange()
+    } else if currentTrackIndex > 0 {
+      currentTrackIndex -= 1
+    } else {
+      castManager?.seek(to: 0)
+      return
     }
+
+    guard let target = currentTracks[safe: currentTrackIndex] else { return }
+    castManager?.setExpectedCurrentTrack(target.id)
+    onChangeTrackListeners.forEach { $0(target, .skip) }
+    loadCastQueue(autoplay: intendedToPlay, position: 0)
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+  }
+
+  // MARK: - Emit (cast-derived events → JS listeners; run on playerQueue)
+
+  /// Track change from the receiver: temp-list bookkeeping, index/type classification, and the JS event.
+  func emitCastTrackChange(_ track: TrackItem, previousTrackId: String? = nil) {
+    // Leaving a temp track removes it from its list (mirrors the local handler).
+    if let prev = previousTrackId, prev != track.id {
+      if let i = playNextStack.firstIndex(where: { $0.id == prev }) {
+        playNextStack.remove(at: i)
+        notifyTemporaryQueueChange()
+      } else if let i = upNextQueue.firstIndex(where: { $0.id == prev }) {
+        upNextQueue.remove(at: i)
+        notifyTemporaryQueueChange()
+      }
+    }
+
+    // Classify the new current track — temp lists take priority (matches determineCurrentTemporaryType).
+    if playNextStack.contains(where: { $0.id == track.id }) {
+      currentTemporaryType = .playNext
+    } else if upNextQueue.contains(where: { $0.id == track.id }) {
+      currentTemporaryType = .upNext
+    } else {
+      currentTemporaryType = .none
+      if let idx = currentTracks.firstIndex(where: { $0.id == track.id }) {
+        currentTrackIndex = idx
+      }
+    }
+
     onChangeTrackListeners.forEach { $0(track, .skip) }
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
   }
 
   func emitCastPlaybackState(_ state: TrackPlayerState) {

package/ios/core/TrackPlayerPlayback.swift

@@ -47,7 +47,8 @@ extension TrackPlayerCore {
 
   func skipToPrevious() async {
     if isCasting {
-      castManager?.skipToPrevious()
+      // The receiver queue starts at the current track, so queuePreviousItem has nothing behind it — use core state instead.
+      await withPlayerQueueNoThrow { self.skipToPreviousCastInternal() }
       return
     }
     await withPlayerQueueNoThrow { self.skipToPreviousInternal() }
@@ -57,6 +58,7 @@ extension TrackPlayerCore {
     await withPlayerQueueNoThrow {
       self.currentRepeatMode = mode
       self.player?.actionAtItemEnd = (mode == .track) ? .none : .advance
+      if self.isCasting { self.castManager?.setQueueRepeatMode(mode) }
       NitroPlayerLogger.log("TrackPlayerCore", "🔁 setRepeatMode: \(mode)")
     }
   }

package/ios/core/TrackPlayerQueue.swift

@@ -20,11 +20,7 @@ extension TrackPlayerCore {
 
   func skipToIndex(index: Int) async -> Bool {
     if isCasting {
-      return await withPlayerQueueNoThrow {
-        guard index >= 0 && index < self.getActualQueueInternal().count else { return false }
-        self.castManager?.jump(toQueueIndex: index)
-        return true
-      }
+      return await withPlayerQueueNoThrow { self.skipToIndexCastInternal(index: index) }
     }
     return await withPlayerQueueNoThrow { self.skipToIndexInternal(index: index) }
   }
@@ -40,6 +36,29 @@ extension TrackPlayerCore {
   // MARK: - Internal (run on playerQueue)
 
   func getStateInternal() -> PlayerState {
+    // While casting, report the receiver's cached state — the local AVQueuePlayer is paused/stale.
+    if isCasting, let cast = castManager {
+      let currentTrack = getCurrentTrack()
+      let playingType: CurrentPlayingType
+      if currentTrack == nil { playingType = .notPlaying }
+      else {
+        switch currentTemporaryType {
+        case .none: playingType = .playlist
+        case .playNext: playingType = .playNext
+        case .upNext: playingType = .upNext
+        }
+      }
+      return PlayerState(
+        currentTrack: currentTrack.map { Variant_NullType_TrackItem.second($0) },
+        currentPosition: cast.lastKnownRemotePosition,
+        totalDuration: cast.lastKnownRemoteDuration,
+        currentState: cast.cachedPlaybackState,
+        currentPlaylistId: currentPlaylistId.map { Variant_NullType_String.second($0) },
+        currentIndex: currentTrackIndex >= 0 ? Double(currentTrackIndex) : -1.0,
+        currentPlayingType: playingType
+      )
+    }
+
     guard let player else {
       return PlayerState(
         currentTrack: nil, currentPosition: 0.0, totalDuration: 0.0,
@@ -96,7 +115,7 @@ extension TrackPlayerCore {
     if let current = getCurrentTrack() { queue.append(current) }
 
     // Add playNext stack — skip the currently playing track by ID (already added as current)
-    let currentId = player?.currentItem?.trackId
+    let currentId = activeCurrentTrackId
     if currentTemporaryType == .playNext, let currentId = currentId {
       var skipped = false
       for track in playNextStack {
@@ -126,10 +145,7 @@ extension TrackPlayerCore {
   }
 
   func getCurrentTrack() -> TrackItem? {
-    if currentTemporaryType != .none,
-      let currentItem = player?.currentItem,
-      let trackId = currentItem.trackId
-    {
+    if currentTemporaryType != .none, let trackId = activeCurrentTrackId {
       if currentTemporaryType == .playNext { return playNextStack.first(where: { $0.id == trackId }) }
       if currentTemporaryType == .upNext { return upNextQueue.first(where: { $0.id == trackId }) }
     }
@@ -222,7 +238,7 @@ extension TrackPlayerCore {
   }
 
   func determineCurrentTemporaryType() -> TemporaryType {
-    guard let trackId = player?.currentItem?.trackId else { return .none }
+    guard let trackId = activeCurrentTrackId else { return .none }
     if playNextStack.contains(where: { $0.id == trackId }) { return .playNext }
     if upNextQueue.contains(where: { $0.id == trackId }) { return .upNext }
     return .none

package/ios/core/TrackPlayerQueueBuild.swift

@@ -240,6 +240,12 @@ extension TrackPlayerCore {
   /// - Parameter changedTrackIds: When non-nil, performs a surgical update:
   ///   only AVPlayerItems whose track ID is in this set are removed and re-created.
   func rebuildAVQueueFromCurrentPosition(changedTrackIds: Set<String>? = nil) {
+    // While casting, queue changes are applied to the receiver — the local AVQueuePlayer is dormant.
+    if isCasting {
+      syncCastQueueAfterCurrent()
+      return
+    }
+
     guard let player = self.player else { return }
 
     let currentItem = player.currentItem

package/ios/core/TrackPlayerUrlLoader.swift

@@ -78,8 +78,8 @@ extension TrackPlayerCore {
     // Update in PlaylistManager
     let affectedPlaylists = self.playlistManager.updateTracks(tracks: safeTracks)
 
-    // If the current track had no URL and now has one, replace the current AVPlayerItem
-    if let update = currentTrack, currentTrackIsEmpty, !update.url.isEmpty {
+    // Replace the current AVPlayerItem when its URL just resolved (local only — cast reloads below instead).
+    if !self.isCasting, let update = currentTrack, currentTrackIsEmpty, !update.url.isEmpty {
       NitroPlayerLogger.log("TrackPlayerCore",
         "🔄 Replacing current AVPlayerItem for track with resolved URL: \(update.id)")
       if let newItem = self.createGaplessPlayerItem(for: update, isPreload: false) {
@@ -101,6 +101,30 @@ extension TrackPlayerCore {
           "📥 Synced currentTracks from PlaylistManager (\(self.currentTracks.count) tracks)")
       }
 
+      if self.isCasting {
+        // Resolved URLs are applied by (re)loading/extending the remote queue — never by touching the silent local player.
+        let currentResolvedNow = currentTrackIsEmpty
+          && currentTrackId.map { id in updatedTrackIds.contains(id) } ?? false
+        let staleOnReceiver = !updatedTrackIds
+          .isDisjoint(with: Set(self.castManager?.loadedTrackIds ?? []))
+
+        if currentResolvedNow || !(self.castManager?.hasLoadedMedia ?? false) {
+          // Parked track just became castable (or nothing loaded) — atomic load from current.
+          self.loadCastQueue(autoplay: self.intendedToPlay, position: 0)
+        } else if staleOnReceiver {
+          // URLs changed for items already on the receiver — reload at position before stale ones fail.
+          self.loadCastQueue(
+            autoplay: self.intendedToPlay,
+            position: self.castManager?.lastKnownRemotePosition ?? 0
+          )
+        } else {
+          // Newly castable tracks extend the receiver queue without interrupting playback.
+          self.syncCastQueueAfterCurrent()
+        }
+        NitroPlayerLogger.log("TrackPlayerCore", "✅ Cast queue synced after track updates")
+        return
+      }
+
       if self.player?.currentItem == nil, let player = self.player {
         // No AVPlayerItem exists yet — lazy-load mode: URLs were empty when the queue first loaded.
         NitroPlayerLogger.log("TrackPlayerCore",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "1.5.0-alpha.1",
+  "version": "1.5.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",