react-native-queue-player 1.0.0

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

@@ -0,0 +1,95 @@
+package com.margelo.nitro.queueplayer.cast
+
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * Route-change signal hub + active-session / player holder for cast
+ * `PcmStream` sessions (AirPlay 1 + AirPlay 2).
+ *
+ * The audio for an AirPlay session is carried by the dedicated `AirPlayEngine`,
+ * which `TrackPlayer` swaps in when [setActiveSession] fires the route change
+ * and binds the session's `audioSink()` to its renderer directly. This object
+ * just holds the active session + the active ExoPlayer reference (for
+ * metadata-aware sessions) and broadcasts activate/deactivate transitions — it
+ * does not touch the audio pipeline itself.
+ */
+@UnstableApi
+object CastSinkRouter {
+
+  /**
+   * The active PcmStream session (AirPlay 1/2), or `null` for local playback.
+   * `@Volatile` because the death path clears it off the main thread
+   * (`CastManager.onAirplaySessionDied` runs on the native drain thread) while
+   * `activeSession()`/`isRemoteActive()` are read on main.
+   */
+  @Volatile
+  private var activeSession: CastSession.PcmStream? = null
+
+  /**
+   * Listeners notified on every push-PCM route activate (`true`) / deactivate
+   * (`false`) transition. `TrackPlayer` uses this to swap the dedicated
+   * `AirPlayEngine` in/out. Does NOT replay the current state on subscribe —
+   * callers that need a starting snapshot read [isRemoteActive] directly, so
+   * subscribers registered during class construction don't run against
+   * half-initialized state.
+   */
+  private val routeChangeListeners =
+    java.util.concurrent.CopyOnWriteArraySet<(Boolean) -> Unit>()
+
+  fun addRouteChangeListener(listener: (Boolean) -> Unit): () -> Unit {
+    routeChangeListeners.add(listener)
+    return { routeChangeListeners.remove(listener) }
+  }
+
+  private fun fireRouteChange(active: Boolean) {
+    for (l in routeChangeListeners) l(active)
+  }
+
+  /**
+   * Reference to the active ExoPlayer, held so metadata-aware session subtypes
+   * (`MetadataAwareSession.onActivated`) can hook player events. Set by the
+   * engine on construction via [registerPlayer].
+   */
+  @Volatile
+  private var playerRef: Player? = null
+
+  fun registerPlayer(player: Player) {
+    playerRef = player
+  }
+
+  // Read at AirPlay engine activation (TrackPlayer.applyEngineSwapForMode) to
+  // hand the engine's ExoPlayer to the active session's receiver metadata sync.
+  fun player(): Player? = playerRef
+
+  /**
+   * Record an active PcmStream session (AirPlay 1/2) and fire the route
+   * change. The audio is carried by the dedicated `AirPlayEngine` that
+   * `TrackPlayer` swaps in on this signal. Must be called on the main thread
+   * (the same thread ExoPlayer is driven from).
+   */
+  fun setActiveSession(session: CastSession.PcmStream) {
+    activeSession = session
+    fireRouteChange(true)
+  }
+
+  /**
+   * Clear the active session and fire the route change. `TrackPlayer`'s
+   * route-change listener swaps the dedicated `AirPlayEngine` back out for the
+   * user's gapless/crossfade engine.
+   */
+  fun clearActiveSession() {
+    activeSession = null
+    fireRouteChange(false)
+  }
+
+  fun activeSession(): CastSession.PcmStream? = activeSession
+
+  /**
+   * `true` when an AirPlay (push-PCM) session is active. Used by the engine
+   * selector: while AirPlay is active the dedicated `AirPlayEngine` is in use,
+   * so crossfade is unavailable (the wire protocol has no sender-side
+   * cross-stream mixing).
+   */
+  fun isRemoteActive(): Boolean = activeSession != null
+}

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

