# React Native Nitro Player A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay. Documentation: [https://nitroplayer.riteshshukla.in/](https://nitroplayer.riteshshukla.in/) ## Installation ```bash npm install react-native-nitro-player # or yarn add react-native-nitro-player ``` ### Peer Dependencies Make sure you have these installed: ```bash npm install react-native-nitro-modules ``` ## API Reference ### React Hooks | Name | Platform | Description | | ----------------------------- | -------- | ------------------------------------------------------------------------------- | | `useOnChangeTrack` | Both | Returns current track and change reason. Updates automatically. | | `useOnPlaybackStateChange` | Both | Returns current playback state (playing/paused) and change reason. | | `useOnPlaybackProgressChange` | Both | Returns real-time playback progress, duration, and seek status. | | `useOnSeek` | Both | Returns information about the last seek event (position/duration). | | `useNowPlaying` | Both | Returns complete player state (track, state, duration, playlist) in one object. | | `useActualQueue` | Both | Returns the efficient playback queue including temporary tracks. | | `usePlaylist` | Both | Manages playlist state, providing access to all playlists and tracks. | | `useEqualizer` | Both | Controls the 5-band equalizer, including presets and individual band gains. | | `useAndroidAutoConnection` | Both | Monitors Android Auto connection status. | | `useCarPlayConnection` | iOS | Monitors CarPlay connection status. | | `useAudioDevices` | Android | Returns list of available audio output devices. | | `useAudioOutputs` | Both | Returns the devices audio plays through, updated when they change. | | `useDownloadProgress` | Both | Tracks download progress for tracks. Returns progress map and overall status. | | `useDownloadedTracks` | Both | Returns all downloaded tracks and playlists with query helpers. | ### TrackPlayer Methods Command-style methods return **`Promise`** (or another **`Promise`**) and **reject** on failure; **`getRepeatMode()`** and **`isAndroidAutoConnected()`** are synchronous reads. | Name | Platform | Description | | --------------------------- | -------- | ------------------------------------------------------------------- | | `play()` | Both | **Async**. Resumes playback. | | `pause()` | Both | **Async**. Pauses playback. | | `playSong(id, playlistId?)` | Both | **Async**. Plays a specific song, optionally from a playlist. | | `skipToNext()` | Both | **Async**. Skips to the next track in the queue. Wraps to the first under `'Playlist'` repeat (restarts a single-track queue). | | `skipToPrevious()` | Both | **Async**. Skips to the previous track, or restarts it past 2 seconds. Wraps to the last under `'Playlist'` repeat. | | `seek(position)` | Both | **Async**. Seeks to a specific time position in seconds. | | `setPlaybackSpeed(speed)` | Both | **Async**. Sets playback speed; rejects non-finite and non-positive values. | | `getPlaybackSpeed()` | Both | **Async**. Gets the current playback speed. | | `setVolume(0-100)` | Both | **Async**. Sets playback volume (0-100). | | `setRepeatMode(mode)` | Both | **Async**. Sets repeat mode (`off`, `track`, `Playlist`). | | `getRepeatMode()` | Both | **Sync**. Current repeat mode. | | `addToUpNext(id)` | Both | **Async**. Adds a track to the "up next" queue (FIFO). | | `playNext(id)` | Both | **Async**. Adds a track to the "play next" stack (LIFO). | | `getActualQueue()` | Both | **Async**. Full playback queue including temporary tracks. | | `getState()` | Both | **Async**. Snapshot of player state. | | `skipToIndex(index)` | Both | **Async**. Skips to an index in the actual queue (`Promise`). | | `configure(config)` | Both | **Async**. Player settings (Android Auto, CarPlay, notification). | | `isAndroidAutoConnected()` | Both | **Sync**. Android Auto connection. | ### PlayerQueue Methods Mutations return **`Promise`** (or **`Promise`** for `createPlaylist`). **`getPlaylist`** / **`getAllPlaylists`** / **`getCurrentPlaylistId`** are synchronous reads. | Name | Platform | Description | | --------------------------------------- | -------- | ------------------------------------------------------- | | `createPlaylist(name, ...)` | Both | **Async**. Creates a playlist; resolves to playlist ID. | | `deletePlaylist(id)` | Both | **Async**. Deletes a playlist by ID. | | `updatePlaylist(id, ...)` | Both | **Async**. Updates metadata (name, description, artwork). | | `getPlaylist(id)` | Both | Gets a specific playlist object. | | `getAllPlaylists()` | Both | Gets all available playlists. | | `loadPlaylist(id)` | Both | **Async**. Loads a playlist for playback. | | `getCurrentPlaylistId()` | Both | Gets the ID of the currently playing playlist. | | `addTrackToPlaylist(pid, track)` | Both | **Async**. Adds a track to a playlist. | | `addTracksToPlaylist(pid, tracks)` | Both | **Async**. Adds multiple tracks to a playlist. | | `removeTrackFromPlaylist(pid, tid)` | Both | **Async**. Removes a track from a playlist. | | `reorderTrackInPlaylist(pid, tid, idx)` | Both | **Async**. Moves a track to a new position. | | `removeTracksFromPlaylist(pid, tids)` | Both | **Async**. Removes several tracks in one call. | | `shufflePlaylist(pid, options?)` | Both | **Async**. Shuffles a playlist without stopping playback.| ### Platform-Specific APIs | Name | Platform | Description | | ---------------------------------------- | -------- | ------------------------------------------------- | | `AudioDevices.getAudioDevices()` | Android | Returns list of available audio devices. | | `AudioDevices.setAudioDevice(id)` | Android | Sets the active audio output device. | | `AudioDevices.getCurrentOutputs()` | Both | Returns the devices audio plays through now. | | `AudioDevices.onOutputsChange(cb)` | Both | Fires when headphones connect, disconnect, etc. | | `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. | | `CarPlayHelper.set(...)` | iOS | Sets CarPlay tabs, lists, grids and Now Playing. | | `CarPlayHelper.reload(templateId?)` | iOS | Loads lazy CarPlay templates again. | ### DownloadManager Methods | Name | Platform | Description | | -------------------------------------- | -------- | ------------------------------------------------------------- | | `configure(config)` | Both | Configures download settings (storage, concurrency, etc.). | | `downloadTrack(track, playlistId?)` | Both | **Async**. Downloads a track. Returns download ID. | | `downloadPlaylist(playlistId, tracks)` | Both | **Async**. Downloads all tracks in a playlist. | | `pauseDownload(downloadId)` | Both | **Async**. Pauses an active download. | | `resumeDownload(downloadId)` | Both | **Async**. Resumes a paused download. | | `cancelDownload(downloadId)` | Both | **Async**. Cancels a download. | | `isTrackDownloaded(trackId)` | Both | **Async**. Checks on-disk download state. | | `getAllDownloadedTracks()` | Both | **Async**. Lists persisted downloaded tracks. | | `getEffectiveUrl(track)` | Both | **Async**. Local or remote URL from preference + downloads. | | `syncDownloads()` | Both | **Async**. Reconcile DB with files; returns cleanup count. | | `deleteDownloadedTrack(trackId)` | Both | **Async**. Deletes a downloaded track. | | `getStorageInfo()` | Both | **Async**. Gets download storage usage information. | | `setPlaybackSourcePreference(pref)` | Both | Sets playback source: `'auto'`, `'download'`, or `'network'`. | > [!NOTE] > See [DOWNLOADS.md](./DOWNLOADS.md) for complete downloads API documentation. ## Quick Start `TrackPlayer` / `PlayerQueue` commands return **Promises**. The snippets use `await`—run them inside an `async` function, or use `.then()` / `void` / `.catch()` as appropriate. ### 1. Configure the Player Configure the player before using it in your app: ```typescript import { TrackPlayer } from 'react-native-nitro-player' await TrackPlayer.configure({ androidAutoEnabled: true, carPlayEnabled: false, showInNotification: true, remoteSkipForwardInterval: 15, remoteSkipBackwardInterval: 15, }) ``` Remote skip intervals are in seconds. iOS uses them for AirPods/Control Center fixed skip buttons and exposes remote playback rates `0.5, 1.0, 1.25, 1.5, 1.75, 2.0`; Android uses them for the Media3 seek back/forward notification buttons and does not expose a playback-rate media button. Press-and-hold continuous seek is not implemented on either platform. Custom intervals apply to local playback; during a Google Cast session the receiver skips by a fixed 15 seconds. The skip buttons are left out for a live stream or any track that can't seek, and previous/next are left out when they could do nothing, for example on a live stream with no other track to move to. On Android, set `androidShowRemoteSkipButtons: false` to hide the skip buttons for every track. On Android, playback keeps going when the app is swiped away from recent apps. Set `androidStopOnTaskRemoved: true` to pause playback and remove the notification instead; the queue and position are kept, so a headset play button can resume it. It doesn't apply while casting or while Android Auto is connected, and iOS ignores it. ### 2. Create Playlists ```typescript import { PlayerQueue } from 'react-native-nitro-player' import type { TrackItem } from 'react-native-nitro-player' const tracks: TrackItem[] = [ { id: '1', title: 'Song Title', artist: 'Artist Name', album: 'Album Name', duration: 180.0, // in seconds url: 'https://example.com/song.mp3', artwork: 'https://example.com/artwork.jpg', // Optional custom data (accessible in player state) extraPayload: { artistId: '123', genre: 'Rock', isFavorite: true, }, }, ] const playlistId = await PlayerQueue.createPlaylist( 'My Playlist', 'Playlist description', 'https://example.com/playlist-artwork.jpg' ) await PlayerQueue.addTracksToPlaylist(playlistId, tracks) ``` ### 3. Play Music ```typescript import { TrackPlayer, PlayerQueue } from 'react-native-nitro-player' await PlayerQueue.loadPlaylist(playlistId) await TrackPlayer.playSong('song-id', playlistId) await TrackPlayer.play() await TrackPlayer.pause() await TrackPlayer.skipToNext() await TrackPlayer.skipToPrevious() await TrackPlayer.seek(30) await TrackPlayer.setRepeatMode('off') await TrackPlayer.setRepeatMode('Playlist') await TrackPlayer.setRepeatMode('track') await TrackPlayer.setVolume(50) await TrackPlayer.setVolume(0) await TrackPlayer.setVolume(100) // Add temporary tracks to queue await TrackPlayer.addToUpNext('song-id') // Add to up-next queue (FIFO) await TrackPlayer.playNext('song-id') // Add to play-next stack (LIFO) ``` ### 4. Download for Offline Playback (Optional) ```typescript import { DownloadManager } from 'react-native-nitro-player' // Configure downloads DownloadManager.configure({ maxConcurrentDownloads: 3, backgroundDownloadsEnabled: true, downloadArtwork: true, }) // Download a track const downloadId = await DownloadManager.downloadTrack(track) // Download entire playlist const playlist = PlayerQueue.getPlaylist(playlistId) await DownloadManager.downloadPlaylist(playlist.id, playlist.tracks) // Set playback to prefer downloaded tracks DownloadManager.setPlaybackSourcePreference('auto') ``` > [!NOTE] > See [DOWNLOADS.md](./DOWNLOADS.md) for complete offline downloads documentation. ## Temporary Queue Management The player supports adding temporary tracks to the queue without modifying the original playlist. These tracks are automatically removed after playing. ### `addToUpNext(trackId: string): Promise` Adds a track to the **up-next queue** (FIFO - First In, First Out). Tracks play in the order they were added. **Behavior:** - Track is inserted after the current track and any "play next" tracks - Multiple tracks can be added - they play in the order added - Track is automatically removed after playing - Does not modify the original playlist **Example:** ```typescript // Add tracks to up-next queue await TrackPlayer.addToUpNext('song-1') // Will play 3rd await TrackPlayer.addToUpNext('song-2') // Will play 4th await TrackPlayer.addToUpNext('song-3') // Will play 5th // Order: [current] → [song-1] → [song-2] → [song-3] ``` ### `playNext(trackId: string): Promise` Adds a track to the **play-next stack** (LIFO - Last In, First Out). The most recently added track plays first. **Behavior:** - Track is inserted immediately after the current track - Multiple tracks can be added - the last added plays first - Track is automatically removed after playing - Does not modify the original playlist **Example:** ```typescript // Add tracks to play-next stack await TrackPlayer.playNext('song-1') // Will play 3rd await TrackPlayer.playNext('song-2') // Will play 2nd (most recent) await TrackPlayer.playNext('song-3') // Will play 1st (most recent) // Order: [current] → [song-3] → [song-2] → [song-1] ``` ### Queue Order The actual playback order is: ``` [original tracks before current] + [CURRENT TRACK] + [playNext stack (LIFO)] + [upNext queue (FIFO)] + [original tracks after current] ``` ### Clearing Temporary Tracks Temporary tracks are automatically cleared when: - `await TrackPlayer.playSong()` is called - `await PlayerQueue.loadPlaylist()` is called ### `skipToIndex(index: number): Promise` Skips to a specific index in the **actual queue** (the combined queue with temporary tracks). **Behavior:** - Takes an index into the actual queue structure - If the target is a temporary track (playNext or upNext), plays that track - If the target is beyond temporary tracks (in the remaining original playlist), clears all temporary tracks and plays from the original playlist - Returns `true` if successful, `false` if the index is invalid **Example:** ```typescript // Queue: [track1(0), track2(1, current), playNext-A(2), upNext-B(3), track3(4), track4(5)] // Skip to playNext track await TrackPlayer.skipToIndex(2) // Plays playNext-A // Skip to original playlist track (clears temporary tracks) await TrackPlayer.skipToIndex(4) // Clears temps, plays track3 ``` ### Getting the Actual Queue Use `useActualQueue()` hook to see the complete queue including temporary tracks: ```typescript import { useActualQueue } from 'react-native-nitro-player' function QueueView() { const { queue, refreshQueue, isLoading } = useActualQueue() return ( {queue.map((track, index) => ( {index + 1}. {track.title} ))} ) } ``` **Returns:** - `queue: TrackItem[]` - Complete queue in playback order - `refreshQueue: () => void` - Manually refresh the queue - `isLoading: boolean` - Whether the queue is currently loading ## CurrentPlayingType The `currentPlayingType` field in `PlayerState` indicates the source of the currently playing track: | Value | Description | | -------------- | -------------------------------------------------------- | | `'playlist'` | Playing from the original playlist | | `'play-next'` | Playing a track added via `playNext()` (LIFO stack) | | `'up-next'` | Playing a track added via `addToUpNext()` (FIFO queue) | | `'not-playing'`| No track is currently playing | **Example:** ```typescript const state = await TrackPlayer.getState() if (state.currentPlayingType === 'play-next') { console.log('Playing a play-next track') } else if (state.currentPlayingType === 'up-next') { console.log('Playing an up-next track') } else if (state.currentPlayingType === 'playlist') { console.log('Playing from the original playlist') } ``` ## Core Concepts ### PlayerQueue Manages playlists and tracks. Use it to: - Create, update, and delete playlists - Add or remove tracks from playlists - Load playlists for playback - Listen to playlist changes ### TrackPlayer Controls playback. Use it to: - Play, pause, and seek - Skip tracks - Control repeat mode - Control volume - Add temporary tracks to queue (`addToUpNext`, `playNext`) - Get current player state - Listen to playback events ## React Hooks The library provides React hooks for reactive state management. These hooks automatically update your components when player state changes. ### `useOnChangeTrack()` Returns the current track and the reason why it changed. **Returns:** - `track: TrackItem | undefined` - The current track, or `undefined` if no track is playing - `reason: Reason | undefined` - The reason for the track change (`'user_action'`, `'skip'`, `'end'`, or `'error'`) ### `useOnPlaybackStateChange()` Returns the current playback state and the reason for the state change. **Returns:** - `state: TrackPlayerState | undefined` - Current playback state (`'playing'`, `'paused'`, or `'stopped'`) - `reason: Reason | undefined` - The reason for the state change ### `useOnPlaybackProgressChange()` Returns real-time playback progress updates. **Returns:** - `position: number` - Current playback position in seconds - `totalDuration: number` - Total duration of the current track in seconds - `isManuallySeeked: boolean | undefined` - `true` if the user manually seeked, `undefined` otherwise ### `useOnSeek()` Returns information about the last seek event. **Returns:** - `position: number | undefined` - The position where the user seeked to, or `undefined` if no seek has occurred - `totalDuration: number | undefined` - The total duration at the time of seek, or `undefined` if no seek has occurred ### `useAndroidAutoConnection()` Monitors Android Auto connection status. **Returns:** - `isConnected: boolean` - `true` if connected to Android Auto, `false` otherwise ### `useAudioDevices()` (Android only) Automatically polls for audio device changes every 2 seconds. Returns an empty list on iOS. **Returns:** - `devices: TAudioDevice[]` - Array of available audio devices ### `useAudioOutputs()` Returns the devices audio plays through, and updates when they change (for example when Bluetooth headphones connect or headphones are unplugged). Works on iOS and Android. **Returns:** - `outputs: TAudioOutput[]` - The current outputs, usually one - `isReady: boolean` - `true` once the outputs have been read from native ### `useNowPlaying()` Returns the complete current player state (same as `TrackPlayer.getState()`). This hook provides all player information in a single object and automatically updates when the player state changes. **Returns:** - `PlayerState` object containing: - `currentTrack: TrackItem | null` - The current track being played, or `null` if no track is playing - `totalDuration: number` - Total duration of the current track in seconds - `currentState: TrackPlayerState` - Current playback state (`'playing'`, `'paused'`, or `'stopped'`) - `currentPlaylistId: string | null` - ID of the currently loaded playlist, or `null` if no playlist is loaded - `currentIndex: number` - Index of the current track in the playlist (-1 if no track is playing) - `currentPlayingType: CurrentPlayingType` - Source of the current track (`'playlist'`, `'play-next'`, `'up-next'`, or `'not-playing'`) **Note:** This hook is equivalent to calling `TrackPlayer.getState()` but provides reactive updates. It listens to track changes and playback state changes to update automatically. Also dont rely on progress from this hook ### `useActualQueue()` Returns the actual playback queue including temporary tracks (from `addToUpNext` and `playNext`). **Returns:** - `queue: TrackItem[]` - Complete queue in playback order: `[tracks_before_current] + [current] + [playNext_stack] + [upNext_queue] + [remaining_tracks]` - `refreshQueue: () => void` - Manually refresh the queue (useful after adding tracks) - `isLoading: boolean` - Whether the queue is currently loading **Auto-updates when:** - Track changes - Temporary tracks are added (`playNext`/`addToUpNext`) - Playback state changes **Example:** ```typescript import { useActualQueue } from 'react-native-nitro-player' function QueueView() { const { queue, refreshQueue, isLoading } = useActualQueue() const handleAddToUpNext = async (trackId: string) => { await TrackPlayer.addToUpNext(trackId) // Refresh queue after adding track setTimeout(refreshQueue, 100) } return ( {queue.map((track, index) => ( {index + 1}. {track.title} ))} ) } ``` ### `usePlaylist()` Manages playlist-related state and provides access to all playlists and tracks. **Returns:** - `currentPlaylist: Playlist | null` - The currently loaded playlist - `currentPlaylistId: string | null` - ID of the currently loaded playlist - `allPlaylists: Playlist[]` - Array of all playlists - `allTracks: TrackItem[]` - Array of all tracks from all playlists - `isLoading: boolean` - Whether playlists are currently loading - `refreshPlaylists: () => void` - Manually refresh playlist data **Example:** ```typescript import { usePlaylist } from 'react-native-nitro-player' function PlaylistView() { const { allPlaylists, allTracks, refreshPlaylists } = usePlaylist() return ( Playlists: {allPlaylists.length} Total Tracks: {allTracks.length} ) } ``` ## Audio Device APIs ### `AudioDevices` Audio output devices. `getCurrentOutputs()` and `onOutputsChange()` work on iOS and Android; `getAudioDevices()` and `setAudioDevice()` are Android only. #### `getCurrentOutputs(): TAudioOutput[]` Returns the devices audio plays through right now, usually one. Each `TAudioOutput` has: - `id: string` - Identifies the output; stays the same when the device reconnects - `name: string` - Device name (e.g., "WH-1000XM4"); wired outputs usually report "Headphones" or "USB Audio" - `type: TAudioOutputType` - `'built_in_speaker'`, `'built_in_earpiece'`, `'wired_headphones'`, `'line_out'`, `'bluetooth'`, `'usb'`, `'airplay'`, `'car_audio'`, `'hdmi'` or `'unknown'` #### `onOutputsChange(callback: (outputs: TAudioOutput[], reason: TAudioOutputChangeReason) => void): void` Fires when the outputs change: Bluetooth headphones connect or disconnect, headphones or a USB DAC are plugged in, or playback falls back to the speaker. `reason` is `'device_connected'`, `'device_disconnected'` or `'route_changed'`. Each call adds a listener that can't be removed, so register it once at app start; in components, use `useAudioOutputs()`. **Example:** ```typescript import { AudioDevices } from 'react-native-nitro-player' AudioDevices.onOutputsChange((outputs) => { const output = outputs[0] if (output) applyEqProfileFor(output.id) }) ``` #### `getAudioDevices(): TAudioDevice[]` (Android only) Returns the list of available audio output devices. Returns an empty list on iOS. **Returns:** Array of `TAudioDevice` objects with: - `id: number` - Unique device ID - `name: string` - Device name (e.g., "Built-in Speaker", "Bluetooth") - `type: number` - Device type constant - `isActive: boolean` - Whether this device is currently active **Example:** ```typescript import { AudioDevices } from 'react-native-nitro-player' // Android only; an empty list on iOS const devices = AudioDevices.getAudioDevices() devices.forEach((device) => { console.log(`${device.name} - Active: ${device.isActive}`) }) ``` #### `setAudioDevice(deviceId: number): Promise` (Android only) Sets the active audio output device. Rejects if the device can't be set, and always on iOS. **Parameters:** - `deviceId: number` - The ID of the device to activate **Example:** ```typescript import { AudioDevices } from 'react-native-nitro-player' await AudioDevices.setAudioDevice(deviceId) ``` ### `AudioRoutePicker` (iOS only) iOS-specific API for displaying the native audio route picker (AirPlay menu). #### `showRoutePicker(): void` Shows the native AVRoutePickerView for selecting audio output routes like AirPlay, Bluetooth, etc. **Example:** ```typescript import { AudioRoutePicker } from 'react-native-nitro-player' if (AudioRoutePicker) { AudioRoutePicker.showRoutePicker() } ``` ## 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 {isCasting ? `Casting to ${deviceName}` : 'Playing locally'} } ``` ### `` 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' ``` 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//Info.plist`: ```xml NSLocalNetworkUsageDescription ${PRODUCT_NAME} uses the local network to discover Cast devices. NSBonjourServices _googlecast._tcp _CC1AD845._googlecast._tcp NSBluetoothAlwaysUsageDescription ${PRODUCT_NAME} uses Bluetooth to discover nearby Cast devices. ``` 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. ### `useEqualizer()` Returns the current equalizer state and control methods. **Returns:** - `isEnabled: boolean` - Whether the equalizer is currently active - `bands: EqualizerBand[]` - Current gain settings for all 5 bands - `currentPreset: string | null` - Name of the currently applied preset - `setEnabled(enabled: boolean): boolean` - Toggle the equalizer on/off - `setBandGain(index: number, gainDb: number): boolean` - Set gain for a specific band (range: -12dB to +12dB) - `setAllBandGains(gains: number[]): boolean` - Set all band gains at once - `reset(): void` - Reset to flat response **Bands:** The equalizer features 5 bands at the following center frequencies: 1. **60 Hz** - Sub-bass/Bass 2. **230 Hz** - Bass/Low-mids 3. **910 Hz** - Mids 4. **3.6 kHz** - Upper-mids/Treble 5. **14 kHz** - High treble/Air **Example:** ```typescript import { useEqualizer } from 'react-native-nitro-player' function EqualizerControl() { const { isEnabled, setEnabled, bands, setBandGain, reset } = useEqualizer() return ( {bands.map((band) => ( {band.frequencyLabel} setBandGain(band.index, value)} /> ))}