react-native-nitro-player 1.4.4-alpha.0 → 1.5.0-alpha.1

package/NitroPlayer.podspec

@@ -27,5 +27,11 @@ Pod::Spec.new do |s|
 
   s.dependency 'React-jsi'
   s.dependency 'React-callinvoker'
+
+  # Google Cast (CAF) — provides GCKCastContext / GCKRemoteMediaClient used by the
+  # Cast HybridObject. Requires NSBonjourServices + NSLocalNetworkUsageDescription
+  # (and, for guest mode, NSBluetoothAlwaysUsageDescription) in the host app's Info.plist.
+  s.dependency 'google-cast-sdk', '~> 4.8'
+
   install_modules_dependencies(s)
 end

package/README.md

@@ -90,6 +90,8 @@ Mutations return **`Promise<void>`** (or **`Promise<string>`** for `createPlayli
 | `AudioDevices.getAudioDevices()`         | Android  | Returns list of available audio devices.          |
 | `AudioDevices.setAudioDevice(id)`        | Android  | Sets the active audio output device.              |
 | `AudioRoutePicker.showRoutePicker()`     | iOS      | Opens the native AirPlay/Audio Route picker menu. |
+| `Cast.showCastPicker()`                  | iOS & Android | Opens the native Google Cast device picker.  |
+| `Cast.isCasting()` / `useIsCasting()`    | iOS & Android | Whether playback is routed to a Cast device. |
 | `AndroidAutoMediaLibraryHelper.set(...)` | Android  | Sets custom folder structure for Android Auto.    |
 | `AndroidAutoMediaLibraryHelper.clear()`  | Android  | Resets Android Auto structure to default.         |
 
@@ -598,6 +600,118 @@ if (AudioRoutePicker) {
 ```
 
 
+## Google Cast
+
+Cast playback to Chromecast / Google TV devices. Casting is **seamless**: it is
+implemented as an internal playback-backend swap, so a Cast device behaves like
+another output for the existing player. When a session is connected, audio plays
+**only on the Cast device**, the local output is silenced automatically, and your
+existing queue, transport controls (in-app, lock screen, notification) and events
+keep working against the remote. On disconnect, local playback resumes at the same
+position.
+
+- **Android** uses Media3's `CastPlayer` (the local ExoPlayer is swapped to it).
+- **iOS** uses the Google Cast SDK (`GCKRemoteMediaClient`).
+
+### JS API
+
+```ts
+import { Cast, CastButton, useIsCasting, useCastState } from 'react-native-nitro-player'
+
+// Optional: call once early (e.g. on app start) to use your own registered
+// Web Receiver. Omit / pass nothing to use the Default Media Receiver.
+await Cast.configure('YOUR_RECEIVER_APP_ID')
+
+Cast.isCasting()           // boolean — is playback currently on a Cast device
+Cast.getCastState()        // 'no_devices_available' | 'not_connected' | 'connecting' | 'connected'
+Cast.getCastDeviceName()   // string | null
+Cast.showCastPicker()      // present the native device chooser / disconnect dialog
+await Cast.endCastSession() // stop casting, resume locally
+
+// Low-level event listener (the hooks below wrap this)
+Cast.onCastStateChange((state, deviceName) => { /* ... */ })
+```
+
+> ℹ️ The receiver application ID is fixed for the process lifetime once Cast
+> initializes. Call `Cast.configure(id)` as early as possible; otherwise the change
+> applies on the next app launch. The **Default Media Receiver** works out of the box.
+
+### Hooks
+
+```tsx
+function NowPlaying() {
+  const isCasting = useIsCasting() // boolean
+
+  // Or the richer variant:
+  const { state, deviceName, isCasting, isReady } = useCastState()
+
+  return <Text>{isCasting ? `Casting to ${deviceName}` : 'Playing locally'}</Text>
+}
+```
+
+### `<CastButton />`
+
+A ready-to-use button that reflects the live connection state, hides itself when
+no devices are available, and opens the native Cast dialog on press.
+
+```tsx
+import { CastButton } from 'react-native-nitro-player'
+
+<CastButton size={28} color="#888" activeColor="#1DB954" />
+```
+
+Props: `size`, `color`, `activeColor`, `hideWhenNoDevices` (default `true`),
+`style`, `onPress` (override the default picker), and `renderIcon` (supply your own
+icon — receives `{ state, isCasting, size, color }`). Any other `Pressable` prop is
+forwarded. Prefer building your own button? Call `Cast.showCastPicker()` directly.
+
+### Setup
+
+Cast requires native configuration in your **app** (not just the library).
+
+**iOS** — add to `ios/<App>/Info.plist`:
+
+```xml
+<key>NSLocalNetworkUsageDescription</key>
+<string>${PRODUCT_NAME} uses the local network to discover Cast devices.</string>
+<key>NSBonjourServices</key>
+<array>
+  <string>_googlecast._tcp</string>
+  <!-- Receiver-specific service. Use _CC1AD845._googlecast._tcp for the Default
+       Media Receiver, or _<YOUR_RECEIVER_APP_ID>._googlecast._tcp for a custom one. -->
+  <string>_CC1AD845._googlecast._tcp</string>
+</array>
+<!-- Only if you use Cast guest mode (full SDK): -->
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>${PRODUCT_NAME} uses Bluetooth to discover nearby Cast devices.</string>
+```
+
+The Google Cast SDK is pulled in automatically via the pod dependency — just run
+`pod install`. No `AppDelegate` code is required; the library initializes the Cast
+context on launch (with the Default Media Receiver, or your `Cast.configure` ID).
+
+**Android** — no app code required. The library declares the Cast `OptionsProvider`
+and discovery permissions in its manifest (merged automatically) and initializes the
+Cast framework from its playback service at launch. Cast device discovery requires
+Google Play services on the device (unavailable on most emulators).
+
+> Apps that also use another Cast `OptionsProvider` (e.g. `react-native-google-cast`)
+> must override the merged meta-data with `tools:replace`. To set a custom receiver
+> ID without `Cast.configure`, override the
+> `com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME` meta-data with
+> your own provider.
+
+### Notes & limitations
+
+- **Testing requires a real Cast device** on the same Wi-Fi network — there is no
+  simulator/emulator support.
+- The full effective queue (playlist + play-next + up-next) is mirrored to the
+  device, so skip / previous / seek work remotely.
+- On iOS, while casting the lock-screen Now Playing metadata is best-effort; the
+  transport buttons themselves control the Cast device.
+- If a device has no Google Play services (Android) or the SDK is otherwise
+  unavailable, Cast features degrade to inert no-ops (`isCasting` stays `false`).
+
 ## Equalizer
 
 The player includes a powerful 5-band equalizer that works on both iOS and Android.
@@ -1121,6 +1235,7 @@ AndroidAutoMediaLibraryHelper.set({
 - ✅ **Notification Controls**: Show playback controls in notifications
 - ✅ **Progress Tracking**: Real-time playback progress updates
 - ✅ **Offline Downloads**: Download tracks and playlists for offline playback
+- ✅ **Google Cast**: Seamless casting to Chromecast / Google TV (iOS & Android)
 
 ## TypeScript Support
 

package/android/build.gradle

@@ -45,6 +45,8 @@ android {
     minSdkVersion getExtOrIntegerDefault("minSdkVersion")
     targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
     buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+    // Keep the Cast OptionsProvider (referenced reflectively from the manifest) under R8.
+    consumerProguardFiles "consumer-rules.pro"
 
     externalNativeBuild {
       cmake {
@@ -147,6 +149,12 @@ dependencies {
   implementation "androidx.media3:media3-common:$media3_version"
   implementation "androidx.media:media:1.7.0"
 
+  // Google Cast: CastPlayer (drop-in Media3 Player), the Cast framework and the
+  // MediaRouter chooser/controller dialogs used by Cast.showCastPicker().
+  implementation "androidx.media3:media3-cast:$media3_version"
+  implementation "com.google.android.gms:play-services-cast-framework:21.5.0"
+  implementation "androidx.mediarouter:mediarouter:1.7.0"
+
   // WorkManager for background downloads.
   implementation "androidx.work:work-runtime-ktx:2.10.5" // Latest version of 2.10
 }

package/android/src/main/AndroidManifest.xml

@@ -8,12 +8,23 @@
     <uses-permission android:name="android.permission.WAKE_LOCK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
+    <!-- Google Cast device discovery (mDNS / Cast SDK) -->
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
+
     <!-- Required so Android Auto / Assistant treat this as a media app. -->
     <uses-feature
         android:name="android.hardware.audio.output"
         android:required="false" />
 
     <application>
+        <!-- Google Cast: supplies CastOptions (receiver app ID) to the Cast SDK.
+             Apps shipping their own OptionsProvider must override with tools:replace. -->
+        <meta-data
+            android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
+            android:value="com.margelo.nitro.nitroplayer.media.NitroCastOptionsProvider" />
+
         <!-- PlaybackService keeps music alive when screen is locked / app backgrounded -->
         <service
             android:name="com.margelo.nitro.nitroplayer.media.NitroPlayerPlaybackService"

package/android/src/main/java/com/margelo/nitro/nitroplayer/HybridCast.kt

@@ -0,0 +1,79 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
+package com.margelo.nitro.nitroplayer
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.NullType
+import com.margelo.nitro.core.Promise
+import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.configureCast
+import com.margelo.nitro.nitroplayer.core.endCastSession
+import com.margelo.nitro.nitroplayer.core.getCastDeviceName
+import com.margelo.nitro.nitroplayer.core.getCastState
+import com.margelo.nitro.nitroplayer.core.isCasting
+import com.margelo.nitro.nitroplayer.core.showCastPicker
+
+/**
+ * Nitro module exposing the Google Cast control surface to JS. Routing of actual
+ * playback to/from the Cast device is handled internally by [TrackPlayerCore]
+ * (see `TrackPlayerCast`); this object only forwards Cast-specific calls.
+ */
+@DoNotStrip
+@Keep
+class HybridCast : HybridCastSpec() {
+    private val applicationContext = NitroModules.applicationContext
+    private val core: TrackPlayerCore
+
+    private val listenerIds = mutableListOf<Long>()
+
+    init {
+        val context =
+            applicationContext
+                ?: throw IllegalStateException("React Context is not initialized")
+        core = TrackPlayerCore.getInstance(context)
+    }
+
+    override fun configure(receiverApplicationId: String?): Promise<Unit> =
+        Promise.async { core.configureCast(receiverApplicationId) }
+
+    override fun isCasting(): Boolean = core.isCasting()
+
+    override fun getCastState(): CastState = core.getCastState()
+
+    override fun getCastDeviceName(): Variant_NullType_String {
+        val name = core.getCastDeviceName()
+        return if (name != null) {
+            Variant_NullType_String.create(name)
+        } else {
+            Variant_NullType_String.create(NullType.NULL)
+        }
+    }
+
+    override fun showCastPicker() {
+        val activity = applicationContext?.currentActivity ?: return
+        activity.runOnUiThread { core.showCastPicker(activity) }
+    }
+
+    override fun endCastSession(): Promise<Unit> = Promise.async { core.endCastSession() }
+
+    override fun onCastStateChange(callback: (state: CastState, deviceName: Variant_NullType_String?) -> Unit) {
+        // Replace any prior listener registered through this HybridObject so JS
+        // reloads (Fast Refresh) don't accumulate handlers.
+        listenerIds.forEach { core.removeOnCastStateChangeListener(it) }
+        listenerIds.clear()
+
+        val id =
+            core.addOnCastStateChangeListener { state, deviceName ->
+                callback(state, deviceName?.let { Variant_NullType_String.create(it) })
+            }
+        listenerIds += id
+    }
+
+    override fun dispose() {
+        super.dispose()
+        listenerIds.forEach { core.removeOnCastStateChangeListener(it) }
+        listenerIds.clear()
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/ExoPlayerCore.kt

@@ -2,18 +2,21 @@ package com.margelo.nitro.nitroplayer.core
 
 import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
-import androidx.media3.exoplayer.ExoPlayer
 
 /**
- * Thin wrapper around an [ExoPlayer] instance owned by the playback service.
- * All delegation methods are unchanged — only the constructor now accepts an
- * existing player instead of building one.
+ * Thin wrapper around the **currently active** Media3 [Player].
+ *
+ * This is normally the service-owned `ExoPlayer` (local playback) but can be
+ * swapped to a `CastPlayer` while a Google Cast session is active — both
+ * implement the same [Player] interface, so every delegation method below works
+ * unchanged regardless of which backend is playing. The wrapper instance is
+ * reassigned (see `TrackPlayerCast.switchToPlayer`) when the backend changes.
  */
 class ExoPlayerCore(
-    exoPlayer: ExoPlayer,
+    player: Player,
 ) {
-    /** The underlying ExoPlayer instance — accessible for wiring. */
-    internal val player: ExoPlayer = exoPlayer
+    /** The underlying active player instance — accessible for wiring. */
+    internal val player: Player = player
 
     // ── Playback ───────────────────────────────────────────────────────────
     fun play() = player.play()

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerCast.kt

@@ -0,0 +1,122 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
+package com.margelo.nitro.nitroplayer.core
+
+import android.app.Activity
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
+import com.margelo.nitro.nitroplayer.CastState
+import com.margelo.nitro.nitroplayer.media.NitroCastConfig
+
+/**
+ * Google Cast backend integration for [TrackPlayerCore].
+ *
+ * Casting is modelled as a *backend swap*: the active Media3 [Player] wrapped by
+ * [ExoPlayerCore] is switched from the local `ExoPlayer` to the `CastPlayer` (and
+ * back) while keeping all queue state, listeners and the [androidx.media3.session.MediaSession]
+ * pointed at whichever player is active. Because both implement [Player], the rest
+ * of the core is unaware of which backend is playing.
+ *
+ * All functions here run on the player (main) looper.
+ */
+
+// ── Backend switching ──────────────────────────────────────────────────────
+
+internal fun TrackPlayerCore.switchToCastPlayer() {
+    val controller = castSessionController ?: return
+    switchToPlayer(controller.castPlayer)
+    isCastingField = true
+    notifyCastStateChange(CastState.CONNECTED, controller.currentDeviceName())
+}
+
+internal fun TrackPlayerCore.switchToLocalPlayer() {
+    val controller = castSessionController ?: return
+    switchToPlayer(controller.localPlayer)
+    isCastingField = false
+    notifyCastStateChange(controller.getCastState(), controller.currentDeviceName())
+}
+
+private fun TrackPlayerCore.switchToPlayer(target: Player) {
+    if (!isExoInitialized) return
+    val current = exo.player
+    if (current === target) return
+
+    // Move listener, queue and position from the current player to the target,
+    // then make the target authoritative for the MediaSession & notification.
+    playerListener?.let { current.removeListener(it) }
+    transferPlaybackState(current, target)
+    current.playWhenReady = false // silence the player we're leaving
+
+    exo = ExoPlayerCore(target)
+    playerListener?.let { target.addListener(it) }
+
+    try {
+        castSessionController?.let { it.mediaSession.player = target }
+    } catch (e: Exception) {
+        NitroPlayerLogger.log("TrackPlayerCast") { "setPlayer on MediaSession failed: ${e.message}" }
+    }
+}
+
+/** Copy the queue, index, position, repeat mode and play-when-ready from one player to another. */
+private fun transferPlaybackState(
+    from: Player,
+    to: Player,
+) {
+    val count = from.mediaItemCount
+    if (count == 0) return
+    val items = ArrayList<MediaItem>(count)
+    for (i in 0 until count) items.add(from.getMediaItemAt(i))
+    val index = from.currentMediaItemIndex.coerceAtLeast(0)
+    val position = if (from.currentPosition >= 0) from.currentPosition else 0L
+
+    to.setMediaItems(items, index, position)
+    to.repeatMode = from.repeatMode
+    to.playWhenReady = from.playWhenReady
+    to.prepare()
+}
+
+// ── Notifications ──────────────────────────────────────────────────────────
+
+internal fun TrackPlayerCore.notifyCastStateChange(
+    state: CastState,
+    deviceName: String?,
+) {
+    onCastStateChangeListeners.forEach { it(state, deviceName) }
+}
+
+// ── Public accessors (used by HybridCast) ──────────────────────────────────
+
+internal fun TrackPlayerCore.isCasting(): Boolean = isCastingField
+
+internal fun TrackPlayerCore.getCastState(): CastState =
+    if (isCastingField) {
+        CastState.CONNECTED
+    } else {
+        castSessionController?.getCastState() ?: CastState.NO_DEVICES_AVAILABLE
+    }
+
+internal fun TrackPlayerCore.getCastDeviceName(): String? = castSessionController?.currentDeviceName()
+
+internal fun TrackPlayerCore.endCastSession() {
+    castSessionController?.endCurrentSession()
+}
+
+internal fun TrackPlayerCore.showCastPicker(activity: Activity) {
+    val controller = castSessionController
+    if (controller == null) {
+        NitroPlayerLogger.log("TrackPlayerCast") { "showCastPicker ignored — Cast unavailable" }
+        return
+    }
+    controller.showCastPicker(activity)
+}
+
+internal fun TrackPlayerCore.configureCast(receiverApplicationId: String?) {
+    if (receiverApplicationId != null) {
+        NitroCastConfig.receiverApplicationId = receiverApplicationId
+        if (castSessionController != null) {
+            NitroPlayerLogger.log("TrackPlayerCast") {
+                "configureCast called after CastContext init — receiver ID takes effect on next app launch"
+            }
+        }
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerCore.kt

@@ -90,6 +90,15 @@ class TrackPlayerCore private constructor(
         ListenerRegistry<(List<TrackItem>, List<TrackItem>) -> Unit>()
     internal val onAndroidAutoConnectionListeners =
         ListenerRegistry<(Boolean) -> Unit>()
+    internal val onCastStateChangeListeners =
+        ListenerRegistry<(com.margelo.nitro.nitroplayer.CastState, String?) -> Unit>()
+
+    // ── Google Cast ──────────────────────────────────────────────────────────
+    /** Set once the playback service has a usable CastContext; null when Cast is unavailable. */
+    internal var castSessionController: com.margelo.nitro.nitroplayer.media.CastSessionController? = null
+
+    /** True while the active backend is the CastPlayer (audio routed to a remote device). */
+    @Volatile internal var isCastingField: Boolean = false
 
     // ── Progress & playlist-update runnables ───────────────────────────────
     internal val progressUpdateRunnable =
@@ -294,4 +303,8 @@ class TrackPlayerCore private constructor(
     fun addOnAndroidAutoConnectionListener(cb: (Boolean) -> Unit): Long = onAndroidAutoConnectionListeners.add(cb)
 
     fun removeOnAndroidAutoConnectionListener(id: Long): Boolean = onAndroidAutoConnectionListeners.remove(id)
+
+    fun addOnCastStateChangeListener(cb: (com.margelo.nitro.nitroplayer.CastState, String?) -> Unit): Long = onCastStateChangeListeners.add(cb)
+
+    fun removeOnCastStateChangeListener(id: Long): Boolean = onCastStateChangeListeners.remove(id)
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerSetup.kt

@@ -28,6 +28,13 @@ internal fun TrackPlayerCore.initFromService(binder: NitroPlayerPlaybackService.
     playerListener = listener
     exo.addListener(listener)
 
+    // Wire Google Cast (if available on this device) so sessions can swap the
+    // active player to/from the CastPlayer.
+    binder.castController?.let { controller ->
+        castSessionController = controller
+        controller.attachCore(this)
+    }
+
     // The audio session ID is assigned during ExoPlayer construction (in
     // PlaybackService.onCreate), before our listener is attached.
     // onAudioSessionIdChanged only fires on *changes*, so we'd miss the

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/CastSessionController.kt

@@ -0,0 +1,160 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
+package com.margelo.nitro.nitroplayer.media
+
+import android.app.Activity
+import android.os.Handler
+import androidx.media3.cast.CastPlayer
+import androidx.media3.cast.SessionAvailabilityListener
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.mediarouter.app.MediaRouteChooserDialog
+import androidx.mediarouter.app.MediaRouteControllerDialog
+import com.google.android.gms.cast.framework.CastContext
+import com.google.android.gms.cast.framework.CastStateListener
+import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
+import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.notifyCastStateChange
+import com.margelo.nitro.nitroplayer.core.switchToCastPlayer
+import com.margelo.nitro.nitroplayer.core.switchToLocalPlayer
+import androidx.media3.session.MediaSession
+import com.google.android.gms.cast.framework.CastState as GmsCastState
+import com.margelo.nitro.nitroplayer.CastState
+
+/**
+ * Owns the Google Cast [CastPlayer] and bridges Cast session lifecycle into the
+ * player core.
+ *
+ * Created by [NitroPlayerPlaybackService] once a `CastContext` is available, then
+ * wired to [TrackPlayerCore] via [attachCore]. When a Cast session starts, the
+ * core swaps its active player to [castPlayer] (see `TrackPlayerCast`), so audio
+ * plays only on the remote device; on disconnect it swaps back to [localPlayer].
+ */
+@UnstableApi
+class CastSessionController(
+    private val castContext: CastContext,
+    val castPlayer: CastPlayer,
+    val localPlayer: Player,
+    val mediaSession: MediaSession,
+    private val mainHandler: Handler,
+) {
+    private var core: TrackPlayerCore? = null
+
+    // Cast SDK reads (castState, current session) MUST happen on the main thread —
+    // it throws IllegalStateException otherwise. Nitro sync getters run on the JS
+    // thread, so we keep a main-thread-updated cache and serve the getters from it.
+    @Volatile private var cachedState: CastState = CastState.NO_DEVICES_AVAILABLE
+    @Volatile private var cachedDeviceName: String? = null
+
+    private val castStateListener =
+        CastStateListener {
+            val c = core ?: return@CastStateListener
+            mainHandler.post {
+                refreshCacheOnMain()
+                c.notifyCastStateChange(cachedState, cachedDeviceName)
+            }
+        }
+
+    private val sessionAvailabilityListener =
+        object : SessionAvailabilityListener {
+            override fun onCastSessionAvailable() {
+                mainHandler.post {
+                    refreshCacheOnMain()
+                    core?.switchToCastPlayer()
+                }
+            }
+
+            override fun onCastSessionUnavailable() {
+                mainHandler.post {
+                    refreshCacheOnMain()
+                    core?.switchToLocalPlayer()
+                }
+            }
+        }
+
+    /** Wire this controller to the core and start listening for Cast events. */
+    fun attachCore(core: TrackPlayerCore) {
+        this.core = core
+        castPlayer.setSessionAvailabilityListener(sessionAvailabilityListener)
+        castContext.addCastStateListener(castStateListener)
+
+        // If a session is already live (e.g. resumed on app launch), adopt it.
+        if (castPlayer.isCastSessionAvailable) {
+            mainHandler.post { core.switchToCastPlayer() }
+        }
+        // Emit the current state so JS reflects reality immediately.
+        mainHandler.post {
+            refreshCacheOnMain()
+            core.notifyCastStateChange(cachedState, cachedDeviceName)
+        }
+    }
+
+    /** Cached value — safe to call from the JS thread. */
+    fun getCastState(): CastState = cachedState
+
+    /** Cached value — safe to call from the JS thread. */
+    fun currentDeviceName(): String? = cachedDeviceName
+
+    /** Re-read the live Cast state into the cache. MUST run on the main thread. */
+    private fun refreshCacheOnMain() {
+        cachedState =
+            try {
+                mapCastState(castContext.castState)
+            } catch (_: Exception) {
+                cachedState
+            }
+        cachedDeviceName =
+            try {
+                castContext.sessionManager.currentCastSession?.castDevice?.friendlyName
+            } catch (_: Exception) {
+                null
+            }
+    }
+
+    fun endCurrentSession() {
+        mainHandler.post {
+            try {
+                castContext.sessionManager.endCurrentSession(true)
+            } catch (e: Exception) {
+                NitroPlayerLogger.log("CastSessionController") { "endCurrentSession failed: ${e.message}" }
+            }
+        }
+    }
+
+    /**
+     * Present the native Cast dialog: the device chooser when not connected, or
+     * the route controller (with disconnect) when already casting. Requires a
+     * foreground [Activity].
+     */
+    fun showCastPicker(activity: Activity) {
+        try {
+            if (castContext.castState == GmsCastState.CONNECTED) {
+                MediaRouteControllerDialog(activity).show()
+            } else {
+                val selector = castContext.mergedSelector ?: return
+                MediaRouteChooserDialog(activity).apply {
+                    routeSelector = selector
+                }.show()
+            }
+        } catch (e: Exception) {
+            NitroPlayerLogger.log("CastSessionController") { "showCastPicker failed: ${e.message}" }
+        }
+    }
+
+    fun release() {
+        try {
+            castPlayer.setSessionAvailabilityListener(null)
+            castContext.removeCastStateListener(castStateListener)
+            castPlayer.release()
+        } catch (_: Exception) {
+        }
+    }
+
+    private fun mapCastState(state: Int): CastState =
+        when (state) {
+            GmsCastState.NO_DEVICES_AVAILABLE -> CastState.NO_DEVICES_AVAILABLE
+            GmsCastState.CONNECTING -> CastState.CONNECTING
+            GmsCastState.CONNECTED -> CastState.CONNECTED
+            else -> CastState.NOT_CONNECTED
+        }
+}

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/NitroCastConfig.kt

@@ -0,0 +1,23 @@
+package com.margelo.nitro.nitroplayer.media
+
+import com.google.android.gms.cast.CastMediaControlIntent
+
+/**
+ * Process-wide Google Cast configuration.
+ *
+ * The Cast receiver application ID must be known *before* `CastContext` is
+ * initialized (it is a singleton, fixed for the process lifetime). Callers set
+ * [receiverApplicationId] via `Cast.configure(...)` as early as possible; the
+ * [NitroCastOptionsProvider] reads it at init time. When unset, the platform
+ * Default Media Receiver is used, which supports audio playback, metadata and
+ * queues out of the box.
+ */
+object NitroCastConfig {
+    @Volatile
+    var receiverApplicationId: String? = null
+
+    /** The effective receiver ID, falling back to the Default Media Receiver. */
+    val effectiveReceiverId: String
+        get() = receiverApplicationId
+            ?: CastMediaControlIntent.DEFAULT_MEDIA_RECEIVER_APPLICATION_ID
+}