react-native-nitro-player 0.0.1 → 0.3.0-alpha.10

package/README.md

@@ -80,8 +80,116 @@ TrackPlayer.pause()
 TrackPlayer.skipToNext()
 TrackPlayer.skipToPrevious()
 TrackPlayer.seek(30) // Seek to 30 seconds
+
+// Set repeat mode
+TrackPlayer.setRepeatMode('off') // No repeat
+TrackPlayer.setRepeatMode('Playlist') // Repeat entire playlist
+TrackPlayer.setRepeatMode('track') // Repeat current track
+
+// Set volume (0-100)
+TrackPlayer.setVolume(50) // Set volume to 50%
+TrackPlayer.setVolume(0) // Mute
+TrackPlayer.setVolume(100) // Maximum volume
+
+// Add temporary tracks to queue
+TrackPlayer.addToUpNext('song-id') // Add to up-next queue (FIFO)
+TrackPlayer.playNext('song-id') // Add to play-next stack (LIFO)
+```
+
+## 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)`
+
+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
+TrackPlayer.addToUpNext('song-1') // Will play 3rd
+TrackPlayer.addToUpNext('song-2') // Will play 4th
+TrackPlayer.addToUpNext('song-3') // Will play 5th
+// Order: [current] → [song-1] → [song-2] → [song-3]
+```
+
+### `playNext(trackId: string)`
+
+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
+TrackPlayer.playNext('song-1') // Will play 3rd
+TrackPlayer.playNext('song-2') // Will play 2nd (most recent)
+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:
+
+- `TrackPlayer.playSong()` is called
+- `PlayerQueue.loadPlaylist()` is called
+- `TrackPlayer.playFromIndex()` is called
+
+### 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 (
+    <ScrollView>
+      {queue.map((track, index) => (
+        <View key={track.id}>
+          <Text>{index + 1}. {track.title}</Text>
+        </View>
+      ))}
+    </ScrollView>
+  )
+}
+```
+
+**Returns:**
+
+- `queue: TrackItem[]` - Complete queue in playback order
+- `refreshQueue: () => void` - Manually refresh the queue
+- `isLoading: boolean` - Whether the queue is currently loading
+
 ## Core Concepts
 
 ### PlayerQueue
@@ -99,6 +207,9 @@ 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
 
@@ -159,6 +270,93 @@ Automatically polls for audio device changes every 2 seconds.
 
 - `devices: TAudioDevice[]` - Array of available audio devices
 
+### `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)
+
+**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 = (trackId: string) => {
+    TrackPlayer.addToUpNext(trackId)
+    // Refresh queue after adding track
+    setTimeout(refreshQueue, 100)
+  }
+
+  return (
+    <ScrollView>
+      {queue.map((track, index) => (
+        <View key={track.id}>
+          <Text>{index + 1}. {track.title}</Text>
+        </View>
+      ))}
+    </ScrollView>
+  )
+}
+```
+
+### `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 (
+    <View>
+      <Text>Playlists: {allPlaylists.length}</Text>
+      <Text>Total Tracks: {allTracks.length}</Text>
+    </View>
+  )
+}
+```
+
 ## Audio Device APIs
 
 ### `AudioDevices` (Android only)
@@ -183,7 +381,7 @@ import { AudioDevices } from 'react-native-nitro-player'
 
 if (AudioDevices) {
   const devices = AudioDevices.getAudioDevices()
-  devices.forEach((device) => {
+  devices.forEach(device => {
     console.log(`${device.name} - Active: ${device.isActive}`)
   })
 }
@@ -228,6 +426,82 @@ if (AudioRoutePicker) {
 }
 ```
 
+## Repeat Mode
+
+Control how tracks repeat during playback.
+
+### `setRepeatMode(mode: RepeatMode): boolean`
+
+Sets the repeat mode for the player.
+
+**Parameters:**
+
+- `mode: 'off' | 'Playlist' | 'track'` - The repeat mode to set
+  - `'off'` - No repeat, playlist stops at the end
+  - `'Playlist'` - Repeat the entire playlist
+  - `'track'` - Repeat the current track only
+
+**Returns:** `true` if successful, `false` otherwise
+
+**Example:**
+
+```typescript
+import { TrackPlayer } from 'react-native-nitro-player'
+
+// Turn off repeat
+TrackPlayer.setRepeatMode('off')
+
+// Repeat entire playlist
+TrackPlayer.setRepeatMode('Playlist')
+
+// Repeat current track
+TrackPlayer.setRepeatMode('track')
+```
+
+## Volume Control
+
+Control the playback volume level.
+
+### `setVolume(volume: number): boolean`
+
+Sets the playback volume level.
+
+**Parameters:**
+
+- `volume: number` - Volume level between 0 and 100
+  - `0` - Mute (no sound)
+  - `50` - Half volume
+  - `100` - Maximum volume
+
+**Returns:** `true` if successful, `false` otherwise (e.g., if player is not initialized)
+
+**Example:**
+
+```typescript
+import { TrackPlayer } from 'react-native-nitro-player'
+
+// Set volume to 50%
+const success = TrackPlayer.setVolume(50)
+if (success) {
+  console.log('Volume set successfully')
+} else {
+  console.warn('Failed to set volume')
+}
+
+// Mute the player
+TrackPlayer.setVolume(0)
+
+// Set to maximum volume
+TrackPlayer.setVolume(100)
+
+// Incremental volume control
+const currentVolume = 50
+TrackPlayer.setVolume(currentVolume + 10) // Increase by 10%
+TrackPlayer.setVolume(currentVolume - 10) // Decrease by 10%
+```
+
+**Note:** The volume value is automatically clamped to the 0-100 range. Values outside this range will be clamped to the nearest valid value.
+
 ## Usage Examples
 
 ### Using React Hooks
