react-native-queue-player 1.0.0

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

@@ -0,0 +1,136 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import com.margelo.nitro.core.Promise
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.first
+
+/**
+ * Single-slot registry for the JS-side automotive callbacks the
+ * `MediaLibrarySession.Callback` dispatches into. Each slot holds at
+ * most one callback at a time — re-registering replaces the prior
+ * callback, matching the JS-side `registerPlaybackService` factory
+ * semantics where the latest call wins.
+ *
+ * Callable from any thread — slots are [MutableStateFlow]-backed so
+ * a Media3 callback running on the library executor can invoke the
+ * registered callback without contention against a JS-thread
+ * registration. Each slot also exposes a suspending `await*Callback`
+ * that resumes the moment a callback lands (or returns the current
+ * value if one is already registered) — callers no longer poll the
+ * slot via `delay(50)` loops.
+ *
+ * Disposal: each `register*` returns a disposer lambda. Calling the
+ * disposer clears the slot iff the registered callback is still
+ * the active one (idempotent + safe against late dispose-after-
+ * replace).
+ */
+@UnstableApi
+internal class BrowseCallbackRegistry {
+
+  // Browse-tree drilldown — invoked when a controller calls
+  // `getChildren(parentId)` and the parent isn't in the cache.
+  // Returns a Nitro Promise that JS resolves with the children
+  // array. The double-Promise wrapping is Nitro's shape for an
+  // async JS callback.
+  private val onBrowseRequestSlot =
+    MutableStateFlow<((parentId: String) -> Promise<Promise<Array<BrowseItem>>>)?>(null)
+
+  // Search query — invoked when a controller calls `search(query)`
+  // and the cache doesn't have an answer.
+  private val onSearchRequestSlot =
+    MutableStateFlow<((query: String) -> Promise<Promise<Array<BrowseItem>>>)?>(null)
+
+  // "Play from search" — invoked when a controller resolves a
+  // search result to playback (Auto's tap-on-search-result, voice
+  // search). Returns a TrackItem array to set the queue from.
+  private val onPlayFromSearchRequestSlot =
+    MutableStateFlow<((request: MediaSearchRequest) -> Promise<Promise<Array<TrackItem>>>)?>(null)
+
+  // "Play from media id" — invoked when a controller resolves a
+  // browse-leaf to playback (tap on a song in Auto's browse tree).
+  private val onPlayFromIdRequestSlot =
+    MutableStateFlow<((mediaId: String) -> Promise<Promise<Array<TrackItem>>>)?>(null)
+
+  // Connection lifecycle — fired when a known headless-eligible
+  // controller (Auto / Wear / Assistant) binds to the session.
+  private val onCarConnectSlot = MutableStateFlow<(() -> Unit)?>(null)
+  private val onCarDisconnectSlot = MutableStateFlow<(() -> Unit)?>(null)
+
+  // Service-bind lifecycle — fired on every successful JS-side
+  // `onServiceConnected`. The `ServiceReadyReason` argument carries
+  // the lib's reason code; the Nitrogen bridge marshals it as the
+  // underlying string value of the TS enum.
+  private val onServiceReadySlot =
+    MutableStateFlow<((reason: ServiceReadyReason) -> Unit)?>(null)
+
+  fun registerOnBrowseRequest(
+    callback: (parentId: String) -> Promise<Promise<Array<BrowseItem>>>
+  ): () -> Unit = registerSlot(onBrowseRequestSlot, callback)
+
+  fun registerOnSearchRequest(
+    callback: (query: String) -> Promise<Promise<Array<BrowseItem>>>
+  ): () -> Unit = registerSlot(onSearchRequestSlot, callback)
+
+  fun registerOnPlayFromSearchRequest(
+    callback: (request: MediaSearchRequest) -> Promise<Promise<Array<TrackItem>>>
+  ): () -> Unit = registerSlot(onPlayFromSearchRequestSlot, callback)
+
+  fun registerOnPlayFromIdRequest(
+    callback: (mediaId: String) -> Promise<Promise<Array<TrackItem>>>
+  ): () -> Unit = registerSlot(onPlayFromIdRequestSlot, callback)
+
+  fun registerOnCarConnect(callback: () -> Unit): () -> Unit =
+    registerSlot(onCarConnectSlot, callback)
+
+  fun registerOnCarDisconnect(callback: () -> Unit): () -> Unit =
+    registerSlot(onCarDisconnectSlot, callback)
+
+  fun registerOnServiceReady(
+    callback: (reason: ServiceReadyReason) -> Unit
+  ): () -> Unit = registerSlot(onServiceReadySlot, callback)
+
+  fun browseRequestCallback() = onBrowseRequestSlot.value
+  fun searchRequestCallback() = onSearchRequestSlot.value
+  fun playFromSearchRequestCallback() = onPlayFromSearchRequestSlot.value
+  fun playFromIdRequestCallback() = onPlayFromIdRequestSlot.value
+  fun carConnectCallback() = onCarConnectSlot.value
+  fun carDisconnectCallback() = onCarDisconnectSlot.value
+  fun serviceReadyCallback() = onServiceReadySlot.value
+
+  /** Suspend until a callback is registered for [onBrowseRequestSlot],
+   *  returning the current registration if one already exists. */
+  suspend fun awaitBrowseRequestCallback() =
+    onBrowseRequestSlot.filterNotNull().first()
+
+  suspend fun awaitPlayFromSearchRequestCallback() =
+    onPlayFromSearchRequestSlot.filterNotNull().first()
+
+  suspend fun awaitPlayFromIdRequestCallback() =
+    onPlayFromIdRequestSlot.filterNotNull().first()
+
+  suspend fun awaitCarConnectCallback() =
+    onCarConnectSlot.filterNotNull().first()
+
+  fun clear() {
+    onBrowseRequestSlot.value = null
+    onSearchRequestSlot.value = null
+    onPlayFromSearchRequestSlot.value = null
+    onPlayFromIdRequestSlot.value = null
+    onCarConnectSlot.value = null
+    onCarDisconnectSlot.value = null
+    onServiceReadySlot.value = null
+  }
+
+  /** Atomically replace the slot's value with [callback], returning
+   *  a disposer that clears the slot iff [callback] is still the
+   *  registered value. */
+  private fun <T : Any> registerSlot(
+    slot: MutableStateFlow<T?>,
+    callback: T
+  ): () -> Unit {
+    slot.value = callback
+    return { slot.compareAndSet(callback, null) }
+  }
+}

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

