react-native-nitro-player 0.3.0-alpha.9 → 0.4.1-alpha.0

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

package/src/types/EqualizerTypes.ts

@@ -0,0 +1,72 @@
+/**
+ * Represents a single equalizer frequency band
+ */
+export interface EqualizerBand {
+  /** Band index (0-4) */
+  index: number
+  /** Center frequency in Hz */
+  centerFrequency: number
+  /** Current gain in dB (-12 to +12) */
+  gainDb: number
+  /** Human-readable frequency label (e.g., "60 Hz", "3.6 kHz") */
+  frequencyLabel: string
+}
+
+/**
+ * Preset type identifier
+ */
+export type PresetType = 'built-in' | 'custom'
+
+/**
+ * Represents an equalizer preset (built-in or custom)
+ */
+export interface EqualizerPreset {
+  /** Unique preset name */
+  name: string
+  /** Array of 5 gain values in dB for each band */
+  gains: number[]
+  /** Whether this is a built-in or custom preset */
+  type: PresetType
+}
+
+/**
+ * Complete equalizer state
+ */
+export interface EqualizerState {
+  /** Whether equalizer is enabled */
+  enabled: boolean
+  /** Current band settings */
+  bands: EqualizerBand[]
+  /** Currently applied preset name (null if custom values) */
+  currentPreset: string | null
+}
+
+/**
+ * Gain range for equalizer bands
+ */
+export interface GainRange {
+  /** Minimum gain in dB */
+  min: number
+  /** Maximum gain in dB */
+  max: number
+}
+
+/**
+ * Built-in preset names
+ */
+export type BuiltInPresetName =
+  | 'Flat'
+  | 'Bass Boost'
+  | 'Bass Reducer'
+  | 'Treble Boost'
+  | 'Treble Reducer'
+  | 'Vocal Boost'
+  | 'Rock'
+  | 'Pop'
+  | 'Jazz'
+  | 'Classical'
+  | 'Hip Hop'
+  | 'Electronic'
+  | 'Acoustic'
+  | 'R&B'
+  | 'Loudness'

package/src/types/PlayerQueue.ts

@@ -1,3 +1,10 @@
+import type { AnyMap } from 'react-native-nitro-modules'
+
+export type CurrentPlayingType =
+  | 'playlist'
+  | 'up-next'
+  | 'play-next'
+  | 'not-playing'
 export interface TrackItem {
   id: string
   title: string
@@ -6,6 +13,7 @@ export interface TrackItem {
   duration: number
   url: string
   artwork?: string | null
+  extraPayload?: AnyMap
 }
 
 export interface Playlist {
@@ -29,6 +37,7 @@ export interface PlayerState {
   currentState: TrackPlayerState
   currentPlaylistId: string | null
   currentIndex: number
+  currentPlayingType: CurrentPlayingType
 }
 
 export interface PlayerConfig {