react-native-queue-player 1.0.6 → 1.0.8

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

@@ -65,7 +65,6 @@ class PlayerCommandsForTest {
   fun `commands include every skip pair when capability allows both`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = true, canSkipNext = true),
-      hasMediaItems = true,
     )
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -78,7 +77,6 @@ class PlayerCommandsForTest {
   fun `commands omit only the next pair when capability disallows skip-next`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = true, canSkipNext = false),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -91,7 +89,6 @@ class PlayerCommandsForTest {
   fun `commands omit only the previous pair when capability disallows skip-previous`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = false, canSkipNext = true),
-      hasMediaItems = true,
     )
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -104,7 +101,6 @@ class PlayerCommandsForTest {
   fun `commands omit both skip pairs when capability disallows both`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = false, canSkipNext = false),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -119,7 +115,6 @@ class PlayerCommandsForTest {
   fun `repeat OFF at index 0 of a two-track queue exposes only skip-next`() {
     val commands = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.OFF, count = 2, current = 0),
-      hasMediaItems = true,
     )
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -129,7 +124,6 @@ class PlayerCommandsForTest {
   fun `repeat OFF at the last index of a two-track queue exposes only skip-previous`() {
     val commands = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.OFF, count = 2, current = 1),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -139,7 +133,6 @@ class PlayerCommandsForTest {
   fun `repeat OFF on a single-track queue exposes neither skip command`() {
     val commands = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.OFF, count = 1, current = 0),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -149,15 +142,12 @@ class PlayerCommandsForTest {
   fun `repeat QUEUE wraps so both skip commands stay enabled at every queue position`() {
     val first = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.QUEUE, count = 3, current = 0),
-      hasMediaItems = true,
     )
     val mid = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.QUEUE, count = 3, current = 1),
-      hasMediaItems = true,
     )
     val last = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.QUEUE, count = 3, current = 2),
-      hasMediaItems = true,
     )
     for (commands in listOf(first, mid, last)) {
       assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -170,7 +160,6 @@ class PlayerCommandsForTest {
     // First track of 2: next available, no previous (no wrap).
     val atFirst = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.TRACK, count = 2, current = 0),
-      hasMediaItems = true,
     )
     assertTrue(atFirst.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertFalse(atFirst.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -178,31 +167,33 @@ class PlayerCommandsForTest {
     // Last track of 2: previous available, no next (no wrap).
     val atLast = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.TRACK, count = 2, current = 1),
-      hasMediaItems = true,
     )
     assertFalse(atLast.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertTrue(atLast.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
   }
 
   @Test
-  fun `empty queue exposes neither skip command regardless of repeat mode`() {
+  fun `empty queue disables skip but keeps transport commands for the System UI`() {
     for (mode in QueueSkipRepeatMode.entries) {
       val commands = service.playerCommandsFor(
         capabilityFor(repeat = mode, count = 0, current = -1),
-        hasMediaItems = false,
       )
       assertFalse(
-        "skip-next is always disabled with no tracks (repeat=$mode)",
+        "skip-next is disabled with no tracks (repeat=$mode)",
         commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM),
       )
       assertFalse(
-        "skip-previous is always disabled with no tracks (repeat=$mode)",
+        "skip-previous is disabled with no tracks (repeat=$mode)",
         commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM),
       )
-      assertFalse(
-        "PLAY_PAUSE is stripped on empty queue so AA lands on Library (repeat=$mode)",
+      assertTrue(
+        "play/pause is retained so the API 33+ System UI keeps the button (repeat=$mode)",
         commands.contains(Player.COMMAND_PLAY_PAUSE),
       )
+      assertTrue(
+        "in-item seek is retained so the seek scrubber stays draggable (repeat=$mode)",
+        commands.contains(Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM),
+      )
     }
   }
 

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/android/src/test/java/com/margelo/nitro/queueplayer/VisualizerKtTest.kt

@@ -187,6 +187,7 @@ private class FakePlaybackEngineWithSinks : PlaybackEngine {
   override val bufferedPositionMs: Long get() = error("not used in test")
   override val isPlaying: Boolean get() = error("not used in test")
   override val currentMediaItem: androidx.media3.common.MediaItem? get() = error("not used in test")
+  override val isCrossfadeActive: Boolean get() = false
   override val allMediaItems: List<androidx.media3.common.MediaItem> get() = error("not used in test")
   override fun currentAudioSessionIds(): IntArray = IntArray(0)
   override fun addAudioSessionIdListener(listener: (IntArray) -> Unit): () -> Unit = { /* noop */ }

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
+    )
+  }
+}