react-native-nitro-player 0.3.0-alpha.9 → 0.4.0

package/src/hooks/useOnChangeTrack.ts

@@ -48,20 +48,24 @@ export function useOnChangeTrack(): TrackChangeResult {
   useEffect(() => {
     isMounted.current = true
 
-    try {
-      const playerState = TrackPlayer.getState()
-      if (isMounted.current) {
-        setTrack(playerState.currentTrack)
-        setIsReady(true)
-      }
-    } catch (error) {
-      console.error('[useOnChangeTrack] Failed to get initial state:', error)
-      if (isMounted.current) {
-        setTrack(null)
-        setIsReady(true)
+    const initializeTrack = async () => {
+      try {
+        const playerState = await TrackPlayer.getState()
+        if (isMounted.current) {
+          setTrack(playerState.currentTrack)
+          setIsReady(true)
+        }
+      } catch (error) {
+        console.error('[useOnChangeTrack] Failed to get initial state:', error)
+        if (isMounted.current) {
+          setTrack(null)
+          setIsReady(true)
+        }
       }
     }
 
+    initializeTrack()
+
     return () => {
       isMounted.current = false
     }

package/src/hooks/useOnPlaybackStateChange.ts

@@ -47,24 +47,28 @@ export function useOnPlaybackStateChange(): PlaybackStateResult {
   useEffect(() => {
     isMounted.current = true
 
-    // Get initial state synchronously
-    try {
-      const playerState = TrackPlayer.getState()
-      if (isMounted.current) {
-        setState(playerState.currentState)
-        setIsReady(true)
-      }
-    } catch (error) {
-      console.error(
-        '[useOnPlaybackStateChange] Failed to get initial state:',
-        error
-      )
-      if (isMounted.current) {
-        setState('stopped')
-        setIsReady(true)
+    // Get initial state asynchronously
+    const initializeState = async () => {
+      try {
+        const playerState = await TrackPlayer.getState()
+        if (isMounted.current) {
+          setState(playerState.currentState)
+          setIsReady(true)
+        }
+      } catch (error) {
+        console.error(
+          '[useOnPlaybackStateChange] Failed to get initial state:',
+          error
+        )
+        if (isMounted.current) {
+          setState('stopped')
+          setIsReady(true)
+        }
       }
     }
 
+    initializeState()
+
     return () => {
       isMounted.current = false
     }

package/src/hooks/usePlaylist.ts

@@ -0,0 +1,161 @@
+import { useEffect, useState, useRef, useCallback } from 'react'
+import { PlayerQueue } from '../index'
+import { callbackManager } from './callbackManager'
+import type { Playlist, TrackItem } from '../types/PlayerQueue'
+
+export interface UsePlaylistResult {
+  /** The currently loaded playlist */
+  currentPlaylist: Playlist | null
+  /** ID of the currently loaded playlist */
+  currentPlaylistId: string | null
+  /** All available playlists */
+  allPlaylists: Playlist[]
+  /** All tracks from all playlists (flattened) */
+  allTracks: TrackItem[]
+  /** Whether the playlists are currently loading */
+  isLoading: boolean
+  /** Manually refresh playlist data */
+  refreshPlaylists: () => void
+}
+
+/**
+ * Hook to manage playlist state
+ *
+ * Provides current playlist, all playlists, and all tracks across playlists.
+ * Automatically refreshes when:
+ * - Component mounts
+ * - Track changes (to update currentPlaylistId)
+ * - Playlists are modified via PlayerQueue methods
+ *
+ * Call `refreshPlaylists()` after creating/deleting playlists to update the state.
+ *
+ * @returns Object containing playlist state and refresh function
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { currentPlaylist, allTracks, refreshPlaylists } = usePlaylist();
+ *
+ *   const handleCreatePlaylist = () => {
+ *     PlayerQueue.createPlaylist('New Playlist');
+ *     refreshPlaylists(); // Refresh to see the new playlist
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Text>{currentPlaylist?.name}</Text>
+ *       <Text>Total tracks: {allTracks.length}</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function usePlaylist(): UsePlaylistResult {
+  const [currentPlaylist, setCurrentPlaylist] = useState<Playlist | null>(null)
+  const [currentPlaylistId, setCurrentPlaylistId] = useState<string | null>(
+    null
+  )
+  const [allPlaylists, setAllPlaylists] = useState<Playlist[]>([])
+  const [allTracks, setAllTracks] = useState<TrackItem[]>([])
+  const [isLoading, setIsLoading] = useState(true)
+  const isMounted = useRef(true)
+  const hasSubscribed = useRef(false)
+
+  const refreshPlaylists = useCallback(() => {
+    if (!isMounted.current) return
+
+    try {
+      // Get current playlist ID
+      const playlistId = PlayerQueue.getCurrentPlaylistId()
+      if (!isMounted.current) return
+      setCurrentPlaylistId(playlistId)
+
+      // Get current playlist details
+      if (playlistId) {
+        const playlist = PlayerQueue.getPlaylist(playlistId)
+        if (isMounted.current) {
+          setCurrentPlaylist(playlist)
+        }
+      } else {
+        if (isMounted.current) {
+          setCurrentPlaylist(null)
+        }
+      }
+
+      // Get all playlists
+      const playlists = PlayerQueue.getAllPlaylists()
+      if (!isMounted.current) return
+      setAllPlaylists(playlists)
+
+      // Get all tracks from all playlists (deduplicated by id)
+      const trackMap = new Map<string, TrackItem>()
+      playlists.forEach((playlist) => {
+        playlist.tracks.forEach((track) => {
+          if (!trackMap.has(track.id)) {
+            trackMap.set(track.id, track)
+          }
+        })
+      })
+      if (isMounted.current) {
+        setAllTracks(Array.from(trackMap.values()))
+        setIsLoading(false)
+      }
+    } catch (error) {
+      console.error('[usePlaylist] Error refreshing playlists:', error)
+      if (isMounted.current) {
+        setIsLoading(false)
+      }
+    }
+  }, [])
+
+  // Initialize and setup mounted ref
+  useEffect(() => {
+    isMounted.current = true
+
+    // Initial load
+    refreshPlaylists()
+
+    return () => {
+      isMounted.current = false
+    }
+  }, [refreshPlaylists])
+
+  // Subscribe to native playlist changes (only once)
+  useEffect(() => {
+    if (hasSubscribed.current) return
+    hasSubscribed.current = true
+
+    try {
+      PlayerQueue.onPlaylistsChanged(() => {
+        if (isMounted.current) {
+          refreshPlaylists()
+        }
+      })
+    } catch (error) {
+      console.error('[usePlaylist] Error setting up playlist listener:', error)
+    }
+  }, [refreshPlaylists])
+
+  // Also refresh when track changes (as it might indicate playlist loaded)
+  useEffect(() => {
+    const unsubscribe = callbackManager.subscribeToTrackChange(() => {
+      // Refresh to update currentPlaylistId when track changes
+      if (isMounted.current) {
+        refreshPlaylists()
+      }
+    })
+
+    return () => {
+      unsubscribe()
+    }
+  }, [refreshPlaylists])
+
+  return {
+    currentPlaylist,
+    currentPlaylistId,
+    allPlaylists,
+    allTracks,
+    isLoading,
+    refreshPlaylists,
+  }
+}

package/src/index.ts

@@ -9,6 +9,8 @@ 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 { DownloadManager as DownloadManagerType } from './specs/DownloadManager.nitro'
+import type { Equalizer as EqualizerType } from './specs/Equalizer.nitro'
 
 export const PlayerQueue =
   NitroModules.createHybridObject<PlayerQueueType>('PlayerQueue')
@@ -35,12 +37,22 @@ export const AudioRoutePicker =
     ? NitroModules.createHybridObject<AudioRoutePickerType>('AudioRoutePicker')
     : null
 
+// Download Manager
+export const DownloadManager =
+  NitroModules.createHybridObject<DownloadManagerType>('DownloadManager')
+
+// Equalizer
+export const Equalizer =
+  NitroModules.createHybridObject<EqualizerType>('Equalizer')
+
 // Export hooks
 export * from './hooks'
 
 // Export types
 export * from './types/PlayerQueue'
 export * from './types/AndroidAutoMediaLibrary'
+export * from './types/DownloadTypes'
+export * from './types/EqualizerTypes'
 export type { TAudioDevice } from './specs/AudioDevices.nitro'
 export type { RepeatMode } from './specs/TrackPlayer.nitro'
 // Export utilities

package/src/specs/DownloadManager.nitro.ts

@@ -0,0 +1,203 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { TrackItem } from '../types/PlayerQueue'
+import type {
+  DownloadConfig,
+  DownloadTask,
+  DownloadProgress,
+  DownloadedTrack,
+  DownloadedPlaylist,
+  DownloadState,
+  DownloadStorageInfo,
+  DownloadQueueStatus,
+  DownloadError,
+  PlaybackSource,
+} from '../types/DownloadTypes'
+
+export interface DownloadManager
+  extends HybridObject<{ android: 'kotlin'; ios: 'swift' }> {
+  /**
+   * Configure the download manager
+   */
+  configure(config: DownloadConfig): void
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): DownloadConfig
+
+  /**
+   * Download a single track
+   * @returns downloadId for tracking
+   */
+  downloadTrack(track: TrackItem, playlistId?: string): Promise<string>
+
+  // =====================================
+  // PLAYLIST DOWNLOADS
+  // =====================================
+
+  /**
+   * Download an entire playlist
+   * @returns downloadId array for each track
+   */
+  downloadPlaylist(playlistId: string, tracks: TrackItem[]): Promise<string[]>
+  /**
+   * Pause a download
+   */
+  pauseDownload(downloadId: string): Promise<void>
+
+  /**
+   * Resume a paused download
+   */
+  resumeDownload(downloadId: string): Promise<void>
+
+  /**
+   * Cancel a download
+   */
+  cancelDownload(downloadId: string): Promise<void>
+
+  /**
+   * Retry a failed download
+   */
+  retryDownload(downloadId: string): Promise<void>
+
+  /**
+   * Pause all downloads
+   */
+  pauseAllDownloads(): Promise<void>
+
+  /**
+   * Resume all paused downloads
+   */
+  resumeAllDownloads(): Promise<void>
+
+  /**
+   * Cancel all downloads
+   */
+  cancelAllDownloads(): Promise<void>
+  /**
+   * Get download task by ID
+   */
+  getDownloadTask(downloadId: string): DownloadTask | null
+
+  /**
+   * Get all active download tasks
+   */
+  getActiveDownloads(): DownloadTask[]
+
+  /**
+   * Get download queue status
+   */
+  getQueueStatus(): DownloadQueueStatus
+
+  /**
+   * Check if a track is currently downloading
+   */
+  isDownloading(trackId: string): boolean
+
+  /**
+   * Get download state for a track
+   */
+  getDownloadState(trackId: string): DownloadState | null
+
+  /**
+   * Check if a track is downloaded
+   */
+  isTrackDownloaded(trackId: string): boolean
+
+  /**
+   * Check if a playlist is fully downloaded
+   */
+  isPlaylistDownloaded(playlistId: string): boolean
+
+  /**
+   * Check if a playlist is partially downloaded
+   */
+  isPlaylistPartiallyDownloaded(playlistId: string): boolean
+
+  /**
+   * Get downloaded track by track ID
+   */
+  getDownloadedTrack(trackId: string): DownloadedTrack | null
+
+  /**
+   * Get all downloaded tracks
+   */
+  getAllDownloadedTracks(): DownloadedTrack[]
+
+  /**
+   * Get downloaded playlist by playlist ID
+   */
+  getDownloadedPlaylist(playlistId: string): DownloadedPlaylist | null
+
+  /**
+   * Get all downloaded playlists
+   */
+  getAllDownloadedPlaylists(): DownloadedPlaylist[]
+
+  /**
+   * Get local file path for a downloaded track
+   */
+  getLocalPath(trackId: string): string | null
+
+  /**
+   * Delete a downloaded track
+   */
+  deleteDownloadedTrack(trackId: string): Promise<void>
+
+  /**
+   * Delete a downloaded playlist (all its tracks)
+   */
+  deleteDownloadedPlaylist(playlistId: string): Promise<void>
+
+  /**
+   * Delete all downloaded content
+   */
+  deleteAllDownloads(): Promise<void>
+  /**
+   * Get storage information
+   */
+  getStorageInfo(): Promise<DownloadStorageInfo>
+
+  /**
+   * Sync downloads - validates all downloads and removes orphaned records
+   * Call this to clean up after manual file deletion
+   * @returns number of orphaned records that were cleaned up
+   */
+  syncDownloads(): number
+  /**
+   * Set playback source preference
+   */
+  setPlaybackSourcePreference(preference: PlaybackSource): void
+
+  /**
+   * Get current playback source preference
+   */
+  getPlaybackSourcePreference(): PlaybackSource
+
+  /**
+   * Get the effective URL for a track (local or network based on preference)
+   */
+  getEffectiveUrl(track: TrackItem): string
+
+  /**
+   * Called when download progress updates
+   */
+  onDownloadProgress(callback: (progress: DownloadProgress) => void): void
+
+  /**
+   * Called when download state changes
+   */
+  onDownloadStateChange(
+    callback: (
+      downloadId: string,
+      trackId: string,
+      state: DownloadState,
+      error?: DownloadError
+    ) => void
+  ): void
+
+  /**
+   * Called when a download completes
+   */
+  onDownloadComplete(callback: (downloadedTrack: DownloadedTrack) => void): void
+}

package/src/specs/Equalizer.nitro.ts

@@ -0,0 +1,69 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+import type {
+  EqualizerBand,
+  EqualizerPreset,
+  EqualizerState,
+  GainRange,
+} from '../types/EqualizerTypes'
+
+export interface Equalizer
+  extends HybridObject<{ android: 'kotlin'; ios: 'swift' }> {
+  // === Enable/Disable ===
+  /** Enable or disable the equalizer */
+  setEnabled(enabled: boolean): boolean
+
+  /** Check if equalizer is currently enabled */
+  isEnabled(): boolean
+
+  // === Band Control ===
+  /** Get all equalizer bands with current gain values */
+  getBands(): EqualizerBand[]
+
+  /** Set gain for a specific band index (-12 to +12 dB) */
+  setBandGain(bandIndex: number, gainDb: number): boolean
+
+  /** Set gains for all bands at once (array of 5 values) */
+  setAllBandGains(gains: number[]): boolean
+
+  /** Get the valid gain range for bands */
+  getBandRange(): GainRange
+
+  // === Presets ===
+  /** Get all available presets (built-in + custom) */
+  getPresets(): EqualizerPreset[]
+
+  /** Get built-in presets only */
+  getBuiltInPresets(): EqualizerPreset[]
+
+  /** Get custom user presets only */
+  getCustomPresets(): EqualizerPreset[]
+
+  /** Apply a preset by name */
+  applyPreset(presetName: string): boolean
+
+  /** Get currently applied preset name (null if custom values) */
+  getCurrentPresetName(): string | null
+
+  /** Save current settings as a custom preset */
+  saveCustomPreset(name: string): boolean
+
+  /** Delete a custom preset by name */
+  deleteCustomPreset(name: string): boolean
+
+  // === State ===
+  /** Get complete equalizer state */
+  getState(): EqualizerState
+
+  /** Reset to flat response (all bands at 0 dB) */
+  reset(): void
+
+  // === Events ===
+  /** Called when equalizer enabled state changes */
+  onEnabledChange(callback: (enabled: boolean) => void): void
+
+  /** Called when any band gain changes */
+  onBandChange(callback: (bands: EqualizerBand[]) => void): void
+
+  /** Called when preset changes */
+  onPresetChange(callback: (presetName: string | null) => void): void
+}

package/src/specs/TrackPlayer.nitro.ts

@@ -60,11 +60,15 @@ export interface TrackPlayer
   extends HybridObject<{ android: 'kotlin'; ios: 'swift' }> {
   play(): void
   pause(): void
-  playSong(songId: string, fromPlaylist?: string): void
+  playSong(songId: string, fromPlaylist?: string): Promise<void>
   skipToNext(): void
+  skipToIndex(index: number): Promise<boolean>
   skipToPrevious(): void
   seek(position: number): void
-  getState(): PlayerState
+  addToUpNext(trackId: string): Promise<void>
+  playNext(trackId: string): Promise<void>
+  getActualQueue(): Promise<TrackItem[]>
+  getState(): Promise<PlayerState>
   setRepeatMode(mode: RepeatMode): boolean
   configure(config: PlayerConfig): void
   onChangeTrack(callback: (track: TrackItem, reason?: Reason) => void): void

package/src/types/DownloadTypes.ts

@@ -0,0 +1,135 @@
+import type { TrackItem, Playlist } from './PlayerQueue'
+
+/**
+ * Storage location options for downloads
+ */
+export type StorageLocation = 'private' | 'public'
+
+/**
+ * Current state of a download task
+ */
+export type DownloadState =
+  | 'pending'
+  | 'downloading'
+  | 'paused'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+/**
+ * Reason for download failure
+ */
+export type DownloadErrorReason =
+  | 'network_error'
+  | 'storage_full'
+  | 'file_not_found'
+  | 'permission_denied'
+  | 'invalid_url'
+  | 'timeout'
+  | 'unknown'
+
+/**
+ * Source preference for playback
+ */
+export type PlaybackSource = 'auto' | 'download' | 'network'
+
+/**
+ * Progress information for a download
+ */
+export interface DownloadProgress {
+  trackId: string
+  downloadId: string
+  bytesDownloaded: number
+  totalBytes: number
+  progress: number // 0.0 to 1.0
+  state: DownloadState
+}
+
+/**
+ * Download error information
+ */
+export interface DownloadError {
+  code: string
+  message: string
+  reason: DownloadErrorReason
+  isRetryable: boolean
+}
+
+/**
+ * A downloaded track with local file information
+ */
+export interface DownloadedTrack {
+  trackId: string
+  originalTrack: TrackItem
+  localPath: string
+  localArtworkPath?: string | null
+  downloadedAt: number // Unix timestamp
+  fileSize: number // bytes
+  storageLocation: StorageLocation
+}
+
+/**
+ * A playlist with download information
+ */
+export interface DownloadedPlaylist {
+  playlistId: string
+  originalPlaylist: Playlist
+  downloadedTracks: DownloadedTrack[]
+  totalSize: number // bytes
+  downloadedAt: number // Unix timestamp
+  isComplete: boolean // All tracks downloaded
+}
+
+/**
+ * Download task information
+ */
+export interface DownloadTask {
+  downloadId: string
+  trackId: string
+  playlistId?: string | null
+  state: DownloadState
+  progress: DownloadProgress
+  createdAt: number // Unix timestamp
+  startedAt?: number | null
+  completedAt?: number | null
+  error?: DownloadError | null
+  retryCount: number
+}
+
+/**
+ * Configuration for the DownloadManager
+ */
+export interface DownloadConfig {
+  storageLocation?: StorageLocation
+  maxConcurrentDownloads?: number
+  autoRetry?: boolean
+  maxRetryAttempts?: number
+  backgroundDownloadsEnabled?: boolean
+  downloadArtwork?: boolean
+  customDownloadPath?: string | null
+  wifiOnlyDownloads?: boolean
+}
+
+/**
+ * Summary of download storage usage
+ */
+export interface DownloadStorageInfo {
+  totalDownloadedSize: number // bytes
+  trackCount: number
+  playlistCount: number
+  availableSpace: number // bytes
+  totalSpace: number // bytes
+}
+
+/**
+ * Download queue status
+ */
+export interface DownloadQueueStatus {
+  pendingCount: number
+  activeCount: number
+  completedCount: number
+  failedCount: number
+  totalBytesToDownload: number
+  totalBytesDownloaded: number
+  overallProgress: number // 0.0 to 1.0
+}