@@ -0,0 +1,128 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Native cache for the most-recent [BrowseSnapshot] pushed by the
+ * consumer via `setBrowseSnapshot`. The MediaLibrarySession's browse
+ * callbacks read from this cache so a cold-wake from Android Auto /
+ * Google Assistant can answer `onGetLibraryRoot` / `onGetChildren` /
+ * `onGetItem` / `onSearch` without a JS bridge round-trip.
+ *
+ * Snapshot replacement is atomic — `setSnapshot` performs a single
+ * [AtomicReference.set] so a concurrent reader either sees the prior
+ * snapshot in full or the new one in full, never a torn mix.
+ *
+ * Browse tree shape:
+ *  - The root parent's id is the snapshot's [BrowseSnapshot.rootId].
+ *    Its children are one synthetic browsable item per
+ *    [BrowseSection] — id matches the section's id, title matches
+ *    the section's title, never playable, always browsable.
+ *  - Each section id, when used as a parentId, returns that
+ *    section's `items` list paginated.
+ *  - Item ids must be unique across the entire snapshot — the
+ *    consumer's responsibility per the lib's identity contract
+ *    (consumer-supplied data, lib does not interpret).
+ *
+ * Snapshot updates emit a set of parentIds that need to be
+ * re-fetched by connected browse controllers — caller (the
+ * MediaLibrarySession.Callback) loops the set + invokes
+ * `notifyChildrenChanged` for each.
+ */
+@UnstableApi
+internal class BrowseDataProvider {
+
+  private val cell = AtomicReference<BrowseSnapshot?>(null)
+
+  /** Replace the cached snapshot. Pass `null` to clear. Returns the
+   *  set of parentIds whose children list changed (root + every
+   *  section id from the prior + new snapshots) so the caller can
+   *  fan out `notifyChildrenChanged` notifications.
+   *
+   *  Returns an empty set when both the prior and new snapshots are
+   *  `null` (e.g. clearing a cache that was never populated) — no
+   *  controllers to notify in that case. The empty-set case is also
+   *  why [PlaybackService.notifyChildrenChangedForParents] still
+   *  unions in any [PendingBrowseRequests] that accumulated before
+   *  the first snapshot landed: a controller that fetched children
+   *  pre-snapshot is in the pending queue, not in the changed set
+   *  here. */
+  fun setSnapshot(snapshot: BrowseSnapshot?): Set<String> {
+    val previous = cell.getAndSet(snapshot)
+    val changedParents = mutableSetOf<String>()
+    previous?.let { p ->
+      changedParents += p.rootId
+      p.sections.forEach { changedParents += it.id }
+    }
+    snapshot?.let { s ->
+      changedParents += s.rootId
+      s.sections.forEach { changedParents += it.id }
+    }
+    return changedParents
+  }
+
+  /** Read the current snapshot, or `null` if none has been set. */
+  fun getSnapshot(): BrowseSnapshot? = cell.get()
+
+  /** True when the parentId addresses the root of the cached
+   *  snapshot. False when no snapshot is set. */
+  fun isRoot(parentId: String): Boolean =
+    cell.get()?.rootId == parentId
+
+  /** Find a section by id. Returns null when no snapshot is set or
+   *  no section matches. */
+  fun getSection(sectionId: String): BrowseSection? =
+    cell.get()?.sections?.firstOrNull { it.id == sectionId }
+
+  /** Search the full snapshot for an item with the given id. Walks
+   *  every section in declaration order. Returns null when no
+   *  snapshot is set or no item matches. */
+  fun getItem(itemId: String): BrowseItem? {
+    val snapshot = cell.get() ?: return null
+    for (section in snapshot.sections) {
+      for (item in section.items) {
+        if (item.id == itemId) return item
+      }
+    }
+    return null
+  }
+
+  /** Resolve a parentId to its children, paginated.
+   *  - `parentId == snapshot.rootId` returns one synthetic item per
+   *    section: `id = section.id, title = section.title,
+   *    playable = false, hasChildren = true`.
+   *  - `parentId == section.id` returns that section's items.
+   *  - Anything else returns an empty list.
+   *
+   *  Pagination: 0-based page index. `pageSize <= 0` is treated as
+   *  unbounded (returns the full list from `page * pageSize` —
+   *  in practice the page index won't be paged when pageSize is 0
+   *  so it returns the full list). Out-of-range pages return empty. */
+  fun getChildren(parentId: String, page: Int, pageSize: Int): List<BrowseItem> {
+    val snapshot = cell.get() ?: return emptyList()
+    val items: List<BrowseItem> = when (parentId) {
+      snapshot.rootId -> snapshot.sections.map { section ->
+        BrowseItem(
+          id = section.id,
+          title = section.title,
+          subtitle = null,
+          artworkUrl = section.artworkUrl,
+          playable = false,
+          hasChildren = true
+        )
+      }
+      else -> {
+        val section = snapshot.sections.firstOrNull { it.id == parentId }
+          ?: return emptyList()
+        section.items.toList()
+      }
+    }
+    if (pageSize <= 0) return items
+    if (page < 0) return emptyList()
+    val from = page * pageSize
+    if (from >= items.size) return emptyList()
+    val to = (from + pageSize).coerceAtMost(items.size)
+    return items.subList(from, to)
+  }
+}

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

