react-native-nitro-player 0.3.0-alpha.6 → 0.3.0-alpha.7

package/README.md

@@ -1 +1,699 @@
-Refer Root readme
+# React Native Nitro Player
+
+A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay.
+
+## Installation
+
+```bash
+npm install react-native-nitro-player
+# or
+yarn add react-native-nitro-player
+```
+
+### Peer Dependencies
+
+Make sure you have these installed:
+
+```bash
+npm install react-native-nitro-modules
+```
+
+## Quick Start
+
+### 1. Configure the Player
+
+Configure the player before using it in your app:
+
+```typescript
+import { TrackPlayer } from 'react-native-nitro-player'
+
+TrackPlayer.configure({
+  androidAutoEnabled: true,
+  carPlayEnabled: false,
+  showInNotification: true,
+})
+```
+
+### 2. Create Playlists
+
+```typescript
+import { PlayerQueue } from 'react-native-nitro-player'
+import type { TrackItem } from 'react-native-nitro-player'
+
+const tracks: TrackItem[] = [
+  {
+    id: '1',
+    title: 'Song Title',
+    artist: 'Artist Name',
+    album: 'Album Name',
+    duration: 180.0, // in seconds
+    url: 'https://example.com/song.mp3',
+    artwork: 'https://example.com/artwork.jpg',
+  },
+]
+
+// Create a playlist
+const playlistId = PlayerQueue.createPlaylist(
+  'My Playlist',
+  'Playlist description',
+  'https://example.com/playlist-artwork.jpg'
+)
+
+// Add tracks to the playlist
+PlayerQueue.addTracksToPlaylist(playlistId, tracks)
+```
+
+### 3. Play Music
+
+```typescript
+import { TrackPlayer, PlayerQueue } from 'react-native-nitro-player'
+
+// Load and play a playlist
+PlayerQueue.loadPlaylist(playlistId)
+
+// Or play a specific song
+TrackPlayer.playSong('song-id', playlistId)
+
+// Basic controls
+TrackPlayer.play()
+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
+```
+
+## Core Concepts
+
+### PlayerQueue
+
+Manages playlists and tracks. Use it to:
+
+- Create, update, and delete playlists
+- Add or remove tracks from playlists
+- Load playlists for playback
+- Listen to playlist changes
+
+### TrackPlayer
+
+Controls playback. Use it to:
+
+- Play, pause, and seek
+- Skip tracks
+- Control repeat mode
+- Control volume
+- Get current player state
+- Listen to playback events
+
+## React Hooks
+
+The library provides React hooks for reactive state management. These hooks automatically update your components when player state changes.
+
+### `useOnChangeTrack()`
+
+Returns the current track and the reason why it changed.
+
+**Returns:**
+
+- `track: TrackItem | undefined` - The current track, or `undefined` if no track is playing
+- `reason: Reason | undefined` - The reason for the track change (`'user_action'`, `'skip'`, `'end'`, or `'error'`)
+
+### `useOnPlaybackStateChange()`
+
+Returns the current playback state and the reason for the state change.
+
+**Returns:**
+
+- `state: TrackPlayerState | undefined` - Current playback state (`'playing'`, `'paused'`, or `'stopped'`)
+- `reason: Reason | undefined` - The reason for the state change
+
+### `useOnPlaybackProgressChange()`
+
+Returns real-time playback progress updates.
+
+**Returns:**
+
+- `position: number` - Current playback position in seconds
+- `totalDuration: number` - Total duration of the current track in seconds
+- `isManuallySeeked: boolean | undefined` - `true` if the user manually seeked, `undefined` otherwise
+
+### `useOnSeek()`
+
+Returns information about the last seek event.
+
+**Returns:**
+
+- `position: number | undefined` - The position where the user seeked to, or `undefined` if no seek has occurred
+- `totalDuration: number | undefined` - The total duration at the time of seek, or `undefined` if no seek has occurred
+
+### `useAndroidAutoConnection()`
+
+Monitors Android Auto connection status.
+
+**Returns:**
+
+- `isConnected: boolean` - `true` if connected to Android Auto, `false` otherwise
+
+### `useAudioDevices()` (Android only)
+
+Automatically polls for audio device changes every 2 seconds.
+
+**Returns:**
+
+- `devices: TAudioDevice[]` - Array of available audio devices
+
+## Audio Device APIs
+
+### `AudioDevices` (Android only)
+
+Android-specific API for managing audio output devices.
+
+#### `getAudioDevices(): TAudioDevice[]`
+
+Returns the list of available audio output devices.
+
+**Returns:** Array of `TAudioDevice` objects with:
+
+- `id: number` - Unique device ID
+- `name: string` - Device name (e.g., "Built-in Speaker", "Bluetooth")
+- `type: number` - Device type constant
+- `isActive: boolean` - Whether this device is currently active
+
+**Example:**
+
+```typescript
+import { AudioDevices } from 'react-native-nitro-player'
+
+if (AudioDevices) {
+  const devices = AudioDevices.getAudioDevices()
+  devices.forEach(device => {
+    console.log(`${device.name} - Active: ${device.isActive}`)
+  })
+}
+```
+
+#### `setAudioDevice(deviceId: number): boolean`
+
+Sets the active audio output device.
+
+**Parameters:**
+
+- `deviceId: number` - The ID of the device to activate
+
+**Returns:** `true` if successful, `false` otherwise
+
+**Example:**
+
+```typescript
+import { AudioDevices } from 'react-native-nitro-player'
+
+if (AudioDevices) {
+  const success = AudioDevices.setAudioDevice(deviceId)
+  console.log(`Device switch: ${success ? 'success' : 'failed'}`)
+}
+```
+
+### `AudioRoutePicker` (iOS only)
+
+iOS-specific API for displaying the native audio route picker (AirPlay menu).
+
+#### `showRoutePicker(): void`
+
+Shows the native AVRoutePickerView for selecting audio output routes like AirPlay, Bluetooth, etc.
+
+**Example:**
+
+```typescript
+import { AudioRoutePicker } from 'react-native-nitro-player'
+
+if (AudioRoutePicker) {
+  AudioRoutePicker.showRoutePicker()
+}
+```
+
+## 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
+
+The library provides convenient React hooks for reactive state management:
+
+```typescript
+import {
+  useOnChangeTrack,
+  useOnPlaybackStateChange,
+  useOnPlaybackProgressChange,
+  useOnSeek,
+  useAndroidAutoConnection,
+} from 'react-native-nitro-player'
+
+function PlayerComponent() {
+  // Get current track
+  const { track, reason } = useOnChangeTrack()
+
+  // Get playback state (playing, paused, stopped)
+  const { state, reason: stateReason } = useOnPlaybackStateChange()
+
+  // Get playback progress
+  const { position, totalDuration, isManuallySeeked } = useOnPlaybackProgressChange()
+
+  // Get seek events
+  const { position: seekPosition, totalDuration: seekDuration } = useOnSeek()
+
+  // Check Android Auto connection
+  const { isConnected } = useAndroidAutoConnection()
+
+  return (
+    <View>
+      {track && (
+        <Text>Now Playing: {track.title} by {track.artist}</Text>
+      )}
+      <Text>State: {state}</Text>
+      <Text>Progress: {position} / {totalDuration}</Text>
+    </View>
+  )
+}
+```
+
+### Managing Playlists
+
+```typescript
+import { PlayerQueue } from 'react-native-nitro-player'
+import type { TrackItem, Playlist } from 'react-native-nitro-player'
+
+// Get all playlists
+const playlists = PlayerQueue.getAllPlaylists()
+
+// Get a specific playlist
+const playlist = PlayerQueue.getPlaylist(playlistId)
+
+// Get current playing playlist
+const currentPlaylistId = PlayerQueue.getCurrentPlaylistId()
+
+// Update playlist metadata
+PlayerQueue.updatePlaylist(playlistId, {
+  name: 'Updated Name',
+  description: 'New description',
+  artwork: 'https://example.com/new-artwork.jpg',
+})
+
+// Add a single track
+PlayerQueue.addTrackToPlaylist(playlistId, newTrack)
+
+// Add multiple tracks
+PlayerQueue.addTracksToPlaylist(playlistId, [track1, track2, track3])
+
+// Remove a track
+PlayerQueue.removeTrackFromPlaylist(playlistId, trackId)
+
+// Reorder tracks
+PlayerQueue.reorderTrackInPlaylist(playlistId, trackId, newIndex)
+
+// Delete a playlist
+PlayerQueue.deletePlaylist(playlistId)
+```
+
+### Listening to Events
+
+```typescript
+import { PlayerQueue, TrackPlayer } from 'react-native-nitro-player'
+
+// Listen to playlist changes
+PlayerQueue.onPlaylistsChanged((playlists, operation) => {
+  console.log('Playlists updated:', operation)
+  // operation can be: 'add', 'remove', 'clear', 'update'
+})
+
+// Listen to specific playlist changes
+PlayerQueue.onPlaylistChanged((playlistId, playlist, operation) => {
+  console.log('Playlist changed:', playlistId, operation)
+})
+
+// Listen to track changes
+TrackPlayer.onChangeTrack((track, reason) => {
+  console.log('Track changed:', track.title, reason)
+  // reason can be: 'user_action', 'skip', 'end', 'error'
+})
+
+// Listen to playback state changes
+TrackPlayer.onPlaybackStateChange((state, reason) => {
+  console.log('State changed:', state, reason)
+})
+
+// Listen to seek events
+TrackPlayer.onSeek((position, totalDuration) => {
+  console.log('Seeked to:', position)
+})
+
+// Listen to playback progress
+TrackPlayer.onPlaybackProgressChange(
+  (position, totalDuration, isManuallySeeked) => {
+    console.log('Progress:', position, '/', totalDuration)
+  }
+)
+
+// Listen to Android Auto connection changes
+TrackPlayer.onAndroidAutoConnectionChange(connected => {
+  console.log('Android Auto:', connected ? 'Connected' : 'Disconnected')
+})
+```
+
+### Getting Player State
+
+```typescript
+import { TrackPlayer } from 'react-native-nitro-player'
+
+const state = TrackPlayer.getState()
+
+console.log(state.currentState) // 'playing' | 'paused' | 'stopped'
+console.log(state.currentPosition) // current position in seconds
+console.log(state.totalDuration) // total duration in seconds
+console.log(state.currentTrack) // current TrackItem or null
+console.log(state.currentPlaylistId) // current playlist ID or null
+console.log(state.currentIndex) // current track index in playlist
+```
+
+## Track Item Structure
+
+Each track must follow this structure:
+
+```typescript
+interface TrackItem {
+  id: string // Unique identifier
+  title: string // Track title
+  artist: string // Artist name
+  album: string // Album name
+  duration: number // Duration in seconds
+  url: string // Audio file URL
+  artwork?: string | null // Optional artwork URL
+}
+```
+
+## Playlist Structure
+
+```typescript
+interface Playlist {
+  id: string // Unique identifier
+  name: string // Playlist name
+  description?: string | null // Optional description
+  artwork?: string | null // Optional artwork URL
+  tracks: TrackItem[] // Array of tracks
+}
+```
+
+## Android Auto Customization
+
+Customize how your music library appears in Android Auto with a custom folder structure.
+
+### Basic Setup
+
+By default, all playlists are shown in Android Auto. You can create a custom structure:
+
+```typescript
+import { AndroidAutoMediaLibraryHelper } from 'react-native-nitro-player'
+import type { MediaLibrary } from 'react-native-nitro-player'
+
+// Check if available (Android only)
+if (AndroidAutoMediaLibraryHelper.isAvailable()) {
+  const mediaLibrary: MediaLibrary = {
+    layoutType: 'grid', // 'grid' or 'list'
+    rootItems: [
+      {
+        id: 'my_music',
+        title: '🎵 My Music',
+        subtitle: 'Your music collection',
+        mediaType: 'folder',
+        isPlayable: false,
+        layoutType: 'grid',
+        children: [
+          {
+            id: 'favorites',
+            title: 'Favorites',
+            subtitle: '10 tracks',
+            mediaType: 'playlist',
+            playlistId: 'my-playlist-id', // References a playlist created with PlayerQueue
+            isPlayable: false,
+          },
+        ],
+      },
+      {
+        id: 'recent',
+        title: '🕐 Recently Played',
+        mediaType: 'folder',
+        isPlayable: false,
+        children: [
+          // More playlist references...
+        ],
+      },
+    ],
+  }
+
+  AndroidAutoMediaLibraryHelper.set(mediaLibrary)
+}
+
+// Reset to default (show all playlists)
+AndroidAutoMediaLibraryHelper.clear()
+```
+
+### MediaLibrary Structure
+
+```typescript
+interface MediaLibrary {
+  layoutType: 'grid' | 'list' // Default layout for items
+  rootItems: MediaItem[] // Top-level items
+  appName?: string // Optional app name
+  appIconUrl?: string // Optional app icon
+}
+
+interface MediaItem {
+  id: string // Unique identifier
+  title: string // Display title
+  subtitle?: string // Optional subtitle
+  iconUrl?: string // Optional icon/artwork URL
+  isPlayable: boolean // Whether item can be played
+  mediaType: 'folder' | 'audio' | 'playlist' // Type of item
+  playlistId?: string // Reference to playlist (for playlist items)
+  children?: MediaItem[] // Child items (for folders)
+  layoutType?: 'grid' | 'list' // Override default layout
+}
+```
+
+### Example: Organizing Playlists by Genre
+
+```typescript
+import {
+  PlayerQueue,
+  AndroidAutoMediaLibraryHelper,
+} from 'react-native-nitro-player'
+
+// Create playlists first
+const rockPlaylistId = PlayerQueue.createPlaylist('Rock Classics')
+const jazzPlaylistId = PlayerQueue.createPlaylist('Jazz Essentials')
+const popPlaylistId = PlayerQueue.createPlaylist('Pop Hits')
+
+// Add tracks to playlists...
+PlayerQueue.addTracksToPlaylist(rockPlaylistId, rockTracks)
+PlayerQueue.addTracksToPlaylist(jazzPlaylistId, jazzTracks)
+PlayerQueue.addTracksToPlaylist(popPlaylistId, popTracks)
+
+// Create custom Android Auto structure
+AndroidAutoMediaLibraryHelper.set({
+  layoutType: 'list',
+  rootItems: [
+    {
+      id: 'genres',
+      title: '🎸 By Genre',
+      mediaType: 'folder',
+      isPlayable: false,
+      layoutType: 'grid',
+      children: [
+        {
+          id: 'rock',
+          title: 'Rock',
+          mediaType: 'playlist',
+          playlistId: rockPlaylistId,
+          isPlayable: false,
+        },
+        {
+          id: 'jazz',
+          title: 'Jazz',
+          mediaType: 'playlist',
+          playlistId: jazzPlaylistId,
+          isPlayable: false,
+        },
+        {
+          id: 'pop',
+          title: 'Pop',
+          mediaType: 'playlist',
+          playlistId: popPlaylistId,
+          isPlayable: false,
+        },
+      ],
+    },
+    {
+      id: 'all_music',
+      title: '📀 All Music',
+      mediaType: 'folder',
+      isPlayable: false,
+      children: [
+        {
+          id: 'all_rock',
+          title: 'Rock Classics',
+          mediaType: 'playlist',
+          playlistId: rockPlaylistId,
+          isPlayable: false,
+        },
+        {
+          id: 'all_jazz',
+          title: 'Jazz Essentials',
+          mediaType: 'playlist',
+          playlistId: jazzPlaylistId,
+          isPlayable: false,
+        },
+        {
+          id: 'all_pop',
+          title: 'Pop Hits',
+          mediaType: 'playlist',
+          playlistId: popPlaylistId,
+          isPlayable: false,
+        },
+      ],
+    },
+  ],
+})
+```
+
+### Notes
+
+- The `playlistId` field must reference a playlist created with `PlayerQueue.createPlaylist()`
+- Changes are immediately reflected in Android Auto
+- Use folders to organize playlists hierarchically
+- Grid layout is best for album/playlist browsing
+- List layout is best for song lists
+- Only available on Android (use `isAvailable()` to check)
+
+## Features
+
+- ✅ **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
+- ✅ **CarPlay Support**: Control playback from CarPlay (iOS)
+- ✅ **Notification Controls**: Show playback controls in notifications
+- ✅ **Progress Tracking**: Real-time playback progress updates
+
+## TypeScript Support
+
+The library is written in TypeScript and includes full type definitions. All types are exported for your convenience:
+
+```typescript
+import type {
+  TrackItem,
+  Playlist,
+  PlayerState,
+  TrackPlayerState,
+  QueueOperation,
+  Reason,
+  PlayerConfig,
+  MediaLibrary,
+  MediaItem,
+  LayoutType,
+  MediaType,
+} from 'react-native-nitro-player'
+```
+
+## Platform Support
+
+- ✅ **iOS**: Full support with CarPlay integration
+- ✅ **Android**: Full support with Android Auto integration
+- 🎯 **Android Auto Media Library**: Android-only feature for customizing the Android Auto UI
+
+## License
+
+MIT

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

