react-native-queue-player 1.0.2 → 1.0.4

package/android/src/main/cpp/CMakeLists.txt

@@ -36,6 +36,13 @@ target_include_directories(alac PUBLIC
     ${THIRD_PARTY}/alac/codec
     ${THIRD_PARTY}/alac/addons
 )
+# Apple's vendored ALAC reference codec carries benign unused-variable noise we
+# don't patch upstream; silence just those two categories for this third-party
+# target so a consumer's release build stays quiet. Our own code keeps -Wall.
+target_compile_options(alac PRIVATE
+    -Wno-unused-const-variable
+    -Wno-unused-but-set-variable
+)
 
 # --- Curve25519 / Ed25519 (retained for libraop / AP1 only) ---
 add_library(curve25519 STATIC
@@ -70,6 +77,10 @@ add_library(pair_ap STATIC
 )
 target_compile_definitions(pair_ap PRIVATE
     CONFIG_OPENSSL=1
+    # pair.c uses OpenSSL's legacy SHA*_Final API, deprecated in OpenSSL 3.0.
+    # OPENSSL_SUPPRESS_DEPRECATED is OpenSSL's own opt-in for intentional
+    # legacy-API use; the raop + airplay2 targets already set it.
+    OPENSSL_SUPPRESS_DEPRECATED
 )
 target_include_directories(pair_ap PUBLIC
     ${PAIR_AP_DIR}

package/android/src/main/cpp/airplay_jni.cpp

@@ -67,14 +67,17 @@ struct JniSession {
 
     // -- Drain thread --
     pthread_t thread;
-    bool      drain_running;
+    // Stop flag: set on the JNI/control thread, polled in the drain thread's
+    // loop. Atomic so the stop is a data-race-free, promptly-visible read
+    // (the ring buffer has its own mutex; this only gates the loop).
+    std::atomic<bool> drain_running{false};
 
     // -- Tracking --
     std::atomic<int64_t> bytes_sent{0};    // total PCM bytes sent to RAOP
     std::atomic<int64_t> chunks_sent{0};   // total chunks sent
 
     JniSession() : raop(nullptr), write_pos(0), read_pos(0),
-                   drain_running(false), thread{} {
+                   thread{} {
         memset(ring, 0, sizeof(ring));
         pthread_mutex_init(&mutex, nullptr);
     }

package/android/src/main/java/com/margelo/nitro/queueplayer/BufferStateTranslator.kt

@@ -9,7 +9,7 @@ import androidx.media3.common.Player
  *
  * Extracted from [TrackPlayer.computeBufferState] so the discriminator
  * between an initial `BUFFERING` load and a mid-playback `STALLED`
- * rebuffer is unit-testable without a live ExoPlayer, matching the
+ * rebuffer stands alone without a live ExoPlayer, matching the
  * [TransportStateTranslator] pattern.
  */
 internal object BufferStateTranslator {

package/android/src/main/java/com/margelo/nitro/queueplayer/CarConnectionState.kt

@@ -0,0 +1,46 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.annotation.VisibleForTesting
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Process-wide count of attached headless (automotive) controllers, backing
+ * the `isCarConnected()` getter. Holds the same "a car is connected" state
+ * the `onCarConnect` / `onCarDisconnect` events transition between, so a
+ * consumer that missed the connect event — because it fired before the
+ * consumer registered its handler in this process — can still gate car-only
+ * work (e.g. browse-snapshot pushes) on the current connection.
+ *
+ * The count is process-scoped rather than tied to a [PlaybackService]
+ * instance so it stays correct across a service restart while a controller
+ * remains attached: the new instance's `onConnect` and the dying instance's
+ * late `onConnect`/`onDisconnected` all mutate this single source of truth, so
+ * the getter can't momentarily read disconnected mid-handoff. It is
+ * floor-guarded so a stray disconnect can't drive it negative, and process
+ * death clears it (a fresh process starts disconnected), which is correct.
+ *
+ * Only [PlaybackServiceCallback] mutates this — at the same headless
+ * connect / disconnect points that drive the events. This count is separate
+ * from that callback's per-instance counter, which stays per-service so the
+ * events keep their per-session first/last edge semantics.
+ */
+internal object CarConnectionState {
+  private val count = AtomicInteger(0)
+
+  fun isConnected(): Boolean = count.get() > 0
+
+  /** A headless controller attached. */
+  fun retain() {
+    count.incrementAndGet()
+  }
+
+  /** A headless controller detached; never drops below zero. */
+  fun release() {
+    count.updateAndGet { if (it > 0) it - 1 else 0 }
+  }
+
+  @VisibleForTesting
+  fun reset() {
+    count.set(0)
+  }
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/Equalizer.kt

@@ -25,9 +25,7 @@ import com.margelo.nitro.core.Promise
  * The JS-facing methods that mutate state return `Promise<Unit>`
  * via `Promise.async` per the spec, but each delegates to a
  * synchronous `*Internal` method that owns the actual mutation.
- * Unit tests target the synchronous core; the async wrapper is a
- * JS-interface adapter and is exercised at integration via demo
- * Maestro.
+ * The async wrapper is a thin JS-interface adapter.
  *
  * Listener registries follow the same shape as other event
  * listeners on this lib: stable numeric IDs returned via the

package/android/src/main/java/com/margelo/nitro/queueplayer/HeadlessJsMediaService.kt

@@ -141,8 +141,7 @@ public abstract class HeadlessJsMediaService :
   /**
    * The host's [ReactHost]. Returns `null` when the host
    * `Application` does not implement [ReactApplication] — production
-   * Expo / RN consumers always do; the null branch covers the
-   * Robolectric / unit-test path where the application is a stub.
+   * Expo / RN consumers always do.
    */
   protected val reactHost: ReactHost?
     get() = (application as? ReactApplication)?.reactHost
@@ -151,8 +150,7 @@ public abstract class HeadlessJsMediaService :
    * The live [ReactContext] from the consumer app's [ReactHost], or
    * `null` when no context has been created yet (the service kicks
    * one off via [createReactContextAndScheduleTask] in that case) OR
-   * when the host application isn't a [ReactApplication] at all (e.g.
-   * unit-test stubs).
+   * when the host application isn't a [ReactApplication] at all.
    */
   protected val reactContext: ReactContext?
     get() = reactHost?.currentReactContext

package/android/src/main/java/com/margelo/nitro/queueplayer/LookaheadCacheWriter.kt

@@ -285,9 +285,8 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
    * cache state.
    *
    * `runCatching` swallows the "Method myLooper in android.os.Looper
-   * not mocked" exception that fires under plain-JUnit (the writer's
-   * pure-orchestration tests deliberately avoid Robolectric to stay
-   * fast); production reads the looper normally.
+   * not mocked" exception that fires on a JVM host without the Android
+   * framework present; production reads the looper normally.
    */
   private fun requireMainThread() {
     val onMain = runCatching {
@@ -429,12 +428,11 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
         // Errors (OutOfMemoryError etc.) propagate — those are
         // not transient and shouldn't be hidden.
         //
-        // Log via runCatching: android.util.Log is not stubbed in
-        // plain-JUnit test runs (the writer's pure-orchestration
-        // tests deliberately avoid Robolectric), so a Log.w call
-        // would throw "Method w in android.util.Log not mocked"
-        // and terminate the prefetch loop. Production reads this
-        // log normally; tests get a silent no-op.
+        // Log via runCatching: on a JVM host without the Android
+        // framework present, android.util.Log is not stubbed, so a
+        // Log.w call would throw "Method w in android.util.Log not
+        // mocked" and terminate the prefetch loop. Production reads
+        // this log normally.
         runCatching { Log.w(TAG, "Lookahead prefetch failed for ${track.url}: ${e.message}") }
       }
 

package/android/src/main/java/com/margelo/nitro/queueplayer/MilestoneTracker.kt

@@ -2,8 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Tracks fixed playback-progress milestones (25/50/75/90%) for the
- * current track playthrough. Pure + deterministic (no Media3), so it
- * unit-tests directly.
+ * current track playthrough. Pure + deterministic (no Media3).
  *
  * A threshold emits only when forward playback crosses it: [seek] moves
  * the baseline WITHOUT emitting (so thresholds a seek jumps over are

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackService.kt

@@ -150,8 +150,8 @@ class PlaybackService : HeadlessJsMediaService() {
      * [PendingIntentBuffer] TTL: ~3 s for bridge boot + ~17 s of
      * headroom for the consumer's network calls before the controller
      * surfaces "no results" and the user retries. The two platforms'
-     * cold-start windows are deliberately the same so the manual
-     * playbook reads identically on iPhone + Android.
+     * cold-start windows are deliberately kept the same so the
+     * behaviour is identical on iPhone + Android.
      */
     private const val HEADLESS_DISPATCH_TIMEOUT_MS = 20_000L
 
@@ -1455,10 +1455,9 @@ class PlaybackService : HeadlessJsMediaService() {
   override fun getTaskConfig(intent: Intent?): com.facebook.react.jstasks.HeadlessJsTaskConfig? {
     val action = intent?.action ?: return null
     if (action !in HEADLESS_WAKE_ACTIONS) return null
-    // Robolectric / non-ReactApplication hosts cannot spawn a JS
-    // task — short-circuit here so `Arguments.createMap()` never
-    // has to load the React native libs that aren't on the test
-    // classpath.
+    // Non-ReactApplication hosts cannot spawn a JS task —
+    // short-circuit here so `Arguments.createMap()` never has to load
+    // the React native libs such a host lacks.
     if ((application as? com.facebook.react.ReactApplication) == null) return null
     // Belt-and-braces: if a wake intent somehow lands while a React
     // context is already alive (foreground app, prior wake already

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackServiceCallback.kt

@@ -73,7 +73,7 @@ internal class PlaybackServiceCallback(
      *  package (Android Auto, Wear OS, Google Assistant) connects.
      *  Production wires the React-context cold-start through here so
      *  "Hey Google, play …" works from a phone with the app killed.
-     *  Default no-op so unit-test setups without a service can fall
+     *  Default no-op so callers without a wired service fall
      *  through harmlessly. */
     fun onHeadlessControllerConnect(packageName: String) {}
 
@@ -287,6 +287,9 @@ internal class PlaybackServiceCallback(
   ): MediaSession.ConnectionResult {
     if (controller.packageName in HEADLESS_ELIGIBLE_PACKAGES) {
       val previousCount = headlessControllerCount.getAndIncrement()
+      // A headless controller is now attached — record it in the process-wide
+      // count the `isCarConnected()` getter reads.
+      CarConnectionState.retain()
       environment.onHeadlessControllerConnect(controller.packageName)
       // Fire onCarConnect only on the FIRST headless controller of
       // this service-lifetime session — subsequent connects (Wear
@@ -348,6 +351,10 @@ internal class PlaybackServiceCallback(
       } else if (previousCount > 0 && remaining == 0) {
         environment.onHeadlessControllerDisconnect()
       }
+      // Drop this controller from the process-wide connection count the
+      // `isCarConnected()` getter reads (floor-guarded against a stray
+      // disconnect, so it can't go negative).
+      CarConnectionState.release()
     }
     super.onDisconnected(session, controller)
   }

package/android/src/main/java/com/margelo/nitro/queueplayer/ProgressEmissionGate.kt

@@ -3,7 +3,7 @@ package com.margelo.nitro.queueplayer
 /**
  * Throttles the JS `onProgress` fan-out to a configurable cadence, with an
  * optional reduced rate while the app is backgrounded. Pure + deterministic
- * (the caller supplies a monotonic timestamp), so it unit-tests directly.
+ * (the caller supplies a monotonic timestamp).
  *
  * This gates ONLY the JS emission — the native 2 Hz sampler keeps running, so
  * milestone detection and buffer-state recomputation stay full-rate. A tick

package/android/src/main/java/com/margelo/nitro/queueplayer/QueueMutationArithmetic.kt

@@ -2,7 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Pure-Kotlin index-shift arithmetic for queue mutations. Extracted
- * from [TrackPlayer] so the shift semantics are unit-testable without
+ * from [TrackPlayer] so the shift semantics stand alone without
  * an ExoPlayer. Mirrors (and lightly supersedes) the inline math
  * inside iOS `TrackPlayer.swift`'s `addToQueueBody` /
  * `removeFromQueueBody` / `moveInQueueBody` — the iOS backlog carries

package/android/src/main/java/com/margelo/nitro/queueplayer/QueueSkipArithmetic.kt

@@ -4,7 +4,7 @@ package com.margelo.nitro.queueplayer
  * Pure-Kotlin skip-index arithmetic. Mirrors the iOS sibling
  * `ios/QueueSkipArithmetic.swift` 1-for-1.
  *
- * Extracted from [TrackPlayer] so the logic is unit-testable without
+ * Extracted from [TrackPlayer] so the logic stands alone without
  * instantiating an ExoPlayer. [TrackPlayer.computeNextIndex] /
  * [TrackPlayer.computePreviousIndex] are thin adapters that translate
  * the Nitrogen-generated [RepeatMode] enum into [QueueSkipRepeatMode]

package/android/src/main/java/com/margelo/nitro/queueplayer/RemoteCommandDeduper.kt

@@ -29,7 +29,7 @@ package com.margelo.nitro.queueplayer
  *
  * Bias is toward emitting: when in doubt, act rather than swallow a real press.
  *
- * Pure and time-injected ([nowUptimeMs] is passed in) so it unit-tests without an
+ * Pure and time-injected ([nowUptimeMs] is passed in), so it needs no
  * Android runtime. [shouldEmit] is `@Synchronized` so it is safe regardless of
  * which thread an emit site runs on (today they are all main-thread-confined).
  */

package/android/src/main/java/com/margelo/nitro/queueplayer/SleepTimerCore.kt

@@ -2,7 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Pure state machine for the sleep timer — no player, volume, or handler
- * dependencies, so it is unit-testable in isolation. The owning [TrackPlayer]
+ * dependencies, so it stands alone. The owning [TrackPlayer]
  * drives it from a repeating main-looper runnable and applies the returned
  * decision (volume fade, pause) to the engine.
  *
@@ -42,6 +42,12 @@ class SleepTimerCore(
   // defer the pause forever.
   private var tailExtended = false
 
+  // True while an end-of-track timer is pending, and survives the conversion to
+  // a DURATION fade so the real track-end signal (fireAtTrackEnd) knows to fire
+  // — the poll can't hit the boundary exactly and never fires at all when the
+  // duration is unknown (live/streaming).
+  private var originEndOfTrack = false
+
   val isActive: Boolean get() = mode != Mode.INACTIVE
   val isEndOfTrack: Boolean get() = mode == Mode.END_OF_TRACK
 
@@ -49,18 +55,33 @@ class SleepTimerCore(
     mode = Mode.DURATION
     deadlineEpochMs = nowMs + (seconds * 1000).toLong()
     tailExtended = false
+    originEndOfTrack = false
   }
 
   fun armEndOfTrack() {
     mode = Mode.END_OF_TRACK
     deadlineEpochMs = null
     tailExtended = false
+    originEndOfTrack = true
   }
 
   fun clear() {
     mode = Mode.INACTIVE
     deadlineEpochMs = null
     tailExtended = false
+    originEndOfTrack = false
+  }
+
+  /**
+   * Fire the pending end-of-track timer at the current track's real end. The
+   * owning engine calls this from its Media3 auto-transition signal so the pause
+   * lands exactly at the boundary (and fires even when the duration was never
+   * known). No-op unless an end-of-track timer is pending.
+   */
+  fun fireAtTrackEnd(): Tick {
+    if (!originEndOfTrack) return Tick.IDLE
+    clear()
+    return Tick(1.0, pauseNow = true, stateChanged = true)
   }
 
   /** Whole seconds until the fixed deadline, or `null` when inactive / awaiting track end. */
@@ -78,9 +99,13 @@ class SleepTimerCore(
         val tail = trackRemaining(trackDurationSec, trackPositionSec)
         if (tail != null && tail <= tailGraceSeconds) {
           mode = Mode.DURATION
-          deadlineEpochMs = nowMs + ((tail + 1) * 1000).toLong()
+          // Deadline lands AT the track boundary (not 1s past it) so the fade
+          // completes at the end; on the local engine the real track-end signal
+          // (fireAtTrackEnd) owns the actual pause, and this deadline is the
+          // fallback the cast path rides out on the receiver's clock.
+          deadlineEpochMs = nowMs + (tail * 1000).toLong()
           tailExtended = true
-          return Tick(fadeFraction(tail + 1), pauseNow = false, stateChanged = true)
+          return Tick(fadeFraction(tail), pauseNow = false, stateChanged = true)
         }
         return Tick.IDLE
       }
@@ -103,9 +128,7 @@ class SleepTimerCore(
           return Tick(fadeFraction(tail + 1), pauseNow = false, stateChanged = true)
         }
         // Fire.
-        mode = Mode.INACTIVE
-        deadlineEpochMs = null
-        tailExtended = false
+        clear()
         return Tick(1.0, pauseNow = true, stateChanged = true)
       }
     }

package/android/src/main/java/com/margelo/nitro/queueplayer/TrackPlayer.kt

@@ -46,10 +46,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // --- Stored state
   //
   // Mirrors iOS TrackPlayer.swift's "Stored state" block. Field
-  // visibility is `internal` + `@VisibleForTesting` so Robolectric
-  // tests can observe lifecycle transitions without going through
-  // the JNI-backed Nitro Promise machinery (which does not load in
-  // the JVM unit-test runtime).
+  // visibility is `internal` + `@VisibleForTesting` so lifecycle
+  // transitions can be observed without going through the JNI-backed
+  // Nitro Promise machinery (which does not load on a plain JVM).
 
   /**
    * `true` after [configureInternal] has bound + configured the
@@ -158,8 +157,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private var lastEmittedFormatMediaItem: MediaItem? = null
 
   // The fields below are written on main (via `onMain` / `syncMain`
-  // from the Promise adapter path, or directly from Robolectric tests
-  // which run on main). They are read off-main by the synchronous
+  // from the Promise adapter path). They are read off-main by the synchronous
   // snapshot accessors — `getCurrentTrackIndex`, `getQueue` —
   // dispatched on the JS thread by Nitro. `@Volatile` gives the
   // read path a happens-before edge on the most recent main-thread
@@ -581,7 +579,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private val progressEmissionGate = ProgressEmissionGate()
   // ProcessLifecycleOwner observer driving the gate's background state. Held in
   // a nullable field so a re-configureInternal without an intervening
-  // destroyInternal (Robolectric) is a no-op instead of leaking a second
+  // destroyInternal is a no-op instead of leaking a second
   // observer. Registered in configureInternal, removed in destroyInternal.
   private var progressLifecycleObserver: DefaultLifecycleObserver? = null
   private val errorListeners = ListenerRegistry<(PlaybackError) -> Unit>()
@@ -866,11 +864,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Lifecycle configure body. `internal` so Robolectric tests can
-   * exercise it without the Nitro Promise path. Callers MUST hop
-   * to the main thread first — ExoPlayer construction binds to the
-   * calling Looper. Production path goes through `onMain`; tests
-   * run on Robolectric's main-thread dispatcher.
+   * Lifecycle configure body. `internal`, bypassing the Nitro Promise
+   * path. Callers MUST hop to the main thread first — ExoPlayer
+   * construction binds to the calling Looper. Production path goes
+   * through `onMain`.
    *
    * Builds the ExoPlayer with a [MediaSource.Factory] that attaches
    * the config's HTTP headers + User-Agent on every network request.
@@ -879,9 +876,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * Per the universal auto-destroy contract every `configure()` call
    * tears the player down upstream so this body is purely
    * constructive — `player` is guaranteed null on entry from the
-   * production path. Robolectric tests that drive `configureInternal`
-   * directly are responsible for calling `destroyInternal` first
-   * between configures.
+   * production path. Any caller driving `configureInternal` directly
+   * must call `destroyInternal` first between configures.
    */
   @VisibleForTesting
   @MainThread
@@ -2442,9 +2438,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   /**
    * Main-thread body for [setPlaybackSpeed]. The engine applies the
    * active pitch-correction mode's pitch alongside the speed (voice/music
-   * preserve pitch; none lets it follow rate). Exposed `@VisibleForTesting`
-   * so Robolectric exercises the cast + speed-application logic rather than
-   * just bypassing through `ExoPlayer.playbackParameters`.
+   * preserve pitch; none lets it follow rate). Exposed `@VisibleForTesting`;
+   * centralizes the cast + speed-application logic rather than routing
+   * straight through `ExoPlayer.playbackParameters`.
    *
    * Diverges from iOS: on iOS `player.rate = Float(rate)` implicitly
    * starts playback when the player was paused. Android's
@@ -2629,6 +2625,14 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       positionSec = maxOf(0L, serviceBinder?.engine?.currentPositionMs ?: 0L) / 1000.0
     }
     val result = sleepTimerCore.tick(System.currentTimeMillis(), durationSec, positionSec)
+    applySleepTimerResult(result)
+  }
+
+  /**
+   * Apply a [SleepTimerCore.Tick] decision — fade, state emit, boundary pause.
+   * Shared by the polling tick and the real track-end signal ([fireEndOfTrackSleepTimer]).
+   */
+  private fun applySleepTimerResult(result: SleepTimerCore.Tick) {
     applySleepTimerFade(result.fadeFraction)
     if (result.stateChanged) emitSleepTimerChanged()
     if (result.pauseNow) {
@@ -2643,6 +2647,17 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     if (!sleepTimerCore.isActive) stopSleepTimerTick()
   }
 
+  /**
+   * Fire the end-of-track sleep timer at a real auto-transition boundary (the
+   * current track finished and Media3 advanced). Called from the engine's
+   * track-transition callback so the pause lands at the boundary and fires even
+   * when the track duration was never known — no-op unless end-of-track is armed.
+   */
+  private fun fireEndOfTrackSleepTimer() {
+    val result = sleepTimerCore.fireAtTrackEnd()
+    if (result.pauseNow) applySleepTimerResult(result)
+  }
+
   private fun applySleepTimerFade(fraction: Double) {
     // Fade is local-only: the receiver's volume is user/system-owned and
     // `volumeState` tracks the local level, so ramping it on the receiver would
@@ -3013,6 +3028,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   override fun onCarDisconnect(callback: () -> Unit): () -> Unit =
     deferredRegister { it.registerOnCarDisconnect(callback) }
 
+  override fun isCarConnected(): Boolean = CarConnectionState.isConnected()
+
   override fun onServiceReady(
     callback: (reason: ServiceReadyReason) -> Unit
   ): () -> Unit = deferredRegister { it.registerOnServiceReady(callback) }
@@ -3599,6 +3616,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   internal fun maybeEmitQueueEnd(playbackState: Int) {
     if (playbackState != Player.STATE_ENDED) return
     if (tracks.isEmpty()) return
+    // End-of-track sleep timer on the LAST track: STATE_ENDED fires no
+    // MEDIA_ITEM_TRANSITION, so cover the final boundary here — matching iOS,
+    // whose per-item handlePlayerItemDidPlayToEndTime fires on the last track
+    // too. Idempotent, so it can't double-fire with the poll / transition path.
+    fireEndOfTrackSleepTimer()
     queueEndListeners.forEach { it() }
     emitState(PlayerState.ENDED, StateChangeReason.QUEUE_END)
   }
@@ -3622,6 +3644,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val p = player ?: return
     val translated = translateTransitionReason(reason, p)
 
+    // End-of-track sleep timer: a natural track boundary — auto-advance to the
+    // next track OR a repeat-one loop of the same track (both translate to
+    // AUTO_ADVANCE) — is the real end of the current track, so pause here.
+    // fireAtTrackEnd is idempotent, so a deduped crossfade echo can't double-fire.
+    if (translated == TrackChangeReason.AUTO_ADVANCE) fireEndOfTrackSleepTimer()
+
     // Natural track change → reset error dedup so a new item's
     // identical-coded error fires. Without this, a TIMEOUT on
     // track 2 (after a TIMEOUT on track 1) would be silently
@@ -4127,11 +4155,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Test hook: stash a [TrackChangeReason] that the next
+   * Stash a [TrackChangeReason] that the next
    * [handleMediaItemTransition] with `REASON_SEEK` will consume.
-   * Production code reaches this field via `skipTo*Internal`
-   * bodies; the hook just lets Robolectric tests simulate the
-   * stash without driving a real skip + ExoPlayer seek.
+   * Production code reaches this field via `skipTo*Internal` bodies.
    */
   @VisibleForTesting
   internal fun setPendingTrackChangeReasonForTest(reason: TrackChangeReason?) {
@@ -4139,9 +4165,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Test hook: reset the [lastReportedState] dedup edge so
-   * [emitStateIfChanged] tests can force an emit from an already-
-   * NONE state without going through a real Player.Listener fire.
+   * Reset the [lastReportedState] dedup edge, forcing [emitStateIfChanged]
+   * to emit from an already-NONE state without a real Player.Listener fire.
    */
   @VisibleForTesting
   internal fun resetLastReportedStateForTest() {
@@ -4220,8 +4245,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
     /**
      * Decide which [ServiceReadyReason] (if any) to dispatch on a
-     * fresh service-bind. Pure function so the reason-decision logic
-     * is unit-testable without spinning up a service controller.
+     * fresh service-bind. Pure function — no service controller needed.
      *
      *  - First-ever bind ([prior] == null): [ServiceReadyReason.FIRST_BIND].
      *  - Bind against a different binder identity:

package/android/src/main/java/com/margelo/nitro/queueplayer/TransportStateTranslator.kt

@@ -7,8 +7,8 @@ import androidx.media3.common.Player
  * isPlaying, playWhenReady, playbackSuppressionReason, hasTracks,
  * currentTrackIndex)` tuple to the library's [PlayerState] enum.
  *
- * Extracted from [TrackPlayer.getStateInternal] so every branch is
- * unit-testable without a live ExoPlayer. Matches the pattern of
+ * Extracted from [TrackPlayer.getStateInternal] so every branch
+ * stands alone without a live ExoPlayer. Matches the pattern of
  * [QueueSkipArithmetic] + [QueueMutationArithmetic] — TrackPlayer
  * is a thin adapter that reads the live player's state and
  * delegates the translation here.

package/android/src/test/java/com/margelo/nitro/queueplayer/AudioPipelineRenderersFactoryTest.kt

@@ -14,12 +14,9 @@ import java.lang.reflect.Field
 /**
  * Unit coverage for [AudioPipelineRenderersFactory] construction — it wraps a
  * caller-supplied [androidx.media3.common.audio.AudioProcessorChain] and leaves
- * the produced sink at 16-bit (float output off). The engines drive end-to-end exercise of
- * `buildAudioSink` via `ExoPlayer.Builder.build()` in
- * [GaplessEngineLifecycleTest] / [CrossfadeEngineLifecycleTest]; `buildAudioSink`
+ * the produced sink at 16-bit (float output off). `buildAudioSink`
  * itself is `protected` on [DefaultRenderersFactory] and cannot be called
- * outside the Media3 internal call path. Chain composition + order is covered by
- * [PitchAwareAudioProcessorChainTest].
+ * outside the Media3 internal call path.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

package/android/src/test/java/com/margelo/nitro/queueplayer/BrowseCallbackRegistryTest.kt

@@ -9,10 +9,7 @@ import org.junit.Test
 /**
  * Pure-Kotlin coverage for [BrowseCallbackRegistry]'s slot-replace
  * + dispose semantics. The Promise-typed callbacks are stored as
- * function references; tests use simple stand-in lambdas — actual
- * dispatch coverage lives at the integration layer
- * (`PlaybackServiceCallbackSearchTest` for the search dispatch
- * path; future Maestro flows for end-to-end Auto cold-wake).
+ * function references; tests use simple stand-in lambdas.
  */
 @UnstableApi
 class BrowseCallbackRegistryTest {

package/android/src/test/java/com/margelo/nitro/queueplayer/CrossfadeEngineLifecycleTest.kt

@@ -15,8 +15,7 @@ import org.robolectric.annotation.Config
 /**
  * Lifecycle + fade-math coverage for [CrossfadeEngine].
  *
- * Audible verification of the dual-player crossfade runs at the
- * Maestro / demo-app integration layer; this suite exercises:
+ * This suite exercises:
  * empty-state sentinels, role-swap arithmetic, equal-power gain
  * curve, duration-clamp formula, manual-skip cancellation,
  * release idempotence + delegate clearing.

package/android/src/test/java/com/margelo/nitro/queueplayer/CrossfadeEngineReplayGainTest.kt

@@ -24,9 +24,7 @@ import org.robolectric.annotation.Config
  * Media3 metadata dispatch is not emulated by Robolectric without
  * playback, so the listener body composes its work through the
  * engine-internal `handleReplayGainParse(isA, parsed)` helper which
- * these tests drive directly with synthetic [ReplayGainData]. The
- * pure-math piece is covered in [ReplayGainGainTest]; end-to-end
- * propagation lands in the demo app's `replaygain` Maestro suite.
+ * these tests drive directly with synthetic [ReplayGainData].
  * This file covers the no-data baseline + the per-leg
  * `handleReplayGainParse` cache + recompute contract.
  */
@@ -173,8 +171,6 @@ class CrossfadeEngineReplayGainTest {
 
   // The per-leg cache-clear-on-transition path lives inline in each
   // leg's `Player.Listener.onMediaItemTransition` body. Robolectric
-  // does not drive that callback without real playback; integration
-  // coverage is in `RNQP-Demo/src/tests/suites/replaygain.ts` (steps
-  // `cross-track-active-updates` +
-  // `skip-next-mid-playback-resets-from-stale-cache`).
+  // does not drive that callback without real playback, so it is out
+  // of scope here.
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/EqualizerEngineTest.kt

@@ -13,8 +13,7 @@ import org.robolectric.annotation.Config
 /**
  * State-mirror coverage for [EqualizerEngine] on the API 28+ path.
  * Robolectric stubs the audio-effect subsystem at this SDK level so
- * `attach` exercises the construction path without throwing; the
- * audible effect is verified at integration via demo Maestro.
+ * `attach` exercises the construction path without throwing.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

package/android/src/test/java/com/margelo/nitro/queueplayer/EqualizerKtTest.kt

@@ -16,9 +16,7 @@ import org.robolectric.annotation.Config
 /**
  * Wiring coverage for the `Equalizer` HybridObject — engine
  * selection, JS-facing surface routing through the synchronous
- * `*Internal` core, listener registry behaviour. The audible
- * effect is verified at the integration layer via demo Maestro
- * once the engine is hooked to ExoPlayer's audio session.
+ * `*Internal` core, listener registry behaviour.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

package/android/src/test/java/com/margelo/nitro/queueplayer/EqualizerLegacyEngineTest.kt

@@ -13,9 +13,8 @@ import org.robolectric.annotation.Config
  * State-mirror coverage for [EqualizerLegacyEngine] on the API <28 path.
  * Robolectric's audio-effect shadow doesn't model the hardware-side
  * band centre frequencies + gain range; the band-mapping + dB↔mB
- * conversion are the test-reachable invariants. Real audible effect
- * verified at user-led API 26 emulator playbook (legacy API
- * behaviour varies per OEM).
+ * conversion are the invariants this covers. Legacy AudioEffect
+ * behaviour varies per OEM.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [27])