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

package/lib/specs/DownloadManager.nitro.d.ts

@@ -0,0 +1,152 @@
+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>;
+    /**
+     * 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/lib/specs/DownloadManager.nitro.js

@@ -0,0 +1 @@
+export {};

package/lib/specs/Equalizer.nitro.d.ts

@@ -0,0 +1,43 @@
+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 or disable the equalizer */
+    setEnabled(enabled: boolean): boolean;
+    /** Check if equalizer is currently enabled */
+    isEnabled(): boolean;
+    /** 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;
+    /** 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;
+    /** Get complete equalizer state */
+    getState(): EqualizerState;
+    /** Reset to flat response (all bands at 0 dB) */
+    reset(): void;
+    /** 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/lib/specs/Equalizer.nitro.js

@@ -0,0 +1 @@
+export {};

package/lib/specs/TrackPlayer.nitro.d.ts

@@ -25,11 +25,15 @@ export interface TrackPlayer extends HybridObject<{
 }> {
     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/lib/types/DownloadTypes.d.ts

@@ -0,0 +1,110 @@
+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;
+    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;
+    fileSize: number;
+    storageLocation: StorageLocation;
+}
+/**
+ * A playlist with download information
+ */
+export interface DownloadedPlaylist {
+    playlistId: string;
+    originalPlaylist: Playlist;
+    downloadedTracks: DownloadedTrack[];
+    totalSize: number;
+    downloadedAt: number;
+    isComplete: boolean;
+}
+/**
+ * Download task information
+ */
+export interface DownloadTask {
+    downloadId: string;
+    trackId: string;
+    playlistId?: string | null;
+    state: DownloadState;
+    progress: DownloadProgress;
+    createdAt: number;
+    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;
+    trackCount: number;
+    playlistCount: number;
+    availableSpace: number;
+    totalSpace: number;
+}
+/**
+ * Download queue status
+ */
+export interface DownloadQueueStatus {
+    pendingCount: number;
+    activeCount: number;
+    completedCount: number;
+    failedCount: number;
+    totalBytesToDownload: number;
+    totalBytesDownloaded: number;
+    overallProgress: number;
+}

package/lib/types/DownloadTypes.js

@@ -0,0 +1 @@
+export {};

package/lib/types/EqualizerTypes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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/lib/types/EqualizerTypes.js

@@ -0,0 +1 @@
+export {};

package/lib/types/PlayerQueue.d.ts

@@ -1,3 +1,5 @@
+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 +8,7 @@ export interface TrackItem {
     duration: number;
     url: string;
     artwork?: string | null;
+    extraPayload?: AnyMap;
 }
 export interface Playlist {
     id: string;
@@ -24,6 +27,7 @@ export interface PlayerState {
     currentState: TrackPlayerState;
     currentPlaylistId: string | null;
     currentIndex: number;
+    currentPlayingType: CurrentPlayingType;
 }
 export interface PlayerConfig {
     androidAutoEnabled?: boolean;

package/nitro.json

@@ -25,6 +25,14 @@
     },
     "AudioRoutePicker": {
       "swift": "HybridAudioRoutePicker"
+    },
+    "DownloadManager": {
+      "swift": "HybridDownloadManager",
+      "kotlin": "HybridDownloadManager"
+    },
+    "Equalizer": {
+      "swift": "HybridEqualizer",
+      "kotlin": "HybridEqualizer"
     }
   },
   "ignorePaths": ["**/node_modules"]

package/nitrogen/generated/android/NitroPlayer+autolinking.cmake

