react-native-queue-player 1.0.0

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

@@ -0,0 +1,202 @@
+package com.margelo.nitro.queueplayer.cast
+
+import android.content.Context
+import android.media.AudioDeviceCallback
+import android.media.AudioDeviceInfo
+import android.media.AudioManager
+import android.os.Handler
+import android.os.Looper
+import com.margelo.nitro.queueplayer.AudioRoute
+import com.margelo.nitro.queueplayer.AudioRouteKind
+import java.util.concurrent.CopyOnWriteArraySet
+
+/**
+ * Process-wide observer of the currently active audio output. Bridges
+ * Android's [AudioManager.registerAudioDeviceCallback] +
+ * [AudioManager.getDevices] surface to the lib's cross-platform
+ * `AudioRoute` shape.
+ *
+ * Android does not expose a single "where is music going right now"
+ * API for the idle-player case. The active output is inferred from the
+ * connected device list via a priority scan:
+ *   LE Audio  →  classic A2DP  →  USB  →  wired  →  HDMI  →  dock /
+ *   line  →  TYPE_BUS (AAOS)  →  built-in speaker.
+ *
+ * `AudioTrack.getRoutedDevice()` would give a perfect answer for the
+ * actively-playing case but requires deep ExoPlayer hooks
+ * (`AnalyticsListener.onAudioSessionIdChanged` + reflection); the
+ * prioritized scan covers ~95% of cases without that coupling.
+ *
+ * Bluetooth product names degrade to a generic string on Android 12+
+ * without the `BLUETOOTH_CONNECT` runtime permission — consumer apps
+ * decide whether to request it; the route still reports the right
+ * kind regardless.
+ */
+internal class AudioRouteState(private val context: Context) {
+
+  private val audioManager: AudioManager =
+    context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+
+  private val mainHandler = Handler(Looper.getMainLooper())
+
+  private val listeners = CopyOnWriteArraySet<(AudioRoute) -> Unit>()
+
+  @Volatile
+  private var cached: AudioRoute = computeCurrent()
+
+  private val deviceCallback = object : AudioDeviceCallback() {
+    override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>?) {
+      recompute()
+    }
+
+    override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>?) {
+      recompute()
+    }
+  }
+
+  private var isObserving = false
+
+  fun start() {
+    if (isObserving) return
+    isObserving = true
+    audioManager.registerAudioDeviceCallback(deviceCallback, mainHandler)
+    recompute()
+  }
+
+  /** Snapshot the current route. Safe to call from any thread. */
+  fun currentRoute(): AudioRoute = cached
+
+  /**
+   * Subscribe to route changes. Fires once on the main thread with the
+   * current route (consistent with the threading of subsequent
+   * updates), then on every subsequent change. Returns a disposer that
+   * removes the subscription.
+   */
+  fun addListener(callback: (AudioRoute) -> Unit): () -> Unit {
+    listeners.add(callback)
+    val snap = cached
+    mainHandler.post { callback(snap) }
+    return { listeners.remove(callback) }
+  }
+
+  private fun recompute() {
+    val next = computeCurrent()
+    cached = next
+    val snap = next
+    mainHandler.post {
+      for (l in listeners) l(snap)
+    }
+  }
+
+  private fun computeCurrent(): AudioRoute {
+    val outputs = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+    val active = pickPriority(outputs) ?: return LOCAL_SPEAKER
+    return audioRouteFrom(active)
+  }
+
+  /**
+   * Pick the highest-priority output from the connected list. Order
+   * matches Android's own internal music-routing preference: external
+   * devices win over built-in speaker, with BT high-quality codecs
+   * preferred over wired.
+   */
+  private fun pickPriority(outputs: Array<AudioDeviceInfo>): AudioDeviceInfo? {
+    val order = intArrayOf(
+      AudioDeviceInfo.TYPE_BLE_HEADSET,
+      AudioDeviceInfo.TYPE_BLE_SPEAKER,
+      AudioDeviceInfo.TYPE_BLE_BROADCAST,
+      AudioDeviceInfo.TYPE_HEARING_AID,
+      AudioDeviceInfo.TYPE_BLUETOOTH_A2DP,
+      AudioDeviceInfo.TYPE_BLUETOOTH_SCO,
+      AudioDeviceInfo.TYPE_USB_HEADSET,
+      AudioDeviceInfo.TYPE_USB_DEVICE,
+      AudioDeviceInfo.TYPE_USB_ACCESSORY,
+      AudioDeviceInfo.TYPE_LINE_DIGITAL,
+      AudioDeviceInfo.TYPE_WIRED_HEADSET,
+      AudioDeviceInfo.TYPE_WIRED_HEADPHONES,
+      AudioDeviceInfo.TYPE_LINE_ANALOG,
+      AudioDeviceInfo.TYPE_AUX_LINE,
+      AudioDeviceInfo.TYPE_HDMI,
+      AudioDeviceInfo.TYPE_HDMI_ARC,
+      AudioDeviceInfo.TYPE_HDMI_EARC,
+      AudioDeviceInfo.TYPE_DOCK,
+      AudioDeviceInfo.TYPE_DOCK_ANALOG,
+      AudioDeviceInfo.TYPE_BUS,
+      AudioDeviceInfo.TYPE_BUILTIN_SPEAKER,
+      AudioDeviceInfo.TYPE_BUILTIN_SPEAKER_SAFE,
+      AudioDeviceInfo.TYPE_BUILTIN_EARPIECE,
+    )
+    for (preferredType in order) {
+      val match = outputs.firstOrNull { it.type == preferredType }
+      if (match != null) return match
+    }
+    return null
+  }
+
+  private fun audioRouteFrom(device: AudioDeviceInfo): AudioRoute {
+    val kind = mapKind(device.type)
+    val name = device.productName?.toString()?.takeIf { it.isNotEmpty() }
+      ?: defaultName(kind)
+    val identifier = device.address ?: ""
+    return AudioRoute(
+      kind = kind,
+      name = name,
+      identifier = identifier,
+      isExternal = kind != AudioRouteKind.SPEAKER && kind != AudioRouteKind.RECEIVER,
+      isSystemManaged = true,
+    )
+  }
+
+  private fun mapKind(type: Int): AudioRouteKind = when (type) {
+    AudioDeviceInfo.TYPE_BUILTIN_SPEAKER,
+    AudioDeviceInfo.TYPE_BUILTIN_SPEAKER_SAFE -> AudioRouteKind.SPEAKER
+    AudioDeviceInfo.TYPE_BUILTIN_EARPIECE -> AudioRouteKind.RECEIVER
+    AudioDeviceInfo.TYPE_WIRED_HEADSET,
+    AudioDeviceInfo.TYPE_WIRED_HEADPHONES,
+    AudioDeviceInfo.TYPE_LINE_ANALOG,
+    AudioDeviceInfo.TYPE_AUX_LINE,
+    AudioDeviceInfo.TYPE_DOCK,
+    AudioDeviceInfo.TYPE_DOCK_ANALOG -> AudioRouteKind.WIRED
+    AudioDeviceInfo.TYPE_USB_HEADSET,
+    AudioDeviceInfo.TYPE_USB_DEVICE,
+    AudioDeviceInfo.TYPE_USB_ACCESSORY,
+    AudioDeviceInfo.TYPE_LINE_DIGITAL -> AudioRouteKind.USB
+    AudioDeviceInfo.TYPE_HDMI,
+    AudioDeviceInfo.TYPE_HDMI_ARC,
+    AudioDeviceInfo.TYPE_HDMI_EARC -> AudioRouteKind.HDMI
+    AudioDeviceInfo.TYPE_BLUETOOTH_A2DP -> AudioRouteKind.BLUETOOTHA2DP
+    AudioDeviceInfo.TYPE_BLUETOOTH_SCO -> AudioRouteKind.BLUETOOTHHFP
+    AudioDeviceInfo.TYPE_BLE_HEADSET,
+    AudioDeviceInfo.TYPE_BLE_SPEAKER,
+    AudioDeviceInfo.TYPE_BLE_BROADCAST,
+    AudioDeviceInfo.TYPE_HEARING_AID -> AudioRouteKind.BLUETOOTHLE
+    AudioDeviceInfo.TYPE_BUS -> AudioRouteKind.ANDROIDAUTO
+    else -> AudioRouteKind.UNKNOWN
+  }
+
+  private fun defaultName(kind: AudioRouteKind): String = when (kind) {
+    AudioRouteKind.SPEAKER -> "Phone speaker"
+    AudioRouteKind.RECEIVER -> "Phone earpiece"
+    AudioRouteKind.WIRED -> "Wired headphones"
+    AudioRouteKind.USB -> "USB audio"
+    AudioRouteKind.HDMI -> "HDMI audio"
+    AudioRouteKind.BLUETOOTHA2DP -> "Bluetooth audio"
+    AudioRouteKind.BLUETOOTHLE -> "Bluetooth LE audio"
+    AudioRouteKind.BLUETOOTHHFP -> "Bluetooth headset"
+    AudioRouteKind.ANDROIDAUTO -> "Android Auto"
+    AudioRouteKind.AIRPLAY -> "AirPlay"
+    AudioRouteKind.CHROMECAST -> "Chromecast"
+    AudioRouteKind.CARPLAY -> "CarPlay"
+    AudioRouteKind.UNKNOWN -> "Audio output"
+  }
+
+  internal companion object {
+    val LOCAL_SPEAKER: AudioRoute = AudioRoute(
+      kind = AudioRouteKind.SPEAKER,
+      name = "Phone speaker",
+      identifier = "",
+      isExternal = false,
+      isSystemManaged = true,
+    )
+  }
+}

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