@@ -0,0 +1,151 @@
+package com.margelo.nitro.queueplayer.cast
+
+import android.net.Uri
+import com.margelo.nitro.queueplayer.TrackItem
+import kotlinx.coroutines.runBlocking
+
+/**
+ * Transport-side shim — `TrackPlayer`'s per-call entry point for
+ * "should this command route to the receiver, or hit the local
+ * engine?". Each route helper returns `true` when the command was
+ * accepted by a live remote session (caller skips local handling);
+ * `false` when there's no active remote (caller proceeds locally).
+ *
+ * Reads the active remote through [PlaybackStateRouter.activeRemote];
+ * snapshot semantics — by the time the local fallback runs, the
+ * session may have ended, but the local path is the right thing for
+ * the next call anyway.
+ */
+internal object CastTransportRouter {
+
+  fun routePlay(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.play()
+    return true
+  }
+
+  fun routePause(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.pause()
+    return true
+  }
+
+  fun routeStop(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.stop()
+    return true
+  }
+
+  fun routeSeekTo(positionMs: Long): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.seekTo(positionMs)
+    return true
+  }
+
+  fun routeSkipToNext(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.queueNext()
+    return true
+  }
+
+  fun routeSkipToPrevious(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.queuePrev()
+    return true
+  }
+
+  /**
+   * Jump the receiver to the queue item at absolute lib-track [index].
+   * Synchronous fire-and-forget (mirrors iOS `routeSkipToIndex`): the
+   * caller intercepts-and-returns during cast, leaving the local engine
+   * paused so its index write can't desync from the receiver echo.
+   */
+  fun routeSkipToIndex(index: Int): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.skipToQueueIndex(index)
+    return true
+  }
+
+  fun routeSetVolume(value: Float): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    remote.setVolume(value)
+    return true
+  }
+
+  /**
+   * `setQueue` is suspending on the remote side (the receiver
+   * round-trip is awaited). Caller invokes this from a coroutine
+   * scope or uses [routeSetQueueBlocking] from a thread that can
+   * block. Returns `true` when the remote handled the load.
+   */
+  suspend fun routeSetQueue(
+    tracks: List<TrackItem>,
+    startIndex: Int,
+    startPositionMs: Long,
+    playWhenReady: Boolean,
+  ): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    val items = tracks.map(::toCastMediaItem)
+    remote.load(items, startIndex, startPositionMs, playWhenReady)
+    return true
+  }
+
+  fun routeSetQueueBlocking(
+    tracks: List<TrackItem>,
+    startIndex: Int,
+    startPositionMs: Long,
+    playWhenReady: Boolean,
+  ): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    val items = tracks.map(::toCastMediaItem)
+    runBlocking { remote.load(items, startIndex, startPositionMs, playWhenReady) }
+    return true
+  }
+
+  // Queue mutations mirror to the receiver while the local queue stays the
+  // source of truth for the consumer's UI. `false` when no remote is active
+  // (the caller's local mutation is the only effect). Receiver errors are
+  // swallowed — a failed mirror must not fail the local mutation. Mirrors
+  // iOS `CastTransportRouter` routeAddToQueue/Remove/Move/Clear.
+
+  suspend fun routeAddToQueue(tracks: List<TrackItem>, beforeIndex: Int?): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    runCatching { remote.queueInsert(tracks.map(::toCastMediaItem), beforeIndex) }
+    return true
+  }
+
+  suspend fun routeRemoveFromQueue(indices: List<Int>): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    runCatching { remote.queueRemove(indices) }
+    return true
+  }
+
+  suspend fun routeMoveInQueue(fromIndex: Int, toIndex: Int): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    runCatching { remote.queueMove(fromIndex, toIndex) }
+    return true
+  }
+
+  suspend fun routeClearQueue(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    runCatching { remote.queueClear() }
+    return true
+  }
+
+  /**
+   * Convert a `TrackItem` into a `CastMediaItem`. Preserves the raw
+   * URI (including `file://`); `MediaInfoBuilder` does the LAN-HTTP
+   * substitution for receiver fetch on the load path.
+   */
+  private fun toCastMediaItem(track: TrackItem): CastMediaItem {
+    return CastMediaItem(
+      uri = Uri.parse(track.url),
+      title = track.title?.takeIf { it.isNotEmpty() },
+      artist = track.artist?.takeIf { it.isNotEmpty() },
+      album = track.album?.takeIf { it.isNotEmpty() },
+      artwork = track.artworkUrl?.takeIf { it.isNotEmpty() }?.let { Uri.parse(it) },
+      durationMs = track.duration?.takeIf { it > 0 }?.let { (it * 1000).toLong() },
+      contentType = null,
+    )
+  }
+}

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

