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

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/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { useOnChangeTrack } from './useOnChangeTrack';
+export { useOnPlaybackStateChange } from './useOnPlaybackStateChange';
+export { useOnSeek } from './useOnSeek';
+export { useOnPlaybackProgressChange } from './useOnPlaybackProgressChange';
+export { useAndroidAutoConnection } from './useAndroidAutoConnection';
+export { useAudioDevices } from './useAudioDevices';

package/lib/hooks/index.js

@@ -0,0 +1,6 @@
+export { useOnChangeTrack } from './useOnChangeTrack';
+export { useOnPlaybackStateChange } from './useOnPlaybackStateChange';
+export { useOnSeek } from './useOnSeek';
+export { useOnPlaybackProgressChange } from './useOnPlaybackProgressChange';
+export { useAndroidAutoConnection } from './useAndroidAutoConnection';
+export { useAudioDevices } from './useAudioDevices';

package/lib/hooks/useAndroidAutoConnection.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hook to detect Android Auto connection status using the official Android for Cars API
+ * Based on: https://developer.android.com/training/cars/apps#car-connection
+ *
+ * @returns Object with isConnected boolean
+ *
+ * @example
+ * const { isConnected } = useAndroidAutoConnection();
+ * console.log('Android Auto connected:', isConnected);
+ */
+export declare function useAndroidAutoConnection(): {
+    isConnected: boolean;
+};

package/lib/hooks/useAndroidAutoConnection.js

@@ -0,0 +1,26 @@
+import { useEffect, useState } from 'react';
+import { TrackPlayer } from '../index';
+/**
+ * Hook to detect Android Auto connection status using the official Android for Cars API
+ * Based on: https://developer.android.com/training/cars/apps#car-connection
+ *
+ * @returns Object with isConnected boolean
+ *
+ * @example
+ * const { isConnected } = useAndroidAutoConnection();
+ * console.log('Android Auto connected:', isConnected);
+ */
+export function useAndroidAutoConnection() {
+    const [isConnected, setIsConnected] = useState(false);
+    useEffect(() => {
+        // Set initial state
+        const initialState = TrackPlayer.isAndroidAutoConnected();
+        setIsConnected(initialState);
+        // Listen for connection changes
+        TrackPlayer.onAndroidAutoConnectionChange((connected) => {
+            setIsConnected(connected);
+            console.log('🚗 Android Auto connection changed:', connected);
+        });
+    }, []);
+    return { isConnected };
+}

package/lib/hooks/useAudioDevices.d.ts

@@ -0,0 +1,26 @@
+import type { TAudioDevice } from '../specs/AudioDevices.nitro';
+/**
+ * Hook to get audio devices (Android only)
+ *
+ * Polls for device changes every 2 seconds
+ *
+ * @returns Object containing the current list of audio devices
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { devices } = useAudioDevices()
+ *
+ *   return (
+ *     <View>
+ *       {devices.map(device => (
+ *         <Text key={device.id}>{device.name}</Text>
+ *       ))}
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+export declare function useAudioDevices(): {
+    devices: TAudioDevice[];
+};

package/lib/hooks/useAudioDevices.js

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react';
+import { Platform } from 'react-native';
+import { NitroModules } from 'react-native-nitro-modules';
+/**
+ * Hook to get audio devices (Android only)
+ *
+ * Polls for device changes every 2 seconds
+ *
+ * @returns Object containing the current list of audio devices
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { devices } = useAudioDevices()
+ *
+ *   return (
+ *     <View>
+ *       {devices.map(device => (
+ *         <Text key={device.id}>{device.name}</Text>
+ *       ))}
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+export function useAudioDevices() {
+    const [devices, setDevices] = useState([]);
+    useEffect(() => {
+        if (Platform.OS !== 'android') {
+            return undefined;
+        }
+        try {
+            const AudioDevices = NitroModules.createHybridObject('AudioDevices');
+            // Get initial devices
+            const updateDevices = () => {
+                try {
+                    const currentDevices = AudioDevices.getAudioDevices();
+                    setDevices(currentDevices);
+                }
+                catch (error) {
+                    console.error('Error getting audio devices:', error);
+                }
+            };
+            updateDevices();
+            // Poll for changes every 2 seconds
+            const interval = setInterval(updateDevices, 2000);
+            return () => clearInterval(interval);
+        }
+        catch (error) {
+            console.error('Error setting up audio devices polling:', error);
+            return undefined;
+        }
+    }, []);
+    return { devices };
+}

package/lib/hooks/useOnChangeTrack.d.ts

@@ -0,0 +1,9 @@
+import type { TrackItem, Reason } from '../types/PlayerQueue';
+/**
+ * Hook to get the current track and track change reason
+ * @returns Object with current track and reason, or undefined if no track is playing
+ */
+export declare function useOnChangeTrack(): {
+    track: TrackItem | undefined;
+    reason: Reason | undefined;
+};

