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

package/nitrogen/generated/shared/c++/HybridCastSpec.hpp

@@ -0,0 +1,75 @@
+///
+/// HybridCastSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `CastState` to properly resolve imports.
+namespace margelo::nitro::nitroplayer { enum class CastState; }
+
+#include <NitroModules/Promise.hpp>
+#include <string>
+#include <optional>
+#include "CastState.hpp"
+#include <NitroModules/Null.hpp>
+#include <variant>
+#include <functional>
+
+namespace margelo::nitro::nitroplayer {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `Cast`
+   * Inherit this class to create instances of `HybridCastSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridCast: public HybridCastSpec {
+   * public:
+   *   HybridCast(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridCastSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridCastSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridCastSpec() override = default;
+
+    public:
+      // Properties
+      
+
+    public:
+      // Methods
+      virtual std::shared_ptr<Promise<void>> configure(const std::optional<std::string>& receiverApplicationId) = 0;
+      virtual bool isCasting() = 0;
+      virtual CastState getCastState() = 0;
+      virtual std::variant<nitro::NullType, std::string> getCastDeviceName() = 0;
+      virtual void showCastPicker() = 0;
+      virtual std::shared_ptr<Promise<void>> endCastSession() = 0;
+      virtual void onCastStateChange(const std::function<void(CastState /* state */, const std::optional<std::variant<nitro::NullType, std::string>>& /* deviceName */)>& callback) = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "Cast";
+  };
+
+} // namespace margelo::nitro::nitroplayer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "1.4.4-alpha.0",
+  "version": "1.5.0-alpha.1",
   "description": "A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay",
   "main": "lib/index",
   "module": "lib/index",
@@ -57,7 +57,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@react-native/eslint-config": "0.85.0-rc.6",
+    "@react-native/eslint-config": "0.86.0",
     "@release-it-plugins/workspaces": "^5.0.3",
     "@release-it/bumper": "^7.0.5",
     "@release-it/conventional-changelog": "^10.0.1",
@@ -68,7 +68,7 @@
     "nitrogen": "^0.35.2",
     "prettier": "^3.3.3",
     "react": "19.2.3",
-    "react-native": "0.85.0-rc.6",
+    "react-native": "0.86.0",
     "react-native-nitro-modules": "^0.35.2",
     "release-it": "^19.0.4",
     "typescript": "^5.8.3"

package/src/components/CastButton.tsx

@@ -0,0 +1,233 @@
+import React from 'react'
+import {
+  Pressable,
+  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 its bottom-left corner open) and a broadcast signal — a dot
+ * and two concentric arcs — radiating from the bottom-left. 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 / 13))
+  const inset = Math.round(size * 0.14)
+  const dotSize = stroke * 1.5
+  // Origin of the broadcast signal — the screen's bottom-left corner.
+  const cx = inset + stroke / 2
+  const cy = size - inset - stroke / 2
+  // Leave the screen's bottom-left corner open so the signal reads clearly.
+  const gap = size * 0.46
+
+  return (
+    <View style={{ width: size, height: size }}>
+      {/* Screen: top + right + most of bottom + most of left, leaving the
+          bottom-left corner open (composed from edges for a clean cast look). */}
+      {/* Top edge */}
+      <View
+        style={{
+          position: 'absolute',
+          left: inset,
+          top: inset,
+          right: inset,
+          height: stroke,
+          backgroundColor: color,
+          borderRadius: stroke,
+        }}
+      />
+      {/* Right edge */}
+      <View
+        style={{
+          position: 'absolute',
+          top: inset,
+          bottom: inset,
+          right: inset,
+          width: stroke,
+          backgroundColor: color,
+          borderRadius: stroke,
+        }}
+      />
+      {/* Bottom edge (stops short of the bottom-left corner) */}
+      <View
+        style={{
+          position: 'absolute',
+          left: inset + gap,
+          bottom: inset,
+          right: inset,
+          height: stroke,
+          backgroundColor: color,
+          borderRadius: stroke,
+        }}
+      />
+      {/* Left edge (stops short of the bottom-left corner) */}
+      <View
+        style={{
+          position: 'absolute',
+          left: inset,
+          top: inset,
+          height: size - 2 * inset - gap,
+          width: stroke,
+          backgroundColor: color,
+          borderRadius: stroke,
+        }}
+      />
+      {/* Two concentric broadcast arcs radiating from the corner dot */}
+      <RippleArc cx={cx} cy={cy} radius={size * 0.2} stroke={stroke} color={color} />
+      <RippleArc cx={cx} cy={cy} radius={size * 0.34} stroke={stroke} color={color} />
+      {/* Broadcast dot */}
+      <View
+        style={{
+          position: 'absolute',
+          left: cx - dotSize / 2,
+          top: cy - dotSize / 2,
+          width: dotSize,
+          height: dotSize,
+          borderRadius: dotSize / 2,
+          backgroundColor: color,
+        }}
+      />
+    </View>
+  )
+}
+
+/**
+ * A quarter-circle arc (the up-right quadrant) centered at (cx, cy). Rendered as
+ * a circle with only its top border colored, rotated 45° so the visible cap
+ * faces up-and-to-the-right — i.e. radiating from the bottom-left dot.
+ */
+function RippleArc({
+  cx,
+  cy,
+  radius,
+  stroke,
+  color,
+}: {
+  cx: number
+  cy: number
+  radius: number
+  stroke: number
+  color: string
+}): React.ReactElement {
+  return (
+    <View
+      style={{
+        position: 'absolute',
+        left: cx - radius,
+        top: cy - radius,
+        width: radius * 2,
+        height: radius * 2,
+        borderRadius: radius,
+        borderWidth: stroke,
+        borderTopColor: color,
+        borderRightColor: 'transparent',
+        borderBottomColor: 'transparent',
+        borderLeftColor: 'transparent',
+        transform: [{ rotate: '45deg' }],
+      }}
+    />
+  )
+}

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
+}