@@ -0,0 +1,53 @@
+package com.margelo.nitro.queueplayer.cast
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * Process-wide effective discovery state. Combines JS-layer intent with
+ * the process-foreground state into one effective flag that backends
+ * observe to start/stop their scans.
+ *
+ * - **Intent** — what the JS layer asked for, set by
+ *   `CastManager.startDiscovery` / `stopDiscovery`.
+ * - **Foregrounded** — `false` when the host process is fully
+ *   backgrounded (per `androidx.lifecycle.ProcessLifecycleOwner`), `true`
+ *   otherwise. Lifecycle observers in each backend feed this; pausing
+ *   discovery while backgrounded keeps multicast scans off the battery.
+ *
+ * Effective = `intent && foregrounded`. Default state is
+ * `intent=false, foregrounded=true` — processes always start foregrounded.
+ */
+object DiscoveryState {
+
+  private val _intent = MutableStateFlow(false)
+  private val _foregrounded = MutableStateFlow(true)
+  private val _effective = MutableStateFlow(false)
+
+  /** Read-only view; `true` when intent is on AND the process is foregrounded. */
+  val effective: StateFlow<Boolean> = _effective.asStateFlow()
+
+  @Synchronized
+  fun setIntent(intent: Boolean) {
+    _intent.value = intent
+    recompute()
+  }
+
+  @Synchronized
+  fun setForegrounded(foregrounded: Boolean) {
+    _foregrounded.value = foregrounded
+    recompute()
+  }
+
+  @Synchronized
+  fun reset() {
+    _intent.value = false
+    _foregrounded.value = true
+    _effective.value = false
+  }
+
+  private fun recompute() {
+    _effective.value = _intent.value && _foregrounded.value
+  }
+}

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

@@ -0,0 +1,17 @@
+package com.margelo.nitro.queueplayer.cast
+
+import androidx.media3.common.Player
+import kotlinx.coroutines.CoroutineScope
+
+/**
+ * Optional interface for [CastSession.PcmStream] sessions that can
+ * display metadata (title/artist/album/artwork/progress) on the
+ * receiver. Protocol-agnostic — describes WHAT to display, not HOW.
+ */
+interface MetadataAwareSession {
+  /** Begin syncing metadata from [player] to the receiver. */
+  fun onActivated(player: Player, scope: CoroutineScope)
+
+  /** Stop syncing. Safe to call multiple times. */
+  fun onDeactivated()
+}

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

@@ -0,0 +1,65 @@
+package com.margelo.nitro.queueplayer.cast
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * Single source of truth for "is a `RemotePlayer` cast session active
+ * right now?". When yes, transport commands
+ * (`play`/`pause`/`seekTo`/...) and playback-state reads route to the
+ * active session instead of the local ExoPlayer; when no, the local
+ * player handles them. `CastTransportRouter` (the playback-side shim)
+ * reads through [activeRemote] / observes [activeFlow] to decide.
+ *
+ * First-come-wins: a second [setActive] call with a non-null session
+ * while another is registered throws `IllegalStateException`. Multi-
+ * receiver is out of scope. Clearing (via `setActive(null)` or
+ * [clearActive]) is always safe.
+ */
+object PlaybackStateRouter {
+  private val _active = MutableStateFlow<CastSession.RemotePlayer?>(null)
+
+  /**
+   * Reactive view of the currently-active [CastSession.RemotePlayer].
+   * `CastEventBridge` collects this flow to attach / detach its
+   * per-session subscriptions when a remote session becomes active or
+   * is torn down. Emits the current value on subscribe.
+   */
+  val activeFlow: StateFlow<CastSession.RemotePlayer?> = _active.asStateFlow()
+
+  /**
+   * Snapshot the currently-active session, or `null` for local
+   * playback. Callers treat the return as a snapshot — the active
+   * session may change between calls.
+   */
+  fun activeRemote(): CastSession.RemotePlayer? = _active.value
+
+  /**
+   * Register [session] as the live remote-player session. Pass `null`
+   * to clear unconditionally. Registering a non-null session while
+   * another is already registered fails fast.
+   */
+  fun setActive(session: CastSession.RemotePlayer?) {
+    if (session == null) {
+      _active.value = null
+      return
+    }
+    val existing = _active.value
+    if (existing != null && existing !== session) {
+      throw IllegalStateException(
+        "A RemotePlayer session is already active. Clear it first via setActive(null)."
+      )
+    }
+    _active.value = session
+  }
+
+  /**
+   * Clear the active session only if it's still [expected]. Use from a
+   * closing session's teardown path so a newer session that registered
+   * in parallel isn't wiped out. Always safe.
+   */
+  fun clearActive(expected: CastSession.RemotePlayer) {
+    _active.compareAndSet(expected, null)
+  }
+}

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