@@ -0,0 +1,14 @@
+package com.margelo.nitro.queueplayer.cast
+
+/**
+ * Thrown by [CastBackend.connect] when the receiver requires
+ * authentication (e.g. AirPlay password / PIN). `CastManager` catches
+ * this + rejects the connect promise with `authFailed`, surfacing
+ * [authMode] in the rejection payload so JS can show the right
+ * prompt (`"pin"` = 4-digit code shown by receiver; `"password"` =
+ * user already knows it).
+ */
+class AuthRequiredException(
+  message: String,
+  val authMode: String,
+) : RuntimeException(message)

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

@@ -0,0 +1,41 @@
+package com.margelo.nitro.queueplayer.cast
+
+/**
+ * Contract every cast protocol implements. One [CastBackend] per
+ * protocol family — `AirPlayBackend` for the AirPlay 1/2 family,
+ * `ChromecastBackend` for Cast, future DLNA / Sonos similarly. The
+ * core module never knows which backends are present.
+ *
+ * The interface is intentionally tiny. Anything richer (volume,
+ * pairing PIN flow, capability discovery) lives on the [CastSession]
+ * subtype that [connect] returns. Keeps the registry pluggable + the
+ * routing layer protocol-agnostic.
+ */
+interface CastBackend {
+
+  /** Stable string identifier matching the `protocol:` prefix on receiver IDs. */
+  val protocolId: String
+
+  /**
+   * Begin discovery. Callback fires every time the discovered set
+   * changes — backends should debounce. Idempotent: calling when
+   * already running must not duplicate listeners.
+   */
+  fun startDiscovery(onUpdate: (List<Receiver>) -> Unit)
+
+  /** Stop discovery + release resources. Safe when not running. */
+  fun stopDiscovery()
+
+  /**
+   * Connect to a discovered receiver. Suspending because protocol
+   * handshakes are async. Throws on failure; the caller surfaces the
+   * error through the JS promise.
+   *
+   * @param options Protocol-specific. Recognised keys: `"password"`
+   *   (String) — receiver password / PIN for authenticated receivers.
+   */
+  suspend fun connect(
+    receiverId: String,
+    options: Map<String, Any?> = emptyMap(),
+  ): CastSession
+}

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

