react-native-nitro-player 0.5.6 → 0.5.7

package/ios/core/TrackPlayerCore.swift

@@ -50,6 +50,7 @@ class TrackPlayerCore: NSObject {
   private var currentTracks: [TrackItem] = []
   private var isManuallySeeked = false
   private var currentRepeatMode: RepeatMode = .off
+  private var lookaheadCount: Int = 5  // Number of tracks to preload ahead
   private var boundaryTimeObserver: Any?
   private var currentItemObservers: [NSKeyValueObservation] = []
 
@@ -310,6 +311,9 @@ class TrackPlayerCore: NSObject {
     if let player = player {
       NitroPlayerLogger.log("TrackPlayerCore", "📋 Remaining items in queue: \(player.items().count)")
     }
+
+    // Check if upcoming tracks need URLs
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
   }
 
   @objc private func playerItemFailedToPlayToEndTime(notification: Notification) {
@@ -571,6 +575,14 @@ class TrackPlayerCore: NSObject {
       }
     }
   }
+  
+  func setPlaybackSpeed(_ speed: Double) {
+    player?.rate = Float(speed)
+  }
+  
+  func getPlaybackSpeed() -> Double {
+    return Double(player?.rate ?? 1.0)
+  }
 
   private func loadPlaylistInternal(playlistId: String) {
     NitroPlayerLogger.log("TrackPlayerCore", "\n" + String(repeating: "🎼", count: Constants.playlistSeparatorLength))
@@ -596,6 +608,9 @@ class TrackPlayerCore: NSObject {
       self.updatePlayerQueue(tracks: playlist.tracks)
       // Emit initial state (paused/stopped before play)
       self.emitStateChange()
+
+      // Check if upcoming tracks need URLs
+      self.checkUpcomingTracksForUrls(lookahead: lookaheadCount)
     } else {
       NitroPlayerLogger.log("TrackPlayerCore", "   ❌ Playlist NOT FOUND")
       NitroPlayerLogger.log("TrackPlayerCore", String(repeating: "🎼", count: Constants.playlistSeparatorLength) + "\n")
@@ -1301,6 +1316,9 @@ class TrackPlayerCore: NSObject {
       queuePlayer.pause()
       self.notifyPlaybackStateChange(.stopped, .end)
     }
+
+    // Check if upcoming tracks need URLs
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
   }
 
   func skipToPrevious() {
@@ -1343,6 +1361,9 @@ class TrackPlayerCore: NSObject {
       // Already at first track, restart it
       queuePlayer.seek(to: .zero)
     }
+
+    // Check if upcoming tracks need URLs
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
   }
 
   func seek(position: Double) {
@@ -1469,9 +1490,14 @@ class TrackPlayerCore: NSObject {
   func configure(
     androidAutoEnabled: Bool?,
     carPlayEnabled: Bool?,
-    showInNotification: Bool?
+    showInNotification: Bool?,
+    lookaheadCount: Int? = nil
   ) {
     DispatchQueue.main.async { [weak self] in
+      if let lookahead = lookaheadCount {
+        self?.lookaheadCount = lookahead
+        NitroPlayerLogger.log("TrackPlayerCore", "🔄 Lookahead count set to: \(lookahead)")
+      }
       self?.mediaSessionManager?.configure(
         androidAutoEnabled: androidAutoEnabled,
         carPlayEnabled: carPlayEnabled,
@@ -1619,9 +1645,17 @@ class TrackPlayerCore: NSObject {
       upNextQueue.removeAll()
       currentTemporaryType = .none
 
-      return playFromIndexInternalWithResult(index: originalIndex)
+      let result = playFromIndexInternalWithResult(index: originalIndex)
+
+      // Check if upcoming tracks need URLs
+      checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+
+      return result
     }
 
+    // Check if upcoming tracks need URLs after any successful skip
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+
     return false
   }
 
@@ -1857,6 +1891,224 @@ class TrackPlayerCore: NSObject {
     return .none
   }
 
+  // MARK: - Lazy URL Loading Support
+
+  /**
+   * Update entire track objects and rebuild queue if needed
+   * Skips currently playing track to preserve gapless playback
+   * CRITICAL: Invalidates preloaded assets and re-preloads for gapless
+   */
+  func updateTracks(tracks: [TrackItem]) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+
+      NitroPlayerLogger.log("TrackPlayerCore", "🔄 updateTracks: \(tracks.count) updates")
+
+      // Get current track ID to avoid updating it (preserves gapless playback)
+      let currentTrackId = self.getCurrentTrack()?.id
+
+      // Filter out current track and validate
+      let safeTracks = tracks.filter { track in
+        switch true {
+        case track.id == currentTrackId:
+          NitroPlayerLogger.log(
+            "TrackPlayerCore",
+            "⚠️ Skipping update for currently playing track: \(track.id) (preserves gapless)")
+          return false
+        case track.url.isEmpty:
+          NitroPlayerLogger.log(
+            "TrackPlayerCore", "⚠️ Skipping track with empty URL: \(track.id)")
+          return false
+        default:
+          return true
+        }
+      }
+
+      guard !safeTracks.isEmpty else {
+        NitroPlayerLogger.log("TrackPlayerCore", "✅ No valid updates to apply")
+        return
+      }
+
+      // Invalidate preloaded assets for tracks with updated data
+      // This is CRITICAL for gapless playback - old assets might use old URLs
+      let updatedTrackIds = Set(safeTracks.map { $0.id })
+      for trackId in updatedTrackIds {
+        if self.preloadedAssets[trackId] != nil {
+          NitroPlayerLogger.log(
+            "TrackPlayerCore", "🗑️ Invalidating preloaded asset for track: \(trackId)")
+          self.preloadedAssets.removeValue(forKey: trackId)
+        }
+      }
+
+      // Update in PlaylistManager
+      let affectedPlaylists = self.playlistManager.updateTracks(tracks: safeTracks)
+
+      // Rebuild queue if current playlist was affected
+      if let currentId = self.currentPlaylistId,
+        let updateCount = affectedPlaylists[currentId]
+      {
+        NitroPlayerLogger.log(
+          "TrackPlayerCore",
+          "🔄 Rebuilding queue - \(updateCount) tracks updated in current playlist")
+
+        // This method preserves current item
+        self.rebuildAVQueueFromCurrentPosition()
+
+        // Re-preload upcoming tracks for gapless playback
+        // CRITICAL: This restores gapless buffering after queue rebuild
+        self.preloadUpcomingTracks(from: self.currentTrackIndex + 1)
+
+        NitroPlayerLogger.log("TrackPlayerCore", "✅ Queue rebuilt, gapless playback preserved")
+      }
+
+      NitroPlayerLogger.log(
+        "TrackPlayerCore",
+        "✅ Track updates complete - \(affectedPlaylists.count) playlists affected")
+    }
+  }
+
+  /**
+   * Get tracks by IDs from all playlists
+   */
+  func getTracksById(trackIds: [String]) -> [TrackItem] {
+    if Thread.isMainThread {
+      return playlistManager.getTracksById(trackIds: trackIds)
+    } else {
+      var tracks: [TrackItem] = []
+      DispatchQueue.main.sync { [weak self] in
+        tracks = self?.playlistManager.getTracksById(trackIds: trackIds) ?? []
+      }
+      return tracks
+    }
+  }
+
+  /**
+   * Get tracks needing URLs from current playlist
+   */
+  func getTracksNeedingUrls() -> [TrackItem] {
+    if Thread.isMainThread {
+      return getTracksNeedingUrlsInternal()
+    } else {
+      var tracks: [TrackItem] = []
+      DispatchQueue.main.sync { [weak self] in
+        tracks = self?.getTracksNeedingUrlsInternal() ?? []
+      }
+      return tracks
+    }
+  }
+
+  private func getTracksNeedingUrlsInternal() -> [TrackItem] {
+    guard let currentId = currentPlaylistId,
+      let playlist = playlistManager.getPlaylist(playlistId: currentId)
+    else {
+      return []
+    }
+
+    return playlist.tracks.filter { $0.url.isEmpty }
+  }
+
+  /**
+   * Get next N tracks from current position
+   */
+  func getNextTracks(count: Int) -> [TrackItem] {
+    if Thread.isMainThread {
+      return getNextTracksInternal(count: count)
+    } else {
+      var tracks: [TrackItem] = []
+      DispatchQueue.main.sync { [weak self] in
+        tracks = self?.getNextTracksInternal(count: count) ?? []
+      }
+      return tracks
+    }
+  }
+
+  private func getNextTracksInternal(count: Int) -> [TrackItem] {
+    let actualQueue = getActualQueueInternal()
+    guard !actualQueue.isEmpty else { return [] }
+
+    guard let currentTrack = getCurrentTrack(),
+      let currentIndex = actualQueue.firstIndex(where: { $0.id == currentTrack.id })
+    else {
+      return []
+    }
+
+    let startIndex = currentIndex + 1
+    let endIndex = min(startIndex + count, actualQueue.count)
+
+    return startIndex < actualQueue.count ? Array(actualQueue[startIndex..<endIndex]) : []
+  }
+
+  /**
+   * Get current track index in playlist
+   */
+  func getCurrentTrackIndex() -> Int {
+    if Thread.isMainThread {
+      return currentTrackIndex
+    } else {
+      var index = -1
+      DispatchQueue.main.sync { [weak self] in
+        index = self?.currentTrackIndex ?? -1
+      }
+      return index
+    }
+  }
+
+  /**
+   * Callback for tracks needing update
+   */
+  typealias OnTracksNeedUpdateCallback = ([TrackItem], Int) -> Void
+
+  // Add to class properties
+  private var onTracksNeedUpdateListeners: [(callback: OnTracksNeedUpdateCallback, isAlive: Bool)] =
+    []
+  private let tracksNeedUpdateQueue = DispatchQueue(
+    label: "com.nitroplayer.tracksneedupdate", attributes: .concurrent)
+
+  /**
+   * Register listener for when tracks need update
+   */
+  func addOnTracksNeedUpdateListener(callback: @escaping OnTracksNeedUpdateCallback) {
+    tracksNeedUpdateQueue.async(flags: .barrier) { [weak self] in
+      self?.onTracksNeedUpdateListeners.append((callback: callback, isAlive: true))
+    }
+  }
+
+  /**
+   * Notify listeners that tracks need updating
+   */
+  private func notifyTracksNeedUpdate(tracks: [TrackItem], lookahead: Int) {
+    tracksNeedUpdateQueue.async(flags: .barrier) { [weak self] in
+      guard let self = self else { return }
+
+      // Clean up dead listeners
+      self.onTracksNeedUpdateListeners.removeAll { !$0.isAlive }
+      let liveCallbacks = self.onTracksNeedUpdateListeners.map { $0.callback }
+
+      if !liveCallbacks.isEmpty {
+        DispatchQueue.main.async {
+          for callback in liveCallbacks {
+            callback(tracks, lookahead)
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if upcoming tracks need URLs and notify listeners
+   * Call this in playerItemDidPlayToEndTime or after skip operations
+   */
+  private func checkUpcomingTracksForUrls(lookahead: Int = 5) {
+    let nextTracks = getNextTracksInternal(count: lookahead)
+    let tracksNeedingUrls = nextTracks.filter { $0.url.isEmpty }
+
+    if !tracksNeedingUrls.isEmpty {
+      NitroPlayerLogger.log(
+        "TrackPlayerCore", "⚠️ \(tracksNeedingUrls.count) upcoming tracks need URLs")
+      notifyTracksNeedUpdate(tracks: tracksNeedingUrls, lookahead: lookahead)
+    }
+  }
+
   // MARK: - Cleanup
 
   deinit {

package/ios/playlist/PlaylistManager.swift

@@ -274,6 +274,74 @@ class PlaylistManager {
     return true
   }
 
+  /**
+   * Update entire track objects across all playlists
+   * Matches by track.id and replaces the entire track object
+   * @param tracks Array of full TrackItem objects to update
+   * @return Dictionary of playlistId -> count of tracks updated
+   */
+  func updateTracks(tracks: [TrackItem]) -> [String: Int] {
+    let tracksMap = Dictionary(uniqueKeysWithValues: tracks.map { ($0.id, $0) })
+    var affectedPlaylists: [String: Int] = [:]
+
+    queue.sync {
+      for (playlistId, playlist) in playlists {
+        var updateCount = 0
+        let newTracks = playlist.tracks.map { track -> TrackItem in
+          if let updatedTrack = tracksMap[track.id] {
+            updateCount += 1
+            return updatedTrack
+          }
+          return track
+        }
+
+        if updateCount > 0 {
+          affectedPlaylists[playlistId] = updateCount
+          playlists[playlistId] = PlaylistModel(
+            id: playlist.id,
+            name: playlist.name,
+            description: playlist.description,
+            artwork: playlist.artwork,
+            tracks: newTracks
+          )
+        }
+      }
+    }
+
+    if !affectedPlaylists.isEmpty {
+      scheduleSave()
+      affectedPlaylists.keys.forEach { playlistId in
+        notifyPlaylistChanged(playlistId, .update)
+      }
+      notifyPlaylistsChanged(.update)
+    }
+
+    return affectedPlaylists
+  }
+
+  /**
+   * Get tracks by IDs from all playlists
+   * @param trackIds Array of track IDs to fetch
+   * @return Array of matching TrackItem objects
+   */
+  func getTracksById(trackIds: [String]) -> [TrackItem] {
+    let trackIdSet = Set(trackIds)
+    var foundTracks: [String: TrackItem] = [:]
+
+    queue.sync {
+      for playlist in playlists.values {
+        for track in playlist.tracks {
+          if trackIdSet.contains(track.id) && foundTracks[track.id] == nil {
+            foundTracks[track.id] = track
+          }
+        }
+      }
+    }
+
+    // Return in same order as requested
+    return trackIds.compactMap { foundTracks[$0] }
+  }
+
   /**
    * Get the current playlist ID
    */

package/lib/specs/TrackPlayer.nitro.d.ts

@@ -44,4 +44,51 @@ export interface TrackPlayer extends HybridObject<{
     onAndroidAutoConnectionChange(callback: (connected: boolean) => void): void;
     isAndroidAutoConnected(): boolean;
     setVolume(volume: number): boolean;
+    /**
+     * Update entire track objects across all playlists
+     * Matches by track.id and updates all properties (url, artwork, title, etc.)
+     * Note: Empty string "" is valid for TrackItem.url to support lazy loading
+     * @param tracks Array of full TrackItem objects to update
+     * @returns Promise that resolves when updates complete
+     */
+    updateTracks(tracks: TrackItem[]): Promise<void>;
+    /**
+     * Get tracks by IDs from all playlists
+     * @param trackIds Array of track IDs to fetch
+     * @returns Promise resolving to array of matching tracks
+     */
+    getTracksById(trackIds: string[]): Promise<TrackItem[]>;
+    /**
+     * Get tracks with missing/empty URLs from current playlist
+     * @returns Promise resolving to array of tracks needing URLs
+     */
+    getTracksNeedingUrls(): Promise<TrackItem[]>;
+    /**
+     * Get next N tracks from current position in playlist
+     * Useful for preloading URLs before they're needed
+     * @param count Number of upcoming tracks to return
+     * @returns Promise resolving to array of next tracks
+     */
+    getNextTracks(count: number): Promise<TrackItem[]>;
+    /**
+     * Get current track index in the active playlist
+     * @returns Promise resolving to 0-based index, or -1 if no track playing
+     */
+    getCurrentTrackIndex(): Promise<number>;
+    /**
+     * Register callback that fires when tracks will be needed soon
+     * Useful for proactive URL resolution in Android Auto/CarPlay
+     * @param callback Function called with tracks needing URLs and lookahead count
+     */
+    onTracksNeedUpdate(callback: (tracks: TrackItem[], lookahead: number) => void): void;
+    /**
+     * Get the current track index in the active playlist
+     * @returns Promise resolving to 0-based index, or -1 if no track playing
+     */
+    setPlaybackSpeed(speed: number): Promise<void>;
+    /**
+     * Get the current playback speed
+     * @returns Promise resolving to playback speed
+     */
+    getPlaybackSpeed(): Promise<number>;
 }

package/lib/types/PlayerQueue.d.ts

@@ -33,4 +33,9 @@ export interface PlayerConfig {
     androidAutoEnabled?: boolean;
     carPlayEnabled?: boolean;
     showInNotification?: boolean;
+    /**
+     * Number of upcoming tracks to preload URLs for (default: 5)
+     * Higher values = more proactive loading, but more network requests
+     */
+    lookaheadCount?: number;
 }

package/nitrogen/generated/android/NitroPlayerOnLoad.cpp

@@ -33,6 +33,7 @@
 #include "JFunc_void_TrackPlayerState_std__optional_Reason_.hpp"
 #include "JFunc_void_double_double.hpp"
 #include "JFunc_void_double_double_std__optional_bool_.hpp"
+#include "JFunc_void_std__vector_TrackItem__double.hpp"
 #include <NitroModules/DefaultConstructableObject.hpp>
 
 namespace margelo::nitro::nitroplayer {
@@ -62,6 +63,7 @@ int initialize(JavaVM* vm) {
     margelo::nitro::nitroplayer::JFunc_void_TrackPlayerState_std__optional_Reason__cxx::registerNatives();
     margelo::nitro::nitroplayer::JFunc_void_double_double_cxx::registerNatives();
     margelo::nitro::nitroplayer::JFunc_void_double_double_std__optional_bool__cxx::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_std__vector_TrackItem__double_cxx::registerNatives();
 
     // Register Nitro Hybrid Objects
     HybridObjectRegistry::registerHybridObjectConstructor(

package/nitrogen/generated/android/c++/JFunc_void_std__vector_TrackItem__double.hpp

@@ -0,0 +1,104 @@
+///
+/// JFunc_void_std__vector_TrackItem__double.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include <functional>
+
+#include "TrackItem.hpp"
+#include <vector>
+#include <functional>
+#include <NitroModules/JNICallable.hpp>
+#include "JTrackItem.hpp"
+#include <string>
+#include <NitroModules/Null.hpp>
+#include <variant>
+#include <optional>
+#include "JVariant_NullType_String.hpp"
+#include <NitroModules/JNull.hpp>
+#include <NitroModules/AnyMap.hpp>
+#include <NitroModules/JAnyMap.hpp>
+
+namespace margelo::nitro::nitroplayer {
+
+  using namespace facebook;
+
+  /**
+   * Represents the Java/Kotlin callback `(tracks: Array<TrackItem>, lookahead: Double) -> Unit`.
+   * This can be passed around between C++ and Java/Kotlin.
+   */
+  struct JFunc_void_std__vector_TrackItem__double: public jni::JavaClass<JFunc_void_std__vector_TrackItem__double> {
+  public:
+    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/Func_void_std__vector_TrackItem__double;";
+
+  public:
+    /**
+     * Invokes the function this `JFunc_void_std__vector_TrackItem__double` instance holds through JNI.
+     */
+    void invoke(const std::vector<TrackItem>& tracks, double lookahead) const {
+      static const auto method = javaClassStatic()->getMethod<void(jni::alias_ref<jni::JArrayClass<JTrackItem>> /* tracks */, double /* lookahead */)>("invoke");
+      method(self(), [&]() {
+        size_t __size = tracks.size();
+        jni::local_ref<jni::JArrayClass<JTrackItem>> __array = jni::JArrayClass<JTrackItem>::newArray(__size);
+        for (size_t __i = 0; __i < __size; __i++) {
+          const auto& __element = tracks[__i];
+          auto __elementJni = JTrackItem::fromCpp(__element);
+          __array->setElement(__i, *__elementJni);
+        }
+        return __array;
+      }(), lookahead);
+    }
+  };
+
+  /**
+   * An implementation of Func_void_std__vector_TrackItem__double that is backed by a C++ implementation (using `std::function<...>`)
+   */
+  class JFunc_void_std__vector_TrackItem__double_cxx final: public jni::HybridClass<JFunc_void_std__vector_TrackItem__double_cxx, JFunc_void_std__vector_TrackItem__double> {
+  public:
+    static jni::local_ref<JFunc_void_std__vector_TrackItem__double::javaobject> fromCpp(const std::function<void(const std::vector<TrackItem>& /* tracks */, double /* lookahead */)>& func) {
+      return JFunc_void_std__vector_TrackItem__double_cxx::newObjectCxxArgs(func);
+    }
+
+  public:
+    /**
+     * Invokes the C++ `std::function<...>` this `JFunc_void_std__vector_TrackItem__double_cxx` instance holds.
+     */
+    void invoke_cxx(jni::alias_ref<jni::JArrayClass<JTrackItem>> tracks, double lookahead) {
+      _func([&]() {
+              size_t __size = tracks->size();
+              std::vector<TrackItem> __vector;
+              __vector.reserve(__size);
+              for (size_t __i = 0; __i < __size; __i++) {
+                auto __element = tracks->getElement(__i);
+                __vector.push_back(__element->toCpp());
+              }
+              return __vector;
+            }(), lookahead);
+    }
+
+  public:
+    [[nodiscard]]
+    inline const std::function<void(const std::vector<TrackItem>& /* tracks */, double /* lookahead */)>& getFunction() const {
+      return _func;
+    }
+
+  public:
+    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/Func_void_std__vector_TrackItem__double_cxx;";
+    static void registerNatives() {
+      registerHybrid({makeNativeMethod("invoke_cxx", JFunc_void_std__vector_TrackItem__double_cxx::invoke_cxx)});
+    }
+
+  private:
+    explicit JFunc_void_std__vector_TrackItem__double_cxx(const std::function<void(const std::vector<TrackItem>& /* tracks */, double /* lookahead */)>& func): _func(func) { }
+
+  private:
+    friend HybridBase;
+    std::function<void(const std::vector<TrackItem>& /* tracks */, double /* lookahead */)> _func;
+  };
+
+} // namespace margelo::nitro::nitroplayer