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

package/src/components/CastButton.tsx

@@ -0,0 +1,196 @@
+import React from 'react'
+import {
+  Pressable,
+  StyleSheet,
+  View,
+  type PressableProps,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native'
+import { Cast } from '../index'
+import { useCastState } from '../hooks/useCastState'
+import type { CastState } from '../specs/Cast.nitro'
+
+export interface CastButtonProps extends Omit<PressableProps, 'children'> {
+  /** Icon size in points. Defaults to `24`. */
+  size?: number
+  /** Glyph color when not connected. Defaults to `#000000`. */
+  color?: string
+  /** Glyph color while connecting / connected. Defaults to `#1E88E5`. */
+  activeColor?: string
+  /** Style applied to the pressable container. */
+  style?: StyleProp<ViewStyle>
+  /**
+   * Hide the button entirely when no Cast devices are available on the network,
+   * matching standard platform Cast-button behaviour. Defaults to `true`.
+   */
+  hideWhenNoDevices?: boolean
+  /**
+   * Render a custom icon instead of the built-in Cast glyph. Receives the live
+   * connection state so you can theme it yourself.
+   */
+  renderIcon?: (info: {
+    state: CastState
+    isCasting: boolean
+    size: number
+    color: string
+  }) => React.ReactNode
+}
+
+/**
+ * A ready-to-use Google Cast button.
+ *
+ * Reflects the live connection state, hides itself when no devices are available
+ * (configurable), and presents the native Cast dialog on press. For full control
+ * over the icon, pass `renderIcon`; for custom press handling, pass `onPress`
+ * (the default opens the system Cast picker).
+ *
+ * @example
+ * ```tsx
+ * import { CastButton } from 'react-native-nitro-player'
+ *
+ * <CastButton size={28} activeColor="#1DB954" />
+ * ```
+ */
+export function CastButton({
+  size = 24,
+  color = '#000000',
+  activeColor = '#1E88E5',
+  hideWhenNoDevices = true,
+  renderIcon,
+  onPress,
+  style,
+  ...rest
+}: CastButtonProps): React.ReactElement | null {
+  const { state, isCasting } = useCastState()
+
+  if (hideWhenNoDevices && state === 'no_devices_available') {
+    return null
+  }
+
+  const active = state === 'connected' || state === 'connecting'
+  const glyphColor = active ? activeColor : color
+
+  const handlePress: PressableProps['onPress'] = (event) => {
+    if (onPress) {
+      onPress(event)
+      return
+    }
+    try {
+      Cast.showCastPicker()
+    } catch (error) {
+      console.error('[CastButton] Failed to present cast picker:', error)
+    }
+  }
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={isCasting ? 'Casting' : 'Cast'}
+      accessibilityState={{ selected: isCasting }}
+      hitSlop={8}
+      onPress={handlePress}
+      style={style}
+      {...rest}
+    >
+      {renderIcon ? (
+        renderIcon({ state, isCasting, size, color: glyphColor })
+      ) : (
+        <CastGlyph size={size} color={glyphColor} />
+      )}
+    </Pressable>
+  )
+}
+
+/**
+ * Dependency-free rendition of the standard Cast glyph: a rounded "screen"
+ * rectangle with a broadcast signal (dot + two arcs) in the bottom-left corner.
+ * Drawn purely with `View`s so the library stays dependency-free.
+ */
+function CastGlyph({
+  size,
+  color,
+}: {
+  size: number
+  color: string
+}): React.ReactElement {
+  const stroke = Math.max(1.5, Math.round(size * 0.083))
+  const inset = stroke
+  const dotSize = stroke * 1.7
+  const r1 = size * 0.28 // inner arc radius
+  const r2 = size * 0.46 // outer arc radius
+
+  return (
+    <View style={{ width: size, height: size }}>
+      {/* Screen outline */}
+      <View
+        style={[
+          StyleSheet.absoluteFill,
+          {
+            borderWidth: stroke,
+            borderColor: color,
+            borderRadius: Math.max(2, size * 0.12),
+          },
+        ]}
+      />
+      {/* Broadcast dot */}
+      <View
+        style={{
+          position: 'absolute',
+          left: inset,
+          bottom: inset,
+          width: dotSize,
+          height: dotSize,
+          borderRadius: dotSize / 2,
+          backgroundColor: color,
+        }}
+      />
+      {/* Two concentric quarter arcs radiating from the dot */}
+      <Arc origin={inset + dotSize / 2} radius={r1} stroke={stroke} color={color} />
+      <Arc origin={inset + dotSize / 2} radius={r2} stroke={stroke} color={color} />
+    </View>
+  )
+}
+
+/**
+ * A quarter-circle arc (the top-right quadrant) centered at the bottom-left
+ * `origin` point. Produced by clipping a full bordered circle to one quadrant.
+ */
+function Arc({
+  origin,
+  radius,
+  stroke,
+  color,
+}: {
+  origin: number
+  radius: number
+  stroke: number
+  color: string
+}): React.ReactElement {
+  return (
+    <View
+      // Clip box reveals only the quadrant facing up-and-right from the origin.
+      style={{
+        position: 'absolute',
+        left: origin,
+        bottom: origin - radius,
+        width: radius,
+        height: radius,
+        overflow: 'hidden',
+      }}
+    >
+      <View
+        style={{
+          position: 'absolute',
+          left: -radius,
+          top: 0,
+          width: radius * 2,
+          height: radius * 2,
+          borderRadius: radius,
+          borderWidth: stroke,
+          borderColor: color,
+        }}
+      />
+    </View>
+  )
+}