@@ -94,4 +94,8 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
 
     @Keep
     override fun isAndroidAutoConnected(): Boolean = core.isAndroidAutoConnected()
+
+    @DoNotStrip
+    @Keep
+    override fun setVolume(volume: Double): Boolean = core.setVolume(volume)
 }

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

@@ -4,6 +4,8 @@ package com.margelo.nitro.nitroplayer.core
 
 import android.content.Context
 import android.net.Uri
+import androidx.media3.common.AudioAttributes
+import androidx.media3.common.C
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
 import androidx.media3.common.Player
@@ -72,25 +74,43 @@ class TrackPlayerCore private constructor(
 
     init {
         handler.post {
-            // Configure LoadControl for gapless playback
-            // This enables pre-buffering of the next track for seamless transitions
+            // ============================================================
+            // GAPLESS PLAYBACK CONFIGURATION
+            // ============================================================
+            // Configure LoadControl for maximum gapless playback
+            // Large buffers ensure next track is fully ready before current ends
             val loadControl =
                 DefaultLoadControl
                     .Builder()
                     .setBufferDurationsMs(
-                        DefaultLoadControl.DEFAULT_MIN_BUFFER_MS, // Minimum buffer: 1.5s
-                        DefaultLoadControl.DEFAULT_MAX_BUFFER_MS, // Maximum buffer: 5s
-                        DefaultLoadControl.DEFAULT_BUFFER_FOR_PLAYBACK_MS, // Buffer for playback: 2.5s
-                        DefaultLoadControl.DEFAULT_BUFFER_FOR_PLAYBACK_AFTER_REBUFFER_MS, // Buffer after rebuffer: 5s
-                    ).setBackBuffer(DefaultLoadControl.DEFAULT_BACK_BUFFER_DURATION_MS, true) // Keep back buffer for seamless transitions
+                        30_000, // MIN_BUFFER_MS: 30 seconds minimum buffer
+                        120_000, // MAX_BUFFER_MS: 2 minutes maximum buffer (enables preloading next tracks)
+                        2_500, // BUFFER_FOR_PLAYBACK_MS: 2.5s before playback starts
+                        5_000, // BUFFER_FOR_PLAYBACK_AFTER_REBUFFER_MS: 5s after rebuffer
+                    ).setBackBuffer(30_000, true) // Keep 30s back buffer for seamless seek-back
+                    .setTargetBufferBytes(C.LENGTH_UNSET) // No size limit - prioritize time
                     .setPrioritizeTimeOverSizeThresholds(true) // Prioritize time-based buffering
                     .build()
 
+            // Configure audio attributes for optimal music playback
+            // This enables gapless audio processing in the audio pipeline
+            val audioAttributes =
+                AudioAttributes
+                    .Builder()
+                    .setUsage(C.USAGE_MEDIA)
+                    .setContentType(C.AUDIO_CONTENT_TYPE_MUSIC)
+                    .build()
+
             player =
                 ExoPlayer
                     .Builder(context)
                     .setLoadControl(loadControl)
+                    .setAudioAttributes(audioAttributes, true) // handleAudioFocus = true for gapless
+                    .setHandleAudioBecomingNoisy(true) // Pause when headphones disconnected
+                    .setPauseAtEndOfMediaItems(false) // Don't pause between items - key for gapless!
                     .build()
+
+            println("🎵 TrackPlayerCore: Gapless playback configured - 120s buffer, audio focus handling enabled")
             mediaSessionManager =
                 MediaSessionManager(context, player, playlistManager).apply {
                     setTrackPlayerCore(this@TrackPlayerCore)
@@ -652,4 +672,21 @@ class TrackPlayerCore private constructor(
             NitroPlayerMediaBrowserService.getInstance()?.onPlaylistsUpdated()
         }
     }
+
+    // Set volume (0-100 range, converted to 0.0-1.0 for ExoPlayer)
+    fun setVolume(volume: Double): Boolean =
+        if (::player.isInitialized) {
+            handler.post {
+                // Clamp volume to 0-100 range
+                val clampedVolume = volume.coerceIn(0.0, 100.0)
+                // Convert to 0.0-1.0 range for ExoPlayer
+                val normalizedVolume = (clampedVolume / 100.0).toFloat()
+                player.volume = normalizedVolume
+                println("🔊 TrackPlayerCore: Volume set to $clampedVolume% (normalized: $normalizedVolume)")
+            }
+            true
+        } else {
+            println("⚠️ TrackPlayerCore: Cannot set volume - player not initialized")
+            false
+        }
 }

package/ios/HybridTrackPlayer.swift

@@ -101,4 +101,10 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
   func isAndroidAutoConnected() throws -> Bool {
     return false
   }
+
+  // MARK: - Volume Control
+
+  func setVolume(volume: Double) throws -> Bool {
+    return core.setVolume(volume: volume)
+  }
 }