@@ -0,0 +1,35 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.Player
+
+/**
+ * Pure-Kotlin translator from ExoPlayer's `playbackState` plus the
+ * library's `(hasStartedPlaying, wantsToPlay)` intent flags to the
+ * public [BufferState] enum.
+ *
+ * Extracted from [TrackPlayer.computeBufferState] so the discriminator
+ * between an initial `BUFFERING` load and a mid-playback `STALLED`
+ * rebuffer is unit-testable without a live ExoPlayer, matching the
+ * [TransportStateTranslator] pattern.
+ */
+internal object BufferStateTranslator {
+
+  /**
+   * - `STATE_READY` / `STATE_ENDED` → [BufferState.FULL] (able to play now).
+   * - `STATE_IDLE` (and any other) → [BufferState.EMPTY] (nothing loaded).
+   * - `STATE_BUFFERING` → [BufferState.STALLED] when playback had started and
+   *   is intended (a mid-play rebuffer), else [BufferState.BUFFERING] (the
+   *   initial load, or loading while not trying to play).
+   */
+  fun translate(
+    @Player.State playbackState: Int,
+    hasStartedPlaying: Boolean,
+    wantsToPlay: Boolean,
+  ): BufferState =
+    when (playbackState) {
+      Player.STATE_READY, Player.STATE_ENDED -> BufferState.FULL
+      Player.STATE_BUFFERING ->
+        if (hasStartedPlaying && wantsToPlay) BufferState.STALLED else BufferState.BUFFERING
+      else -> BufferState.EMPTY
+    }
+}

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

