react-native-nitro-player 1.6.0-alpha.1 → 1.7.0-alpha.0

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaSessionManager.kt

@@ -1,10 +1,15 @@
 package com.margelo.nitro.nitroplayer.media
 
 import android.content.Context
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.CommandButton
 import androidx.media3.session.MediaSession
+import com.margelo.nitro.nitroplayer.R
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
+import java.text.NumberFormat
 
 /**
  * Thin wrapper around a [MediaSession] owned by the playback service.
@@ -12,11 +17,16 @@ import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
  * No longer creates the session, notification channel, or manages service
  * start/stop — the service handles all of that automatically per Media3 docs.
  */
+@UnstableApi
 class MediaSessionManager(
     private val context: Context,
     session: MediaSession,
     private val playlistManager: PlaylistManager,
 ) {
+    private companion object {
+        const val DEFAULT_REMOTE_SKIP_INTERVAL_MS = 15_000L
+    }
+
     private var trackPlayerCore: TrackPlayerCore? = null
 
     fun setTrackPlayerCore(core: TrackPlayerCore) {
@@ -32,15 +42,26 @@ class MediaSessionManager(
     private var androidAutoEnabled: Boolean = false
     private var carPlayEnabled: Boolean = false
     private var showInNotification: Boolean = true
+    private var remoteSkipForwardIntervalMs: Long = DEFAULT_REMOTE_SKIP_INTERVAL_MS
+    private var remoteSkipBackwardIntervalMs: Long = DEFAULT_REMOTE_SKIP_INTERVAL_MS
+
+    init {
+        updateMediaButtonPreferences()
+    }
 
     fun configure(
         androidAutoEnabled: Boolean?,
         carPlayEnabled: Boolean?,
         showInNotification: Boolean?,
+        remoteSkipForwardIntervalMs: Long,
+        remoteSkipBackwardIntervalMs: Long,
     ) {
         androidAutoEnabled?.let { this.androidAutoEnabled = it }
         carPlayEnabled?.let { this.carPlayEnabled = it }
         showInNotification?.let { this.showInNotification = it }
+        this.remoteSkipForwardIntervalMs = remoteSkipForwardIntervalMs
+        this.remoteSkipBackwardIntervalMs = remoteSkipBackwardIntervalMs
+        updateMediaButtonPreferences()
     }
 
     fun onTrackChanged(track: TrackItem?) {
@@ -55,4 +76,82 @@ class MediaSessionManager(
         // Service owns the session — just null out our reference
         mediaSession = null
     }
+
+    private fun updateMediaButtonPreferences() {
+        val session = mediaSession ?: return
+        // Preferences replace Media3's default layout — prev/next must be declared or they vanish
+        val preserved = session.mediaButtonPreferences.filterNot { it.isManagedButton() }
+        session.setMediaButtonPreferences(
+            listOf(previousTrackButton(), skipBackButton(), skipForwardButton(), nextTrackButton()) + preserved,
+        )
+    }
+
+    private fun previousTrackButton(): CommandButton =
+        CommandButton
+            .Builder(CommandButton.ICON_PREVIOUS)
+            .setPlayerCommand(Player.COMMAND_SEEK_TO_PREVIOUS)
+            .setDisplayName(context.getString(R.string.nitro_player_previous_track))
+            .build()
+
+    private fun nextTrackButton(): CommandButton =
+        CommandButton
+            .Builder(CommandButton.ICON_NEXT)
+            .setPlayerCommand(Player.COMMAND_SEEK_TO_NEXT)
+            .setDisplayName(context.getString(R.string.nitro_player_next_track))
+            .build()
+
+    private fun skipBackButton(): CommandButton =
+        CommandButton
+            .Builder(skipBackIcon(remoteSkipBackwardIntervalMs))
+            .setPlayerCommand(Player.COMMAND_SEEK_BACK)
+            .setDisplayName(
+                context.getString(
+                    R.string.nitro_player_skip_back_seconds,
+                    displaySeconds(remoteSkipBackwardIntervalMs),
+                ),
+            ).build()
+
+    private fun skipForwardButton(): CommandButton =
+        CommandButton
+            .Builder(skipForwardIcon(remoteSkipForwardIntervalMs))
+            .setPlayerCommand(Player.COMMAND_SEEK_FORWARD)
+            .setDisplayName(
+                context.getString(
+                    R.string.nitro_player_skip_forward_seconds,
+                    displaySeconds(remoteSkipForwardIntervalMs),
+                ),
+            ).build()
+
+    private fun CommandButton.isManagedButton(): Boolean =
+        playerCommand == Player.COMMAND_SEEK_BACK ||
+            playerCommand == Player.COMMAND_SEEK_FORWARD ||
+            playerCommand == Player.COMMAND_SEEK_TO_PREVIOUS ||
+            playerCommand == Player.COMMAND_SEEK_TO_NEXT
+
+    private fun skipBackIcon(intervalMs: Long): Int =
+        when (intervalMs) {
+            5_000L -> CommandButton.ICON_SKIP_BACK_5
+            10_000L -> CommandButton.ICON_SKIP_BACK_10
+            15_000L -> CommandButton.ICON_SKIP_BACK_15
+            30_000L -> CommandButton.ICON_SKIP_BACK_30
+            else -> CommandButton.ICON_SKIP_BACK
+        }
+
+    private fun skipForwardIcon(intervalMs: Long): Int =
+        when (intervalMs) {
+            5_000L -> CommandButton.ICON_SKIP_FORWARD_5
+            10_000L -> CommandButton.ICON_SKIP_FORWARD_10
+            15_000L -> CommandButton.ICON_SKIP_FORWARD_15
+            30_000L -> CommandButton.ICON_SKIP_FORWARD_30
+            else -> CommandButton.ICON_SKIP_FORWARD
+        }
+
+    private fun displaySeconds(intervalMs: Long): String =
+        NumberFormat
+            .getNumberInstance()
+            .apply {
+                maximumFractionDigits = 3
+                minimumFractionDigits = 0
+                isGroupingUsed = false
+            }.format(intervalMs / 1000.0)
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/PlaybackService.kt

@@ -1,5 +1,6 @@
 package com.margelo.nitro.nitroplayer.media
 
+import android.app.PendingIntent
 import android.content.Intent
 import android.os.Binder
 import android.os.Handler
@@ -32,6 +33,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
 
     companion object {
         const val ACTION_LOCAL_BIND = "com.margelo.nitro.nitroplayer.LOCAL_BIND"
+        const val EXTRA_STARTED_FROM_NOTIFICATION = "com.margelo.nitro.nitroplayer.STARTED_FROM_NOTIFICATION"
 
         @Volatile
         var notificationSmallIconResName: String? = null
@@ -84,6 +86,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         mediaSession = MediaSession
             .Builder(this, player)
             .setCallback(MediaSessionCallbackFactory.create(this, playlistManager))
+            .apply { buildSessionActivity()?.let { setSessionActivity(it) } }
             .build()
 
         val provider = DefaultMediaNotificationProvider.Builder(this).build()
@@ -104,7 +107,13 @@ class NitroPlayerPlaybackService : MediaSessionService() {
     private fun initCast() {
         try {
             val castContext = CastContext.getSharedInstance(this)
-            val castPlayer = CastPlayer(castContext, NitroMediaItemConverter())
+            val castPlayer =
+                CastPlayer(
+                    castContext,
+                    NitroMediaItemConverter(),
+                    ExoPlayerBuilder.DEFAULT_REMOTE_SKIP_INTERVAL_MS,
+                    ExoPlayerBuilder.DEFAULT_REMOTE_SKIP_INTERVAL_MS,
+                )
             castSessionController =
                 CastSessionController(
                     castContext = castContext,
@@ -119,6 +128,18 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         }
     }
 
+    // Content intent for the notification tap — newer Android has no fallback without it
+    private fun buildSessionActivity(): PendingIntent? {
+        val launch = packageManager.getLaunchIntentForPackage(packageName) ?: return null
+        launch.putExtra(EXTRA_STARTED_FROM_NOTIFICATION, true)
+        return PendingIntent.getActivity(
+            this,
+            0,
+            launch,
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+        )
+    }
+
     private fun applyNotificationSmallIcon() {
         val name = notificationSmallIconResName ?: return
         val provider = notificationProvider ?: return

package/android/src/main/java/com/margelo/nitro/nitroplayer/playlist/PlaylistManager.kt

@@ -28,7 +28,7 @@ class PlaylistManager private constructor(
 ) {
     private val playlists = ConcurrentHashMap<String, Playlist>()
     private val listeners = CopyOnWriteArrayList<(List<Playlist>, QueueOperation?) -> Unit>()
-    private val playlistListeners = mutableMapOf<String, CopyOnWriteArrayList<(Playlist, QueueOperation?) -> Unit>>()
+    private val playlistListeners = ConcurrentHashMap<String, CopyOnWriteArrayList<(Playlist, QueueOperation?) -> Unit>>()
     private var currentPlaylistId: String? = null
 
     private val saveScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
@@ -59,7 +59,8 @@ class PlaylistManager private constructor(
     }
 
     init {
-        // Don't load from file on init - only load when Android Auto needs it
+        // Synchronous so no mutation can race a late async load and be clobbered
+        loadPlaylistsFromFile()
     }
 
     /**
@@ -75,10 +76,7 @@ class PlaylistManager private constructor(
 
         playlists[id] = playlist
 
-        // Only cache for Android Auto if connected
-        if (NitroPlayerMediaBrowserService.isAndroidAutoConnected) {
-            scheduleSave()
-        }
+        scheduleSave()
         notifyPlaylistsChanged(QueueOperation.ADD)
         NitroPlayerMediaBrowserService.getInstance()?.onPlaylistsUpdated()
 
@@ -96,10 +94,7 @@ class PlaylistManager private constructor(
                 currentPlaylistId = null
             }
             playlistListeners.remove(playlistId)
-            // Only cache for Android Auto if connected
-            if (NitroPlayerMediaBrowserService.isAndroidAutoConnected) {
-                scheduleSave()
-            }
+            scheduleSave()
             notifyPlaylistsChanged(QueueOperation.REMOVE)
             NitroPlayerMediaBrowserService.getInstance()?.onPlaylistsUpdated()
             return true
@@ -117,18 +112,18 @@ class PlaylistManager private constructor(
         description: String? = null,
         artwork: String? = null,
     ): Boolean {
-        val playlist = playlists[playlistId] ?: return false
-        playlists[playlistId] =
-            playlist.copy(
-                name = name ?: playlist.name,
-                description = description ?: playlist.description,
-                artwork = artwork ?: playlist.artwork,
-            )
-
-        // Only cache for Android Auto if connected
-        if (NitroPlayerMediaBrowserService.isAndroidAutoConnected) {
-            scheduleSave()
-        }
+        // computeIfPresent: read-copy-put from two threads loses one edit
+        val updated =
+            playlists.computeIfPresent(playlistId) { _, playlist ->
+                playlist.copy(
+                    name = name ?: playlist.name,
+                    description = description ?: playlist.description,
+                    artwork = artwork ?: playlist.artwork,
+                )
+            } != null
+        if (!updated) return false
+
+        scheduleSave()
         notifyPlaylistChanged(playlistId, QueueOperation.UPDATE)
         notifyPlaylistsChanged(QueueOperation.UPDATE)
         NitroPlayerMediaBrowserService.getInstance()?.onPlaylistsUpdated()
@@ -154,19 +149,19 @@ class PlaylistManager private constructor(
         track: TrackItem,
         index: Int? = null,
     ): Boolean {
-        val playlist = playlists[playlistId] ?: return false
-        val tracks = playlist.tracks.toMutableList()
-        if (index != null && index >= 0 && index <= tracks.size) {
-            tracks.add(index, track)
-        } else {
-            tracks.add(track)
-        }
-        playlists[playlistId] = playlist.copy(tracks = tracks)
+        val added =
+            playlists.computeIfPresent(playlistId) { _, playlist ->
+                val tracks = playlist.tracks.toMutableList()
+                if (index != null && index >= 0 && index <= tracks.size) {
+                    tracks.add(index, track)
+                } else {
+                    tracks.add(track)
+                }
+                playlist.copy(tracks = tracks)
+            } != null
+        if (!added) return false
 
-        // Only cache for Android Auto if connected
-        if (NitroPlayerMediaBrowserService.isAndroidAutoConnected) {
-            scheduleSave()
-        }
+        scheduleSave()
         notifyPlaylistChanged(playlistId, QueueOperation.ADD)
         NitroPlayerMediaBrowserService.getInstance()?.onPlaylistUpdated(playlistId)
         return true
@@ -180,19 +175,19 @@ class PlaylistManager private constructor(
         tracks: List<TrackItem>,
         index: Int? = null,
     ): Boolean {
-        val playlist = playlists[playlistId] ?: return false
-        val currentTracks = playlist.tracks.toMutableList()
-        if (index != null && index >= 0 && index <= currentTracks.size) {
-            currentTracks.addAll(index, tracks)
-        } else {
-            currentTracks.addAll(tracks)
-        }
-        playlists[playlistId] = playlist.copy(tracks = currentTracks)
+        val added =
+            playlists.computeIfPresent(playlistId) { _, playlist ->
+                val currentTracks = playlist.tracks.toMutableList()
+                if (index != null && index >= 0 && index <= currentTracks.size) {
+                    currentTracks.addAll(index, tracks)
+                } else {
+                    currentTracks.addAll(tracks)
+                }
+                playlist.copy(tracks = currentTracks)
+            } != null
+        if (!added) return false
 
-        // Only cache for Android Auto if connected
-        if (NitroPlayerMediaBrowserService.isAndroidAutoConnected) {
-            scheduleSave()
-        }
+        scheduleSave()
         notifyPlaylistChanged(playlistId, QueueOperation.ADD)
         NitroPlayerMediaBrowserService.getInstance()?.onPlaylistUpdated(playlistId)
         return true
@@ -205,11 +200,15 @@ class PlaylistManager private constructor(
         playlistId: String,
         trackId: String,
     ): Boolean {
-        val playlist = playlists[playlistId] ?: return false
-        val tracks = playlist.tracks.toMutableList()
-        val removed = tracks.removeAll { it.id == trackId }
-        if (removed) {
-            playlists[playlistId] = playlist.copy(tracks = tracks)
+        var removed = false
+        playlists.computeIfPresent(playlistId) { _, playlist ->
+            val tracks = playlist.tracks.toMutableList()
+            if (tracks.removeAll { it.id == trackId }) {
+                removed = true
+                playlist.copy(tracks = tracks)
+            } else {
+                playlist
+            }
         }
 
         if (removed) {
@@ -229,15 +228,20 @@ class PlaylistManager private constructor(
         trackId: String,
         newIndex: Int,
     ): Boolean {
-        val playlist = playlists[playlistId] ?: return false
-        val tracks = playlist.tracks.toMutableList()
-        val oldIndex = tracks.indexOfFirst { it.id == trackId }
-        if (oldIndex < 0 || newIndex < 0 || newIndex >= tracks.size) {
-            return false
+        var reordered = false
+        playlists.computeIfPresent(playlistId) { _, playlist ->
+            val tracks = playlist.tracks.toMutableList()
+            val oldIndex = tracks.indexOfFirst { it.id == trackId }
+            if (oldIndex < 0 || newIndex < 0 || newIndex >= tracks.size) {
+                playlist
+            } else {
+                val track = tracks.removeAt(oldIndex)
+                tracks.add(newIndex, track)
+                reordered = true
+                playlist.copy(tracks = tracks)
+            }
         }
-        val track = tracks.removeAt(oldIndex)
-        tracks.add(newIndex, track)
-        playlists[playlistId] = playlist.copy(tracks = tracks)
+        if (!reordered) return false
 
         scheduleSave()
         notifyPlaylistChanged(playlistId, QueueOperation.UPDATE)
@@ -255,17 +259,19 @@ class PlaylistManager private constructor(
         val tracksMap = tracks.associateBy { it.id }
         val affectedPlaylists = mutableMapOf<String, Int>()
 
-        playlists.forEach { (playlistId, playlist) ->
-            var updateCount = 0
-            val newTracks =
-                playlist.tracks
-                    .map { track ->
+        for (playlistId in playlists.keys) {
+            playlists.computeIfPresent(playlistId) { _, playlist ->
+                var updateCount = 0
+                val newTracks =
+                    playlist.tracks.map { track ->
                         tracksMap[track.id]?.also { updateCount++ } ?: track
-                    }.toMutableList()
-
-            if (updateCount > 0) {
-                affectedPlaylists[playlistId] = updateCount
-                playlists[playlistId] = playlist.copy(tracks = newTracks)
+                    }
+                if (updateCount > 0) {
+                    affectedPlaylists[playlistId] = updateCount
+                    playlist.copy(tracks = newTracks)
+                } else {
+                    playlist
+                }
             }
         }
 
@@ -336,11 +342,19 @@ class PlaylistManager private constructor(
         playlistId: String,
         listener: (Playlist, QueueOperation?) -> Unit,
     ): () -> Unit {
-        val playlistListeners = playlistListeners.getOrPut(playlistId) { CopyOnWriteArrayList() }
+        val playlistListeners = playlistListeners.computeIfAbsent(playlistId) { CopyOnWriteArrayList() }
         playlistListeners.add(listener)
         return { playlistListeners.remove(listener) }
     }
 
+    private val anyPlaylistListeners = CopyOnWriteArrayList<(Playlist, QueueOperation?) -> Unit>()
+
+    /** Fires for changes to ANY playlist, including ones created after registration. */
+    fun addAnyPlaylistChangeListener(listener: (Playlist, QueueOperation?) -> Unit): () -> Unit {
+        anyPlaylistListeners.add(listener)
+        return { anyPlaylistListeners.remove(listener) }
+    }
+
     private fun notifyPlaylistsChanged(operation: QueueOperation?) {
         listeners.forEach { it(playlists.values.toList(), operation) }
     }
@@ -351,6 +365,7 @@ class PlaylistManager private constructor(
     ) {
         val playlist = playlists[playlistId] ?: return
         playlistListeners[playlistId]?.forEach { it(playlist, operation) }
+        anyPlaylistListeners.forEach { it(playlist, operation) }
     }
 
     // MARK: - Persistence

package/android/src/main/res/values/strings.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <string name="nitro_player_skip_back_seconds">Skip back %1$s seconds</string>
+  <string name="nitro_player_skip_forward_seconds">Skip forward %1$s seconds</string>
+  <string name="nitro_player_previous_track">Previous track</string>
+  <string name="nitro_player_next_track">Next track</string>
+</resources>

package/ios/HybridDownloadManager.swift

@@ -213,20 +213,30 @@ final class HybridDownloadManager: HybridDownloadManagerSpec {
 
   // MARK: - Event Callbacks
 
+  private var progressCallbackIds: [UUID] = []
+  private var stateChangeCallbackIds: [UUID] = []
+  private var completeCallbackIds: [UUID] = []
+
   func onDownloadProgress(callback: @escaping (DownloadProgress) -> Void) throws {
     NitroPlayerLogger.log("HybridDownloadManager", "onDownloadProgress callback registered")
-    core.addProgressCallback(callback)
+    progressCallbackIds.append(core.addProgressCallback(callback))
   }
 
   func onDownloadStateChange(
     callback: @escaping (String, String, DownloadState, DownloadError?) -> Void
   ) throws {
     NitroPlayerLogger.log("HybridDownloadManager", "onDownloadStateChange callback registered")
-    core.addStateChangeCallback(callback)
+    stateChangeCallbackIds.append(core.addStateChangeCallback(callback))
   }
 
   func onDownloadComplete(callback: @escaping (DownloadedTrack) -> Void) throws {
     NitroPlayerLogger.log("HybridDownloadManager", "onDownloadComplete callback registered")
-    core.addCompleteCallback(callback)
+    completeCallbackIds.append(core.addCompleteCallback(callback))
+  }
+
+  deinit {
+    progressCallbackIds.forEach { core.removeProgressCallback(id: $0) }
+    stateChangeCallbackIds.forEach { core.removeStateChangeCallback(id: $0) }
+    completeCallbackIds.forEach { core.removeCompleteCallback(id: $0) }
   }
 }

package/ios/HybridTrackPlayer.swift

@@ -98,7 +98,9 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
         androidAutoEnabled: config.androidAutoEnabled,
         carPlayEnabled: config.carPlayEnabled,
         showInNotification: config.showInNotification,
-        lookaheadCount: config.lookaheadCount.map { Int($0) }
+        lookaheadCount: config.lookaheadCount.map { Int($0) },
+        remoteSkipForwardInterval: config.remoteSkipForwardInterval,
+        remoteSkipBackwardInterval: config.remoteSkipBackwardInterval
       )
     }
   }
@@ -137,7 +139,7 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
 
   // MARK: - Playback speed
   func setPlaybackSpeed(speed: Double) throws -> Promise<Void> {
-    enqueue { self.core.setPlaybackSpeedOnQueue(speed) }
+    enqueueThrowing { try self.core.setPlaybackSpeedOnQueue(speed) }
   }
 
   func getPlaybackSpeed() throws -> Promise<Double> {
@@ -188,6 +190,10 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
     // No-op on iOS
   }
 
+  func appStartedWithNotification(callback: @escaping (_ track: TrackItem) -> Void) throws {
+    // No-op on iOS — Now Playing controls never launch the app
+  }
+
   func isAndroidAutoConnected() throws -> Bool { false }
 
   // MARK: - Event listeners (v2 — store IDs for cleanup)

package/ios/core/TrackPlayerCast.swift

@@ -67,13 +67,44 @@ extension TrackPlayerCore {
       guard let self else { return }
       guard self.isCasting else { return }
       let resumePosition = self.castManager?.lastKnownRemotePosition ?? 0
+      let remoteTrackId = self.castManager?.currentRemoteTrackId
       self.isCasting = false
 
       let index = self.currentTrackIndex
       guard index >= 0 && index < self.currentTracks.count else { return }
 
+      // rebuildQueueFromPlaylistIndex wipes the temp lists — preserve them
+      let savedPlayNext = self.playNextStack
+      let savedUpNext = self.upNextQueue
+
       _ = self.rebuildQueueFromPlaylistIndex(index: index)
-      if resumePosition.isFinite && resumePosition > 0 {
+
+      if !savedPlayNext.isEmpty || !savedUpNext.isEmpty {
+        self.playNextStack = savedPlayNext
+        self.upNextQueue = savedUpNext
+        self.rebuildAVQueueFromCurrentPosition()
+        self.notifyTemporaryQueueChange()
+      }
+
+      // If the receiver was playing the head temp track, make it current again
+      // (mirrors skipToNext: remove from its list before it becomes current)
+      if let target = remoteTrackId, target != self.player?.currentItem?.trackId {
+        if self.playNextStack.first?.id == target {
+          self.playNextStack.removeFirst()
+          self.player?.advanceToNextItem()
+          self.currentTemporaryType = .playNext
+          self.notifyTemporaryQueueChange()
+        } else if self.playNextStack.isEmpty, self.upNextQueue.first?.id == target {
+          self.upNextQueue.removeFirst()
+          self.player?.advanceToNextItem()
+          self.currentTemporaryType = .upNext
+          self.notifyTemporaryQueueChange()
+        }
+      }
+
+      // Only seek when the local current track is the one that was playing remotely
+      if resumePosition.isFinite && resumePosition > 0,
+        remoteTrackId != nil, self.player?.currentItem?.trackId == remoteTrackId {
         let time = CMTime(seconds: resumePosition, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
         self.player?.seek(to: time)
       }

package/ios/core/TrackPlayerCore.swift

@@ -65,6 +65,9 @@ class TrackPlayerCore: NSObject {
 
   // Gapless playback
   internal var preloadedAssets: [String: AVURLAsset] = [:]
+  // playerQueue-owned; bumped on every teardown so in-flight async preloads
+  // can't republish a stale asset into the cache after a queue switch
+  internal var preloadGeneration: Int = 0
   internal let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
   internal var didRequestUrlsForCurrentItem = false
 
@@ -149,14 +152,26 @@ class TrackPlayerCore: NSObject {
 
   internal func setupAudioSession() {
     do {
-      let audioSession = AVAudioSession.sharedInstance()
-      try audioSession.setCategory(.playback, mode: .default, options: [])
-      try audioSession.setActive(true)
+      // Category only — setActive(true) is deferred to first play so merely
+      // loading the module doesn't silence other apps' audio.
+      try AVAudioSession.sharedInstance().setCategory(.playback, mode: .default, options: [])
     } catch {
       NitroPlayerLogger.log("TrackPlayerCore", "❌ Failed to setup audio session - \(error)")
     }
   }
 
+  private var audioSessionActivated = false
+
+  internal func activateAudioSessionIfNeeded() {
+    guard !audioSessionActivated else { return }
+    do {
+      try AVAudioSession.sharedInstance().setActive(true)
+      audioSessionActivated = true
+    } catch {
+      NitroPlayerLogger.log("TrackPlayerCore", "❌ Failed to activate audio session - \(error)")
+    }
+  }
+
   // MARK: - withPlayerQueue (async bridge to player thread)
 
   internal func withPlayerQueue<T>(_ block: @escaping () throws -> T) async throws -> T {
@@ -261,6 +276,7 @@ class TrackPlayerCore: NSObject {
       self.pathMonitor = nil
       for asset in self.preloadedAssets.values { asset.cancelLoading() }
       self.preloadedAssets.removeAll()
+      self.preloadGeneration += 1
       self.failedItemRetryCounts.removeAll()
       self.redirectResolver.clear()
     }