package/lib/hooks/useOnChangeTrack.js

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+import { TrackPlayer } from '../index';
+/**
+ * Hook to get the current track and track change reason
+ * @returns Object with current track and reason, or undefined if no track is playing
+ */
+export function useOnChangeTrack() {
+    const [track, setTrack] = useState(undefined);
+    const [reason, setReason] = useState(undefined);
+    useEffect(() => {
+        TrackPlayer.onChangeTrack((newTrack, newReason) => {
+            setTrack(newTrack);
+            setReason(newReason);
+        });
+    }, []);
+    return { track, reason };
+}

package/lib/hooks/useOnPlaybackProgressChange.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hook to get the current playback progress
+ * @returns Object with current position, total duration, and manual seek indicator
+ */
+export declare function useOnPlaybackProgressChange(): {
+    position: number;
+    totalDuration: number;
+    isManuallySeeked: boolean | undefined;
+};

package/lib/hooks/useOnPlaybackProgressChange.js

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+import { TrackPlayer } from '../index';
+/**
+ * Hook to get the current playback progress
+ * @returns Object with current position, total duration, and manual seek indicator
+ */
+export function useOnPlaybackProgressChange() {
+    const [position, setPosition] = useState(0);
+    const [totalDuration, setTotalDuration] = useState(0);
+    const [isManuallySeeked, setIsManuallySeeked] = useState(undefined);
+    useEffect(() => {
+        TrackPlayer.onPlaybackProgressChange((newPosition, newTotalDuration, newIsManuallySeeked) => {
+            setPosition(newPosition);
+            setTotalDuration(newTotalDuration);
+            setIsManuallySeeked(newIsManuallySeeked);
+        });
+    }, []);
+    return { position, totalDuration, isManuallySeeked };
+}

package/lib/hooks/useOnPlaybackStateChange.d.ts

@@ -0,0 +1,9 @@
+import type { TrackPlayerState, Reason } from '../types/PlayerQueue';
+/**
+ * Hook to get the current playback state and reason
+ * @returns Object with current playback state and reason
+ */
+export declare function useOnPlaybackStateChange(): {
+    state: TrackPlayerState | undefined;
+    reason: Reason | undefined;
+};

package/lib/hooks/useOnPlaybackStateChange.js

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+import { TrackPlayer } from '../index';
+/**
+ * Hook to get the current playback state and reason
+ * @returns Object with current playback state and reason
+ */
+export function useOnPlaybackStateChange() {
+    const [state, setState] = useState(undefined);
+    const [reason, setReason] = useState(undefined);
+    useEffect(() => {
+        TrackPlayer.onPlaybackStateChange((newState, newReason) => {
+            setState(newState);
+            setReason(newReason);
+        });
+    }, []);
+    return { state, reason };
+}

package/lib/hooks/useOnSeek.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hook to get the last seek event information
+ * @returns Object with last seek position and total duration, or undefined if no seek has occurred
+ */
+export declare function useOnSeek(): {
+    position: number | undefined;
+    totalDuration: number | undefined;
+};