@@ -36,14 +36,23 @@ target_sources(
   ../nitrogen/generated/shared/c++/HybridAndroidAutoMediaLibrarySpec.cpp
   ../nitrogen/generated/shared/c++/HybridAudioDevicesSpec.cpp
   ../nitrogen/generated/shared/c++/HybridAudioRoutePickerSpec.cpp
+  ../nitrogen/generated/shared/c++/HybridDownloadManagerSpec.cpp
+  ../nitrogen/generated/shared/c++/HybridEqualizerSpec.cpp
   ../nitrogen/generated/shared/c++/HybridPlayerQueueSpec.cpp
   ../nitrogen/generated/shared/c++/HybridTrackPlayerSpec.cpp
   # Android-specific Nitrogen C++ sources
   ../nitrogen/generated/android/c++/JHybridAndroidAutoMediaLibrarySpec.cpp
   ../nitrogen/generated/android/c++/JHybridAudioDevicesSpec.cpp
+  ../nitrogen/generated/android/c++/JHybridDownloadManagerSpec.cpp
+  ../nitrogen/generated/android/c++/JVariant_NullType_String.cpp
+  ../nitrogen/generated/android/c++/JVariant_NullType_DownloadTask.cpp
+  ../nitrogen/generated/android/c++/JVariant_NullType_Double.cpp
+  ../nitrogen/generated/android/c++/JVariant_NullType_DownloadError.cpp
+  ../nitrogen/generated/android/c++/JVariant_NullType_DownloadedTrack.cpp
+  ../nitrogen/generated/android/c++/JVariant_NullType_DownloadedPlaylist.cpp
+  ../nitrogen/generated/android/c++/JHybridEqualizerSpec.cpp
   ../nitrogen/generated/android/c++/JHybridPlayerQueueSpec.cpp
   ../nitrogen/generated/android/c++/JVariant_NullType_Playlist.cpp
-  ../nitrogen/generated/android/c++/JVariant_NullType_String.cpp
   ../nitrogen/generated/android/c++/JHybridTrackPlayerSpec.cpp
   ../nitrogen/generated/android/c++/JVariant_NullType_TrackItem.cpp
 )

package/nitrogen/generated/android/NitroPlayerOnLoad.cpp

@@ -17,6 +17,14 @@
 
 #include "JHybridAndroidAutoMediaLibrarySpec.hpp"
 #include "JHybridAudioDevicesSpec.hpp"
+#include "JHybridDownloadManagerSpec.hpp"
+#include "JFunc_void_DownloadProgress.hpp"
+#include "JFunc_void_std__string_std__string_DownloadState_std__optional_DownloadError_.hpp"
+#include "JFunc_void_DownloadedTrack.hpp"
+#include "JHybridEqualizerSpec.hpp"
+#include "JFunc_void_bool.hpp"
+#include "JFunc_void_std__vector_EqualizerBand_.hpp"
+#include "JFunc_void_std__optional_std__variant_nitro__NullType__std__string__.hpp"
 #include "JHybridPlayerQueueSpec.hpp"
 #include "JFunc_void_std__vector_Playlist__std__optional_QueueOperation_.hpp"
 #include "JFunc_void_std__string_Playlist_std__optional_QueueOperation_.hpp"
@@ -25,7 +33,6 @@
 #include "JFunc_void_TrackPlayerState_std__optional_Reason_.hpp"
 #include "JFunc_void_double_double.hpp"
 #include "JFunc_void_double_double_std__optional_bool_.hpp"
