react-native-queue-player 1.1.1 → 1.1.2

package/ios/GaplessEngine.swift

@@ -277,11 +277,17 @@ final class GaplessEngine: PlaybackEngine {
     reapplyPitchAlgorithm()
   }
 
-  func setRepeatMode(_: RepeatMode) {
-    // AVQueuePlayer doesn't have a native repeat mode equivalent
-    // to ExoPlayer; TrackPlayer's QueueSkipArithmetic handles the
-    // repeat semantics by rebuilding the queue at the appropriate
-    // moment. No work to do at the engine layer.
+  func setRepeatMode(_ mode: RepeatMode) {
+    // AVQueuePlayer has no native repeat mode. Under repeat-one, hold the
+    // finished item at its end (`actionAtItemEnd = .none`) so the player
+    // does not auto-advance — `TrackPlayer.handlePlayerItemDidPlayToEndTime`
+    // then deterministically rewinds it to zero and replays it. `.off` /
+    // `.queue` advance + wrap are driven by TrackPlayer's queue rebuild, so
+    // they keep `.advance`. Switching mode only affects future end-of-item
+    // behaviour; an item already parked at its end (repeat-one + the
+    // end-of-track sleep-timer pause) is not retroactively advanced — a
+    // resume or skip recovers it.
+    player.actionAtItemEnd = (mode == .track) ? .none : .advance
   }
 
   func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {

package/ios/Tests/GaplessEngineLifecycleTests.swift

@@ -30,6 +30,32 @@ final class GaplessEngineLifecycleTests: XCTestCase {
     XCTAssertNil(engine.delegate)
   }
 
+  // MARK: - Repeat mode
+
+  /// Repeat-one holds the current item at its end
+  /// (`actionAtItemEnd = .none`) so `TrackPlayer`'s end-of-track handler
+  /// can deterministically rewind + replay it; off / queue keep the
+  /// default `.advance`. Without the hold, the AVQueuePlayer advances
+  /// into the next enqueued item before the async rewind runs, so the
+  /// track skips forward instead of repeating.
+  func testRepeatTrackHoldsItemAtEndWhileOthersAdvance() {
+    let engine = GaplessEngine()
+    XCTAssertEqual(engine.player.actionAtItemEnd, .advance)
+
+    engine.setRepeatMode(.track)
+    XCTAssertEqual(engine.player.actionAtItemEnd, .none)
+
+    engine.setRepeatMode(.queue)
+    XCTAssertEqual(engine.player.actionAtItemEnd, .advance)
+
+    engine.setRepeatMode(.off)
+    XCTAssertEqual(engine.player.actionAtItemEnd, .advance)
+
+    // Re-entering repeat-one re-applies the hold.
+    engine.setRepeatMode(.track)
+    XCTAssertEqual(engine.player.actionAtItemEnd, .none)
+  }
+
   // MARK: - Queue-mutation surface
 
   /// `setItems` installs the slice from `startIndex` onward; items

package/ios/TrackPlayer.swift

@@ -3952,10 +3952,12 @@ class TrackPlayer: HybridTrackPlayerSpec {
   ///   pre-wrote.
   ///
   /// Repeat-track handling: when `repeatModeState == .track`, seek
-  /// the just-finished item back to zero + replay. The notification
-  /// fires BEFORE AVQueuePlayer auto-advances (per Apple docs), so
-  /// we get the chance to rewind without flashing through the next
-  /// item. We do NOT set `didPlayToEndPending` in this branch —
+  /// the just-finished item back to zero + replay. The gapless engine
+  /// holds the item at its end (`AVQueuePlayer.actionAtItemEnd = .none`
+  /// under `.track`, set in `GaplessEngine.setRepeatMode`), so the
+  /// player does not advance and `player.currentItem` is still the
+  /// finished item when this async block runs — the rewind is
+  /// deterministic. We do NOT set `didPlayToEndPending` in this branch —
   /// the seek-to-zero produces no `\.currentItem` change, so there
   /// is no auto-advance to gate.
   @objc private func handlePlayerItemDidPlayToEndTime(_ notification: Notification) {
@@ -3968,30 +3970,21 @@ class TrackPlayer: HybridTrackPlayerSpec {
       let sleepFired = self.sleepTimerCore.fireAtTrackEnd()
       if sleepFired.pauseNow { self.applySleepTimerResult(sleepFired) }
       // Branch on repeat-track FIRST, separately from the
-      // currentItem === item check. The notification dispatches
-      // async to main but AVQueuePlayer
-      // runs `actionAtItemEnd = .advance` synchronously on its own
-      // queue — under load, the player can have already advanced
-      // by the time our async block runs. Falling through to the
-      // auto-advance branch in repeat-track mode would incorrectly
-      // arm `didPlayToEndPending`; the resync would then run on
-      // the unintended-advance currentItem and clobber the user's
-      // expected repeat-track stay-on-current.
+      // currentItem === item check, and never arm `didPlayToEndPending`
+      // here — in repeat-track mode there is no auto-advance to gate.
       if self.repeatModeState == .track {
-        // Repeat-track: rewind the just-finished item + replay.
-        // Apple's docs note the notification fires BEFORE
-        // actionAtItemEnd is honoured, so the seek-to-zero +
-        // play normally beats the auto-advance.
+        // Repeat-track: rewind the just-finished item + replay. The
+        // gapless engine holds the item via `actionAtItemEnd = .none`
+        // under `.track`, so the player does not advance and
+        // `currentItem` is still the finished item here.
         if let player = self.player {
           // Repeat-one loop = a new milestone playthrough of the same track.
           // The gapless engine fires no track-change / delegate here, so
           // dispatchTrackChange's reset is skipped — reset directly, and
-          // UNCONDITIONALLY for the gapless engine (self.player non-nil), not
-          // only when the rewind race below is won: under load this async block
-          // can run AFTER AVQueuePlayer already chain-advanced, in which case
-          // the seek is skipped but the track still loops, so milestones must
-          // re-arm regardless. (CrossfadeEngine has self.player == nil here and
-          // resets via engineDidPlayItemToEnd instead — no double reset.)
+          // UNCONDITIONALLY for the gapless engine (self.player non-nil), so
+          // milestones re-arm for the new playthrough. (CrossfadeEngine has
+          // self.player == nil here and resets via engineDidPlayItemToEnd
+          // instead — no double reset.)
           self.milestoneTracker.reset()
           if let item = notification.object as? AVPlayerItem,
              player.currentItem === item {
@@ -4003,15 +3996,13 @@ class TrackPlayer: HybridTrackPlayerSpec {
             if !sleepFired.pauseNow { self.engine?.play() }
           }
         }
-        // If the rewind window was lost (player chain-advanced
-        // before our async block ran), accept that the
-        // KVO fire will re-sync currentTrackIndex via the next
-        // currentItem change — but DO NOT arm `didPlayToEndPending`
-        // here, because in repeat-track mode the auto-advance
-        // shouldn't have happened. The resync via KVO without
-        // didPlayToEndPending stays correct because user
-        // mutations pre-write the index; nothing overwrites the
-        // shadow index incorrectly.
+        // Defense in depth: if `currentItem` is somehow not the finished
+        // item (e.g. a mode change raced this fire before `.none` was
+        // applied), skip the rewind and let the `\.currentItem` KVO
+        // re-sync `currentTrackIndex` — WITHOUT arming
+        // `didPlayToEndPending`, since repeat-track should not advance.
+        // User mutations pre-write the index, so the shadow index stays
+        // correct.
         return
       }
       // Repeat-off / repeat-queue: arm the resync gate so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-queue-player",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Nitro Modules audio playback library for React Native — gapless, EQ, crossfade, automotive, voice, casting",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/index.d.ts",