@@ -0,0 +1,56 @@
+package com.margelo.nitro.queueplayer.cast
+
+import com.margelo.nitro.queueplayer.cast.http.LocalMediaServer
+
+/**
+ * Process-wide registry of available [CastBackend]s. Backends self-install
+ * during app startup (e.g. AirPlay via androidx.startup
+ * `InitializationProvider`); the [com.margelo.nitro.queueplayer.CastManager]
+ * looks them up by protocol id.
+ *
+ * Thread-safe via a synchronized list — registration happens during app
+ * init while the rest of the app may already be spinning up other threads.
+ */
+object CastBackends {
+
+  private val backends = mutableListOf<CastBackend>()
+  private val lock = Any()
+
+  /**
+   * Process-wide [LocalMediaServer] singleton shared across cast
+   * backends (Chromecast `file://` serving today; future DLNA / Sonos).
+   * Lazy — never instantiated for apps that don't cast local files.
+   * `by lazy` is thread-safe; two concurrent first-touches see the
+   * same instance.
+   */
+  val localMediaServer: LocalMediaServer by lazy { LocalMediaServer() }
+
+  /**
+   * Register a backend. Idempotent for the same instance — registering
+   * twice is a no-op. Registering a different backend with the same
+   * [CastBackend.protocolId] throws — it indicates a real configuration bug.
+   */
+  fun register(backend: CastBackend) {
+    synchronized(lock) {
+      if (backends.contains(backend)) return
+      val existing = backends.firstOrNull { it.protocolId == backend.protocolId }
+      require(existing == null) {
+        "A backend for protocol '${backend.protocolId}' is already registered: $existing"
+      }
+      backends.add(backend)
+    }
+  }
+
+  /** Snapshot of currently registered backends. Defensive copy — safe to iterate. */
+  fun all(): List<CastBackend> = synchronized(lock) { backends.toList() }
+
+  /** Look up a backend by [CastBackend.protocolId], or `null` if absent. */
+  fun byProtocol(protocolId: String): CastBackend? = synchronized(lock) {
+    backends.firstOrNull { it.protocolId == protocolId }
+  }
+
+  /** Clear all registered backends. Used by tests. */
+  fun reset() {
+    synchronized(lock) { backends.clear() }
+  }
+}

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