@@ -0,0 +1,79 @@
+package com.margelo.nitro.queueplayer
+
+import java.net.URI
+
+/**
+ * MIME-type plumbing for the lookahead cache. Mirrors iOS's
+ * `LookaheadCache.extensionFromMimeType` / `extensionFromUrl` —
+ * lets the Android cache record the same Content-Type signal so
+ * Media3 can be told the format up front via
+ * [androidx.media3.common.MediaItem.Builder.setMimeType] instead of
+ * falling back on extractor sniffing.
+ *
+ * Pure helpers — no allocator, no state. Safe to call from any
+ * thread.
+ */
+internal object CacheMimeTypes {
+
+  /**
+   * Canonical MIME type for an HTTP `Content-Type` header value, or
+   * `null` when the type isn't recognised as audio. Strips any
+   * `; charset=...` or other parameters before matching.
+   * `application/octet-stream` is treated as opaque (returns null)
+   * so the caller can fall back to URL-derived hints.
+   */
+  fun fromContentType(contentType: String?): String? {
+    if (contentType.isNullOrEmpty()) return null
+    val mime = contentType.substringBefore(';').trim().lowercase()
+    return when (mime) {
+      "audio/mpeg",
+      "audio/mp4",
+      "audio/mp4a-latm",
+      "audio/aac",
+      "audio/wav",
+      "audio/wave",
+      "audio/x-wav",
+      "audio/flac",
+      "audio/x-flac",
+      "audio/ogg",
+      "application/ogg",
+      "audio/opus",
+      "audio/x-m4a",
+      "application/x-mpegurl",
+      "application/vnd.apple.mpegurl" -> mime
+      else -> null
+    }
+  }
+
+  /**
+   * URL-derived MIME fallback. Reads the URI's path extension and
+   * maps known audio extensions to their canonical MIME type.
+   * Returns `null` for opaque / parameterised paths so callers can
+   * fall through to extractor sniffing.
+   */
+  fun fromUrl(url: String): String? {
+    val path = try { URI(url).path } catch (_: Throwable) { return null }
+      ?: return null
+    val dot = path.lastIndexOf('.')
+    if (dot < 0 || dot == path.length - 1) return null
+    val ext = path.substring(dot + 1).lowercase()
+    return when (ext) {
+      "mp3" -> "audio/mpeg"
+      "m4a", "m4b", "m4r", "mp4" -> "audio/mp4"
+      "aac" -> "audio/aac"
+      "wav", "wave" -> "audio/wav"
+      "flac" -> "audio/flac"
+      "ogg", "opus" -> "audio/ogg"
+      "m3u8" -> "application/x-mpegurl"
+      else -> null
+    }
+  }
+
+  /**
+   * Resolve the best-known MIME for `url` given an optional response
+   * `Content-Type`. Content-Type wins; URL extension is the fallback;
+   * `null` when neither yields anything recognisable.
+   */
+  fun resolve(url: String, contentType: String?): String? =
+    fromContentType(contentType) ?: fromUrl(url)
+}