package/src/hooks/castCallbackManager.ts

@@ -0,0 +1,55 @@
+import { Cast } from '../index'
+import type { CastState } from '../specs/Cast.nitro'
+
+type CastStateCallback = (state: CastState, deviceName: string | null) => void
+
+/**
+ * Internal subscription manager that allows multiple hooks/components to
+ * subscribe to the single native `Cast.onCastStateChange` callback without
+ * overwriting each other. Mirrors {@link callbackManager}.
+ */
+class CastCallbackSubscriptionManager {
+  private castStateSubscribers = new Set<CastStateCallback>()
+  private isCastStateRegistered = false
+
+  /**
+   * Subscribe to Cast connection state changes.
+   * @returns Unsubscribe function
+   */
+  subscribeToCastState(callback: CastStateCallback): () => void {
+    this.castStateSubscribers.add(callback)
+    this.ensureCastStateRegistered()
+
+    return () => {
+      this.castStateSubscribers.delete(callback)
+    }
+  }
+
+  private ensureCastStateRegistered(): void {
+    if (this.isCastStateRegistered) return
+
+    try {
+      Cast.onCastStateChange((state, deviceName) => {
+        this.castStateSubscribers.forEach((subscriber) => {
+          try {
+            subscriber(state, deviceName)
+          } catch (error) {
+            console.error(
+              '[CastCallbackManager] Error in cast state subscriber:',
+              error
+            )
+          }
+        })
+      })
+      this.isCastStateRegistered = true
+    } catch (error) {
+      console.error(
+        '[CastCallbackManager] Failed to register cast state callback:',
+        error
+      )
+    }
+  }
+}
+
+// Export singleton instance
+export const castCallbackManager = new CastCallbackSubscriptionManager()

package/src/hooks/index.ts

@@ -12,6 +12,11 @@ export type { UsePlaylistResult } from './usePlaylist'
 export { useActualQueue } from './useActualQueue'
 export type { UseActualQueueResult } from './useActualQueue'
 