@@ -0,0 +1,122 @@
+package com.margelo.nitro.queueplayer.cast
+
+import android.util.Log
+import com.margelo.nitro.queueplayer.PlayerState
+import com.margelo.nitro.queueplayer.StateChangeReason
+import com.margelo.nitro.queueplayer.TrackPlayer
+import kotlinx.coroutines.CoroutineExceptionHandler
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.collectLatest
+import kotlinx.coroutines.launch
+
+/**
+ * Bridges cast `RemotePlayer` session state back into the lib's
+ * existing event surface (`onStateChange` / etc.). Observes
+ * [PlaybackStateRouter.activeFlow]: when a session becomes active,
+ * subscribes to its StateFlows + fans receiver updates through
+ * `TrackPlayer.emitRemoteState`. When the session ends, unsubscribes
+ * cleanly.
+ *
+ * Single-instance — `TrackPlayer.init` constructs one bridge and
+ * holds it for the process lifetime (HybridObject singleton). The
+ * bridge's own scope is `SupervisorJob() + Dispatchers.Main` so a
+ * collector failure on one session doesn't tear down the watcher
+ * for the next.
+ */
+internal class CastEventBridge(private val owner: TrackPlayer) {
+
+  // Last-resort guard: an unexpected throw in a per-session collector
+  // (e.g. a receiver-load failure surfacing through the handoff) must log,
+  // not crash the app's main thread.
+  private val exceptionHandler = CoroutineExceptionHandler { _, t ->
+    Log.w("CastEventBridge", "Cast bridge collector failed", t)
+  }
+
+  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main + exceptionHandler)
+
+  /** Active per-session collection job (cancelled on session change). */
+  private var sessionJob: Job? = null
+
+  // Continuous snapshot of the receiver's last-known position + track
+  // index while casting, applied to the local engine on the cast->local
+  // handback so it lands on the receiver's last spot (paused).
+  private var lastPositionMs: Long = 0L
+  private var lastTrackIndex: Int = -1
+
+  fun start() {
+    scope.launch {
+      PlaybackStateRouter.activeFlow.collectLatest { session ->
+        sessionJob?.cancel()
+        sessionJob = null
+        if (session == null) {
+          // Returning to local — seek the local engine to where the
+          // receiver left off and stay paused (the user resumes locally).
+          owner.resumeLocalAfterCast(
+            trackIndex = lastTrackIndex,
+            positionMs = lastPositionMs,
+          )
+          return@collectLatest
+        }
+        // New session — reset the snapshot, then hand off current local
+        // playback to the receiver so it continues from the same position
+        // + play/pause.
+        lastPositionMs = 0L
+        lastTrackIndex = -1
+        owner.handoffCurrentPlaybackToCast()
+        sessionJob = scope.launch {
+          launch {
+            session.state.collectLatest { remoteState ->
+              owner.emitRemoteState(mapState(remoteState), StateChangeReason.SYSTEM)
+            }
+          }
+          launch {
+            session.positionMs.collectLatest { pos -> lastPositionMs = pos }
+          }
+          launch {
+            session.currentTrackIndex.collectLatest { idx ->
+              if (idx >= 0) {
+                lastTrackIndex = idx
+                // Fan the receiver's queue position to the JS now-playing
+                // surface (onTrackChange + getCurrentTrackIndex), not just
+                // the resume snapshot.
+                owner.emitRemoteTrackChange(idx)
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  fun stop() {
+    sessionJob?.cancel()
+    sessionJob = null
+    scope.cancel()
+  }
+
+  /**
+   * Seed the resume snapshot from the local pre-handoff position + index
+   * so a disconnect before the receiver reports (rapid connect/disconnect,
+   * before the load round-trip settles) still lands local on the right
+   * spot. Receiver position/index updates collected during the session
+   * take precedence as they arrive.
+   */
+  fun seedResumeSnapshot(trackIndex: Int, positionMs: Long) {
+    lastTrackIndex = trackIndex
+    lastPositionMs = positionMs
+  }
+
+  private fun mapState(state: RemotePlaybackState): PlayerState = when (state) {
+    RemotePlaybackState.PLAYING -> PlayerState.PLAYING
+    RemotePlaybackState.PAUSED -> PlayerState.PAUSED
+    RemotePlaybackState.LOADING -> PlayerState.BUFFERING
+    RemotePlaybackState.BUFFERING -> PlayerState.BUFFERING
+    RemotePlaybackState.IDLE -> PlayerState.NONE
+    RemotePlaybackState.ENDED -> PlayerState.ENDED
+    RemotePlaybackState.ERROR -> PlayerState.ERROR
+  }
+}

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

@@ -0,0 +1,20 @@
+package com.margelo.nitro.queueplayer.cast
+
+import android.net.Uri
+
+/**
+ * Protocol-neutral media item handed to cast backends. Cast backends
+ * consume typed fields directly — no reflection. Translation from the
+ * lib's `TrackItem` happens at the bridge boundary so the backend
+ * never depends on the Nitro JS-bridge contract.
+ */
+data class CastMediaItem(
+  val uri: Uri,
+  val title: String? = null,
+  val artist: String? = null,
+  val album: String? = null,
+  val artwork: Uri? = null,
+  val durationMs: Long? = null,
+  val contentType: String? = null,
+  val headers: Map<String, String>? = null,
+)

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

@@ -0,0 +1,193 @@
+package com.margelo.nitro.queueplayer.cast
+
+import androidx.media3.common.Player
+import androidx.media3.exoplayer.audio.AudioSink
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * A live cast session — what [CastBackend.connect] returns. Sealed
+ * with two cases reflecting the two cast paradigms:
+ *
+ * - [PcmStream] — sender keeps decoding via ExoPlayer; session exposes
+ *   an [AudioSink] that ExoPlayer pushes its decoded PCM into. AirPlay
+ *   1 and AirPlay 2 both fit here.
+ * - [RemotePlayer] — receiver decodes; ExoPlayer goes idle and the
+ *   session forwards transport commands to the remote device.
+ *   Chromecast + future DLNA/Sonos fit here.
+ */
+sealed class CastSession {
+
+  /**
+   * `true` when the backend expects the sender to keep decoding and
+   * push PCM frames into an `AudioSink` (AirPlay); `false` when the
+   * receiver pulls + decodes itself (Chromecast). Read by the
+   * cast-transport router to decide whether to intercept
+   * `TrackPlayer.*` calls or let the local player handle them.
+   */
+  abstract val isPushSink: Boolean
+
+  /** Adjust receiver volume `0.0..1.0`. No-op when not supported. */
+  abstract fun setVolume(value: Float)
+
+  /** Tear down. Safe to call multiple times. */
+  abstract fun close()
+
+  /**
+   * Invoked by the backend when the receiver side died unexpectedly
+   * (WiFi loss, power-off, keep-alive timeout). Set by `CastManager`
+   * after `connect()`; backend invokes on a detection thread.
+   * Handlers must post cleanup to the main thread themselves.
+   */
+  @Volatile
+  var deathListener: ((reason: String) -> Unit)? = null
+
+  /** Paradigm A — backend is an `AudioSink`. */
+  abstract class PcmStream : CastSession() {
+    final override val isPushSink: Boolean = true
+
+    /**
+     * Return the `AudioSink` ExoPlayer should push decoded PCM into.
+     * Called once per active session by `CastSinkRouter` when the
+     * session becomes active.
+     */
+    abstract fun audioSink(): AudioSink
+  }
+
+  /** Paradigm B — backend is a remote player. */
+  abstract class RemotePlayer : CastSession() {
+    final override val isPushSink: Boolean = false
+
+    /**
+     * Optional `Player` implementation for `MediaSession`. When
+     * non-null, `MusicService` swaps `mediaSession.player` to this on
+     * cast connect and back on disconnect. Chromecast returns a
+     * `RemoteCastPlayer` from `media3-cast`. Default null.
+     */
+    open val mediaSessionPlayer: Player? = null
+
+    /**
+     * Push the full [items] queue to the receiver starting at
+     * [startIndex] + [startPositionMs], beginning playback only when
+     * [playWhenReady] is true (a handoff from a paused local session
+     * starts the receiver paused at that position).
+     */
+    abstract suspend fun load(
+      items: List<CastMediaItem>,
+      startIndex: Int,
+      startPositionMs: Long,
+      playWhenReady: Boolean,
+    )
+
+    abstract fun play()
+    abstract fun pause()
+    abstract fun stop()
+    abstract fun seekTo(positionMs: Long)
+    abstract fun queueNext()
+    abstract fun queuePrev()
+
+    /**
+     * Jump the receiver to the queue item at absolute lib-track [index].
+     * The backend resolves [index] to the receiver itemId against the
+     * full queue (the Cast SDK `MediaQueue`), so callers pass lib
+     * indices, never opaque receiver itemIds. Out-of-range / unresolved
+     * indices are a no-op.
+     */
+    abstract fun skipToQueueIndex(index: Int)
+
+    /**
+     * Insert [items] before the queue item at absolute lib-track
+     * [beforeIndex] (resolved to a receiver itemId against the full
+     * queue); `null` / out-of-range appends.
+     */
+    abstract suspend fun queueInsert(
+      items: List<CastMediaItem>,
+      beforeIndex: Int?,
+    )
+
+    /** Remove the queue items at the given absolute lib-track indices. */
+    abstract suspend fun queueRemove(indices: List<Int>)
+
+    /**
+     * Move the queue item at [fromIndex] to [toIndex] (array-move
+     * semantics).
+     */
+    abstract suspend fun queueMove(fromIndex: Int, toIndex: Int)
+
+    /** Remove every item from the receiver queue. */
+    abstract suspend fun queueClear()
+
+    abstract fun setPlaybackRate(rate: Float)
+    abstract fun setRepeatMode(mode: RemoteRepeatMode)
+
+    /** Receiver-driven playback state for `PlaybackStateRouter`. */
+    abstract val state: StateFlow<RemotePlaybackState>
+
+    /** Receiver-driven position in ms. */
+    abstract val positionMs: StateFlow<Long>
+
+    /** Receiver-reported stream duration in ms. */
+    abstract val durationMs: StateFlow<Long>
+
+    /**
+     * RNQP track index derived from media-session player's
+     * `currentMediaItemIndex`. `-1` = unknown.
+     */
+    open val currentTrackIndex: StateFlow<Int>
+      get() = MutableStateFlow(-1)
+
+    /** Fires when receiver enters IDLE with non-NONE idleReason. */
+    abstract val endedReason: SharedFlow<RemoteEndReason>
+
+    /** Fires once per receiver media error. */
+    abstract val mediaError: SharedFlow<RemoteMediaError>
+
+    /** Fires once per completed seek with the resolved position (ms). */
+    abstract val seekCompleted: SharedFlow<Long>
+  }
+}
+
+/**
+ * Reason a track ended on the receiver. Maps `MediaStatus.IDLE_REASON_*`
+ * (Android) and `GCKMediaPlayerIdleReason*` (iOS) onto one enum.
+ */
+enum class RemoteEndReason {
+  FINISHED,
+  INTERRUPTED,
+  CANCELED,
+  ERROR,
+}
+
+/**
+ * Error from the receiver during playback. [code] is platform-native;
+ * [message] is platform-native description when available.
+ */
+data class RemoteMediaError(
+  val code: Int,
+  val message: String?,
+)
+
+/**
+ * Receiver-queue repeat mode. Maps `MediaStatus.REPEAT_MODE_*` /
+ * `GCKMediaRepeatMode*`. `ALL_AND_SHUFFLE` intentionally absent.
+ */
+enum class RemoteRepeatMode {
+  OFF,
+  SINGLE,
+  ALL,
+}
+
+/**
+ * Playback state from a [CastSession.RemotePlayer]. Mapping to lib's
+ * local-side `State` enum lives in `PlaybackStateRouter`.
+ */
+enum class RemotePlaybackState {
+  IDLE,
+  LOADING,
+  PLAYING,
+  PAUSED,
+  BUFFERING,
+  ENDED,
+  ERROR,
+}