react-native-queue-player 1.2.0 → 2.0.1

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

@@ -17,7 +17,6 @@ import android.os.IBinder
 import android.os.Looper
 import androidx.core.content.ContextCompat
 import androidx.annotation.VisibleForTesting
-import androidx.media3.common.C
 import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
@@ -26,25 +25,17 @@ import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.exoplayer.source.MediaSource
 import androidx.media3.session.CacheBitmapLoader
 import androidx.media3.session.CommandButton
-import androidx.media3.session.LibraryResult
 import androidx.media3.session.MediaLibraryService
-import androidx.media3.session.MediaLibraryService.LibraryParams
 import androidx.media3.session.MediaLibraryService.MediaLibrarySession
 import androidx.media3.session.MediaSession
-import androidx.media3.session.SessionResult
-import com.google.common.collect.ImmutableList
-import com.google.common.util.concurrent.Futures
 import com.google.common.util.concurrent.ListenableFuture
 import com.google.common.util.concurrent.MoreExecutors
 import com.google.common.util.concurrent.SettableFuture
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.queueplayer.cast.PlaybackStateRouter
 import java.util.UUID
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.cancel
-import kotlinx.coroutines.currentCoroutineContext
-import kotlinx.coroutines.delay
-import kotlinx.coroutines.flow.collect
-import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
@@ -147,7 +138,7 @@ class PlaybackService : HeadlessJsMediaService() {
      * resolve — covers (a) the JS bridge spinning up + the consumer's
      * `registerPlaybackService` running, AND (b) the consumer's
      * resolution Promise running. 20 s mirrors the iOS
-     * [PendingIntentBuffer] TTL: ~3 s for bridge boot + ~17 s of
+     * `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 kept the same so the
@@ -260,8 +251,8 @@ class PlaybackService : HeadlessJsMediaService() {
 
   /**
    * Per-query cache of JS-supplied search results. Populated by
-   * `TrackPlayer.setSearchResults` once the JS handler
-   * responds to a search request; read by
+   * [dispatchSearchToJs] once the JS `onSearchRequest` handler
+   * responds; read by
    * [PlaybackServiceCallback.onGetSearchResult]. Empty by default —
    * a controller's `getSearchResult` call before the JS responder
    * has answered returns an empty page.
@@ -315,7 +306,7 @@ class PlaybackService : HeadlessJsMediaService() {
       // Cold-wake the JS bridge so the consumer's
       // `registerPlaybackService` can fire its callbacks before
       // Media3's framework dispatches `onAddMediaItems`. Idempotent
-      // — `HeadlessJsMediaService.initialized` latches the JS task
+      // — `HeadlessJsMediaService.initialized` is set by the JS task
       // spawn so re-entrant connects do not double-spawn.
       this@PlaybackService.selfWakeForHeadlessClient(packageName)
     }
@@ -341,14 +332,16 @@ class PlaybackService : HeadlessJsMediaService() {
     }
 
     override fun onPlayFromSearchRequest(
-      request: MediaSearchRequest
+      request: MediaSearchRequest,
+      append: Boolean
     ): ListenableFuture<List<MediaItem>> =
-      this@PlaybackService.dispatchPlayFromSearchToJs(request)
+      this@PlaybackService.dispatchPlayFromSearchToJs(request, append)
 
     override fun onPlayFromIdRequest(
-      mediaId: String
+      mediaId: String,
+      append: Boolean
     ): ListenableFuture<List<MediaItem>> =
-      this@PlaybackService.dispatchPlayFromIdToJs(mediaId)
+      this@PlaybackService.dispatchPlayFromIdToJs(mediaId, append)
 
     override fun onPlayFromIdRequestNoSync(mediaId: String) {
       this@PlaybackService.dispatchPlayFromIdToJsFireOnly(mediaId)
@@ -425,14 +418,6 @@ class PlaybackService : HeadlessJsMediaService() {
      */
     val instanceId: java.util.UUID = java.util.UUID.randomUUID()
 
-    /**
-     * Direct access to the underlying ExoPlayer. Retained as a
-     * back-compat shim for [TrackPlayer] until its transport /
-     * queue calls migrate onto the [engine] surface; engine-aware
-     * code paths use [engine] instead.
-     */
-    val player: ExoPlayer get() = exoPlayer
-
     /**
      * Strategy-pattern engine wrapping the active player(s).
      * Routes through the abstract [PlaybackEngine] surface so
@@ -464,7 +449,7 @@ class PlaybackService : HeadlessJsMediaService() {
      * AVRCP, Android Auto, and Wear surfaces grey out skip buttons
      * that the queue boundary makes invalid. No-op when no handler
      * is registered (no authoritative capability source) or when no
-     * controllers have connected yet (next [PlaybackCallback.onConnect]
+     * controllers have connected yet (next [PlaybackServiceCallback.onConnect]
      * picks up the fresh capability).
      */
     internal fun refreshAvailableCommands() {
@@ -504,9 +489,12 @@ class PlaybackService : HeadlessJsMediaService() {
   private val localBinder by lazy { LocalBinder() }
 
   /**
-   * Currently-registered handler consulted by [PlaybackCallback]
-   * before the default routing runs. `null` until
-   * [TrackPlayer.configureInternal] wires itself in; under that
+   * Currently-registered handler consulted by [SessionCommandForwardingPlayer]
+   * before the default routing runs, by [MediaButtonDispatch] for raw
+   * media-button intents, by the audio-focus listener, and by
+   * [PlaybackServiceCallback.onConnect] for the initial player commands.
+   * `null` until
+   * [TrackPlayer.configureInternal] registers one; under that
    * state every callback falls through to the Media3 default and
    * raw media-button intents fall through to the framework.
    */
@@ -640,7 +628,7 @@ class PlaybackService : HeadlessJsMediaService() {
    * PcmStream (AirPlay) session is not a RemotePlayer.
    */
   private val castBindScope = kotlinx.coroutines.CoroutineScope(
-    kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.Main.immediate
+    kotlinx.coroutines.SupervisorJob() + Dispatchers.Main.immediate
   )
 
   override fun onCreate() {
@@ -925,8 +913,8 @@ class PlaybackService : HeadlessJsMediaService() {
    * the new leading player, swap `MediaSession` to the new
    * player, carry the delegate over, re-wire the Equalizer, and
    * release the old engine. Queue migration is the caller's
-   * responsibility — `TrackPlayer` re-installs the canonical
-   * queue model onto the new engine before the swap if needed.
+   * responsibility — `TrackPlayer` seeds the new engine through
+   * `setMediaItems` after this returns.
    */
   fun swapEngine(newEngine: PlaybackEngine): PlaybackEngine {
     return swapEngineInternal(newEngine)
@@ -1080,6 +1068,16 @@ class PlaybackService : HeadlessJsMediaService() {
    * complete kill. A future multi-session change would need to stop each.
    */
   override fun onTaskRemoved(rootIntent: Intent?) {
+    // Stop the engine, not the session's player. Under crossfade the session
+    // is bound to a forwarding wrapper that addresses one leg, so stopping it
+    // leaves the other leg running: the task is swiped away, the notification
+    // and session go, and audio keeps playing with nothing left to control
+    // it. The engine stops both legs and abandons audio focus.
+    engine.stop()
+    // And the session's player. While cast-bound that is the receiver, which
+    // the engine does not own — stopping only the legs leaves the Chromecast
+    // playing after the task, notification and session are all gone. Off cast
+    // it is the forwarding wrapper around a leg the engine just stopped.
     mediaSession?.player?.stop()
     stopForeground(Service.STOP_FOREGROUND_REMOVE)
     stopSelf()
@@ -1129,7 +1127,7 @@ class PlaybackService : HeadlessJsMediaService() {
    */
   private val callbackDispatchScope =
     kotlinx.coroutines.CoroutineScope(
-      kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.IO
+      kotlinx.coroutines.SupervisorJob() + Dispatchers.IO
     )
 
   /**
@@ -1152,6 +1150,9 @@ class PlaybackService : HeadlessJsMediaService() {
         kotlinx.coroutines.withTimeoutOrNull(SEARCH_DISPATCH_TIMEOUT_MS) {
           callback(query).await().await().toList()
         } ?: emptyList()
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         // JS handler threw — surface as an empty answered result so
         // the controller stops waiting. The thrown error is the
@@ -1165,7 +1166,11 @@ class PlaybackService : HeadlessJsMediaService() {
         emptyList()
       }
       searchResultCache.setResults(query, items)
-      notifySearchResultChanged(query, items.size)
+      // `mediaSession` is owned by main and nulled by onDestroy there; the
+      // notify has to read it on the same thread or it races the release.
+      withContext(Dispatchers.Main) {
+        notifySearchResultChanged(query, items.size)
+      }
     }
   }
 
@@ -1185,9 +1190,11 @@ class PlaybackService : HeadlessJsMediaService() {
    * retries).
    */
   internal fun dispatchPlayFromSearchToJs(
-    request: MediaSearchRequest
+    request: MediaSearchRequest,
+    append: Boolean = false
   ): ListenableFuture<List<MediaItem>> = dispatchAssistantPlay(
     methodLabel = "onPlayFromSearchRequest",
+    append = append,
     awaitSlot = { browseCallbacks.awaitPlayFromSearchRequestCallback() }
   ) { browseCallbacks.playFromSearchRequestCallback()?.invoke(request) }
 
@@ -1198,9 +1205,11 @@ class PlaybackService : HeadlessJsMediaService() {
    * [dispatchPlayFromSearchToJs].
    */
   internal fun dispatchPlayFromIdToJs(
-    mediaId: String
+    mediaId: String,
+    append: Boolean = false
   ): ListenableFuture<List<MediaItem>> = dispatchAssistantPlay(
     methodLabel = "onPlayFromIdRequest",
+    append = append,
     awaitSlot = { browseCallbacks.awaitPlayFromIdRequestCallback() }
   ) { browseCallbacks.playFromIdRequestCallback()?.invoke(mediaId) }
 
@@ -1233,6 +1242,9 @@ class PlaybackService : HeadlessJsMediaService() {
               }
           promise?.await()?.await()
         }
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         android.util.Log.w(
           LOG_TAG,
@@ -1263,6 +1275,9 @@ class PlaybackService : HeadlessJsMediaService() {
               }
           promise?.await()?.await()?.toList() ?: emptyList()
         } ?: emptyList()
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         android.util.Log.w(
           LOG_TAG,
@@ -1286,6 +1301,7 @@ class PlaybackService : HeadlessJsMediaService() {
 
   private inline fun dispatchAssistantPlay(
     methodLabel: String,
+    append: Boolean,
     crossinline awaitSlot: suspend () -> Unit,
     crossinline invoke: () -> Promise<Promise<Array<TrackItem>>>?
   ): ListenableFuture<List<MediaItem>> {
@@ -1303,6 +1319,9 @@ class PlaybackService : HeadlessJsMediaService() {
           }
           promise?.await()?.await()?.toList() ?: emptyList()
         } ?: emptyList()
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         android.util.Log.w(
           LOG_TAG,
@@ -1316,7 +1335,7 @@ class PlaybackService : HeadlessJsMediaService() {
       // with whatever this future resolves to, so we MUST return the
       // real items — returning emptyList here would wipe the queue
       // immediately after Media3 installs it.
-      val items = applyAssistantQueueOnMain(tracks)
+      val items = applyAssistantQueueOnMain(tracks, append)
       future.set(items)
     }
     // Cancel the launched dispatch when the controller drops the
@@ -1355,26 +1374,27 @@ class PlaybackService : HeadlessJsMediaService() {
         )
         return@launch
       }
-      kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Main) {
+      withContext(Dispatchers.Main) {
         callback()
       }
     }
   }
 
   private suspend fun applyAssistantQueueOnMain(
-    tracks: List<TrackItem>
+    tracks: List<TrackItem>,
+    append: Boolean
   ): List<MediaItem> {
     if (tracks.isEmpty()) return emptyList()
     val player = TrackPlayer.current ?: return emptyList()
-    return kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Main) {
-      player.applyResolvedAssistantQueue(tracks)
+    return withContext(Dispatchers.Main) {
+      player.applyResolvedAssistantQueue(tracks, append)
     }
   }
 
   /**
    * Boot the JS task IF a headless-eligible controller has connected
    * AND no JS task is already running. Idempotent — the
-   * `HeadlessJsMediaService.initialized` latch + the wake-intent
+   * `HeadlessJsMediaService.initialized` flag + the wake-intent
    * action gate prevent re-entrancy.
    */
   internal fun selfWakeForHeadlessClient(packageName: String) {
@@ -1593,6 +1613,8 @@ class PlaybackService : HeadlessJsMediaService() {
   /**
    * Fire `notifySearchResultChanged` for [query] across every
    * connected controller after [searchResultCache] is populated.
+   * Caller is on main; the session's own thread-safety contract
+   * handles the controller iteration.
    */
   private fun notifySearchResultChanged(query: String, count: Int) {
     val session = mediaSession ?: return
@@ -1626,11 +1648,11 @@ class PlaybackService : HeadlessJsMediaService() {
   }
 
   /**
-   * Hook the [PlaybackCallback] consults before letting Media3 route
+   * Interface [SessionCommandForwardingPlayer] consults before letting Media3 route
    * a controller-initiated command to the bound player. Calls run on
    * the service main looper. Skip-next / skip-previous / seek-to-queue-item
    * return true when the implementation has handled the command itself,
-   * so the default routing is suppressed; the transport hook fires for
+   * so the default routing is suppressed; `onTransportCommand` fires for
    * play / pause / in-item seek / setPlaybackSpeed and is purely a
    * side-channel notification (no return value).
    */
@@ -1654,7 +1676,7 @@ class PlaybackService : HeadlessJsMediaService() {
     /**
      * Returns the lib's current authoritative skip capability —
      * driven by repeat-mode + queue position + queue size on the
-     * `TrackPlayer` side. Read by [PlaybackCallback.onConnect] and
+     * `TrackPlayer` side. Read by [PlaybackServiceCallback.onConnect] and
      * [LocalBinder.refreshAvailableCommands] so the available
      * `Player.Commands` reflect what skip arithmetic actually allows.
      */

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

@@ -91,7 +91,8 @@ internal class PlaybackServiceCallback(
      *  registered, the controller's "play X" voice command surfaces
      *  as "no results". */
     fun onPlayFromSearchRequest(
-      request: MediaSearchRequest
+      request: MediaSearchRequest,
+      append: Boolean = false
     ): ListenableFuture<List<MediaItem>> =
       Futures.immediateFuture(emptyList())
 
@@ -101,7 +102,8 @@ internal class PlaybackServiceCallback(
      *
      *  Default returns an empty list. */
     fun onPlayFromIdRequest(
-      mediaId: String
+      mediaId: String,
+      append: Boolean = false
     ): ListenableFuture<List<MediaItem>> =
       Futures.immediateFuture(emptyList())
 
@@ -194,7 +196,7 @@ internal class PlaybackServiceCallback(
           requestMetadata.extras
         )
         return Futures.transform(
-          environment.onPlayFromSearchRequest(request),
+          environment.onPlayFromSearchRequest(request, append = true),
           { items -> items.toMutableList() },
           MoreExecutors.directExecutor()
         )
@@ -202,7 +204,7 @@ internal class PlaybackServiceCallback(
       val mediaId = unresolved.mediaId.takeIf { it.isNotEmpty() }
       if (mediaId != null) {
         return Futures.transform(
-          environment.onPlayFromIdRequest(mediaId),
+          environment.onPlayFromIdRequest(mediaId, append = true),
           { items -> items.toMutableList() },
           MoreExecutors.directExecutor()
         )
@@ -749,7 +751,6 @@ internal class PlaybackServiceCallback(
     internal const val CONTENT_STYLE_PLAYABLE_HINT =
       "android.media.browse.CONTENT_STYLE_PLAYABLE_HINT"
     internal const val CONTENT_STYLE_LIST_ITEM = 1
-    internal const val CONTENT_STYLE_GRID_ITEM = 2
 
     /** Root extras flag: when `true`, gearhead surfaces a search
      *  affordance ("Search artists, albums, songs" mic / magnifying-

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

@@ -1,12 +1,11 @@
 package com.margelo.nitro.queueplayer
 
 /**
- * Pure-Kotlin index-shift arithmetic for queue mutations. Extracted
- * 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
- * an item to extract the same shapes on that side for parity.
+ * Pure-Kotlin index-shift arithmetic for queue mutations, kept out of
+ * [TrackPlayer] so the shift semantics stand alone without an
+ * ExoPlayer. Its iOS counterpart is `QueueMutationArithmetic.swift`,
+ * with the same function shapes and input/output semantics for these
+ * five helpers.
  *
  * The helper only computes the new `currentTrackIndex` and (for
  * `removeFromQueue`) which original indices apply after dedup /

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

@@ -4,11 +4,12 @@ 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 stands alone without
- * instantiating an ExoPlayer. [TrackPlayer.computeNextIndex] /
- * [TrackPlayer.computePreviousIndex] are thin adapters that translate
- * the Nitrogen-generated [RepeatMode] enum into [QueueSkipRepeatMode]
- * and delegate.
+ * Kept separate from [TrackPlayer] so the logic runs without an
+ * ExoPlayer. [TrackPlayer.computeNextIndex] is the thin adapter that
+ * translates the Nitrogen-generated [RepeatMode] enum into
+ * [QueueSkipRepeatMode] and delegates; the skip-previous path goes
+ * through [QueueSkipArithmetic.resolveSkipToPrevious], which wraps
+ * [QueueSkipArithmetic.computePrevious].
  *
  * Value order (0/1/2) is held fixed across the iOS enum and this one
  * so a test that asserts the raw integer catches any accidental
@@ -102,7 +103,9 @@ internal object QueueSkipArithmetic {
    * When [restartEnabled] is true (`PlayerConfig.skipToPreviousBehavior
    * == RESTART_OR_PREVIOUS`), Previous is enabled whenever a track is
    * loaded — even at index 0, where past the threshold it restarts the
-   * current track — so the control never greys out.
+   * current track — so the control never greys out while something is
+   * playing. With no loaded track (`currentIndex < 0`) there is nothing
+   * to restart, matching what resolveSkipToPrevious does for that state.
    */
   fun canSkipPrevious(
     trackCount: Int,
@@ -110,7 +113,7 @@ internal object QueueSkipArithmetic {
     repeatMode: QueueSkipRepeatMode,
     restartEnabled: Boolean = false
   ): Boolean =
-    if (restartEnabled) trackCount > 0
+    if (restartEnabled) trackCount > 0 && currentIndex >= 0
     else computePrevious(trackCount, currentIndex, repeatMode) != null
 
   /**
@@ -126,7 +129,7 @@ internal object QueueSkipArithmetic {
     data class Previous(val index: Int) : SkipToPreviousAction
     /** Restart the current track (seek to 0) — not a track change. */
     object RestartCurrent : SkipToPreviousAction
-    /** Nothing to do (empty queue). */
+    /** Nothing to do (empty queue, or no loaded track). */
     object NoOp : SkipToPreviousAction
   }
 

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

@@ -12,8 +12,20 @@ import kotlin.math.roundToInt
  * gain to a PCM stream. No knowledge of the engine, the EQ stage, or the
  * visualizer pipeline — purely "given a PCM buffer, multiply by
  * [linearGain]". The owning engine pushes a new gain via [setLinearGain]
- * from its `Player.Listener` callbacks; `onMediaItemTransition` resets to
- * unity until the next track's tags arrive.
+ * from its `Player.Listener` callbacks and from the ReplayGain-mode
+ * setter; `onMediaItemTransition` resets to unity until the next track's
+ * tags arrive.
+ *
+ * It is **always active** on a supported PCM encoding once configured, NOT
+ * gated on the current gain. Media3's
+ * [androidx.media3.common.audio.AudioProcessingPipeline] fixes the
+ * active-processor set in `configure()` / `flush()` and never re-evaluates
+ * it while a stream plays, so gating `isActive` on the (later-pushed) gain
+ * would exclude this processor from the pipeline for any queue loaded at
+ * unity and no gain could ever reach the audio afterwards. Staying active
+ * and passing the block straight through at unity keeps it present and
+ * ready, at the cost of one bulk buffer copy per block when no gain is
+ * applied.
  *
  * Handles both 16-bit and float PCM. The sink runs at 16-bit (see
  * [AudioPipelineRenderersFactory] — float output would drop the whole
@@ -30,7 +42,7 @@ internal class ReplayGainAudioProcessor : BaseAudioProcessor() {
    * it on every [queueInput] while the engine's main thread writes it
    * from the metadata listener. The value is `pow(10, gainDb / 20)`
    * already clip-capped against the track peak (caller's job); a
-   * value of `1.0f` means RG is inactive for this track.
+   * value of `1.0f` passes the stream through untouched.
    */
   @Volatile
   private var linearGain: Float = 1.0f
@@ -43,8 +55,8 @@ internal class ReplayGainAudioProcessor : BaseAudioProcessor() {
   private var encoding: Int = C.ENCODING_INVALID
 
   /**
-   * Push a new linear gain. `1.0f` disables the processor's per-sample
-   * multiply via [isActive].
+   * Push a new linear gain, observed from the next [queueInput] onwards.
+   * `1.0f` skips the per-sample multiply and passes the block through.
    */
   fun setLinearGain(value: Float) {
     linearGain = value
@@ -60,7 +72,7 @@ internal class ReplayGainAudioProcessor : BaseAudioProcessor() {
   }
 
   override fun isActive(): Boolean =
-    super.isActive() && linearGain != 1.0f &&
+    super.isActive() &&
       (encoding == C.ENCODING_PCM_FLOAT || encoding == C.ENCODING_PCM_16BIT)
 
   override fun queueInput(input: ByteBuffer) {
@@ -68,6 +80,14 @@ internal class ReplayGainAudioProcessor : BaseAudioProcessor() {
     val byteCount = input.remaining()
     if (byteCount == 0) return
     val out = replaceOutputBuffer(byteCount)
+    if (gain == 1.0f) {
+      // Unity — present in the pipeline but applying nothing. A bulk copy
+      // is ~25x cheaper per block than walking the samples for a multiply
+      // by one, and both consume the input and produce identical bytes.
+      out.put(input)
+      out.flip()
+      return
+    }
     if (encoding == C.ENCODING_PCM_FLOAT) {
       val inF = input.asFloatBuffer()
       val outF = out.asFloatBuffer()

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

@@ -31,9 +31,10 @@ data class ReplayGainData(
    *   both may be null when the album tag is absent. No fallback
    *   to track gain.
    *
-   * Caller computes `linearGain = 10^(gainDb / 20)` and clip-caps via
-   * peak when both are non-null. When `gainDb` is null the caller
-   * treats RG as inactive for this track (`linearGain = 1.0f`,
+   * Caller computes `linearGain = 10^(gainDb / 20)` and clip-caps it
+   * at `1 / peak` when the peak is usable, at unity when it is not —
+   * see [computeLinearGain]. When `gainDb` is null the caller treats
+   * RG as inactive for this track (`linearGain = 1.0f`,
    * `replayGainActive = false`).
    */
   fun selectGain(mode: ReplayGainMode): Pair<Float?, Float?> = when (mode) {
@@ -41,4 +42,22 @@ data class ReplayGainData(
     ReplayGainMode.TRACK -> trackGainDb to trackPeak
     ReplayGainMode.ALBUM -> albumGainDb to albumPeak
   }
+
+  companion object {
+    /**
+     * Resolve the ReplayGain a track plays with, all-or-nothing per
+     * item. [suppliedClaimed] is `true` when the consumer put any of
+     * the four fields on the `TrackItem`, computed before any value
+     * is validated: a claim discards detection outright, including
+     * for the mode the consumer never mentioned.
+     * `suppliedClaimed && supplied == null` is a real state — the
+     * consumer owns the track and gave nothing usable, so no gain is
+     * applied and the file's own tags stay unused.
+     */
+    internal fun merge(
+      suppliedClaimed: Boolean,
+      supplied: ReplayGainData?,
+      detected: ReplayGainData?,
+    ): ReplayGainData? = if (suppliedClaimed) supplied else detected
+  }
 }

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

@@ -159,7 +159,9 @@ internal object ReplayGainExtractor {
   /**
    * Parse a `REPLAYGAIN_*_GAIN` string (e.g. `"-6.54 dB"`,
    * `"+3.21"`, `"−1.0 dB"` with U+2212 minus) into a Float dB.
-   * Returns `null` for unparseable / NaN / Inf inputs.
+   * Returns `null` for unparseable input; the parsed number is then
+   * put through [acceptGainDb], so text handling is all this adds
+   * over the numeric entry point.
    */
   internal fun parseGainDb(rawInput: String): Float? {
     var trimmed = rawInput.trim()
@@ -184,25 +186,49 @@ internal object ReplayGainExtractor {
     // Reject comma decimals (RG2 spec — period only).
     if (trimmed.contains(',')) return null
 
-    val value = trimmed.toFloatOrNull() ?: return null
+    val value = trimmed.toDoubleOrNull() ?: return null
+    return acceptGainDb(value)
+  }
+
+  /**
+   * Shared numeric acceptance for a peak value, whatever entry point
+   * it arrived through — a tag string or a consumer-supplied number.
+   * Accepts `0.001 ... 2.0` inclusive (`1.0` is digital full scale and
+   * a legitimate measurement); rejects anything outside that band and
+   * anything non-finite. The band is checked on the `Double`, before the
+   * narrowing to `Float`, so a value just past it cannot round in.
+   */
+  internal fun acceptPeak(value: Double): Float? {
+    if (value.isNaN() || value.isInfinite()) return null
+    // Band-check the Double: 2.0000001 narrows to 2.0f, so a check
+    // applied after the narrowing would let it through.
+    if (value < 0.001 || value > 2.0) return null
+    return value.toFloat()
+  }
+
+  /**
+   * Shared numeric acceptance for a gain in dB, whatever entry point
+   * it arrived through. There is no plausibility band on gain — only
+   * non-finite values are rejected, including a magnitude that
+   * narrows to an infinite [Float].
+   */
+  internal fun acceptGainDb(value: Double): Float? {
     if (value.isNaN() || value.isInfinite()) return null
-    return value
+    val narrowed = value.toFloat()
+    if (narrowed.isInfinite()) return null
+    return narrowed
   }
 
   /**
    * Parse a `REPLAYGAIN_*_PEAK` string (linear, period decimal).
-   * Returns `null` for unparseable / NaN / Inf / out-of-range
-   * values, or for the encoder-default sentinels (peak `< 0.001`
-   * or peak exactly `1.0`, both signal the analyser didn't run).
+   * Returns `null` for unparseable input; the parsed number is then
+   * put through [acceptPeak], which holds the `0.001 ... 2.0`
+   * acceptance band — a full-scale `1.0` included.
    */
   internal fun parsePeak(rawInput: String): Float? {
     val trimmed = rawInput.trim()
-    val value = trimmed.toFloatOrNull() ?: return null
-    if (value.isNaN() || value.isInfinite()) return null
-    if (value < 0f || value > 2.0f) return null
-    if (value < 0.001f) return null
-    if (value == 1.0f) return null
-    return value
+    val value = trimmed.toDoubleOrNull() ?: return null
+    return acceptPeak(value)
   }
 
   // endregion

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

@@ -5,30 +5,34 @@ import kotlin.math.pow
 
 /**
  * Pure gain math per NOTES.md §25. Selects the `(gainDb, peak)` pair
- * from [data] under [mode] (strict, no fallback), then:
+ * from [data] under [mode] (strict, no fallback), then caps the result
+ * for clip safety:
  *
  * ```
- * linearGain = pow(10, gainDb / 20)
- * if peak != null and peak > 0.001 and peak != 1.0:
- *   linearGain = min(linearGain, 1.0 / peak)
+ * cap = usable peak ? 1.0 / peak : 1.0
+ * linearGain = min(pow(10, gainDb / 20), cap)
  * ```
  *
+ * A peak is usable inside the `0.001 .. 2.0` band that
+ * [ReplayGainExtractor.acceptPeak] holds — full scale (`1.0`) and true
+ * peaks above it included. With no usable peak the cap sits at unity,
+ * so a boost is suppressed rather than applied unprotected: a peak
+ * cannot be derived from a gain. Attenuation is untouched either way,
+ * since a negative gain can never clip. The band is re-checked here so
+ * the math stays correct for any caller that bypasses the extractor.
+ *
  * Returns `1.0f` (unity) whenever the selected mode's gain tag is
  * absent — RG is inactive for that track. Mirrors the iOS
  * `AudioTapProvider.computeLinearGain(data:mode:)` contract so a tag
  * fixture parses to the same linear gain on both platforms.
- *
- * Encoder-default sentinels (`peak == 1.0` and `peak < 0.001`) bypass
- * the peak-based clip cap. The extractor returns `null` for both
- * already, but defending here keeps the math correct against any
- * future caller that bypasses the extractor.
  */
 internal fun computeLinearGain(data: ReplayGainData?, mode: ReplayGainMode): Float {
   val (gainDb, peak) = data?.selectGain(mode) ?: (null to null)
   if (gainDb == null) return 1.0f
-  var raw = 10.0.pow(gainDb.toDouble() / 20.0).toFloat()
-  if (peak != null && peak > 0.001f && peak != 1.0f) {
-    raw = min(raw, 1.0f / peak)
+  val raw = 10.0.pow(gainDb.toDouble() / 20.0).toFloat()
+  var cap = 1.0f
+  if (peak != null && peak >= 0.001f && peak <= 2.0f) {
+    cap = 1.0f / peak
   }
-  return raw
+  return min(raw, cap)
 }