react-native-nitro-player 0.7.0 → 0.7.1-alpha.1

package/README.md

@@ -42,41 +42,46 @@ npm install react-native-nitro-modules
 
 ### TrackPlayer Methods
 
+Command-style methods return **`Promise<void>`** (or another **`Promise`**) and **reject** on failure; **`getRepeatMode()`** and **`isAndroidAutoConnected()`** are synchronous reads.
+
 | Name                        | Platform | Description                                                         |
 | --------------------------- | -------- | ------------------------------------------------------------------- |
-| `play()`                    | Both     | Resumes playback.                                                   |
-| `pause()`                   | Both     | Pauses playback.                                                    |
+| `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     | Skips to the next track in the queue.                               |
-| `skipToPrevious()`          | Both     | Skips to the previous track.                                        |
-| `seek(position)`            | Both     | Seeks to a specific time position in seconds.                       |
+| `skipToNext()`              | Both     | **Async**. Skips to the next track in the queue.                    |
+| `skipToPrevious()`          | Both     | **Async**. Skips to the previous track.                             |
+| `seek(position)`            | Both     | **Async**. Seeks to a specific time position in seconds.           |
 | `setPlaybackSpeed(speed)`   | Both     | **Async**. Sets playback speed (e.g. 0.5x, 1x, 1.5x, 2x).           |
 | `getPlaybackSpeed()`        | Both     | **Async**. Gets the current playback speed.                         |
-| `setVolume(0-100)`          | Both     | Sets playback volume (0-100).                                       |
-| `setRepeatMode(mode)`       | Both     | Sets repeat mode (`off`, `track`, `Playlist`).                      |
+| `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**. Gets the full playback queue including temporary tracks. |
-| `getState()`                | Both     | **Async**. Gets the current player state immediately.               |
-| `skipToIndex(index)`        | Both     | **Async**. Skips to a specific index in the actual queue.           |
-| `configure(config)`         | Both     | Configures player settings (Android Auto, etc.).                    |
-| `isAndroidAutoConnected()`  | Both     | Checks if Android Auto is currently connected.                      |
+| `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<boolean>`). |
+| `configure(config)`         | Both     | **Async**. Player settings (Android Auto, CarPlay, notification).   |
+| `isAndroidAutoConnected()`  | Both     | **Sync**. Android Auto connection.                                  |
 
 ### PlayerQueue Methods
 
+Mutations return **`Promise<void>`** (or **`Promise<string>`** for `createPlaylist`). **`getPlaylist`** / **`getAllPlaylists`** / **`getCurrentPlaylistId`** are synchronous reads.
+
 | Name                                    | Platform | Description                                             |
 | --------------------------------------- | -------- | ------------------------------------------------------- |
-| `createPlaylist(name, ...)`             | Both     | Creates a new playlist. Returns ID.                     |
-| `deletePlaylist(id)`                    | Both     | Deletes a playlist by ID.                               |
-| `updatePlaylist(id, ...)`               | Both     | Updates playlist metadata (name, description, artwork). |
+| `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     | Loads a playlist for playback.                          |
+| `loadPlaylist(id)`                      | Both     | **Async**. Loads a playlist for playback.               |
 | `getCurrentPlaylistId()`                | Both     | Gets the ID of the currently playing playlist.          |
-| `addTrackToPlaylist(pid, track)`        | Both     | Adds a track to a playlist.                             |
-| `addTracksToPlaylist(pid, tracks)`      | Both     | Adds multiple tracks to a playlist.                     |
-| `removeTrackFromPlaylist(pid, tid)`     | Both     | Removes a track from a playlist.                        |
-| `reorderTrackInPlaylist(pid, tid, idx)` | Both     | Moves a track to a new position in the 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.             |
 
 ### Platform-Specific APIs
 
@@ -98,8 +103,10 @@ npm install react-native-nitro-modules
 | `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     | Checks if a track is downloaded.                              |
-| `getAllDownloadedTracks()`             | Both     | Gets all downloaded tracks.                                   |
+| `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'`. |
@@ -109,6 +116,8 @@ npm install react-native-nitro-modules
 
 ## 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:
