expo-native-track-player 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-02-20
+
+### Added
+- Core TrackPlayer module with constants, events, hooks, and native integration.
+- Event handling with typed payloads and event constants.
+- Playback snapshot type for persisted playback state.
+- Track metadata, resource objects, and extended track types.
+- Example app scaffold for testing core playback flows.
+
+### Changed
+- Improved ExpoNativeTrackPlayer playback state management and event emission.
+- Expanded metadata handling and resource resolution for tracks.
+- Commitlint configuration allows up to 500 characters in header.
+- `.gitignore` includes Yarn install state and common caches.
+
+### Fixed
+- Project configuration and documentation updates for initial setup.
+

package/README.md

@@ -2,15 +2,21 @@
 
 TurboModule track player for React Native New Architecture (iOS + Android).
 
+## Docs
+
+- [Full documentation](docs/README.md)
+- [Types reference](docs/types.md)
+
 ## Features
 
-- Native queue management
+- Native queue management (no JS-side queue required)
 - Repeat modes: `off`, `track`, `queue`, `loop_portion`
-- Full track metadata
-- Background playback ready (native)
-- Android foreground service + media notification
-- Audio focus handling (Android)
-- Simple async JS API
+- Full track metadata + custom fields
+- Background playback with lock-screen / notification controls
+- iOS: MPRemoteCommandCenter + Now Playing info
+- Android: MediaSession + foreground service + notification
+- Playback snapshots (native) for recovery after background/kill
+- Typed events + hooks (`useProgress`, `useQueue`, etc.)
 
 ## Installation (outside this repo)
 
@@ -78,7 +84,7 @@ Enable background audio in your app target:
 ### Android
 
 This module uses a foreground media service for reliable background playback.