@@ -0,0 +1,35 @@
+package com.margelo.nitro.queueplayer.cast
+
+/**
+ * A discovered cast target. One [Receiver] per remote device the user
+ * could potentially connect to. Backends namespace [id] with their own
+ * [protocol] prefix (e.g. `airplay:livingroom-homepod`,
+ * `chromecast:abc-123`) so the registry can deduplicate cleanly across
+ * backends.
+ */
+data class Receiver(
+  val id: String,
+  val protocol: String,
+  val name: String,
+  val iconHint: String,
+  val capabilities: ReceiverCapabilities,
+  val protocolVersion: String? = null,
+  val extras: Map<String, String> = emptyMap(),
+)
+
+/**
+ * Typed capability flags shared between [Receiver] and [Route]. Picker
+ * UI reads these to decide what controls to render — never branch on
+ * protocol name in UI code.
+ */
+data class ReceiverCapabilities(
+  val supportsRemoteVolume: Boolean,
+  val streamingModel: StreamingModel,
+  val requiresPairing: Boolean,
+)
+
+/** Cast paradigm: PCM-stream (AirPlay) vs URL-pull (Chromecast / DLNA). */
+enum class StreamingModel {
+  PUSH_PCM,
+  PULL_URL,
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/AirPlay2JNI.kt

@@ -0,0 +1,129 @@
+package com.margelo.nitro.queueplayer.cast.airplay
+
+/**
+ * JNI surface for the native libairplay2 library. Methods are
+ * registered via `JNI_OnLoad` in airplay2_jni.cpp using RegisterNatives.
+ *
+ * Session lifecycle:
+ *   [nativeAp2Open] → [nativeAp2Connect] → stream/control → [nativeAp2Disconnect] → [nativeAp2Destroy]
+ *
+ * The handle returned by [nativeAp2Open] is an opaque pointer (Long);
+ * pass it to every subsequent call.
+ */
+object AirPlay2JNI {
+
+    /** State constants matching ap2_state enum in airplay2_session.h. */
+    const val STATE_INIT          = 0
+    const val STATE_INFO          = 1
+    const val STATE_AUTH_SETUP    = 2
+    const val STATE_PAIR          = 3
+    const val STATE_ENCRYPTED     = 4
+    const val STATE_SETUP_SESSION = 5
+    const val STATE_SETUP_STREAM  = 6
+    const val STATE_RECORD        = 7
+    const val STATE_STREAMING     = 8
+    const val STATE_TEARDOWN      = 9
+
+    /** Auth mode constants matching ap2_auth_mode enum in airplay2_session.h. */
+    const val AUTH_TRANSIENT = 0
+    const val AUTH_PIN       = 1
+    const val AUTH_PASSWORD  = 2
+
+    /**
+     * `true` when libairplay2.so loaded successfully. Mirrors
+     * [AirplayJNI.isAvailable] — ABIs without prebuilt native libs report
+     * `false` and callers must skip every JNI entry rather than crash.
+     */
+    @JvmStatic
+    val isAvailable: Boolean = try {
+      System.loadLibrary("airplay2")
+      true
+    } catch (t: Throwable) {
+      android.util.Log.w("AirPlay2JNI", "libairplay2.so unavailable on this ABI: $t")
+      false
+    }
+
+    /** Session-death reason codes matching airplay2_jni.cpp AP2_DIED_*. */
+    const val DIED_FEEDBACK_TIMEOUT = 1
+
+    /**
+     * Registry of live sessions, keyed by native handle. Populated by
+     * [AirPlay2Session] on construction, removed on close. Native code
+     * upcalls into [onNativeSessionDied] with a handle and we dispatch
+     * to the registered session's own `onRemoteDied`.
+     */
+    private val sessionRegistry: MutableMap<Long, (Int) -> Unit> =
+        java.util.concurrent.ConcurrentHashMap()
+
+    @JvmStatic
+    internal fun registerSession(handle: Long, onDied: (Int) -> Unit) {
+        sessionRegistry[handle] = onDied
+    }
+
+    @JvmStatic
+    internal fun unregisterSession(handle: Long) {
+        sessionRegistry.remove(handle)
+    }
+
+    /**
+     * Called from the native drain thread when the session is declared dead.
+     * Runs on whatever thread JNI attaches us to; dispatch must be minimal —
+     * forward to the registered handler and return.
+     */
+    @JvmStatic
+    fun onNativeSessionDied(handle: Long, reason: Int) {
+        sessionRegistry[handle]?.invoke(reason)
+    }
+
+    // -- Session lifecycle --
+
+    @JvmStatic external fun nativeAp2Open(
+        host: String, port: Int,
+        sampleRate: Int, sampleSize: Int, channels: Int,
+        volume: Float,
+    ): Long
+
+    @JvmStatic external fun nativeAp2SetAuthKey(handle: Long, authKey: String)
+    @JvmStatic external fun nativeAp2SetDeviceName(handle: Long, name: String)
+    @JvmStatic external fun nativeAp2Connect(handle: Long): Boolean
+    @JvmStatic external fun nativeAp2Disconnect(handle: Long)
+    @JvmStatic external fun nativeAp2Destroy(handle: Long)
+
+    // -- Pairing --
+
+    @JvmStatic external fun nativeAp2NeedsPairing(handle: Long): Boolean
+    @JvmStatic external fun nativeAp2PairPinStart(handle: Long): Boolean
+    @JvmStatic external fun nativeAp2PairSetup(handle: Long, credential: String): String?
+    @JvmStatic external fun nativeAp2GetPairingState(handle: Long): Int
+    @JvmStatic external fun nativeAp2GetAuthMode(handle: Long): Int
+    @JvmStatic external fun nativeAp2GetDeviceId(handle: Long): String?
+    @JvmStatic external fun nativeAp2SetPassword(handle: Long, password: String)
+
+    // -- Audio --
+
+    /** Feed PCM data into the native ring buffer. Returns bytes consumed. */
+    @JvmStatic external fun nativeAp2FeedPcm(
+        handle: Long, pcm: ByteArray, offset: Int, length: Int,
+    ): Int
+
+    @JvmStatic external fun nativeAp2GetBytesSent(handle: Long): Long
+    @JvmStatic external fun nativeAp2RingAvailable(handle: Long): Int
+
+    // -- Control --
+
+    @JvmStatic external fun nativeAp2SetVolume(handle: Long, volume: Float)
+    @JvmStatic external fun nativeAp2SetMetadata(handle: Long, title: String?, artist: String?, album: String?)
+    @JvmStatic external fun nativeAp2SetArtwork(handle: Long, jpeg: ByteArray, length: Int)
+    @JvmStatic external fun nativeAp2SetProgressMs(handle: Long, elapsed: Long, duration: Long)
+    @JvmStatic external fun nativeAp2Pause(handle: Long)
+    @JvmStatic external fun nativeAp2Resume(handle: Long)
+
+    // -- Status --
+
+    @JvmStatic external fun nativeAp2GetState(handle: Long): Int
+
+    // -- File logging (persists on device when USB disconnected) --
+
+    @JvmStatic external fun nativeAp2InitFileLog(path: String)
+    @JvmStatic external fun nativeAp2CloseFileLog()
+}