@@ -259,6 +533,9 @@ function PlayerComponent() {
   // Check Android Auto connection
   const { isConnected } = useAndroidAutoConnection()
 
+  // Get complete player state (alternative to individual hooks)
+  const nowPlaying = useNowPlaying()
+
   return (
     <View>
       {track && (
@@ -266,6 +543,8 @@ function PlayerComponent() {
       )}
       <Text>State: {state}</Text>
       <Text>Progress: {position} / {totalDuration}</Text>
+      {/* Or use useNowPlaying for all state at once */}
+      <Text>Now Playing State: {nowPlaying.currentState}</Text>
     </View>
   )
 }
@@ -349,7 +628,7 @@ TrackPlayer.onPlaybackProgressChange(
 )
 
 // Listen to Android Auto connection changes
-TrackPlayer.onAndroidAutoConnectionChange((connected) => {
+TrackPlayer.onAndroidAutoConnectionChange(connected => {
   console.log('Android Auto:', connected ? 'Connected' : 'Disconnected')
 })
 ```
@@ -572,6 +851,7 @@ AndroidAutoMediaLibraryHelper.set({
 
 - ✅ **Playlist Management**: Create, update, and manage multiple playlists
 - ✅ **Playback Controls**: Play, pause, seek, skip tracks
+- ✅ **Volume Control**: Adjust playback volume (0-100)
 - ✅ **React Hooks**: Built-in hooks for reactive state management
 - ✅ **Event Listeners**: Listen to track changes, state changes, and more
 - ✅ **Android Auto Support**: Control playback from Android Auto with customizable UI

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

@@ -7,21 +7,21 @@ import android.os.Build
 import com.margelo.nitro.NitroModules
 
 class HybridAudioDevices : HybridAudioDevicesSpec() {
-
-    val applicationContext = NitroModules.applicationContext;
+    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
-        )
+        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
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
             types.add(AudioDeviceInfo.TYPE_BLE_HEADSET)
@@ -29,7 +29,7 @@ class HybridAudioDevices : HybridAudioDevicesSpec() {
         }
         types
     }
-    
+
     override fun getAudioDevices(): Array<TAudioDevice> {
         val devices = audioManager.getDevices(android.media.AudioManager.GET_DEVICES_OUTPUTS)
         var activeDevice: AudioDeviceInfo? = null
@@ -37,20 +37,23 @@ class HybridAudioDevices : HybridAudioDevicesSpec() {
         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()
+        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()
     }
-    
-    private fun getDeviceTypeName(type: Int): String {
-        return when (type) {
+
+    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"
@@ -62,11 +65,11 @@ class HybridAudioDevices : HybridAudioDevicesSpec() {
             27 -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) "BLE Speaker" else "Type 27"
             else -> "Type $type"
         }
-    }
 
     override fun setAudioDevice(deviceId: Double): Boolean {
         val device =
-            audioManager.getDevices(android.media.AudioManager.GET_DEVICES_OUTPUTS)
+            audioManager
+                .getDevices(android.media.AudioManager.GET_DEVICES_OUTPUTS)
                 .firstOrNull { it.id == deviceId.toInt() }
                 ?: return false
 
@@ -83,21 +86,26 @@ class HybridAudioDevices : HybridAudioDevicesSpec() {
                 // Pre-Android 12 fallback (best-effort)
                 when (device.type) {
                     android.media.AudioDeviceInfo.TYPE_BLUETOOTH_SCO,
-                    android.media.AudioDeviceInfo.TYPE_BLUETOOTH_A2DP -> {
+                    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 -> {
+                    android.media.AudioDeviceInfo.TYPE_WIRED_HEADPHONES,
+                    -> {
                         audioManager.isSpeakerphoneOn = false
                         audioManager.isBluetoothScoOn = false
                         true
                     }
+
                     else -> {
                         android.util.Log.w(TAG, "Unsupported device type for pre-Android 12: ${device.type}")
                         false

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

@@ -53,10 +53,30 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
         core.seek(position)
     }
 
+    @DoNotStrip
+    @Keep
+    override fun addToUpNext(trackId: String) {
+        core.addToUpNext(trackId)
+    }
+
+    @DoNotStrip
+    @Keep
+    override fun playNext(trackId: String) {
+        core.playNext(trackId)
+    }
+
+    @DoNotStrip
+    @Keep
+    override fun getActualQueue(): Array<TrackItem> = core.getActualQueue().toTypedArray()
+
     @DoNotStrip
     @Keep
     override fun getState(): PlayerState = core.getState()
 
+    @DoNotStrip
+    @Keep
+    override fun setRepeatMode(mode: RepeatMode): Boolean = core.setRepeatMode(mode)
+
     override fun onChangeTrack(callback: (track: TrackItem, reason: Reason?) -> Unit) {
         core.onChangeTrack = callback
     }
@@ -90,4 +110,8 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
 
     @Keep
     override fun isAndroidAutoConnected(): Boolean = core.isAndroidAutoConnected()
+
+    @DoNotStrip
+    @Keep
+    override fun setVolume(volume: Double): Boolean = core.setVolume(volume)
 }