react-native-queue-player 1.0.7 → 1.0.8

package/android/src/main/java/com/margelo/nitro/queueplayer/TrackPlayer.kt

@@ -544,6 +544,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // simultaneously without clobbering each other.
   private val stateChangeListeners = ListenerRegistry<(PlayerState, StateChangeReason) -> Unit>()
   private val trackChangeListeners = ListenerRegistry<(TrackItem?, Double, TrackChangeReason, Double?) -> Unit>()
+  private val queueChangeListeners = ListenerRegistry<(Array<TrackItem>, Double, QueueChangeReason) -> Unit>()
   private val progressListeners = ListenerRegistry<(PlayerProgress) -> Unit>()
   // Buffer state — discrete empty/buffering/stalled/full for the active track, derived
   // from Media3's playback state + buffered-ahead. Recomputed on the engine
@@ -1445,6 +1446,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    emitQueueChange(QueueChangeReason.SET_QUEUE)
   }
 
   /**
@@ -1503,6 +1505,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    emitQueueChange(QueueChangeReason.SET_QUEUE)
     return items
   }
 
@@ -1595,6 +1598,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(this.tracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    emitQueueChange(QueueChangeReason.ADD)
     return at
   }
 
@@ -1688,6 +1692,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(this.tracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    // Reached only past the `sanitised.isEmpty()` guard, so ≥1 track was
+    // removed; tracks + index are final.
+    emitQueueChange(QueueChangeReason.REMOVE)
     return sanitised
   }
 
@@ -1753,6 +1760,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     for (i in this.tracks.indices) retryAttemptsRemaining[i] = attempts
     rescheduleLookahead()
     recomputeCapabilities()
+    // Reached only past the invalid / `from == to` / pinned-current
+    // guards, so the order actually changed.
+    emitQueueChange(QueueChangeReason.MOVE)
     return true
   }
 
@@ -1771,6 +1781,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   @VisibleForTesting
   internal fun clearQueueInternal() {
     val p = player ?: return
+    val queueWasNonEmpty = tracks.isNotEmpty()
     // Reset authoritative state BEFORE the ExoPlayer mutation.
     // `clearMediaItems()` fires `onMediaItemTransition(null,
     // REASON_PLAYLIST_CHANGED)` synchronously, which routes through
@@ -1788,6 +1799,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     retryAttemptsRemaining.clear()
     tracks = emptyList()
     currentTrackIndex = -1
+    // Fire queue-change BEFORE setMediaItems (which synchronously fires
+    // onTrackChange via onMediaItemTransition) so a `useQueue()` consumer
+    // sees the empty queue + index -1 together. Only when the queue was
+    // actually non-empty — clearing an empty queue is a no-op.
+    if (queueWasNonEmpty) emitQueueChange(QueueChangeReason.CLEAR)
     // Route through the engine surface (not directly through the
     // leading leg) so CrossfadeEngine can also tear down the
     // standby leg's preroll'd items + cancel any in-flight fade.
@@ -2802,6 +2818,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
     rescheduleLookahead()
     recomputeCapabilities()
+    // Skip a single-track shuffle — the order can't change.
+    if (newTracks.size > 1) emitQueueChange(QueueChangeReason.SHUFFLE)
 
     return ShuffleResult(
       tracks = newTracks.toTypedArray(),
@@ -2892,6 +2910,27 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     return { trackChangeListeners.remove(id) }
   }
 
+  override fun onQueueChange(
+    callback: (queue: Array<TrackItem>, currentIndex: Double, reason: QueueChangeReason) -> Unit
+  ): () -> Unit {
+    val id = queueChangeListeners.add(callback)
+    return { queueChangeListeners.remove(id) }
+  }
+
+  /**
+   * Fire onQueueChange with an atomic snapshot of the post-mutation
+   * queue + current index. Main-thread only — every queue mutation
+   * commits on main, so [tracks] / [currentTrackIndex] are settled here.
+   * Callers gate this on an actual content/order change so a no-op
+   * mutation never emits.
+   */
+  @MainThread
+  private fun emitQueueChange(reason: QueueChangeReason) {
+    val snapshot = tracks.toTypedArray()
+    val index = currentTrackIndex.toDouble()
+    queueChangeListeners.forEach { it(snapshot, index, reason) }
+  }
+
   override fun onProgress(
     callback: (progress: PlayerProgress) -> Unit
   ): () -> Unit {

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerQueueChangeTest.kt

@@ -0,0 +1,180 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * `onQueueChange` emission coverage against a live ExoPlayer via
+ * Robolectric. Every queue-content/order mutation fires exactly one
+ * event carrying the post-mutation `(queue, index, reason)`; a no-op
+ * mutation fires nothing. `emitQueueChange` runs synchronously inside
+ * the mutation on the test (main) thread, so no looper idle is needed to
+ * observe the fire.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class TrackPlayerQueueChangeTest {
+
+  private lateinit var player: TrackPlayer
+  private lateinit var serviceHandle: PlaybackServiceTestHandle
+
+  private data class QueueEvent(
+    val queue: List<TrackItem>,
+    val index: Int,
+    val reason: QueueChangeReason,
+  )
+
+  private fun context() =
+    ApplicationProvider.getApplicationContext<android.content.Context>()
+
+  private fun track(id: String) = TrackItem(
+    id = id, url = "https://example.com/$id.m4a",
+    title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+  )
+
+  @Before
+  fun setUp() {
+    player = TrackPlayer()
+    serviceHandle = bindPlaybackServiceForTest(player, context())
+    player.configureInternal(
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null), context()
+    )
+    player.setQueueInternal((1..5).map { track("t$it") })
+  }
+
+  @After
+  fun tearDown() {
+    player.destroyInternal()
+    serviceHandle.destroy()
+  }
+
+  /** Register a capturing listener AFTER the @Before setQueue (which is
+   *  therefore not captured — onQueueChange does not auto-fire). */
+  private fun capture(): Pair<MutableList<QueueEvent>, () -> Unit> {
+    val events = mutableListOf<QueueEvent>()
+    val dispose = player.onQueueChange { queue, idx, reason ->
+      events.add(QueueEvent(queue.toList(), idx.toInt(), reason))
+    }
+    return events to dispose
+  }
+
+  // --- one emission per mutation, with the post-mutation snapshot
+
+  @Test
+  fun `setQueue fires SET_QUEUE with the new queue + resolved index`() {
+    val (events, dispose) = capture()
+    player.setQueueInternal((1..3).map { track("n$it") }, startAtIndex = 1)
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.SET_QUEUE, events[0].reason)
+    assertEquals(3, events[0].queue.size)
+    assertEquals(1, events[0].index)
+  }
+
+  @Test
+  fun `addToQueue fires ADD with the grown queue`() {
+    val (events, dispose) = capture()
+    player.addToQueueInternal(listOf(track("n1")), insertBefore = null)
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.ADD, events[0].reason)
+    assertEquals(6, events[0].queue.size)
+    assertEquals("n1", events[0].queue[5].id)
+  }
+
+  @Test
+  fun `removeFromQueue fires REMOVE with the shrunk queue`() {
+    val (events, dispose) = capture()
+    player.removeFromQueueInternal(listOf(3)) // remove t4; cur=0 pinned
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.REMOVE, events[0].reason)
+    assertEquals(listOf("t1", "t2", "t3", "t5"), events[0].queue.map { it.id })
+  }
+
+  @Test
+  fun `moveInQueue fires MOVE`() {
+    val (events, dispose) = capture()
+    player.moveInQueueInternal(from = 3, to = 1) // cur=0 not moved
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.MOVE, events[0].reason)
+    // t4 (index 3) removed + reinserted at 1 → t1,t4,t2,t3,t5.
+    assertEquals(listOf("t1", "t4", "t2", "t3", "t5"), events[0].queue.map { it.id })
+  }
+
+  @Test
+  fun `clearQueue fires CLEAR with an empty queue + index -1`() {
+    val (events, dispose) = capture()
+    player.clearQueueInternal()
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.CLEAR, events[0].reason)
+    assertEquals(0, events[0].queue.size)
+    assertEquals(-1, events[0].index)
+  }
+
+  @Test
+  fun `shuffleQueue fires SHUFFLE with a full queue at index 0`() {
+    val (events, dispose) = capture()
+    player.shuffleQueueInternal()
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.SHUFFLE, events[0].reason)
+    assertEquals(5, events[0].queue.size)
+    assertEquals(0, events[0].index)
+  }
+
+  // --- no-op mutations do not fire
+
+  @Test
+  fun `empty addToQueue does not fire`() {
+    val (events, dispose) = capture()
+    player.addToQueueInternal(emptyList(), insertBefore = null)
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `no-op move (from == to) does not fire`() {
+    val (events, dispose) = capture()
+    player.moveInQueueInternal(from = 2, to = 2)
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `out-of-range remove does not fire`() {
+    val (events, dispose) = capture()
+    player.removeFromQueueInternal(listOf(99))
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `clearing an already-empty queue does not fire`() {
+    player.clearQueueInternal() // empties (fires; no listener yet)
+    val (events, dispose) = capture()
+    player.clearQueueInternal() // already empty → no-op
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `unsubscribe stops emissions`() {
+    val (events, dispose) = capture()
+    dispose()
+    player.addToQueueInternal(listOf(track("n1")), insertBefore = null)
+    assertTrue(events.isEmpty())
+  }
+}

package/ios/AVQueueBuilder.swift

@@ -55,6 +55,35 @@ public enum AVQueueBuilder {
     }
   }
 
+  /// Best-effort warm-up of a freshly-built item's asset BEFORE it is
+  /// inserted into a live `AVQueuePlayer`. When the insert lands in the
+  /// immediate-next slot of a playing queue, `AVQueuePlayer` prerolls the
+  /// new item on the shared decode/render pipeline while the current item
+  /// is still rendering; faulting the asset's `tracks` / `duration` /
+  /// `playable` keys in synchronously at that moment briefly disturbs the
+  /// currently-playing item. Loading them here first makes that preroll
+  /// cheap.
+  ///
+  /// Best-effort: the load races a [timeout] deadline and the caller
+  /// proceeds as soon as either wins. `AVAsset`'s async loader honours
+  /// task cancellation, so `cancelAll` caps a slow / unreachable remote
+  /// asset at [timeout] and the item is inserted unwarmed rather than
+  /// deferring the enqueue. Load errors are ignored for the same reason.
+  @MainActor
+  static func preloadAssetForInsert(_ item: AVPlayerItem, timeout: TimeInterval = 2.0) async {
+    let asset = item.asset
+    await withTaskGroup(of: Void.self) { group in
+      group.addTask { @MainActor in
+        _ = try? await asset.load(.tracks, .duration, .isPlayable)
+      }
+      group.addTask {
+        try? await Task.sleep(nanoseconds: UInt64(timeout * 1_000_000_000))
+      }
+      _ = await group.next()
+      group.cancelAll()
+    }
+  }
+
   /// Single-item builder. Used by addToQueue. Honours the cache
   /// lookup when a cache instance is supplied.
   ///

package/ios/QueueState.swift

@@ -23,11 +23,23 @@ internal struct QueueState {
   /// Returns the freshly-generated IDs for the inserted slice.
   mutating func insert(_ newTracks: [TrackItem], at index: Int) -> [String] {
     let newIds = newTracks.map { _ in UUID().uuidString }
-    tracks.insert(contentsOf: newTracks, at: index)
-    queueItemIds.insert(contentsOf: newIds, at: index)
+    insert(newTracks, at: index, ids: newIds)
     return newIds
   }
 
+  /// Insert with caller-supplied IDs — used when the AVPlayerItems were
+  /// built (and their assets preloaded) ahead of the state mutation, so
+  /// the same lib-generated `queueItemId` that was stamped on each item
+  /// stays 1:1 with `queueItemIds`. `ids` must parallel `newTracks`.
+  mutating func insert(_ newTracks: [TrackItem], at index: Int, ids: [String]) {
+    precondition(
+      ids.count == newTracks.count,
+      "QueueState.insert requires ids parallel to newTracks (1:1)"
+    )
+    tracks.insert(contentsOf: newTracks, at: index)
+    queueItemIds.insert(contentsOf: ids, at: index)
+  }
+
   /// Returns the removed `queueItemId`.
   mutating func remove(at index: Int) -> String {
     let removedId = queueItemIds.remove(at: index)

package/ios/Tests/AVQueueBuilderTests.swift

@@ -15,6 +15,10 @@ import AVFoundation
 /// overloads are adapters that unpack the Nitro structs and delegate here,
 /// so exercising the raw entry points is sufficient coverage for the
 /// merge + routing behaviour.
+// Main-actor-isolated: several assertions read `AVPlayerItem.asset`, which
+// the SDK marks main-actor-isolated; running the cases on the main actor
+// keeps those reads warning-free.
+@MainActor
 final class AVQueueBuilderTests: XCTestCase {
 
   // MARK: - httpOptionsRaw merging
@@ -421,10 +425,80 @@ final class AVQueueBuilderTests: XCTestCase {
       "queueItemId must be set even when track.id is empty string")
   }
 
+  // MARK: - preloadAssetForInsert
+
+  func testPreloadAssetForInsertLoadsTracksForLocalFile() async throws {
+    let url = try Self.writeTinyWav()
+    defer { try? FileManager.default.removeItem(at: url) }
+    let item = try XCTUnwrap(
+      AVQueueBuilder.makeItemRaw(urlString: url.absoluteString, headers: nil, userAgent: nil))
+
+    await AVQueueBuilder.preloadAssetForInsert(item)
+
+    // The load resolved the tracks key on the same asset instance the
+    // enqueue will insert, so the audio track is present without a second
+    // fault — the preroll after insert has nothing left to load.
+    let tracks = try await item.asset.load(.tracks)
+    XCTAssertFalse(tracks.isEmpty,
+      "preload must resolve the local asset's tracks so the enqueue preroll is cheap")
+  }
+
+  func testPreloadAssetForInsertLeavesUnreadableAssetInsertable() async throws {
+    // Best-effort contract: a missing file's load fails but the item stays
+    // intact + insertable, so the enqueue proceeds unwarmed rather than
+    // being blocked or corrupted.
+    let missing = FileManager.default.temporaryDirectory
+      .appendingPathComponent("does-not-exist-\(UUID().uuidString).m4a")
+    let item = try XCTUnwrap(
+      AVQueueBuilder.makeItemRaw(urlString: missing.absoluteString, headers: nil, userAgent: nil))
+
+    let start = Date()
+    await AVQueueBuilder.preloadAssetForInsert(item, timeout: 0.5)
+    let elapsed = Date().timeIntervalSince(start)
+
+    XCTAssertLessThan(elapsed, 2.0,
+      "a best-effort preload of an unreadable asset must return promptly, not hang")
+    let urlAsset = try XCTUnwrap(item.asset as? AVURLAsset)
+    XCTAssertEqual(urlAsset.url, missing,
+      "a failed preload must leave the item's asset unchanged and insertable")
+  }
+
   private func makeTrack(id: String, url: String) -> TrackItem {
     return TrackItem(
       id: id, url: url, title: nil, artist: nil, album: nil,
       duration: nil, artworkUrl: nil, extras: nil
     )
   }
+
+  /// Writes a minimal valid 16-bit PCM mono WAV (silent samples) so
+  /// AVFoundation resolves exactly one audio track from the file.
+  private static func writeTinyWav() throws -> URL {
+    let sampleRate: UInt32 = 44100
+    let channels: UInt16 = 1
+    let bitsPerSample: UInt16 = 16
+    let frameCount = 1024
+    let dataSize = UInt32(frameCount) * UInt32(channels) * UInt32(bitsPerSample / 8)
+    var data = Data()
+    func appendLE<T: FixedWidthInteger>(_ value: T) {
+      withUnsafeBytes(of: value.littleEndian) { data.append(contentsOf: $0) }
+    }
+    data.append(contentsOf: Array("RIFF".utf8))
+    appendLE(UInt32(36) + dataSize)
+    data.append(contentsOf: Array("WAVE".utf8))
+    data.append(contentsOf: Array("fmt ".utf8))
+    appendLE(UInt32(16))
+    appendLE(UInt16(1))
+    appendLE(channels)
+    appendLE(sampleRate)
+    appendLE(sampleRate * UInt32(channels) * UInt32(bitsPerSample / 8))
+    appendLE(UInt16(channels * bitsPerSample / 8))
+    appendLE(bitsPerSample)
+    data.append(contentsOf: Array("data".utf8))
+    appendLE(dataSize)
+    data.append(Data(count: Int(dataSize)))
+    let url = FileManager.default.temporaryDirectory
+      .appendingPathComponent("preload-\(UUID().uuidString).wav")
+    try data.write(to: url)
+    return url
+  }
 }

package/ios/Tests/QueueStateTests.swift

@@ -0,0 +1,50 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `QueueState` holds `tracks` and `queueItemIds` as parallel arrays. The
+/// id-supplying `insert` overload lets a caller reuse the lib-generated
+/// ids it stamped on pre-built AVPlayerItems (the immediate-next preload
+/// path) while preserving the 1:1 invariant.
+final class QueueStateTests: XCTestCase {
+
+  func testInsertWithSuppliedIdsPlacesThemParallelToTracks() {
+    var state = QueueState()
+    _ = state.replaceAll([track("a"), track("b"), track("c")])
+
+    state.insert([track("x"), track("y")], at: 1, ids: ["id-x", "id-y"])
+
+    XCTAssertEqual(state.tracks.map { $0.url }, ["a", "x", "y", "b", "c"])
+    XCTAssertEqual(state.queueItemIds.count, state.tracks.count)
+    XCTAssertEqual(state.queueItemIds[1], "id-x")
+    XCTAssertEqual(state.queueItemIds[2], "id-y")
+  }
+
+  func testInsertWithSuppliedIdsAppendsAtEnd() {
+    var state = QueueState()
+    _ = state.replaceAll([track("a")])
+
+    state.insert([track("z")], at: 1, ids: ["id-z"])
+
+    XCTAssertEqual(state.tracks.map { $0.url }, ["a", "z"])
+    XCTAssertEqual(state.queueItemIds.count, 2)
+    XCTAssertEqual(state.queueItemIds[1], "id-z")
+  }
+
+  func testGeneratingInsertStillReturnsFreshParallelIds() {
+    var state = QueueState()
+    _ = state.replaceAll([track("a"), track("b")])
+
+    let ids = state.insert([track("x")], at: 1)
+
+    XCTAssertEqual(ids.count, 1)
+    XCTAssertEqual(state.queueItemIds[1], ids[0])
+    XCTAssertEqual(state.queueItemIds.count, state.tracks.count)
+  }
+
+  private func track(_ url: String) -> TrackItem {
+    TrackItem(
+      id: nil, url: url, title: nil, artist: nil, album: nil,
+      duration: nil, artworkUrl: nil, extras: nil
+    )
+  }
+}