@@ -116,7 +125,7 @@ Configure the player before using it in your app:
 ```typescript
 import { TrackPlayer } from 'react-native-nitro-player'
 
-TrackPlayer.configure({
+await TrackPlayer.configure({
   androidAutoEnabled: true,
   carPlayEnabled: false,
   showInNotification: true,
@@ -147,15 +156,13 @@ const tracks: TrackItem[] = [
   },
 ]
 
-// Create a playlist
-const playlistId = PlayerQueue.createPlaylist(
+const playlistId = await PlayerQueue.createPlaylist(
   'My Playlist',
   'Playlist description',
   'https://example.com/playlist-artwork.jpg'
 )
 
-// Add tracks to the playlist
-PlayerQueue.addTracksToPlaylist(playlistId, tracks)
+await PlayerQueue.addTracksToPlaylist(playlistId, tracks)
 ```
 
 ### 3. Play Music
@@ -163,28 +170,23 @@ PlayerQueue.addTracksToPlaylist(playlistId, tracks)
 ```typescript
 import { TrackPlayer, PlayerQueue } from 'react-native-nitro-player'
 
-// Load and play a playlist
-PlayerQueue.loadPlaylist(playlistId)
+await PlayerQueue.loadPlaylist(playlistId)
 
-// Or play a specific song
 await TrackPlayer.playSong('song-id', playlistId)
 
-// Basic controls
-TrackPlayer.play()
-TrackPlayer.pause()
-TrackPlayer.skipToNext()
-TrackPlayer.skipToPrevious()
-TrackPlayer.seek(30) // Seek to 30 seconds
+await TrackPlayer.play()
+await TrackPlayer.pause()
+await TrackPlayer.skipToNext()
+await TrackPlayer.skipToPrevious()
+await TrackPlayer.seek(30)
 
-// Set repeat mode
-TrackPlayer.setRepeatMode('off') // No repeat
-TrackPlayer.setRepeatMode('Playlist') // Repeat entire playlist
-TrackPlayer.setRepeatMode('track') // Repeat current track
+await TrackPlayer.setRepeatMode('off')
+await TrackPlayer.setRepeatMode('Playlist')
+await TrackPlayer.setRepeatMode('track')
 
-// Set volume (0-100)
-TrackPlayer.setVolume(50) // Set volume to 50%
-TrackPlayer.setVolume(0) // Mute
-TrackPlayer.setVolume(100) // Maximum volume
+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)
@@ -280,8 +282,7 @@ The actual playback order is:
 Temporary tracks are automatically cleared when:
 
 - `await TrackPlayer.playSong()` is called
-- `PlayerQueue.loadPlaylist()` is called
-- `TrackPlayer.playFromIndex()` is called
+- `await PlayerQueue.loadPlaylist()` is called
 
 ### `skipToIndex(index: number): Promise<boolean>`
 

package/android/src/main/java/com/margelo/nitro/nitroplayer/HybridAndroidAutoMediaLibrary.kt

@@ -3,7 +3,10 @@ package com.margelo.nitro.nitroplayer
 import androidx.annotation.Keep
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.clearAndroidAutoMediaLibrary
+import com.margelo.nitro.nitroplayer.core.setAndroidAutoMediaLibrary
 
 @DoNotStrip
 @Keep
@@ -11,21 +14,14 @@ class HybridAndroidAutoMediaLibrary : HybridAndroidAutoMediaLibrarySpec() {
     private val core: TrackPlayerCore
 
     init {
-        val context =
-            NitroModules.applicationContext
-                ?: throw IllegalStateException("React Context is not initialized")
+        val context = NitroModules.applicationContext
+            ?: throw IllegalStateException("React Context is not initialized")
         core = TrackPlayerCore.getInstance(context)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun setMediaLibrary(libraryJson: String) {
-        core.setAndroidAutoMediaLibrary(libraryJson)
-    }
+    override fun setMediaLibrary(libraryJson: String): Promise<Unit> =
+        Promise.async { core.setAndroidAutoMediaLibrary(libraryJson) }
 
-    @DoNotStrip
-    @Keep
-    override fun clearMediaLibrary() {
-        core.clearAndroidAutoMediaLibrary()
-    }
+    override fun clearMediaLibrary(): Promise<Unit> =
+        Promise.async { core.clearAndroidAutoMediaLibrary() }
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/HybridAudioDevices.kt

@@ -1,3 +1,5 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
 package com.margelo.nitro.nitroplayer
 
 import android.content.Context
@@ -7,6 +9,7 @@ import android.os.Build
 import androidx.annotation.Keep
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
 
 @DoNotStrip
@@ -15,19 +18,13 @@ class HybridAudioDevices : HybridAudioDevicesSpec() {
     val applicationContext = NitroModules.applicationContext
     private val audioManager = applicationContext?.getSystemService(Context.AUDIO_SERVICE) as AudioManager
 
-    // Device types that can be set as communication devices
     private val validCommunicationDeviceTypes: Set<Int> by lazy {
-        val types =
-            mutableSetOf(
-                AudioDeviceInfo.TYPE_BUILTIN_EARPIECE,
-                AudioDeviceInfo.TYPE_BUILTIN_SPEAKER,
-                AudioDeviceInfo.TYPE_WIRED_HEADSET,
-                AudioDeviceInfo.TYPE_WIRED_HEADPHONES,
-                AudioDeviceInfo.TYPE_BLUETOOTH_SCO,
-                AudioDeviceInfo.TYPE_BLUETOOTH_A2DP,
-                AudioDeviceInfo.TYPE_USB_HEADSET,
-            )
-        // BLE types are only available on Android S (API 31) and above
+        val types = mutableSetOf(
+            AudioDeviceInfo.TYPE_BUILTIN_EARPIECE, AudioDeviceInfo.TYPE_BUILTIN_SPEAKER,
+            AudioDeviceInfo.TYPE_WIRED_HEADSET, AudioDeviceInfo.TYPE_WIRED_HEADPHONES,
+            AudioDeviceInfo.TYPE_BLUETOOTH_SCO, AudioDeviceInfo.TYPE_BLUETOOTH_A2DP,
+            AudioDeviceInfo.TYPE_USB_HEADSET,
+        )
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
             types.add(AudioDeviceInfo.TYPE_BLE_HEADSET)
             types.add(AudioDeviceInfo.TYPE_BLE_SPEAKER)
@@ -35,100 +32,58 @@ class HybridAudioDevices : HybridAudioDevicesSpec() {
         types
     }
 
-    @DoNotStrip
-    @Keep
     override fun getAudioDevices(): Array<TAudioDevice> {
-        val devices = audioManager.getDevices(android.media.AudioManager.GET_DEVICES_OUTPUTS)
-        var activeDevice: AudioDeviceInfo? = null
-
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-            activeDevice = audioManager.communicationDevice
-        }
-
-        // Filter to only include valid communication devices
-        return devices
-            .filter { device ->
-                validCommunicationDeviceTypes.contains(device.type)
-            }.map { device ->
-                TAudioDevice(
-                    id = device.id.toDouble(),
-                    name = device.productName?.toString() ?: getDeviceTypeName(device.type),
-                    type = device.type.toDouble(),
-                    isActive = device == activeDevice,
-                )
-            }.toTypedArray()
+        val devices = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+        val activeDevice: AudioDeviceInfo? = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) audioManager.communicationDevice else null
+        return devices.filter { validCommunicationDeviceTypes.contains(it.type) }.map { device ->
+            TAudioDevice(
+                id = device.id.toDouble(),
+                name = device.productName?.toString() ?: getDeviceTypeName(device.type),
+                type = device.type.toDouble(),
+                isActive = device == activeDevice,
+            )
+        }.toTypedArray()
     }
 
-    private fun getDeviceTypeName(type: Int): String =
-        when (type) {
-            AudioDeviceInfo.TYPE_BUILTIN_EARPIECE -> "Built-in Earpiece"
-            AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> "Built-in Speaker"
-            AudioDeviceInfo.TYPE_WIRED_HEADSET -> "Wired Headset"
-            AudioDeviceInfo.TYPE_WIRED_HEADPHONES -> "Wired Headphones"
-            AudioDeviceInfo.TYPE_BLUETOOTH_SCO -> "Bluetooth SCO"
-            AudioDeviceInfo.TYPE_BLUETOOTH_A2DP -> "Bluetooth"
-            AudioDeviceInfo.TYPE_USB_HEADSET -> "USB Headset"
-            26 -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) "BLE Headset" else "Type 26"
-            27 -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) "BLE Speaker" else "Type 27"
-            else -> "Type $type"
-        }
-
-    @DoNotStrip
-    @Keep
-    override fun setAudioDevice(deviceId: Double): Boolean {
-        val device =
-            audioManager
-                .getDevices(android.media.AudioManager.GET_DEVICES_OUTPUTS)
-                .firstOrNull { it.id == deviceId.toInt() }
-                ?: return false
-
-        // Check if device type is valid for communication
+    /** v2: setAudioDevice now returns Promise<Unit> instead of Boolean */
+    override fun setAudioDevice(deviceId: Double): Promise<Unit> = Promise.async {
+        val device = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+            .firstOrNull { it.id == deviceId.toInt() }
+            ?: throw IllegalArgumentException("Audio device $deviceId not found")
         if (!validCommunicationDeviceTypes.contains(device.type)) {
-            NitroPlayerLogger.log("HybridAudioDevices", "Device type ${device.type} is not a valid communication device")
-            return false
+            throw IllegalArgumentException("Device type ${device.type} is not a valid communication device")
         }
-
-        return try {
-            if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S) {
+        try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
                 audioManager.setCommunicationDevice(device)
             } else {
-                // Pre-Android 12 fallback (best-effort)
                 when (device.type) {
-                    android.media.AudioDeviceInfo.TYPE_BLUETOOTH_SCO,
-                    android.media.AudioDeviceInfo.TYPE_BLUETOOTH_A2DP,
-                    -> {
-                        audioManager.startBluetoothSco()
-                        audioManager.isBluetoothScoOn = true
-                        true
-                    }
-
-                    android.media.AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> {
-                        audioManager.isSpeakerphoneOn = true
-                        true
-                    }
-
-                    android.media.AudioDeviceInfo.TYPE_WIRED_HEADSET,
-                    android.media.AudioDeviceInfo.TYPE_WIRED_HEADPHONES,
-                    -> {
-                        audioManager.isSpeakerphoneOn = false
-                        audioManager.isBluetoothScoOn = false
-                        true
+                    AudioDeviceInfo.TYPE_BLUETOOTH_SCO, AudioDeviceInfo.TYPE_BLUETOOTH_A2DP -> {
+                        audioManager.startBluetoothSco(); audioManager.isBluetoothScoOn = true
                     }
-
-                    else -> {
-                        NitroPlayerLogger.log("HybridAudioDevices", "Unsupported device type for pre-Android 12: ${device.type}")
-                        false
+                    AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> audioManager.isSpeakerphoneOn = true
+                    AudioDeviceInfo.TYPE_WIRED_HEADSET, AudioDeviceInfo.TYPE_WIRED_HEADPHONES -> {
+                        audioManager.isSpeakerphoneOn = false; audioManager.isBluetoothScoOn = false
                     }
+                    else -> throw IllegalArgumentException("Unsupported device type for pre-Android 12: ${device.type}")
                 }
             }
         } catch (e: Exception) {
             NitroPlayerLogger.log("HybridAudioDevices", "Error setting audio device: ${e.message}")
-            e.printStackTrace()
-            false
+            throw e
         }
     }
 
-    companion object {
-        private const val TAG = "HybridAudioDevices"
+    private fun getDeviceTypeName(type: Int): String = when (type) {
+        AudioDeviceInfo.TYPE_BUILTIN_EARPIECE -> "Built-in Earpiece"
+        AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> "Built-in Speaker"
+        AudioDeviceInfo.TYPE_WIRED_HEADSET -> "Wired Headset"
+        AudioDeviceInfo.TYPE_WIRED_HEADPHONES -> "Wired Headphones"
+        AudioDeviceInfo.TYPE_BLUETOOTH_SCO -> "Bluetooth SCO"
+        AudioDeviceInfo.TYPE_BLUETOOTH_A2DP -> "Bluetooth"
+        AudioDeviceInfo.TYPE_USB_HEADSET -> "USB Headset"
+        26 -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) "BLE Headset" else "Type 26"
+        27 -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) "BLE Speaker" else "Type 27"
+        else -> "Type $type"
     }
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/HybridDownloadManager.kt

@@ -1,3 +1,5 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
 package com.margelo.nitro.nitroplayer
 
 import androidx.annotation.Keep
@@ -7,219 +9,83 @@ import com.margelo.nitro.core.NullType
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.download.DownloadManagerCore
 
-/**
- * Hybrid implementation of DownloadManagerSpec for Android
- * Bridges Nitro modules with the native DownloadManagerCore implementation
- */
 @DoNotStrip
 @Keep
 class HybridDownloadManager : HybridDownloadManagerSpec() {
     private val core: DownloadManagerCore
 
     init {
-        val context =
-            NitroModules.applicationContext
-                ?: throw IllegalStateException("React Context is not initialized")
+        val context = NitroModules.applicationContext
+            ?: throw IllegalStateException("React Context is not initialized")
         core = DownloadManagerCore.getInstance(context)
     }
 
-    // Configuration
-    @DoNotStrip
-    @Keep
-    override fun configure(config: DownloadConfig) {
-        core.configure(config)
-    }
-
-    @DoNotStrip
-    @Keep
+    // ── Configuration ─────────────────────────────────────────────────────────
+    override fun configure(config: DownloadConfig) = core.configure(config)
     override fun getConfig(): DownloadConfig = core.getConfig()
 
-    // Download Operations
-    override fun downloadTrack(
-        track: TrackItem,
-        playlistId: String?,
-    ): Promise<String> =
-        Promise.async {
-            core.downloadTrack(track, playlistId)
-        }
-
-    override fun downloadPlaylist(
-        playlistId: String,
-        tracks: Array<TrackItem>,
-    ): Promise<Array<String>> =
-        Promise.async {
-            core.downloadPlaylist(playlistId, tracks)
-        }
-
-    // Download Control
-    override fun pauseDownload(downloadId: String): Promise<Unit> =
-        Promise.async {
-            core.pauseDownload(downloadId)
-        }
-
-    override fun resumeDownload(downloadId: String): Promise<Unit> =
-        Promise.async {
-            core.resumeDownload(downloadId)
-        }
-
-    override fun cancelDownload(downloadId: String): Promise<Unit> =
-        Promise.async {
-            core.cancelDownload(downloadId)
-        }
-
-    override fun retryDownload(downloadId: String): Promise<Unit> =
-        Promise.async {
-            core.retryDownload(downloadId)
-        }
-
-    override fun pauseAllDownloads(): Promise<Unit> =
-        Promise.async {
-            core.pauseAllDownloads()
-        }
-
-    override fun resumeAllDownloads(): Promise<Unit> =
-        Promise.async {
-            core.resumeAllDownloads()
-        }
-
-    override fun cancelAllDownloads(): Promise<Unit> =
-        Promise.async {
-            core.cancelAllDownloads()
-        }
-
-    // Download Status
-    @DoNotStrip
-    @Keep
+    // ── Download operations ───────────────────────────────────────────────────
+    override fun downloadTrack(track: TrackItem, playlistId: String?): Promise<String> = Promise.async { core.downloadTrack(track, playlistId) }
+    override fun downloadPlaylist(playlistId: String, tracks: Array<TrackItem>): Promise<Array<String>> = Promise.async { core.downloadPlaylist(playlistId, tracks) }
+    override fun pauseDownload(downloadId: String): Promise<Unit> = Promise.async { core.pauseDownload(downloadId) }
+    override fun resumeDownload(downloadId: String): Promise<Unit> = Promise.async { core.resumeDownload(downloadId) }
+    override fun cancelDownload(downloadId: String): Promise<Unit> = Promise.async { core.cancelDownload(downloadId) }
+    override fun retryDownload(downloadId: String): Promise<Unit> = Promise.async { core.retryDownload(downloadId) }
+    override fun pauseAllDownloads(): Promise<Unit> = Promise.async { core.pauseAllDownloads() }
+    override fun resumeAllDownloads(): Promise<Unit> = Promise.async { core.resumeAllDownloads() }
+    override fun cancelAllDownloads(): Promise<Unit> = Promise.async { core.cancelAllDownloads() }
+
+    // ── Download status (sync) ────────────────────────────────────────────────
     override fun getDownloadTask(downloadId: String): Variant_NullType_DownloadTask {
         val task = core.getDownloadTask(downloadId)
-        return if (task != null) {
-            Variant_NullType_DownloadTask.create(task)
-        } else {
-            Variant_NullType_DownloadTask.create(NullType.NULL)
-        }
+        return if (task != null) Variant_NullType_DownloadTask.create(task)
+        else Variant_NullType_DownloadTask.create(NullType.NULL)
     }
-
-    @DoNotStrip
-    @Keep
     override fun getActiveDownloads(): Array<DownloadTask> = core.getActiveDownloads()
-
-    @DoNotStrip
-    @Keep
     override fun getQueueStatus(): DownloadQueueStatus = core.getQueueStatus()
-
-    @DoNotStrip
-    @Keep
     override fun isDownloading(trackId: String): Boolean = core.isDownloading(trackId)
-
-    @DoNotStrip
-    @Keep
     override fun getDownloadState(trackId: String): DownloadState = core.getDownloadState(trackId)
 
-    // Downloaded Content Queries
-    @DoNotStrip
-    @Keep
-    override fun isTrackDownloaded(trackId: String): Boolean = core.isTrackDownloaded(trackId)
+    // ── Downloaded content queries (now async per spec) ───────────────────────
+    override fun isTrackDownloaded(trackId: String): Promise<Boolean> = Promise.async { core.isTrackDownloaded(trackId) }
+    override fun isPlaylistDownloaded(playlistId: String): Promise<Boolean> = Promise.async { core.isPlaylistDownloaded(playlistId) }
+    override fun isPlaylistPartiallyDownloaded(playlistId: String): Promise<Boolean> = Promise.async { core.isPlaylistPartiallyDownloaded(playlistId) }
 
-    @DoNotStrip
-    @Keep
-    override fun isPlaylistDownloaded(playlistId: String): Boolean = core.isPlaylistDownloaded(playlistId)
-
-    @DoNotStrip
-    @Keep
-    override fun isPlaylistPartiallyDownloaded(playlistId: String): Boolean = core.isPlaylistPartiallyDownloaded(playlistId)
-
-    @DoNotStrip
-    @Keep
-    override fun getDownloadedTrack(trackId: String): Variant_NullType_DownloadedTrack {
+    override fun getDownloadedTrack(trackId: String): Promise<Variant_NullType_DownloadedTrack> = Promise.async {
         val track = core.getDownloadedTrack(trackId)
-        return if (track != null) {
-            Variant_NullType_DownloadedTrack.create(track)
-        } else {
-            Variant_NullType_DownloadedTrack.create(NullType.NULL)
-        }
+        if (track != null) Variant_NullType_DownloadedTrack.create(track)
+        else Variant_NullType_DownloadedTrack.create(NullType.NULL)
     }
+    override fun getAllDownloadedTracks(): Promise<Array<DownloadedTrack>> = Promise.async { core.getAllDownloadedTracks() }
 
-    @DoNotStrip
-    @Keep
-    override fun getAllDownloadedTracks(): Array<DownloadedTrack> = core.getAllDownloadedTracks()
-
-    @DoNotStrip
-    @Keep
-    override fun getDownloadedPlaylist(playlistId: String): Variant_NullType_DownloadedPlaylist {
+    override fun getDownloadedPlaylist(playlistId: String): Promise<Variant_NullType_DownloadedPlaylist> = Promise.async {
         val playlist = core.getDownloadedPlaylist(playlistId)
-        return if (playlist != null) {
-            Variant_NullType_DownloadedPlaylist.create(playlist)
-        } else {
-            Variant_NullType_DownloadedPlaylist.create(NullType.NULL)
-        }
+        if (playlist != null) Variant_NullType_DownloadedPlaylist.create(playlist)
+        else Variant_NullType_DownloadedPlaylist.create(NullType.NULL)
     }
+    override fun getAllDownloadedPlaylists(): Promise<Array<DownloadedPlaylist>> = Promise.async { core.getAllDownloadedPlaylists() }
 
-    @DoNotStrip
-    @Keep
-    override fun getAllDownloadedPlaylists(): Array<DownloadedPlaylist> = core.getAllDownloadedPlaylists()
-
-    @DoNotStrip
-    @Keep
-    override fun getLocalPath(trackId: String): Variant_NullType_String {
+    override fun getLocalPath(trackId: String): Promise<Variant_NullType_String> = Promise.async {
         val path = core.getLocalPath(trackId)
-        return if (path != null) {
-            Variant_NullType_String.create(path)
-        } else {
-            Variant_NullType_String.create(NullType.NULL)
-        }
+        if (path != null) Variant_NullType_String.create(path)
+        else Variant_NullType_String.create(NullType.NULL)
     }
 
-    // Deletion
-    override fun deleteDownloadedTrack(trackId: String): Promise<Unit> =
-        Promise.async {
-            core.deleteDownloadedTrack(trackId)
-        }
+    override fun syncDownloads(): Promise<Double> = Promise.async { core.syncDownloads().toDouble() }
+    override fun getEffectiveUrl(track: TrackItem): Promise<String> = Promise.async { core.getEffectiveUrl(track) }
 
-    override fun deleteDownloadedPlaylist(playlistId: String): Promise<Unit> =
-        Promise.async {
-            core.deleteDownloadedPlaylist(playlistId)
-        }
+    // ── Deletion ──────────────────────────────────────────────────────────────
+    override fun deleteDownloadedTrack(trackId: String): Promise<Unit> = Promise.async { core.deleteDownloadedTrack(trackId) }
+    override fun deleteDownloadedPlaylist(playlistId: String): Promise<Unit> = Promise.async { core.deleteDownloadedPlaylist(playlistId) }
+    override fun deleteAllDownloads(): Promise<Unit> = Promise.async { core.deleteAllDownloads() }
+    override fun getStorageInfo(): Promise<DownloadStorageInfo> = Promise.async { core.getStorageInfo() }
 
-    override fun deleteAllDownloads(): Promise<Unit> =
-        Promise.async {
-            core.deleteAllDownloads()
-        }
-
-    // Storage Management
-    override fun getStorageInfo(): Promise<DownloadStorageInfo> =
-        Promise.async {
-            core.getStorageInfo()
-        }
-
-    @DoNotStrip
-    @Keep
-    override fun syncDownloads(): Double = core.syncDownloads().toDouble()
-
-    // Playback Source Preference
-    @DoNotStrip
-    @Keep
-    override fun setPlaybackSourcePreference(preference: PlaybackSource) {
-        core.setPlaybackSourcePreference(preference)
-    }
-
-    @DoNotStrip
-    @Keep
+    // ── Playback source ───────────────────────────────────────────────────────
+    override fun setPlaybackSourcePreference(preference: PlaybackSource) = core.setPlaybackSourcePreference(preference)
     override fun getPlaybackSourcePreference(): PlaybackSource = core.getPlaybackSourcePreference()
 
-    @DoNotStrip
-    @Keep
-    override fun getEffectiveUrl(track: TrackItem): String = core.getEffectiveUrl(track)
-
-    // Event Callbacks
-    override fun onDownloadProgress(callback: (progress: DownloadProgress) -> Unit) {
-        core.addProgressCallback(callback)
-    }
-
-    override fun onDownloadStateChange(callback: (downloadId: String, trackId: String, state: DownloadState, error: DownloadError?) -> Unit) {
-        core.addStateChangeCallback(callback)
-    }
-
-    override fun onDownloadComplete(callback: (downloadedTrack: DownloadedTrack) -> Unit) {
-        core.addCompleteCallback(callback)
-    }
+    // ── Events ────────────────────────────────────────────────────────────────
+    override fun onDownloadProgress(callback: (progress: DownloadProgress) -> Unit) = core.addProgressCallback(callback)
+    override fun onDownloadStateChange(callback: (downloadId: String, trackId: String, state: DownloadState, error: DownloadError?) -> Unit) = core.addStateChangeCallback(callback)
+    override fun onDownloadComplete(callback: (downloadedTrack: DownloadedTrack) -> Unit) = core.addCompleteCallback(callback)
 }