react-native-queue-player 1.2.0 → 2.0.0

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)
 }

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

@@ -0,0 +1,66 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * The consumer's ReplayGain claim over one queue entry, resolved from
+ * the `TrackItem` the engine is playing.
+ *
+ * The claim and the values it survived with are two separate facts, and
+ * keeping them separate is the whole point of this type. A `TrackItem`
+ * that supplies only an out-of-band peak has claimed its track just as
+ * firmly as one that supplies all four values, so collapsing the claim
+ * into "did any value survive acceptance" would hand that track back to
+ * the file's own tags. Presence claims the track; validity only decides
+ * what there is to apply.
+ *
+ * An instance therefore exists whenever any of the four fields was
+ * present, and [data] is `null` when none of those values survived
+ * [ReplayGainExtractor]'s acceptance rules — a track that owns its
+ * ReplayGain and plays at unity.
+ *
+ * Mirrors the iOS `SuppliedReplayGain`, which rides on the
+ * `AVPlayerItem` rather than being resolved per read; the shapes match
+ * so one contract covers both platforms.
+ */
+@UnstableApi
+internal class SuppliedReplayGain private constructor(val data: ReplayGainData?) {
+  companion object {
+    /**
+     * Build the claim for [track], or `null` when the consumer supplied
+     * none of the four ReplayGain fields and the track is left on
+     * whatever its file carries.
+     *
+     * Each present value goes through the same
+     * [ReplayGainExtractor.acceptGainDb] / [ReplayGainExtractor.acceptPeak]
+     * pair the tag strings land on, so a supplied number and a tagged
+     * number are held to one rule.
+     */
+    fun from(track: TrackItem): SuppliedReplayGain? {
+      if (track.replayGainTrackGain == null &&
+        track.replayGainTrackPeak == null &&
+        track.replayGainAlbumGain == null &&
+        track.replayGainAlbumPeak == null
+      ) {
+        return null
+      }
+      val trackGain = track.replayGainTrackGain?.let { ReplayGainExtractor.acceptGainDb(it) }
+      val trackPeak = track.replayGainTrackPeak?.let { ReplayGainExtractor.acceptPeak(it) }
+      val albumGain = track.replayGainAlbumGain?.let { ReplayGainExtractor.acceptGainDb(it) }
+      val albumPeak = track.replayGainAlbumPeak?.let { ReplayGainExtractor.acceptPeak(it) }
+      if (trackGain == null && trackPeak == null &&
+        albumGain == null && albumPeak == null
+      ) {
+        return SuppliedReplayGain(null)
+      }
+      return SuppliedReplayGain(
+        ReplayGainData(
+          trackGainDb = trackGain,
+          trackPeak = trackPeak,
+          albumGainDb = albumGain,
+          albumPeak = albumPeak,
+        )
+      )
+    }
+  }
+}