+// Cast hooks
+export { useIsCasting } from './useIsCasting'
+export { useCastState } from './useCastState'
+export type { UseCastStateResult } from './useCastState'
+
 // Download hooks
 export { useDownloadProgress } from './useDownloadProgress'
 export type {

package/src/hooks/useCastState.ts

@@ -0,0 +1,67 @@
+import { useEffect, useRef, useState } from 'react'
+import { Cast } from '../index'
+import { castCallbackManager } from './castCallbackManager'
+import type { CastState } from '../specs/Cast.nitro'
+
+export interface UseCastStateResult {
+  /** The current Cast connection state. */
+  state: CastState
+  /** Friendly name of the connected device, or `null` when not connected. */
+  deviceName: string | null
+  /** Convenience flag, equivalent to `state === 'connected'`. */
+  isCasting: boolean
+  /** Whether the initial state has been read from native. */
+  isReady: boolean
+}
+
+/**
+ * Hook to subscribe to the full Google Cast connection state.
+ *
+ * Provides the connection {@link CastState}, the connected device name, and a
+ * convenience `isCasting` flag. For a simple boolean prefer {@link useIsCasting}.
+ *
+ * @example
+ * ```tsx
+ * function CastStatus() {
+ *   const { state, deviceName, isCasting } = useCastState()
+ *   if (!isCasting) return null
+ *   return <Text>Casting to {deviceName} ({state})</Text>
+ * }
+ * ```
+ */
+export function useCastState(): UseCastStateResult {
+  const [state, setState] = useState<CastState>('not_connected')
+  const [deviceName, setDeviceName] = useState<string | null>(null)
+  const [isReady, setIsReady] = useState(false)
+  const isMounted = useRef(true)
+
+  useEffect(() => {
+    isMounted.current = true
+
+    // Seed from current native state.
+    try {
+      setState(Cast.getCastState())
+      setDeviceName(Cast.getCastDeviceName())
+    } catch (error) {
+      console.error('[useCastState] Failed to read initial cast state:', error)
+    } finally {
+      setIsReady(true)
+    }
+
+    const unsubscribe = castCallbackManager.subscribeToCastState(
+      (newState, newDeviceName) => {
+        if (isMounted.current) {
+          setState(newState)
+          setDeviceName(newDeviceName)
+        }
+      }
+    )
+
+    return () => {
+      isMounted.current = false
+      unsubscribe()
+    }
+  }, [])
+
+  return { state, deviceName, isCasting: state === 'connected', isReady }
+}

package/src/hooks/useIsCasting.ts

@@ -0,0 +1,47 @@
+import { useEffect, useRef, useState } from 'react'
+import { Cast } from '../index'
+import { castCallbackManager } from './castCallbackManager'
+
+/**
+ * Hook that returns whether playback is currently routed to a Google Cast device.
+ *
+ * Updates in real time as Cast sessions start and end. Initializes synchronously
+ * from the native player's current state.
+ *
+ * @returns `true` while connected to a Cast device, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * function NowPlaying() {
+ *   const isCasting = useIsCasting()
+ *   return <Text>{isCasting ? 'Casting' : 'Playing locally'}</Text>
+ * }
+ * ```
+ */
+export function useIsCasting(): boolean {
+  const [isCasting, setIsCasting] = useState<boolean>(() => {
+    try {
+      return Cast.isCasting()
+    } catch {
+      return false
+    }
+  })
+  const isMounted = useRef(true)
+
+  useEffect(() => {
+    isMounted.current = true
+
+    const unsubscribe = castCallbackManager.subscribeToCastState((state) => {
+      if (isMounted.current) {
+        setIsCasting(state === 'connected')
+      }
+    })
+
+    return () => {
+      isMounted.current = false
+      unsubscribe()
+    }
+  }, [])
+
+  return isCasting
+}

package/src/index.ts

@@ -9,6 +9,7 @@ import type {
 import type { AndroidAutoMediaLibrary as AndroidAutoMediaLibraryType } from './specs/AndroidAutoMediaLibrary.nitro'
 import type { AudioDevices as AudioDevicesType } from './specs/AudioDevices.nitro'
 import type { AudioRoutePicker as AudioRoutePickerType } from './specs/AudioRoutePicker.nitro'
+import type { Cast as CastType } from './specs/Cast.nitro'
 import type { DownloadManager as DownloadManagerType } from './specs/DownloadManager.nitro'
 import type { Equalizer as EqualizerType } from './specs/Equalizer.nitro'
 
@@ -37,6 +38,9 @@ export const AudioRoutePicker =
     ? NitroModules.createHybridObject<AudioRoutePickerType>('AudioRoutePicker')
     : null
 
+// Google Cast (iOS + Android)
+export const Cast = NitroModules.createHybridObject<CastType>('Cast')
+
 // Download Manager
 export const DownloadManager =
   NitroModules.createHybridObject<DownloadManagerType>('DownloadManager')
@@ -48,7 +52,12 @@ export const Equalizer =
 // Export hooks
 export * from './hooks'
 
+// Export components
+export { CastButton } from './components/CastButton'
+export type { CastButtonProps } from './components/CastButton'
+
 // Export types
+export type { CastState } from './specs/Cast.nitro'
 export * from './types/PlayerQueue'
 export * from './types/AndroidAutoMediaLibrary'
 export * from './types/DownloadTypes'

package/src/specs/Cast.nitro.ts

@@ -0,0 +1,72 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * The current Google Cast connection state.
+ *
+ * - `no_devices_available`: No Cast devices are discoverable on the network.
+ *   The Cast button is typically hidden in this state.
+ * - `not_connected`: Cast devices are available but none is connected.
+ * - `connecting`: A session is being established with a device.
+ * - `connected`: A session is active and playback is routed to the device.
+ */
+export type CastState =
+  | 'no_devices_available'
+  | 'not_connected'
+  | 'connecting'
+  | 'connected'
+
+/**
+ * Google Cast control surface.
+ *
+ * Casting is implemented as an internal playback backend swap inside the native
+ * player core: when a session is `connected`, every playback operation (play,
+ * pause, seek, skip, queue) is routed to the remote Cast device and local audio
+ * is suppressed automatically. The existing {@link TrackPlayer} API keeps
+ * working unchanged — this object only exposes the Cast-specific surface.
+ */
+export interface Cast extends HybridObject<{
+  android: 'kotlin'
+  ios: 'swift'
+}> {
+  /**
+   * Initialize the Cast framework. Must be called once early in app startup
+   * (before the first Cast interaction). Safe to call multiple times.
+   *
+   * @param receiverApplicationId Optional Web Receiver application ID registered
+   *   in the Google Cast Developer Console. When omitted, the platform Default
+   *   Media Receiver (`CC1AD845`) is used, which supports audio playback,
+   *   metadata and queues out of the box.
+   */
+  configure(receiverApplicationId?: string): Promise<void>
+
+  /**
+   * Whether playback is currently routed to a Cast device.
+   * Equivalent to `getCastState() === 'connected'`.
+   */
+  isCasting(): boolean
+
+  /** The current Cast connection state. */
+  getCastState(): CastState
+
+  /** The friendly name of the connected device, or `null` when not connected. */
+  getCastDeviceName(): string | null
+
+  /**
+   * Present the native Cast dialog. Shows the device chooser when not connected,
+   * or the cast controls / disconnect dialog when already connected. Mirrors the
+   * behaviour of the standard platform Cast button.
+   */
+  showCastPicker(): void
+
+  /** End the current Cast session and resume local playback. No-op when not connected. */
+  endCastSession(): Promise<void>
+
+  /**
+   * Register a callback fired whenever the Cast connection state changes.
+   * The callback receives the new {@link CastState} and the connected device
+   * name (or `null`).
+   */
+  onCastStateChange(
+    callback: (state: CastState, deviceName: string | null) => void
+  ): void
+}