-Ensure your app has these permissions:
+Ensure your app has these permissions (app manifest):
 
 ```xml
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
@@ -91,7 +97,7 @@ media notification to appear.
 
 Make sure you test background playback on a real device.
 
-## Usage
+## Quick start
 
 ```tsx
 import TrackPlayer, {
@@ -112,34 +118,11 @@ await TrackPlayer.addToQueue(track);
 await TrackPlayer.play(null);
 ```
 
-## API
+## API (summary)
 
 All time values are milliseconds unless stated otherwise.
 
-### Types
-
-```ts
-export interface TrackMetadata {
-  id: string;
-  url: string;
-  title?: string;
-  artist?: string;
-  albumName?: string;
-  artworkUri?: string;
-  trackNumber?: number;
-  composer?: string;
-  conductor?: string;
-  genre?: string;
-  compilation?: string;
-  subtitle?: string;
-  description?: string;
-  station?: string;
-  mediaType?: number;
-}
-
-export type RepeatMode = 'off' | 'track' | 'queue' | 'loop_portion';
-export type PlaybackState = 'playing' | 'paused' | 'stopped';
-```
+See [Types reference](docs/types.md) for the full list.
 
 ### Queue
 
@@ -203,6 +186,12 @@ export type PlaybackState = 'playing' | 'paused' | 'stopped';
 - Ensure device volume and notification permission are enabled.
 - Test on a real device; emulators are not reliable for audio focus/Doze.
 
+### iOS: snapshot crash on load/reset
+
+- Snapshots are saved natively and must be valid property list values.
+- If you changed native code recently, delete the app to clear old snapshots.
+- Avoid `NaN`/`Infinity` positions; use `0` when duration is unknown.
+
 ### Android: queue empty after add
 
 - The example app sets a local queue immediately and then syncs from native.

package/android/src/main/java/com/exponativetrackplayer/ExpoNativeTrackPlayerModule.kt

@@ -1,5 +1,7 @@
 package com.exponativetrackplayer
 
+import android.content.Context
+import android.content.SharedPreferences
 import android.os.Handler
 import android.os.Looper
 import androidx.media3.common.AudioAttributes
@@ -19,6 +21,7 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.WritableArray
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
+import org.json.JSONObject
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.atomic.AtomicReference
 
@@ -33,6 +36,12 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
   private var loopEndMs: Long? = null
   private var playbackState: String = "stopped"
   private var playbackRate: Float = 1f
+  private var lastSnapshotSavedAtMs: Long = 0
+  private val snapshotPrefs: SharedPreferences =
+    reactApplicationContext.getSharedPreferences(
+      "expo-native-track-player",
+      Context.MODE_PRIVATE
+    )
 
   private val eventPlaybackState = "playback-state"
   private val eventPlaybackPosition = "playback-progress-updated"
@@ -48,6 +57,8 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
     ExoPlayer.Builder(reactContext)
       .setAudioAttributes(audioAttributes, true)
       .setHandleAudioBecomingNoisy(true)
+      .setSeekForwardIncrementMs(15000)
+      .setSeekBackIncrementMs(15000)
       .build()
       .apply {
       addListener(object : Player.Listener {
@@ -251,6 +262,15 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
     return playbackRate.toDouble()
   }
 
+  override fun getLastPlaybackSnapshot(): WritableMap? {
+    val raw = snapshotPrefs.getString("snapshot", null) ?: return null
+    return try {
+      jsonToWritableMap(JSONObject(raw))
+    } catch (error: Exception) {
+      null
+    }
+  }
+
   override fun addListener(eventName: String) {
   }
 
@@ -328,6 +348,7 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
       putString("state", playbackState)
     }
     emitEvent(eventPlaybackState, payload)
+    saveSnapshotWithCurrentValues(force = true)
   }
 
   private fun emitQueueUpdated() {
@@ -363,6 +384,66 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
       putInt("trackIndex", currentIndex)
     }
     emitEvent(eventPlaybackPosition, payload)
+    saveSnapshotIfNeeded(
+      positionMs = player.currentPosition,
+      durationMs = if (duration > 0) duration else 0,
+      trackIndex = currentIndex,
+      force = false
+    )
+  }
+
+  private fun saveSnapshotWithCurrentValues(force: Boolean) {
+    val duration = player.duration
+    saveSnapshotIfNeeded(
+      positionMs = player.currentPosition,
+      durationMs = if (duration > 0) duration else 0,
+      trackIndex = currentIndex,
+      force = force
+    )
+  }
+
+  private fun saveSnapshotIfNeeded(
+    positionMs: Long,
+    durationMs: Long,
+    trackIndex: Int,
+    force: Boolean
+  ) {
+    val now = System.currentTimeMillis()
+    if (!force && now - lastSnapshotSavedAtMs < 1000) return
+    lastSnapshotSavedAtMs = now
+    val trackId = queue.getOrNull(trackIndex)?.get("id") as? String
+    val snapshot = JSONObject().apply {
+      put("state", playbackState)
+      put("position", positionMs.toDouble())
+      put("duration", durationMs.toDouble())
+      put("trackIndex", trackIndex)
+      if (trackId != null) put("trackId", trackId) else put("trackId", JSONObject.NULL)
+      put("rate", playbackRate.toDouble())
+      put("volume", player.volume.toDouble())
+      put("repeatMode", repeatMode)
+      put("savedAt", now.toDouble())
+    }
+    snapshotPrefs.edit().putString("snapshot", snapshot.toString()).apply()
+  }
+
+  private fun jsonToWritableMap(json: JSONObject): WritableMap {
+    val map = Arguments.createMap()
+    val keys = json.keys()
+    while (keys.hasNext()) {
+      val key = keys.next()
+      val value = json.get(key)
+      when (value) {
+        JSONObject.NULL -> map.putNull(key)
+        is String -> map.putString(key, value)
+        is Int -> map.putInt(key, value)
+        is Long -> map.putDouble(key, value.toDouble())
+        is Double -> map.putDouble(key, value)
+        is Float -> map.putDouble(key, value.toDouble())
+        is Boolean -> map.putBoolean(key, value)
+        else -> map.putString(key, value.toString())
+      }
+    }
+    return map
   }
 
   private fun emitPlaybackQueueEnded() {
@@ -421,6 +502,7 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
     val title = track["title"] as? String
     val artist = track["artist"] as? String
     val albumName = track["albumName"] as? String
+    val artworkUri = track["artworkUri"] as? String
     return MediaItem.Builder()
       .setMediaId(id)
       .setUri(url)
@@ -429,6 +511,7 @@ class ExpoNativeTrackPlayerModule(reactContext: ReactApplicationContext) :
           .setTitle(title)
           .setArtist(artist)
           .setAlbumTitle(albumName)
+          .setArtworkUri(if (artworkUri != null) android.net.Uri.parse(artworkUri) else null)
           .build()
       )
       .build()

package/android/src/main/java/com/exponativetrackplayer/ExpoNativeTrackPlayerService.kt

@@ -98,7 +98,7 @@ class ExpoNativeTrackPlayerService : MediaSessionService() {
             }
           })
           .build()
-          .apply { setPlayer(player) }
+          .also { manager -> manager.setPlayer(player) }
       } else {
         notificationManager?.setPlayer(player)
       }

package/ios/ExpoNativeTrackPlayer.mm

@@ -1,5 +1,6 @@
 #import "ExpoNativeTrackPlayer.h"
 #import <AVFoundation/AVFoundation.h>
+#import <MediaPlayer/MediaPlayer.h>
 #import <React/RCTBridge.h>
 
 @interface ExpoNativeTrackPlayer ()
@@ -14,6 +15,7 @@
 @property (nonatomic, assign) float playbackRate;
 @property (nonatomic, strong, nullable) id timeObserver;
 @property (nonatomic, strong, nullable) id endObserver;
+@property (nonatomic, assign) double lastSnapshotSavedAtMs;
 
 @end
 
@@ -29,6 +31,8 @@ static NSString *const ExpoNativeTrackPlayerEventPlaybackActiveTrackChanged =
 static NSString *const ExpoNativeTrackPlayerEventPlaybackQueueEnded =
   @"playback-queue-ended";
 static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated";
+static NSString *const ExpoNativeTrackPlayerSnapshotKey =
+  @"expo-native-track-player.snapshot";
 
 - (instancetype)init
 {
@@ -40,6 +44,7 @@ static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated"
     _playbackState = @"stopped";
     _playbackRate = 1.0f;
     [self configureAudioSession];
+    [self setupRemoteCommands];
     [self startLoopWatcher];
   }
   return self;
@@ -117,6 +122,7 @@ static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated"
   [self emitEvent:ExpoNativeTrackPlayerEventPlaybackState body:@{
     @"state": self.playbackState ?: @"stopped"
   }];
+  [self updateNowPlayingInfo];
 }
 
 - (void)emitQueueUpdated
@@ -140,6 +146,7 @@ static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated"
     @"track": track ?: (id)kCFNull
   };
   [self emitEvent:ExpoNativeTrackPlayerEventPlaybackActiveTrackChanged body:payload];
+  [self updateNowPlayingInfo];
 }
 
 - (void)emitPlaybackPositionWithPosition:(double)position
@@ -152,6 +159,8 @@ static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated"
     @"trackIndex": @(trackIndex)
   };
   [self emitEvent:ExpoNativeTrackPlayerEventPlaybackProgress body:payload];
+  [self updateNowPlayingInfoWithPosition:position duration:duration];
+  [self saveSnapshotIfNeededWithPosition:position duration:duration trackIndex:trackIndex force:NO];
 }
 
 - (void)emitPlaybackQueueEnded
@@ -456,6 +465,94 @@ static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated"
   NSString *nextState = state ?: @"stopped";
   _playbackState = [nextState copy];
   [self emitPlaybackState];
+  [self saveSnapshotWithCurrentValuesForce:YES];
+}
+
+- (NSDictionary *)currentSnapshotWithPosition:(double)position
+                                      duration:(double)duration
+                                     trackIndex:(NSInteger)trackIndex
+{
+  NSString *trackId = nil;
+  if (trackIndex >= 0 && trackIndex < (NSInteger)self.queue.count) {
+    NSDictionary *track = self.queue[(NSUInteger)trackIndex];
+    if ([track[@"id"] isKindOfClass:[NSString class]]) {
+      trackId = track[@"id"];
+    }
+  }
+  double savedAt = [[NSDate date] timeIntervalSince1970] * 1000.0;
+  double safePosition = isfinite(position) ? position : 0.0;
+  double safeDuration = isfinite(duration) ? duration : 0.0;
+  NSMutableDictionary *snapshot = [@{
+    @"state": self.playbackState ?: @"stopped",
+    @"position": @(safePosition),
+    @"duration": @(safeDuration),
+    @"trackIndex": @(trackIndex),
+    @"rate": @(self.playbackRate),
+    @"volume": @(self.player.volume),
+    @"repeatMode": self.repeatMode ?: @"off",
+    @"savedAt": @(savedAt)
+  } mutableCopy];
+  if (trackId != nil) {
+    snapshot[@"trackId"] = trackId;
+  }
+  return snapshot;
+}
+
+- (void)saveSnapshotIfNeededWithPosition:(double)position
+                                duration:(double)duration
+                               trackIndex:(NSInteger)trackIndex
+                                   force:(BOOL)force
+{
+  if (trackIndex < 0) {
+    [[NSUserDefaults standardUserDefaults] removeObjectForKey:ExpoNativeTrackPlayerSnapshotKey];
+    return;
+  }
+  if (!isfinite(position) || !isfinite(duration)) {
+    return;
+  }
+  double nowMs = [[NSDate date] timeIntervalSince1970] * 1000.0;
+  if (!force && nowMs - self.lastSnapshotSavedAtMs < 1000.0) return;
+  self.lastSnapshotSavedAtMs = nowMs;
+  NSDictionary *snapshot =
+    [self currentSnapshotWithPosition:position duration:duration trackIndex:trackIndex];
+  if (![NSPropertyListSerialization propertyList:snapshot
+                                        isValidForFormat:NSPropertyListBinaryFormat_v1_0]) {
+    return;
+  }
+  [[NSUserDefaults standardUserDefaults] setObject:snapshot
+                                            forKey:ExpoNativeTrackPlayerSnapshotKey];
+}
+
+- (void)saveSnapshotWithCurrentValuesForce:(BOOL)force
+{
+  if (self.currentIndex < 0) {
+    [[NSUserDefaults standardUserDefaults] removeObjectForKey:ExpoNativeTrackPlayerSnapshotKey];
+    return;
+  }
+  double position = CMTimeGetSeconds([self.player currentTime]) * 1000.0;
+  if (!isfinite(position)) {
+    position = 0.0;
+  }
+  double duration = 0.0;
+  AVPlayerItem *item = self.player.currentItem;
+  if (item != nil) {
+    duration = CMTimeGetSeconds(item.duration) * 1000.0;
+    if (!isfinite(duration)) {
+      duration = 0.0;
+    }
+  }
+  [self saveSnapshotIfNeededWithPosition:position
+                                duration:duration
+                               trackIndex:self.currentIndex
+                                   force:force];
+}
+
+- (NSDictionary * _Nullable)getLastPlaybackSnapshot
+{
+  NSDictionary *snapshot =
+    [[NSUserDefaults standardUserDefaults] objectForKey:ExpoNativeTrackPlayerSnapshotKey];
+  if (![snapshot isKindOfClass:[NSDictionary class]]) return nil;
+  return snapshot;
 }
 
 - (void)configureAudioSession
@@ -466,6 +563,128 @@ static NSString *const ExpoNativeTrackPlayerEventQueueUpdated = @"queue-updated"
   [session setActive:YES error:&error];
 }
 
+- (void)setupRemoteCommands
+{
+  MPRemoteCommandCenter *commandCenter = [MPRemoteCommandCenter sharedCommandCenter];
+  commandCenter.playCommand.enabled = YES;
+  commandCenter.pauseCommand.enabled = YES;
+  commandCenter.nextTrackCommand.enabled = YES;
+  commandCenter.previousTrackCommand.enabled = YES;
+  commandCenter.changePlaybackPositionCommand.enabled = YES;
+  commandCenter.skipForwardCommand.enabled = YES;
+  commandCenter.skipBackwardCommand.enabled = YES;
+  commandCenter.skipForwardCommand.preferredIntervals = @[@(15)];
+  commandCenter.skipBackwardCommand.preferredIntervals = @[@(15)];
+
+  __weak ExpoNativeTrackPlayer *weakSelf = self;
+  [commandCenter.playCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    [weakSelf playInternal:nil];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+  [commandCenter.pauseCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    [weakSelf pause];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+  [commandCenter.nextTrackCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    [weakSelf skipToNext];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+  [commandCenter.previousTrackCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    [weakSelf skipToPrevious];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+  [commandCenter.changePlaybackPositionCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    if (![event isKindOfClass:[MPChangePlaybackPositionCommandEvent class]]) {
+      return MPRemoteCommandHandlerStatusCommandFailed;
+    }
+    MPChangePlaybackPositionCommandEvent *seekEvent = (MPChangePlaybackPositionCommandEvent *)event;
+    double positionMs = seekEvent.positionTime * 1000.0;
+    [weakSelf seekTo:positionMs];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+  [commandCenter.skipForwardCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    double position = CMTimeGetSeconds([weakSelf.player currentTime]) * 1000.0;
+    [weakSelf seekTo:(position + 15000.0)];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+  [commandCenter.skipBackwardCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent *event) {
+    double position = CMTimeGetSeconds([weakSelf.player currentTime]) * 1000.0;
+    [weakSelf seekTo:MAX(0.0, position - 15000.0)];
+    return MPRemoteCommandHandlerStatusSuccess;
+  }];
+}
+
+- (void)updateNowPlayingInfo
+{
+  NSDictionary *track = nil;
+  if (self.currentIndex >= 0 && self.currentIndex < (NSInteger)self.queue.count) {
+    track = self.queue[(NSUInteger)self.currentIndex];
+  }
+  NSMutableDictionary *info = [NSMutableDictionary dictionary];
+  if (track[@"title"]) info[MPMediaItemPropertyTitle] = track[@"title"];
+  if (track[@"artist"]) info[MPMediaItemPropertyArtist] = track[@"artist"];
+  if (track[@"albumName"]) info[MPMediaItemPropertyAlbumTitle] = track[@"albumName"];
+  if (track[@"artworkUri"] && [track[@"artworkUri"] isKindOfClass:[NSString class]]) {
+    NSString *artworkUri = track[@"artworkUri"];
+    NSURL *url = [NSURL URLWithString:artworkUri];
+    if (url != nil) {
+      dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+        NSData *data = [NSData dataWithContentsOfURL:url];
+        UIImage *image = data != nil ? [UIImage imageWithData:data] : nil;
+        if (image != nil) {
+          MPMediaItemArtwork *artwork =
+            [[MPMediaItemArtwork alloc] initWithBoundsSize:image.size
+                                             requestHandler:^UIImage * _Nonnull(CGSize size) {
+            return image;
+          }];
+          dispatch_async(dispatch_get_main_queue(), ^{
+            NSMutableDictionary *updated = [info mutableCopy];
+            updated[MPMediaItemPropertyArtwork] = artwork;
+            [MPNowPlayingInfoCenter defaultCenter].nowPlayingInfo = updated;
+          });
+        }
+      });
+    }
+  }
+  double position = CMTimeGetSeconds([self.player currentTime]);
+  double duration = 0.0;
+  AVPlayerItem *item = self.player.currentItem;
+  if (item != nil) {
+    duration = CMTimeGetSeconds(item.duration);
+    if (!isfinite(duration)) {
+      duration = 0.0;
+    }
+  }
+  if (isfinite(position)) {
+    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = @(position);
+  }
+  info[MPMediaItemPropertyPlaybackDuration] = @(duration);
+  info[MPNowPlayingInfoPropertyPlaybackRate] =
+    [self.playbackState isEqualToString:@"playing"] ? @(self.playbackRate) : @(0);
+  [MPNowPlayingInfoCenter defaultCenter].nowPlayingInfo = info;
+}
+
+- (void)updateNowPlayingInfoWithPosition:(double)positionMs duration:(double)durationMs
+{
+  NSMutableDictionary *info =
+    [[MPNowPlayingInfoCenter defaultCenter].nowPlayingInfo mutableCopy];
+  if (info == nil) {
+    [self updateNowPlayingInfo];
+    return;
+  }
+  double position = positionMs / 1000.0;
+  double duration = durationMs / 1000.0;
+  if (isfinite(position)) {
+    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = @(position);
+  }
+  if (isfinite(duration)) {
+    info[MPMediaItemPropertyPlaybackDuration] = @(duration);
+  }
+  info[MPNowPlayingInfoPropertyPlaybackRate] =
+    [self.playbackState isEqualToString:@"playing"] ? @(self.playbackRate) : @(0);
+  [MPNowPlayingInfoCenter defaultCenter].nowPlayingInfo = info;
+}
+
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
     (const facebook::react::ObjCTurboModule::InitParams &)params
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-native-track-player",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TurboModule track player (New Architecture)",
   "main": "./lib/module/index.js",
   "react-native": "./src/index.tsx",
@@ -57,7 +57,7 @@
   "bugs": {
     "url": "/issues"
   },
-  "homepage": "#readme",
+  "homepage": "https://github.com/StanSarr/expo-native-track-player#readme",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -66,8 +66,8 @@
     "@eslint/compat": "^1.3.2",
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.35.0",
-    "@react-native/babel-preset": "0.83.0",
-    "@react-native/eslint-config": "0.83.0",
+    "@react-native/babel-preset": "0.83.1",
+    "@react-native/eslint-config": "0.83.1",
     "@release-it/conventional-changelog": "^10.0.1",
     "@types/jest": "^29.5.14",
     "@types/react": "^19.2.0",
@@ -80,7 +80,7 @@
     "lefthook": "^2.0.3",
     "prettier": "^2.8.8",
     "react": "19.2.0",
-    "react-native": "0.83.0",
+    "react-native": "0.83.1",
     "react-native-builder-bob": "^0.40.17",
     "release-it": "^19.0.4",
     "turbo": "^2.5.6",
@@ -134,7 +134,14 @@
   "commitlint": {
     "extends": [
       "@commitlint/config-conventional"
-    ]
+    ],
+    "rules": {
+      "header-max-length": [
+        2,
+        "always",
+        500
+      ]
+    }
   },
   "release-it": {
     "git": {

package/src/NativeExpoNativeTrackPlayer.ts

@@ -34,6 +34,18 @@ export type State =
   | 'error'
   | 'ended';
 export type PlaybackState = State;
+
+export interface PlaybackSnapshot {
+  state: State;
+  position: number;
+  duration: number;
+  trackIndex: number;
+  trackId?: string;
+  rate: number;
+  volume: number;
+  repeatMode: RepeatMode;
+  savedAt: number;
+}
 export interface Spec extends TurboModule {
   addToQueue(track: TrackMetadata): void;
   addQueue(tracks: Array<TrackMetadata>): void;
@@ -63,6 +75,7 @@ export interface Spec extends TurboModule {
   getVolume(): number;
   setRate(rate: number): void;
   getRate(): number;
+  getLastPlaybackSnapshot(): PlaybackSnapshot | null;
   addListener(eventName: string): void;
   removeListeners(count: number): void;
 }

package/src/hooks.ts

@@ -51,7 +51,7 @@ export function useProgress(intervalMs: number = 1000): PlaybackProgress {
         const duration = ExpoNativeTrackPlayer.getDuration();
         const trackIndex = ExpoNativeTrackPlayer.getCurrentTrackIndex();
         setProgress({ position, duration, trackIndex });
-      } catch (error) {
+      } catch {
         setProgress({ position: 0, duration: 0, trackIndex: -1 });
       }
     };
@@ -76,7 +76,7 @@ export function useQueue(): TrackMetadata[] {
     try {
       const result = ExpoNativeTrackPlayer.getQueue();
       if (isActive) setQueue(result);
-    } catch (error) {
+    } catch {
       if (isActive) setQueue([]);
     }
 
@@ -103,7 +103,7 @@ export function useCurrentTrack(): TrackMetadata | null {
     try {
       const result = ExpoNativeTrackPlayer.getCurrentTrack();
       if (isActive) setTrack(result);
-    } catch (error) {
+    } catch {
       if (isActive) setTrack(null);
     }
 
@@ -130,7 +130,7 @@ export function useCurrentTrackIndex(): number {
     try {
       const result = ExpoNativeTrackPlayer.getCurrentTrackIndex();
       if (isActive) setIndex(result);
-    } catch (error) {
+    } catch {
       if (isActive) setIndex(-1);
     }
 

package/src/index.tsx

@@ -21,6 +21,7 @@ import {
   useQueue,
 } from './hooks';
 import type { AddTrack, Track } from './types/Track';
+import type { PlaybackSnapshot } from './types/PlaybackSnapshot';
 import type { ResourceObject } from './types/ResourceObject';
 import type { TrackMetadataBase } from './types/TrackMetadataBase';
 import { PitchAlgorithms, TrackTypes } from './constants';
@@ -188,6 +189,10 @@ export function getRate(): Promise<number> {
   return callValue(() => ExpoNativeTrackPlayer.getRate());
 }
 
+export function getLastPlaybackSnapshot(): Promise<PlaybackSnapshot | null> {
+  return callValue(() => ExpoNativeTrackPlayer.getLastPlaybackSnapshot());
+}
+
 const TrackPlayer = {
   addToQueue,
   addQueue,
@@ -213,6 +218,7 @@ const TrackPlayer = {
   getVolume,
   setRate,
   getRate,
+  getLastPlaybackSnapshot,
 };
 
 export default TrackPlayer;
@@ -229,6 +235,7 @@ export type {
   PitchAlgorithm,
   RepeatModeType,
   StateType,
+  PlaybackSnapshot,
 };
 export {
   AudioEvents,

package/src/types/PlaybackSnapshot.ts

@@ -0,0 +1,13 @@
+import type { RepeatMode, State } from '../NativeExpoNativeTrackPlayer';
+
+export interface PlaybackSnapshot {
+  state: State;
+  position: number;
+  duration: number;
+  trackIndex: number;
+  trackId?: string;
+  rate: number;
+  volume: number;
+  repeatMode: RepeatMode;
+  savedAt: number;
+}