-#include "JFunc_void_bool.hpp"
 #include <NitroModules/DefaultConstructableObject.hpp>
 
 namespace margelo::nitro::nitroplayer {
@@ -39,6 +46,14 @@ int initialize(JavaVM* vm) {
     // Register native JNI methods
     margelo::nitro::nitroplayer::JHybridAndroidAutoMediaLibrarySpec::registerNatives();
     margelo::nitro::nitroplayer::JHybridAudioDevicesSpec::registerNatives();
+    margelo::nitro::nitroplayer::JHybridDownloadManagerSpec::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_DownloadProgress_cxx::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_std__string_std__string_DownloadState_std__optional_DownloadError__cxx::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_DownloadedTrack_cxx::registerNatives();
+    margelo::nitro::nitroplayer::JHybridEqualizerSpec::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_bool_cxx::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_std__vector_EqualizerBand__cxx::registerNatives();
+    margelo::nitro::nitroplayer::JFunc_void_std__optional_std__variant_nitro__NullType__std__string___cxx::registerNatives();
     margelo::nitro::nitroplayer::JHybridPlayerQueueSpec::registerNatives();
     margelo::nitro::nitroplayer::JFunc_void_std__vector_Playlist__std__optional_QueueOperation__cxx::registerNatives();
     margelo::nitro::nitroplayer::JFunc_void_std__string_Playlist_std__optional_QueueOperation__cxx::registerNatives();
@@ -47,7 +62,6 @@ int initialize(JavaVM* vm) {
     margelo::nitro::nitroplayer::JFunc_void_TrackPlayerState_std__optional_Reason__cxx::registerNatives();
     margelo::nitro::nitroplayer::JFunc_void_double_double_cxx::registerNatives();
     margelo::nitro::nitroplayer::JFunc_void_double_double_std__optional_bool__cxx::registerNatives();
-    margelo::nitro::nitroplayer::JFunc_void_bool_cxx::registerNatives();
 
     // Register Nitro Hybrid Objects
     HybridObjectRegistry::registerHybridObjectConstructor(
@@ -82,6 +96,22 @@ int initialize(JavaVM* vm) {
         return instance->cthis()->shared();
       }
     );
+    HybridObjectRegistry::registerHybridObjectConstructor(
+      "DownloadManager",
+      []() -> std::shared_ptr<HybridObject> {
+        static DefaultConstructableObject<JHybridDownloadManagerSpec::javaobject> object("com/margelo/nitro/nitroplayer/HybridDownloadManager");
+        auto instance = object.create();
+        return instance->cthis()->shared();
+      }
+    );
+    HybridObjectRegistry::registerHybridObjectConstructor(
+      "Equalizer",
+      []() -> std::shared_ptr<HybridObject> {
+        static DefaultConstructableObject<JHybridEqualizerSpec::javaobject> object("com/margelo/nitro/nitroplayer/HybridEqualizer");
+        auto instance = object.create();
+        return instance->cthis()->shared();
+      }
+    );
   });
 }
 

package/nitrogen/generated/android/c++/JCurrentPlayingType.hpp

@@ -0,0 +1,65 @@
+///
+/// JCurrentPlayingType.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include "CurrentPlayingType.hpp"
+
+namespace margelo::nitro::nitroplayer {
+
+  using namespace facebook;
+
+  /**
+   * The C++ JNI bridge between the C++ enum "CurrentPlayingType" and the the Kotlin enum "CurrentPlayingType".
+   */
+  struct JCurrentPlayingType final: public jni::JavaClass<JCurrentPlayingType> {
+  public:
+    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/CurrentPlayingType;";
+
+  public:
+    /**
+     * Convert this Java/Kotlin-based enum to the C++ enum CurrentPlayingType.
+     */
+    [[maybe_unused]]
+    [[nodiscard]]
+    CurrentPlayingType toCpp() const {
+      static const auto clazz = javaClassStatic();
+      static const auto fieldOrdinal = clazz->getField<int>("value");
+      int ordinal = this->getFieldValue(fieldOrdinal);
+      return static_cast<CurrentPlayingType>(ordinal);
+    }
+
+  public:
+    /**
+     * Create a Java/Kotlin-based enum with the given C++ enum's value.
+     */
+    [[maybe_unused]]
+    static jni::alias_ref<JCurrentPlayingType> fromCpp(CurrentPlayingType value) {
+      static const auto clazz = javaClassStatic();
+      static const auto fieldPLAYLIST = clazz->getStaticField<JCurrentPlayingType>("PLAYLIST");
+      static const auto fieldUP_NEXT = clazz->getStaticField<JCurrentPlayingType>("UP_NEXT");
+      static const auto fieldPLAY_NEXT = clazz->getStaticField<JCurrentPlayingType>("PLAY_NEXT");
+      static const auto fieldNOT_PLAYING = clazz->getStaticField<JCurrentPlayingType>("NOT_PLAYING");
+      
+      switch (value) {
+        case CurrentPlayingType::PLAYLIST:
+          return clazz->getStaticFieldValue(fieldPLAYLIST);
+        case CurrentPlayingType::UP_NEXT:
+          return clazz->getStaticFieldValue(fieldUP_NEXT);
+        case CurrentPlayingType::PLAY_NEXT:
+          return clazz->getStaticFieldValue(fieldPLAY_NEXT);
+        case CurrentPlayingType::NOT_PLAYING:
+          return clazz->getStaticFieldValue(fieldNOT_PLAYING);
+        default:
+          std::string stringValue = std::to_string(static_cast<int>(value));
+          throw std::invalid_argument("Invalid enum value (" + stringValue + "!");
+      }
+    }
+  };
+
+} // namespace margelo::nitro::nitroplayer