react-native-nitro-player 0.4.1-alpha.0 → 0.5.1

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

@@ -50,6 +50,7 @@ class DownloadFileManager private constructor(
     fun createDownloadFile(
         trackId: String,
         storageLocation: StorageLocation,
+        extension: String = "mp3",
     ): File {
         val destinationDir =
             when (storageLocation) {
@@ -58,7 +59,7 @@ class DownloadFileManager private constructor(
             }
 
         // Create unique filename based on trackId
-        val fileName = "$trackId.mp3"
+        val fileName = "$trackId.$extension"
         return File(destinationDir, fileName)
     }
 
@@ -119,15 +120,17 @@ class DownloadFileManager private constructor(
 
     fun getLocalPath(trackId: String): String? {
         // Check private directory first
-        val privateFile = File(privateDownloadsDir, "$trackId.mp3")
-        if (privateFile.exists()) {
-            return privateFile.absolutePath
+        privateDownloadsDir.listFiles()?.forEach { file ->
+            if (file.nameWithoutExtension == trackId) {
+                return file.absolutePath
+            }
         }
 
         // Check public directory
-        val publicFile = File(publicDownloadsDir, "$trackId.mp3")
-        if (publicFile.exists()) {
-            return publicFile.absolutePath
+        publicDownloadsDir.listFiles()?.forEach { file ->
+            if (file.nameWithoutExtension == trackId) {
+                return file.absolutePath
+            }
         }
 
         return null

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

@@ -8,6 +8,7 @@ import androidx.core.app.NotificationCompat
 import androidx.work.CoroutineWorker
 import androidx.work.ForegroundInfo
 import androidx.work.WorkerParameters
+import android.webkit.MimeTypeMap
 import com.margelo.nitro.nitroplayer.*
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -122,16 +123,42 @@ class DownloadWorker(
                 if (responseCode != HttpURLConnection.HTTP_OK) {
                     throw Exception("Server returned HTTP $responseCode")
                 }
+                // Determine extension
+                var extension = MimeTypeMap.getFileExtensionFromUrl(urlString)
+
+                // 1. Try Content-Disposition
+                if (extension.isNullOrEmpty()) {
+                    val contentDisposition = connection.getHeaderField("Content-Disposition")
+                    if (contentDisposition != null) {
+                        val match = Regex("filename=\"?([^\";]+)\"?").find(contentDisposition)
+                        if (match != null) {
+                            val filename = match.groupValues[1]
+                            extension = MimeTypeMap.getFileExtensionFromUrl(filename)
+                        }
+                    }
+                }
+
+                // 2. Try Content-Type
+                if (extension.isNullOrEmpty()) {
+                    val contentType = connection.contentType
+                    if (contentType != null) {
+                        val mimeType = contentType.split(";")[0].trim()
+                        extension = MimeTypeMap.getSingleton().getExtensionFromMimeType(mimeType)
+                    }
+                }
+
+                val finalExtension = if (extension.isNullOrEmpty()) "mp3" else extension
 
-                val totalBytes = connection.contentLengthLong
-                var bytesDownloaded: Long = 0
 
                 // Create destination file
-                val destinationFile = fileManager.createDownloadFile(trackId, storageLocation)
+                val destinationFile = fileManager.createDownloadFile(trackId, storageLocation, finalExtension)
 
                 inputStream = BufferedInputStream(connection.inputStream)
                 outputStream = FileOutputStream(destinationFile)
 
+                val totalBytes = connection.contentLengthLong
+                var bytesDownloaded: Long = 0
+
                 val buffer = ByteArray(BUFFER_SIZE)
                 var bytesRead: Int
                 var lastProgressUpdate = System.currentTimeMillis()

package/ios/core/TrackPlayerCore.swift

@@ -125,9 +125,10 @@ class TrackPlayerCore: NSObject {
 
     // MARK: - Gapless Playback Configuration
 
-    // Disable automatic waiting to minimize stalling - this allows smoother transitions
-    // between tracks as AVPlayer won't pause to buffer excessively
-    player?.automaticallyWaitsToMinimizeStalling = false
+    // Start with stall-waiting enabled so the first track buffers before playing.
+    // Once the first item is ready (readyToPlay), this is flipped to false for
+    // gapless inter-track transitions (see setupCurrentItemObservers).
+    player?.automaticallyWaitsToMinimizeStalling = true
 
     // Set playback rate to 1.0 immediately when ready (reduces gap between tracks)
     player?.actionAtItemEnd = .advance
@@ -138,7 +139,7 @@ class TrackPlayerCore: NSObject {
     }
 
     print(
-      "🎵 TrackPlayerCore: Gapless playback configured - automaticallyWaitsToMinimizeStalling=false")
+      "🎵 TrackPlayerCore: Gapless playback configured - automaticallyWaitsToMinimizeStalling=true (flipped to false on first readyToPlay)")
 
     setupPlayerObservers()
   }
@@ -569,6 +570,8 @@ class TrackPlayerCore: NSObject {
       if item.status == .readyToPlay {
         print("✅ TrackPlayerCore: Item ready, setting up boundaries")
         self?.setupBoundaryTimeObserver()
+        // First item is buffered and ready — disable stall waiting for gapless inter-track transitions
+        self?.player?.automaticallyWaitsToMinimizeStalling = false
         // Update now playing info now that duration is available
         self?.mediaSessionManager?.updateNowPlayingInfo()
       } else if item.status == .failed {
@@ -736,12 +739,11 @@ class TrackPlayerCore: NSObject {
       asset = preloadedAsset
       print("🚀 TrackPlayerCore: Using preloaded asset for \(track.title)")
     } else {
-      // Create asset with options optimized for gapless playback
-      asset = AVURLAsset(
-        url: url,
-        options: [
-          AVURLAssetPreferPreciseDurationAndTimingKey: true  // Ensures accurate duration for gapless transitions
-        ])
+      // No AVURLAssetPreferPreciseDurationAndTimingKey — gapless playback is achieved via
+      // AVQueuePlayer's internal audio buffer pre-roll, not timing metadata.
+      // Precise timing only helps with accurate VBR duration display, at the cost of
+      // deep file scanning that delays readyToPlay.
+      asset = AVURLAsset(url: url)
     }
 
     let item = AVPlayerItem(asset: asset)
@@ -807,11 +809,7 @@ class TrackPlayerCore: NSObject {
 
         guard let url = URL(string: track.url) else { continue }
 
-        let asset = AVURLAsset(
-          url: url,
-          options: [
-            AVURLAssetPreferPreciseDurationAndTimingKey: true
-          ])
+        let asset = AVURLAsset(url: url)
 
         // Preload essential keys for gapless playback
         asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) { [weak self] in
@@ -1000,7 +998,7 @@ class TrackPlayerCore: NSObject {
     print("📋 TrackPlayerCore: UPDATE PLAYER QUEUE - Received \(tracks.count) tracks")
     print(String(repeating: "=", count: Constants.separatorLineLength))
 
-    // Print the full playlist being fed and check download status
+    #if DEBUG
     for (index, track) in tracks.enumerated() {
       let isDownloaded = DownloadManagerCore.shared.isTrackDownloaded(trackId: track.id)
       let downloadStatus = isDownloaded ? "📥 DOWNLOADED" : "🌐 REMOTE"
@@ -1013,6 +1011,7 @@ class TrackPlayerCore: NSObject {
       }
     }
     print(String(repeating: "=", count: Constants.separatorLineLength) + "\n")
+    #endif
 
     // Store tracks for index tracking
     currentTracks = tracks
@@ -1025,12 +1024,15 @@ class TrackPlayerCore: NSObject {
       boundaryTimeObserver = nil
     }
 
+    // Re-enable stall waiting for the new first track so it buffers before playing.
+    // Will be flipped back to false once the first item reaches readyToPlay.
+    player?.automaticallyWaitsToMinimizeStalling = true
+
     // Clear old preloaded assets when loading new queue
     preloadedAssets.removeAll()
 
     // Create gapless-optimized AVPlayerItems from tracks
     let items = tracks.enumerated().compactMap { (index, track) -> AVPlayerItem? in
-      // First few items get preload treatment for faster initial playback
       let isPreload = index < Constants.gaplessPreloadCount
       return createGaplessPlayerItem(for: track, isPreload: isPreload)
     }
@@ -1068,23 +1070,25 @@ class TrackPlayerCore: NSObject {
       }
     }
 
-    // Verify what's actually in the player now
+    #if DEBUG
+    let trackById = Dictionary(uniqueKeysWithValues: tracks.map { ($0.id, $0) })
     print(
       "\n🔍 TrackPlayerCore: VERIFICATION - Player now has \(existingPlayer.items().count) items:")
     for (index, item) in existingPlayer.items().enumerated() {
-      if let trackId = item.trackId, let track = tracks.first(where: { $0.id == trackId }) {
+      if let trackId = item.trackId, let track = trackById[trackId] {
         print("  [\(index + 1)] ✓ \(track.title) - \(track.artist) (ID: \(track.id))")
       } else {
         print("  [\(index + 1)] ⚠️ Unknown item (no trackId)")
       }
     }
-
-    if let currentItem = existingPlayer.currentItem, let trackId = currentItem.trackId {
-      if let track = tracks.first(where: { $0.id == trackId }) {
-        print("▶️  Current item: \(track.title)")
-      }
+    if let currentItem = existingPlayer.currentItem,
+      let trackId = currentItem.trackId,
+      let track = trackById[trackId]
+    {
+      print("▶️  Current item: \(track.title)")
     }
     print(String(repeating: "=", count: Constants.separatorLineLength) + "\n")
+    #endif
 
     // Note: Boundary time observers will be set up automatically when item becomes ready
     // This happens in setupCurrentItemObservers() -> status observer -> setupBoundaryTimeObserver()
@@ -1715,7 +1719,6 @@ class TrackPlayerCore: NSObject {
 
     // Create gapless-optimized player items
     let items = tracksToPlay.enumerated().compactMap { (offset, track) -> AVPlayerItem? in
-      // First few items get preload treatment for faster playback
       let isPreload = offset < Constants.gaplessPreloadCount
       return self.createGaplessPlayerItem(for: track, isPreload: isPreload)
     }
@@ -1731,6 +1734,10 @@ class TrackPlayerCore: NSObject {
       self.boundaryTimeObserver = nil
     }
 
+    // Re-enable stall waiting for the new first track so it buffers before playing.
+    // Will be flipped back to false once the first item reaches readyToPlay.
+    player.automaticallyWaitsToMinimizeStalling = true
+
     // Clear and rebuild queue
     player.removeAllItems()
     var lastItem: AVPlayerItem? = nil
@@ -1785,6 +1792,7 @@ class TrackPlayerCore: NSObject {
     if self.player?.currentItem != nil {
       self.rebuildAVQueueFromCurrentPosition()
     }
+    mediaSessionManager?.onQueueChanged()
   }
 
   /**
@@ -1814,6 +1822,7 @@ class TrackPlayerCore: NSObject {
     if self.player?.currentItem != nil {
       self.rebuildAVQueueFromCurrentPosition()
     }
+    mediaSessionManager?.onQueueChanged()
   }
 
   /**

package/ios/download/DownloadFileManager.swift

@@ -56,20 +56,28 @@ final class DownloadFileManager {
 
   func saveDownloadedFile(
     from temporaryLocation: URL, trackId: String, storageLocation: StorageLocation,
-    originalURL: String? = nil
+    originalURL: String? = nil,
+    suggestedFilename: String? = nil
   ) -> String? {
     print("🎯 DownloadFileManager: saveDownloadedFile called for trackId=\(trackId)")
     print("   From: \(temporaryLocation.path)")
     print("   Original URL: \(originalURL ?? "nil")")
+    print("   Suggested Filename: \(suggestedFilename ?? "nil")")
 
     let destinationDirectory =
       storageLocation == .private ? privateDownloadsDirectory : publicDownloadsDirectory
     print("   Destination directory: \(destinationDirectory.path)")
 
-    // Determine file extension from the original URL, not the temp file
-    // The temp file has .tmp extension which AVPlayer cannot play
+    // Determine file extension
     var fileExtension = "mp3"  // Default fallback
-    if let originalURL = originalURL, let url = URL(string: originalURL) {
+
+    if let suggestedFilename = suggestedFilename, !suggestedFilename.isEmpty {
+      let url = URL(fileURLWithPath: suggestedFilename)
+      let pathExtension = url.pathExtension.lowercased()
+      if !pathExtension.isEmpty {
+        fileExtension = pathExtension
+      }
+    } else if let originalURL = originalURL, let url = URL(string: originalURL) {
       let pathExtension = url.pathExtension.lowercased()
       if !pathExtension.isEmpty {
         fileExtension = pathExtension

package/ios/download/DownloadManagerCore.swift

@@ -681,11 +681,16 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
     let (storageLocation, originalURL) = queue.sync {
       (self.config.storageLocation ?? .private, self.trackMetadata[trackId]?.url)
     }
+
+    // Get suggested filename from response
+    let suggestedFilename = downloadTask.response?.suggestedFilename
+
     let destinationPath = DownloadFileManager.shared.saveDownloadedFile(
       from: location,
       trackId: trackId,
       storageLocation: storageLocation,
-      originalURL: originalURL
+      originalURL: originalURL,
+      suggestedFilename: suggestedFilename
     )
 
     // Now handle the rest asynchronously

package/ios/media/MediaSessionManager.swift

@@ -15,10 +15,6 @@ class MediaSessionManager {
   // MARK: - Constants
 
   private enum Constants {
-    // Seek intervals (in seconds)
-    static let seekInterval: Double = 10.0
-
-    // Artwork size
     static let artworkSize: CGFloat = 500.0
   }
 
@@ -27,10 +23,11 @@ class MediaSessionManager {
   private var trackPlayerCore: TrackPlayerCore?
   private var artworkCache: [String: UIImage] = [:]
 
-  private var androidAutoEnabled: Bool = false
-  private var carPlayEnabled: Bool = false
   private var showInNotification: Bool = true
 
+  // Tracks the artwork URL currently shown so we can discard stale async loads
+  private var lastArtworkUrl: String?
+
   init() {
     setupRemoteCommandCenter()
   }
@@ -44,47 +41,165 @@ class MediaSessionManager {
     carPlayEnabled: Bool?,
     showInNotification: Bool?
   ) {
-    if let androidAutoEnabled = androidAutoEnabled {
-      self.androidAutoEnabled = androidAutoEnabled
-    }
-    if let carPlayEnabled = carPlayEnabled {
-      self.carPlayEnabled = carPlayEnabled
-      // CarPlay is handled by the app's CarPlaySceneDelegate
-      // We just maintain the flag here for reference
-    }
     if let showInNotification = showInNotification {
       self.showInNotification = showInNotification
-      if showInNotification {
-        updateNowPlayingInfo()
+    }
+    refresh()
+  }
+
+  // MARK: - Single refresh entry point
+  //
+  // All public callbacks route here. Always dispatches to main thread so
+  // MPNowPlayingInfoCenter and MPRemoteCommandCenter are only touched from main.
+
+  func refresh() {
+    if Thread.isMainThread {
+      refreshInternal()
+    } else {
+      DispatchQueue.main.async { [weak self] in
+        self?.refreshInternal()
+      }
+    }
+  }
+
+  // Convenience aliases used by TrackPlayerCore call sites
+  func updateNowPlayingInfo() { refresh() }
+  func onTrackChanged() { refresh() }
+  func onPlaybackStateChanged() { refresh() }
+  func onQueueChanged() { refresh() }
+
+  // MARK: - Core internal update (main thread only)
+
+  private func refreshInternal() {
+    guard showInNotification else {
+      clearNowPlayingInfo()
+      disableAllCommands()
+      return
+    }
+
+    guard let core = trackPlayerCore,
+      let track = core.getCurrentTrack()
+    else {
+      clearNowPlayingInfo()
+      disableAllCommands()
+      return
+    }
+
+    // Fetch snapshot once — both calls are cheap on main thread (no sync overhead)
+    let state = core.getState()
+    let queue = core.getActualQueue()
+
+    // Find the actual position of the current track inside the actual queue.
+    // state.currentIndex is the original-playlist index which is wrong when a
+    // temp (playNext / upNext) track is playing.
+    let positionInQueue = queue.firstIndex(where: { $0.id == track.id }) ?? -1
+
+    updateNowPlayingInfoInternal(track: track, state: state, queue: queue, positionInQueue: positionInQueue)
+    updateCommandCenterState(state: state, queue: queue, positionInQueue: positionInQueue)
+  }
+
+  // MARK: - Now Playing Info
+
+  private func updateNowPlayingInfoInternal(
+    track: TrackItem,
+    state: PlayerState,
+    queue: [TrackItem],
+    positionInQueue: Int
+  ) {
+    let playerDuration = state.totalDuration
+    let effectiveDuration: Double
+    if playerDuration > 0 && !playerDuration.isNaN && !playerDuration.isInfinite {
+      effectiveDuration = playerDuration
+    } else if track.duration > 0 {
+      effectiveDuration = track.duration
+    } else {
+      effectiveDuration = 0
+    }
+
+    let currentPosition = state.currentPosition
+    let safePosition = currentPosition.isNaN || currentPosition.isInfinite ? 0 : currentPosition
+    let isPlaying = state.currentState == .playing
+
+    var nowPlayingInfo: [String: Any] = [
+      MPMediaItemPropertyTitle: track.title,
+      MPMediaItemPropertyArtist: track.artist,
+      MPMediaItemPropertyAlbumTitle: track.album,
+      MPNowPlayingInfoPropertyElapsedPlaybackTime: safePosition,
+      MPMediaItemPropertyPlaybackDuration: effectiveDuration,
+      MPNowPlayingInfoPropertyPlaybackRate: isPlaying ? 1.0 : 0.0,
+      MPNowPlayingInfoPropertyDefaultPlaybackRate: 1.0,
+      MPNowPlayingInfoPropertyPlaybackQueueCount: max(1, queue.count),
+      MPNowPlayingInfoPropertyPlaybackQueueIndex: max(0, positionInQueue),
+    ]
+
+    // Artwork: use cache synchronously when available, otherwise kick off async load
+    if let artwork = track.artwork, case .second(let artworkUrl) = artwork {
+      lastArtworkUrl = artworkUrl
+      if let cachedImage = artworkCache[artworkUrl] {
+        nowPlayingInfo[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(
+          boundsSize: CGSize(width: Constants.artworkSize, height: Constants.artworkSize),
+          requestHandler: { _ in cachedImage }
+        )
       } else {
-        clearNowPlayingInfo()
+        // Write info first without artwork, then patch it in when loaded
+        MPNowPlayingInfoCenter.default().nowPlayingInfo = nowPlayingInfo
+        loadArtwork(url: artworkUrl) { [weak self] image in
+          guard let self = self, let image = image else { return }
+          // Discard if track changed while loading
+          guard self.lastArtworkUrl == artworkUrl else { return }
+          var updated = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
+          updated[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(
+            boundsSize: CGSize(width: Constants.artworkSize, height: Constants.artworkSize),
+            requestHandler: { _ in image }
+          )
+          MPNowPlayingInfoCenter.default().nowPlayingInfo = updated
+        }
+        return
       }
+    } else {
+      lastArtworkUrl = nil
     }
+
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nowPlayingInfo
   }
 
+  // MARK: - Command Center State
+
   private func setupRemoteCommandCenter() {
     let commandCenter = MPRemoteCommandCenter.shared()
 
-    // Play command
+    // Clear any previously registered targets before adding fresh ones.
+    // Prevents duplicate handlers if this were ever called more than once.
+    commandCenter.playCommand.removeTarget(nil)
+    commandCenter.pauseCommand.removeTarget(nil)
+    commandCenter.togglePlayPauseCommand.removeTarget(nil)
+    commandCenter.nextTrackCommand.removeTarget(nil)
+    commandCenter.previousTrackCommand.removeTarget(nil)
+    commandCenter.seekForwardCommand.removeTarget(nil)
+    commandCenter.seekBackwardCommand.removeTarget(nil)
+    commandCenter.changePlaybackPositionCommand.removeTarget(nil)
+
+    // Play
     commandCenter.playCommand.isEnabled = true
     commandCenter.playCommand.addTarget { [weak self] _ in
-      self?.trackPlayerCore?.play()
+      guard let core = self?.trackPlayerCore else { return .commandFailed }
+      core.play()
       return .success
     }
 
-    // Pause command
+    // Pause
     commandCenter.pauseCommand.isEnabled = true
     commandCenter.pauseCommand.addTarget { [weak self] _ in
-      self?.trackPlayerCore?.pause()
+      guard let core = self?.trackPlayerCore else { return .commandFailed }
+      core.pause()
       return .success
     }
 
     // Toggle play/pause
     commandCenter.togglePlayPauseCommand.isEnabled = true
     commandCenter.togglePlayPauseCommand.addTarget { [weak self] _ in
-      guard let self = self, let core = self.trackPlayerCore else { return .commandFailed }
-      let state = core.getState()
-      if state.currentState == .playing {
+      guard let core = self?.trackPlayerCore else { return .commandFailed }
+      if core.getState().currentState == .playing {
         core.pause()
       } else {
         core.play()
@@ -92,27 +207,28 @@ class MediaSessionManager {
       return .success
     }
 
-    // Next track command
-    commandCenter.nextTrackCommand.isEnabled = true
+    // Next track — isEnabled managed dynamically in updateCommandCenterState
+    commandCenter.nextTrackCommand.isEnabled = false
     commandCenter.nextTrackCommand.addTarget { [weak self] _ in
-      self?.trackPlayerCore?.skipToNext()
+      guard let core = self?.trackPlayerCore else { return .commandFailed }
+      core.skipToNext()
       return .success
     }
 
-    // Previous track command
-    commandCenter.previousTrackCommand.isEnabled = true
+    // Previous track — isEnabled managed dynamically in updateCommandCenterState
+    commandCenter.previousTrackCommand.isEnabled = false
     commandCenter.previousTrackCommand.addTarget { [weak self] _ in
-      self?.trackPlayerCore?.skipToPrevious()
+      guard let core = self?.trackPlayerCore else { return .commandFailed }
+      core.skipToPrevious()
       return .success
     }
 
-    // Disable continuous seek commands - they replace the interactive scrubber
-    // with non-interactive forward/backward buttons on the lock screen
+    // Disable skip-forward/backward — these replace the scrubber with non-interactive buttons
     commandCenter.seekForwardCommand.isEnabled = false
     commandCenter.seekBackwardCommand.isEnabled = false
 
-    // Change playback position (interactive scrubber)
-    commandCenter.changePlaybackPositionCommand.isEnabled = true
+    // Scrubber — isEnabled managed dynamically based on known duration
+    commandCenter.changePlaybackPositionCommand.isEnabled = false
     commandCenter.changePlaybackPositionCommand.addTarget { [weak self] event in
       guard let self = self,
         let core = self.trackPlayerCore,
@@ -120,11 +236,10 @@ class MediaSessionManager {
       else {
         return .commandFailed
       }
-      // Immediately update elapsed time AND set playback rate to 0 during seek
-      // This prevents the scrubber from freezing/desyncing during the async seek operation
+      // Optimistically freeze the scrubber at the tapped position while the async
+      // seek is in flight — updateNowPlayingInfo in the seek completion restores it.
       if var info = MPNowPlayingInfoCenter.default().nowPlayingInfo {
         info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = positionEvent.positionTime
-        // Set rate to 0 to pause scrubber animation during seek
         info[MPNowPlayingInfoPropertyPlaybackRate] = 0.0
         MPNowPlayingInfoCenter.default().nowPlayingInfo = info
       }
@@ -133,73 +248,43 @@ class MediaSessionManager {
     }
   }
 
-  private func getCurrentTrack() -> TrackItem? {
-    return trackPlayerCore?.getCurrentTrack()
-  }
-
-  func updateNowPlayingInfo() {
-    guard showInNotification else { return }
-
-    guard let track = getCurrentTrack(),
-      let core = trackPlayerCore
-    else {
-      clearNowPlayingInfo()
-      return
-    }
-
-    let state = core.getState()
+  private func updateCommandCenterState(
+    state: PlayerState,
+    queue: [TrackItem],
+    positionInQueue: Int
+  ) {
+    let commandCenter = MPRemoteCommandCenter.shared()
+    let hasCurrentTrack = positionInQueue >= 0
+    let isNotLast = positionInQueue < queue.count - 1
 
-    // Use player duration if valid, otherwise fall back to track metadata duration.
-    // Duration must always be present for the lock screen scrubber to be interactive.
     let playerDuration = state.totalDuration
-    let effectiveDuration: Double
-    if playerDuration > 0 && !playerDuration.isNaN && !playerDuration.isInfinite {
-      effectiveDuration = playerDuration
-    } else {
-      effectiveDuration = track.duration
-    }
+    let hasDuration = playerDuration > 0 && !playerDuration.isNaN && !playerDuration.isInfinite
 
-    var nowPlayingInfo: [String: Any] = [
-      MPMediaItemPropertyTitle: track.title,
-      MPMediaItemPropertyArtist: track.artist,
-      MPMediaItemPropertyAlbumTitle: track.album,
-      MPNowPlayingInfoPropertyElapsedPlaybackTime: state.currentPosition,
-      MPMediaItemPropertyPlaybackDuration: effectiveDuration,
-      MPNowPlayingInfoPropertyPlaybackRate: state.currentState == .playing ? 1.0 : 0.0,
-    ]
+    // Next: only enabled when there is a track after the current one
+    commandCenter.nextTrackCommand.isEnabled = hasCurrentTrack && isNotLast
 
-    // Add artwork synchronously if cached, otherwise load async
-    if let artwork = track.artwork, case .second(let artworkUrl) = artwork {
-      if let cachedImage = artworkCache[artworkUrl] {
-        // Artwork is cached - include it directly to avoid overwrite race condition
-        nowPlayingInfo[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(
-          boundsSize: CGSize(width: Constants.artworkSize, height: Constants.artworkSize),
-          requestHandler: { _ in cachedImage }
-        )
-      } else {
-        // Artwork not cached - load asynchronously and update later
-        loadArtwork(url: artworkUrl) { [weak self] image in
-          guard let self = self, let image = image else { return }
-          // Re-read current nowPlayingInfo to avoid overwriting other updates
-          var updatedInfo = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
-          updatedInfo[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(
-            boundsSize: CGSize(width: Constants.artworkSize, height: Constants.artworkSize),
-            requestHandler: { _ in image }
-          )
-          MPNowPlayingInfoCenter.default().nowPlayingInfo = updatedInfo
-        }
-      }
-    }
+    // Previous: always enabled when something is playing — either restarts current or goes back
+    commandCenter.previousTrackCommand.isEnabled = hasCurrentTrack
 
-    MPNowPlayingInfoCenter.default().nowPlayingInfo = nowPlayingInfo
+    // Scrubber: only enabled when we have a known, finite duration
+    commandCenter.changePlaybackPositionCommand.isEnabled = hasCurrentTrack && hasDuration
+  }
+
+  private func disableAllCommands() {
+    let commandCenter = MPRemoteCommandCenter.shared()
+    commandCenter.nextTrackCommand.isEnabled = false
+    commandCenter.previousTrackCommand.isEnabled = false
+    commandCenter.changePlaybackPositionCommand.isEnabled = false
   }
 
+  // MARK: - Helpers
+
   private func clearNowPlayingInfo() {
     MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    lastArtworkUrl = nil
   }
 
   private func loadArtwork(url: String, completion: @escaping (UIImage?) -> Void) {
-    // Check cache first
     if let cached = artworkCache[url] {
       completion(cached)
       return
@@ -210,33 +295,21 @@ class MediaSessionManager {
       return
     }
 
-    // Load image asynchronously
     URLSession.shared.dataTask(with: imageUrl) { [weak self] data, _, _ in
-      guard let data = data,
-        let image = UIImage(data: data)
-      else {
-        completion(nil)
+      guard let data = data, let image = UIImage(data: data) else {
+        DispatchQueue.main.async { completion(nil) }
         return
       }
-
-      // Cache the image
-      self?.artworkCache[url] = image
       DispatchQueue.main.async {
+        self?.artworkCache[url] = image
         completion(image)
       }
     }.resume()
   }
 
-  func onTrackChanged() {
-    updateNowPlayingInfo()
-  }
-
-  func onPlaybackStateChanged() {
-    updateNowPlayingInfo()
-  }
-
   func release() {
     clearNowPlayingInfo()
+    disableAllCommands()
     artworkCache.removeAll()
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-nitro-player",
-  "version": "0.4.1-alpha.0",
-  "description": "react-native-nitro-player",
+  "version": "0.5.1",
+  "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",
   "types": "lib/index.d.ts",