package/ios/core/TrackPlayerCore.swift

@@ -31,6 +31,13 @@ class TrackPlayerCore: NSObject {
     // UI/Display constants
     static let separatorLineLength: Int = 80
     static let playlistSeparatorLength: Int = 40
+
+    // Gapless playback configuration
+    static let preferredForwardBufferDuration: Double = 30.0  // Buffer 30 seconds ahead
+    static let preloadAssetKeys: [String] = [
+      "playable", "duration", "tracks", "preferredTransform",
+    ]
+    static let gaplessPreloadCount: Int = 3  // Number of tracks to preload ahead
   }
 
   // MARK: - Properties
@@ -46,6 +53,10 @@ class TrackPlayerCore: NSObject {
   private var boundaryTimeObserver: Any?
   private var currentItemObservers: [NSKeyValueObservation] = []
 
+  // Gapless playback: Cache for preloaded assets
+  private var preloadedAssets: [String: AVURLAsset] = [:]
+  private let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
+
   var onChangeTrack: ((TrackItem, Reason?) -> Void)?
   var onPlaybackStateChange: ((TrackPlayerState, Reason?) -> Void)?
   var onSeek: ((Double, Double) -> Void)?
@@ -77,6 +88,24 @@ class TrackPlayerCore: NSObject {
 
   private func setupPlayer() {
     player = AVQueuePlayer()
+
+    // MARK: - Gapless Playback Configuration
+
+    // Disable automatic waiting to minimize stalling - this allows smoother transitions
+    // between tracks as AVPlayer won't pause to buffer excessively
+    player?.automaticallyWaitsToMinimizeStalling = false
+
+    // Set playback rate to 1.0 immediately when ready (reduces gap between tracks)
+    player?.actionAtItemEnd = .advance
+
+    // Configure for high-quality audio playback with minimal latency
+    if #available(iOS 15.0, *) {
+      player?.audiovisualBackgroundPlaybackPolicy = .continuesIfPossible
+    }
+
+    print(
+      "🎵 TrackPlayerCore: Gapless playback configured - automaticallyWaitsToMinimizeStalling=false")
+
     setupPlayerObservers()
   }
 
@@ -446,6 +475,11 @@ class TrackPlayerCore: NSObject {
     if currentItem.status == .readyToPlay {
       setupBoundaryTimeObserver()
     }
+
+    // MARK: - Gapless Playback: Preload upcoming tracks when track changes
+    // This ensures the next tracks are ready for seamless transitions
+    preloadUpcomingTracks(from: currentTrackIndex + 1)
+    cleanupPreloadedAssets(keepingFrom: currentTrackIndex)
   }
 
   private func setupCurrentItemObservers(item: AVPlayerItem) {
@@ -554,6 +588,135 @@ class TrackPlayerCore: NSObject {
     mediaSessionManager?.onPlaybackStateChanged()
   }
 
+  // MARK: - Gapless Playback Helpers
+
+  /// Creates a gapless-optimized AVPlayerItem with proper buffering configuration
+  private func createGaplessPlayerItem(for track: TrackItem, isPreload: Bool = false)
+    -> AVPlayerItem?
+  {
+    guard let url = URL(string: track.url) else {
+      print("❌ TrackPlayerCore: Invalid URL for track: \(track.title) - \(track.url)")
+      return nil
+    }
+
+    // Check if we have a preloaded asset for this track
+    let asset: AVURLAsset
+    if let preloadedAsset = preloadedAssets[track.id] {
+      asset = preloadedAsset
+      print("🚀 TrackPlayerCore: Using preloaded asset for \(track.title)")
+    } else {
+      // Create asset with options optimized for gapless playback
+      asset = AVURLAsset(
+        url: url,
+        options: [
+          AVURLAssetPreferPreciseDurationAndTimingKey: true  // Ensures accurate duration for gapless transitions
+        ])
+    }
+
+    let item = AVPlayerItem(asset: asset)
+
+    // Configure buffer duration for gapless playback
+    // This tells AVPlayer how much content to buffer ahead
+    item.preferredForwardBufferDuration = Constants.preferredForwardBufferDuration
+
+    // Enable automatic loading of item properties for faster starts
+    item.canUseNetworkResourcesForLiveStreamingWhilePaused = true
+
+    // Store track ID for later reference
+    item.trackId = track.id
+
+    // If this is a preload request, start loading asset keys asynchronously
+    if isPreload {
+      asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) {
+        // Asset keys are now loaded, which speeds up playback start
+        var allKeysLoaded = true
+        for key in Constants.preloadAssetKeys {
+          var error: NSError?
+          let status = asset.statusOfValue(forKey: key, error: &error)
+          if status == .failed {
+            print(
+              "⚠️ TrackPlayerCore: Failed to load key '\(key)' for \(track.title): \(error?.localizedDescription ?? "unknown")"
+            )
+            allKeysLoaded = false
+          }
+        }
+        if allKeysLoaded {
+          print("✅ TrackPlayerCore: All asset keys preloaded for \(track.title)")
+        }
+      }
+    }
+
+    return item
+  }
+
+  /// Preloads assets for upcoming tracks to enable gapless playback
+  private func preloadUpcomingTracks(from startIndex: Int) {
+    preloadQueue.async { [weak self] in
+      guard let self = self else { return }
+
+      let endIndex = min(startIndex + Constants.gaplessPreloadCount, self.currentTracks.count)
+
+      for i in startIndex..<endIndex {
+        let track = self.currentTracks[i]
+
+        // Skip if already preloaded
+        if self.preloadedAssets[track.id] != nil {
+          continue
+        }
+
+        guard let url = URL(string: track.url) else { continue }
+
+        let asset = AVURLAsset(
+          url: url,
+          options: [
+            AVURLAssetPreferPreciseDurationAndTimingKey: true
+          ])
+
+        // Preload essential keys for gapless playback
+        asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) { [weak self] in
+          var allKeysLoaded = true
+          for key in Constants.preloadAssetKeys {
+            var error: NSError?
+            let status = asset.statusOfValue(forKey: key, error: &error)
+            if status != .loaded {
+              allKeysLoaded = false
+              break
+            }
+          }
+
+          if allKeysLoaded {
+            DispatchQueue.main.async {
+              self?.preloadedAssets[track.id] = asset
+              print("🎯 TrackPlayerCore: Preloaded asset for upcoming track: \(track.title)")
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /// Clears preloaded assets that are no longer needed
+  private func cleanupPreloadedAssets(keepingFrom currentIndex: Int) {
+    preloadQueue.async { [weak self] in
+      guard let self = self else { return }
+
+      // Keep assets for current track and upcoming tracks within preload range
+      let keepRange =
+        currentIndex..<min(
+          currentIndex + Constants.gaplessPreloadCount + 1, self.currentTracks.count)
+      let keepIds = Set(keepRange.compactMap { self.currentTracks[safe: $0]?.id })
+
+      let assetsToRemove = self.preloadedAssets.keys.filter { !keepIds.contains($0) }
+      for id in assetsToRemove {
+        self.preloadedAssets.removeValue(forKey: id)
+      }
+
+      if !assetsToRemove.isEmpty {
+        print("🧹 TrackPlayerCore: Cleaned up \(assetsToRemove.count) preloaded assets")
+      }
+    }
+  }
+
   // MARK: - Queue Management
 
   private func updatePlayerQueue(tracks: [TrackItem]) {
@@ -578,40 +741,18 @@ class TrackPlayerCore: NSObject {
       boundaryTimeObserver = nil
     }
 
-    // Create AVPlayerItems from tracks
-    let items = tracks.compactMap { track -> AVPlayerItem? in
-      guard let url = URL(string: track.url) else {
-        print("❌ TrackPlayerCore: Invalid URL for track: \(track.title) - \(track.url)")
-        return nil
-      }
-
-      let item = AVPlayerItem(url: url)
-
-      // Set metadata using AVMutableMetadataItem
-      let metadata = AVMutableMetadataItem()
-      metadata.identifier = .commonIdentifierTitle
-      metadata.value = track.title as NSString
-      metadata.locale = Locale.current
-
-      let artistMetadata = AVMutableMetadataItem()
-      artistMetadata.identifier = .commonIdentifierArtist
-      artistMetadata.value = track.artist as NSString
-      artistMetadata.locale = Locale.current
-
-      let albumMetadata = AVMutableMetadataItem()
-      albumMetadata.identifier = .commonIdentifierAlbumName
-      albumMetadata.value = track.album as NSString
-      albumMetadata.locale = Locale.current
-
-      // Note: AVPlayerItem doesn't have externalMetadata property
-      // Metadata will be set via MPNowPlayingInfoCenter in MediaSessionManager
+    // Clear old preloaded assets when loading new queue
+    preloadedAssets.removeAll()
 
-      // Store track ID in item for later reference
-      item.trackId = track.id
-
-      return item
+    // Create gapless-optimized AVPlayerItems from tracks
+    let items = tracks.enumerated().compactMap { (index, track) -> AVPlayerItem? in
+      // First few items get preload treatment for faster initial playback
+      let isPreload = index < Constants.gaplessPreloadCount
+      return createGaplessPlayerItem(for: track, isPreload: isPreload)
     }
 
+    print("🎵 TrackPlayerCore: Created \(items.count) gapless-optimized player items")
+
     guard !items.isEmpty else {
       print("❌ TrackPlayerCore: No valid items to play")
       return
@@ -672,7 +813,10 @@ class TrackPlayerCore: NSObject {
       mediaSessionManager?.onTrackChanged()
     }
 
-    print("✅ TrackPlayerCore: Queue updated with \(items.count) tracks")
+    // Start preloading upcoming tracks for gapless playback
+    preloadUpcomingTracks(from: 1)
+
+    print("✅ TrackPlayerCore: Queue updated with \(items.count) gapless-optimized tracks")
   }
 
   func getCurrentTrack() -> TrackItem? {
@@ -966,6 +1110,28 @@ class TrackPlayerCore: NSObject {
     return playlistManager.getAllPlaylists().map { $0.toGeneratedPlaylist() }
   }
 
+  // MARK: - Volume Control
+
+  func setVolume(volume: Double) -> Bool {
+    guard let player = player else {
+      print("⚠️ TrackPlayerCore: Cannot set volume - no player available")
+      return false
+    }
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self, let currentPlayer = self.player else {
+        return
+      }
+      // Clamp volume to 0-100 range
+      let clampedVolume = max(0.0, min(100.0, volume))
+      // Convert to 0.0-1.0 range for AVQueuePlayer
+      let normalizedVolume = Float(clampedVolume / 100.0)
+      currentPlayer.volume = normalizedVolume
+      print(
+        "🔊 TrackPlayerCore: Volume set to \(Int(clampedVolume))% (normalized: \(normalizedVolume))")
+    }
+    return true
+  }
+
   func playFromIndex(index: Int) {
     DispatchQueue.main.async { [weak self] in
       guard let self = self,
@@ -988,14 +1154,15 @@ class TrackPlayerCore: NSObject {
       // Recreate the queue starting from the target index
       // This ensures all remaining tracks are in the queue
       let tracksToPlay = Array(fullPlaylist[index...])
-      print("   🔄 Creating queue with \(tracksToPlay.count) tracks starting from index \(index)")
-
-      // Update the queue (but keep the full currentTracks for reference)
-      let items = tracksToPlay.compactMap { track -> AVPlayerItem? in
-        guard let url = URL(string: track.url) else { return nil }
-        let item = AVPlayerItem(url: url)
-        item.trackId = track.id
-        return item
+      print(
+        "   🔄 Creating gapless queue with \(tracksToPlay.count) tracks starting from index \(index)"
+      )
+
+      // Create gapless-optimized player items
+      let items = tracksToPlay.enumerated().compactMap { (offset, track) -> AVPlayerItem? in
+        // First few items get preload treatment for faster playback
+        let isPreload = offset < Constants.gaplessPreloadCount
+        return self.createGaplessPlayerItem(for: track, isPreload: isPreload)
       }
 
       guard let player = self.player, !items.isEmpty else {
@@ -1020,13 +1187,16 @@ class TrackPlayerCore: NSObject {
       // Restore the full playlist reference (don't slice it!)
       self.currentTracks = fullPlaylist
 
-      print("   ✅ Queue recreated. Now at index: \(self.currentTrackIndex)")
+      print("   ✅ Gapless queue recreated. Now at index: \(self.currentTrackIndex)")
       if let track = self.getCurrentTrack() {
         print("   🎵 Playing: \(track.title)")
         self.onChangeTrack?(track, .skip)
         self.mediaSessionManager?.onTrackChanged()
       }
 
+      // Start preloading upcoming tracks for gapless playback
+      self.preloadUpcomingTracks(from: index + 1)
+
       player.play()
     }
   }
@@ -1036,6 +1206,9 @@ class TrackPlayerCore: NSObject {
   deinit {
     print("🧹 TrackPlayerCore: Cleaning up...")
 
+    // Clear preloaded assets for gapless playback
+    preloadedAssets.removeAll()
+
     // Remove boundary time observer
     if let boundaryObserver = boundaryTimeObserver, let currentPlayer = player {
       currentPlayer.removeTimeObserver(boundaryObserver)

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

@@ -38,4 +38,5 @@ export interface TrackPlayer extends HybridObject<{
     onPlaybackProgressChange(callback: (position: number, totalDuration: number, isManuallySeeked?: boolean) => void): void;
     onAndroidAutoConnectionChange(callback: (connected: boolean) => void): void;
     isAndroidAutoConnected(): boolean;
+    setVolume(volume: number): boolean;
 }

package/nitrogen/generated/android/c++/JHybridTrackPlayerSpec.cpp

@@ -142,5 +142,10 @@ namespace margelo::nitro::nitroplayer {
     auto __result = method(_javaPart);
     return static_cast<bool>(__result);
   }
+  bool JHybridTrackPlayerSpec::setVolume(double volume) {
+    static const auto method = javaClassStatic()->getMethod<jboolean(double /* volume */)>("setVolume");
+    auto __result = method(_javaPart, volume);
+    return static_cast<bool>(__result);
+  }
 
 } // namespace margelo::nitro::nitroplayer

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

@@ -69,6 +69,7 @@ namespace margelo::nitro::nitroplayer {
     void onPlaybackProgressChange(const std::function<void(double /* position */, double /* totalDuration */, std::optional<bool> /* isManuallySeeked */)>& callback) override;
     void onAndroidAutoConnectionChange(const std::function<void(bool /* connected */)>& callback) override;
     bool isAndroidAutoConnected() override;
+    bool setVolume(double volume) override;
 
   private:
     friend HybridBase;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroplayer/HybridTrackPlayerSpec.kt

@@ -129,6 +129,10 @@ abstract class HybridTrackPlayerSpec: HybridObject() {
   @DoNotStrip
   @Keep
   abstract fun isAndroidAutoConnected(): Boolean
+  
+  @DoNotStrip
+  @Keep
+  abstract fun setVolume(volume: Double): Boolean
 
   private external fun initHybrid(): HybridData
 

package/nitrogen/generated/ios/c++/HybridTrackPlayerSpecSwift.hpp

@@ -177,6 +177,14 @@ namespace margelo::nitro::nitroplayer {
       auto __value = std::move(__result.value());
       return __value;
     }
+    inline bool setVolume(double volume) override {
+      auto __result = _swiftPart.setVolume(std::forward<decltype(volume)>(volume));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+      auto __value = std::move(__result.value());
+      return __value;
+    }
 
   private:
     NitroPlayer::HybridTrackPlayerSpec_cxx _swiftPart;

package/nitrogen/generated/ios/swift/HybridTrackPlayerSpec.swift

@@ -29,6 +29,7 @@ public protocol HybridTrackPlayerSpec_protocol: HybridObject {
   func onPlaybackProgressChange(callback: @escaping (_ position: Double, _ totalDuration: Double, _ isManuallySeeked: Bool?) -> Void) throws -> Void
   func onAndroidAutoConnectionChange(callback: @escaping (_ connected: Bool) -> Void) throws -> Void
   func isAndroidAutoConnected() throws -> Bool
+  func setVolume(volume: Double) throws -> Bool
 }
 
 public extension HybridTrackPlayerSpec_protocol {

package/nitrogen/generated/ios/swift/HybridTrackPlayerSpec_cxx.swift

@@ -334,4 +334,16 @@ open class HybridTrackPlayerSpec_cxx {
       return bridge.create_Result_bool_(__exceptionPtr)
     }
   }
+  
+  @inline(__always)
+  public final func setVolume(volume: Double) -> bridge.Result_bool_ {
+    do {
+      let __result = try self.__implementation.setVolume(volume: volume)
+      let __resultCpp = __result
+      return bridge.create_Result_bool_(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_bool_(__exceptionPtr)
+    }
+  }
 }

package/nitrogen/generated/shared/c++/HybridTrackPlayerSpec.cpp

@@ -29,6 +29,7 @@ namespace margelo::nitro::nitroplayer {
       prototype.registerHybridMethod("onPlaybackProgressChange", &HybridTrackPlayerSpec::onPlaybackProgressChange);
       prototype.registerHybridMethod("onAndroidAutoConnectionChange", &HybridTrackPlayerSpec::onAndroidAutoConnectionChange);
       prototype.registerHybridMethod("isAndroidAutoConnected", &HybridTrackPlayerSpec::isAndroidAutoConnected);
+      prototype.registerHybridMethod("setVolume", &HybridTrackPlayerSpec::setVolume);
     });
   }
 

package/nitrogen/generated/shared/c++/HybridTrackPlayerSpec.hpp

@@ -82,6 +82,7 @@ namespace margelo::nitro::nitroplayer {
       virtual void onPlaybackProgressChange(const std::function<void(double /* position */, double /* totalDuration */, std::optional<bool> /* isManuallySeeked */)>& callback) = 0;
       virtual void onAndroidAutoConnectionChange(const std::function<void(bool /* connected */)>& callback) = 0;
       virtual bool isAndroidAutoConnected() = 0;
+      virtual bool setVolume(double volume) = 0;
 
     protected:
       // Hybrid Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "0.3.0-alpha.6",
+  "version": "0.3.0-alpha.7",
   "description": "react-native-nitro-player",
   "main": "lib/index",
   "module": "lib/index",
@@ -30,13 +30,14 @@
   "scripts": {
     "postinstall": "tsc || exit 0;",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf android/build node_modules/**/android/build lib nitrogen",
+    "clean": "rm -rf android/build node_modules/**/android/build lib nitrogen tsconfig.tsbuildinfo",
     "lint": "eslint \"**/*.{js,ts,tsx}\" --fix",
     "lint-ci": "eslint \"**/*.{js,ts,tsx}\" -f @jamesacarr/github-actions",
     "typescript": "tsc",
-    "specs": "tsc --noEmit false && nitrogen --logLevel=\"debug\"",
+    "specs": "tsc && nitrogen --logLevel=\"debug\"",
+    "copy-readme": "cp ../README.md README.md",
     "release": "release-it",
-    "build": "bun run clean && bun run specs && bun run typescript"
+    "build": "bun run clean && bun run specs && bun run typescript && bun run copy-readme"
   },
   "keywords": [
     "react-native",
@@ -123,6 +124,9 @@
     "github": {
       "release": true
     },
+    "hooks": {
+      "before:release": "bun run clean && bun run specs && bun run typescript && bun run copy-readme"
+    },
     "plugins": {
       "@release-it/bumper": {
         "in": "package.json",

package/src/specs/TrackPlayer.nitro.ts

@@ -81,4 +81,5 @@ export interface TrackPlayer
   ): void
   onAndroidAutoConnectionChange(callback: (connected: boolean) => void): void
   isAndroidAutoConnected(): boolean
+  setVolume(volume: number): boolean
 }