react-native-queue-player 1.0.0

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

@@ -0,0 +1,70 @@
+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.
+ *
+ * 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
+ * emits when at least `interval` has elapsed since the last emit, where
+ * `interval` is the foreground or background cadence per the current app
+ * state. [lastEmittedMs] starts at negative infinity so the first tick after a
+ * subscribe always emits, and a background→foreground transition resets it so
+ * the now-visible UI resumes at the live position on the next tick.
+ *
+ * Unlike iOS, the Android progress tick runs continuously (every 500ms) whether
+ * playing or paused, so a throttled paused seek self-corrects on the next tick
+ * within one interval — no play-state carve-out is needed, and throttling the
+ * repeated paused position is the desired behaviour.
+ *
+ * Main-thread-confined (the progress tick and the ProcessLifecycleOwner
+ * callbacks all run on main), so no synchronisation.
+ */
+internal class ProgressEmissionGate {
+  private var foregroundIntervalMs: Double = 500.0
+  private var backgroundIntervalMs: Double = 500.0
+  private var isBackgrounded: Boolean = false
+  private var lastEmittedMs: Double = Double.NEGATIVE_INFINITY
+
+  /**
+   * Half the native sampler period. The sampler fires at a fixed cadence, so a
+   * configured interval equal to that cadence would drop ~half the ticks to
+   * timing jitter — a tick landing a hair early reads as "too soon". Allowing
+   * emission up to half a sampler period early snaps each emit to the nearest
+   * tick: interval == sampler period emits every tick, 2× the period emits
+   * every other tick, and so on.
+   */
+  private var toleranceMs: Double = 0.0
+
+  /**
+   * Set the foreground + background cadences (already clamped by the caller)
+   * and the native sampler period that drives [shouldEmit]. Runtime state
+   * ([lastEmittedMs], [isBackgrounded]) is preserved so a re-`configure()`
+   * updates the rate without dropping the throttle position.
+   */
+  fun setIntervals(foregroundMs: Double, backgroundMs: Double, samplerPeriodMs: Double) {
+    foregroundIntervalMs = foregroundMs
+    backgroundIntervalMs = backgroundMs
+    toleranceMs = samplerPeriodMs / 2
+  }
+
+  /** Whether a tick at [nowMs] may emit; records the emit time when it does. */
+  fun shouldEmit(nowMs: Long): Boolean {
+    val interval = if (isBackgrounded) backgroundIntervalMs else foregroundIntervalMs
+    if (nowMs - lastEmittedMs < interval - toleranceMs) return false
+    lastEmittedMs = nowMs.toDouble()
+    return true
+  }
+
+  /**
+   * Update the foreground/background state. On a background→foreground
+   * transition, force the next tick to emit immediately (foreground-flush).
+   */
+  fun setBackgrounded(backgrounded: Boolean) {
+    if (isBackgrounded && !backgrounded) {
+      lastEmittedMs = Double.NEGATIVE_INFINITY
+    }
+    isBackgrounded = backgrounded
+  }
+}

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

@@ -0,0 +1,131 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Pure-Kotlin index-shift arithmetic for queue mutations. Extracted
+ * from [TrackPlayer] so the shift semantics are unit-testable 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.
+ *
+ * The helper only computes the new `currentTrackIndex` and (for
+ * `removeFromQueue`) which original indices apply after dedup /
+ * range-filter. Actual mutation of the track list + forwarding to
+ * ExoPlayer happens in [TrackPlayer].
+ */
+internal object QueueMutationArithmetic {
+
+  /**
+   * New `currentTrackIndex` after inserting [count] items at
+   * [insertAt]. If [count] is 0, returns [currentIndex] unchanged.
+   *
+   * Rules:
+   * - empty queue (cur < 0): stays at -1 — inserting into an
+   *   empty queue does NOT auto-start playback; consumers call
+   *   skipToIndex(0) explicitly.
+   * - insertAt <= cur: cur shifts forward by `count` (items slid
+   *   under it).
+   * - insertAt > cur: cur unchanged.
+   */
+  fun currentIndexAfterAdd(
+    currentIndex: Int,
+    insertAt: Int,
+    count: Int
+  ): Int {
+    if (count <= 0) return currentIndex
+    if (currentIndex < 0) return currentIndex
+    return if (insertAt <= currentIndex) currentIndex + count else currentIndex
+  }
+
+  /**
+   * Clamp an `insertBefore` argument to a valid insertion point in
+   * a track list of size [trackCount]. `null` → append (return
+   * trackCount). Out-of-range values clamp into [0, trackCount].
+   */
+  fun clampInsertBefore(insertBefore: Int?, trackCount: Int): Int {
+    if (insertBefore == null) return trackCount
+    if (insertBefore < 0) return 0
+    if (insertBefore > trackCount) return trackCount
+    return insertBefore
+  }
+
+  /**
+   * Filter + dedup a removal-index input, dropping out-of-range and
+   * negative entries. Returned list is ASCENDING — callers iterate
+   * it descending when applying removals to the underlying list,
+   * but the ascending shape is easier to reason about for the shift
+   * math downstream.
+   */
+  fun sanitiseRemoveIndices(
+    rawIndices: List<Int>,
+    trackCount: Int
+  ): List<Int> {
+    return rawIndices
+      .filter { it in 0 until trackCount }
+      .toSortedSet()
+      .toList()
+  }
+
+  /**
+   * New `currentTrackIndex` after removing the given (sanitised,
+   * ascending) indices from the track list.
+   *
+   * Rules (matches iOS `removeFromQueueBody`):
+   * - cur < 0 (empty / not-started): stays -1.
+   * - Every `i < cur` that was removed shifts cur down by 1.
+   * - If cur itself was removed AND the list becomes empty, cur → -1.
+   * - If cur itself was removed but other tracks remain, cur stays
+   *   at the SAME index value (which now points at the track that
+   *   was previously at cur+1 — iOS auto-advance semantics).
+   * - If cur itself was removed AND cur >= newTrackCount, clamp to
+   *   newTrackCount - 1.
+   */
+  fun currentIndexAfterRemove(
+    currentIndex: Int,
+    sanitisedIndices: List<Int>,
+    trackCountBefore: Int
+  ): Int {
+    if (currentIndex < 0) return -1
+    val indexSet = sanitisedIndices.toSet()
+    val removedBelowCur = sanitisedIndices.count { it < currentIndex }
+    val newTrackCount = trackCountBefore - sanitisedIndices.size
+    if (newTrackCount <= 0) return -1
+
+    var newCur = currentIndex - removedBelowCur
+    if (currentIndex in indexSet) {
+      // cur was removed; player auto-advances to what was at cur+1,
+      // which now occupies the same index value after the earlier-
+      // below shift has been applied. Clamp in case cur was at the
+      // tail.
+      if (newCur >= newTrackCount) newCur = newTrackCount - 1
+    }
+    return newCur
+  }
+
+  /**
+   * New `currentTrackIndex` after moving the track at `fromIndex`
+   * to `toIndex`. Inputs are assumed validated (in range, from != to).
+   *
+   * Rules (matches iOS `moveInQueueBody`):
+   * - cur < 0 → -1.
+   * - cur == from → newCur = to (cur moved with the track).
+   * - from < cur && to >= cur → newCur -= 1 (track slid past cur
+   *   from below, cur is now one slot earlier).
+   * - from > cur && to <= cur → newCur += 1 (track slid past cur
+   *   from above, cur is now one slot later).
+   * - otherwise cur unchanged.
+   */
+  fun currentIndexAfterMove(
+    currentIndex: Int,
+    fromIndex: Int,
+    toIndex: Int
+  ): Int {
+    if (currentIndex < 0) return currentIndex
+    return when {
+      currentIndex == fromIndex -> toIndex
+      fromIndex < currentIndex && toIndex >= currentIndex -> currentIndex - 1
+      fromIndex > currentIndex && toIndex <= currentIndex -> currentIndex + 1
+      else -> currentIndex
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+package com.margelo.nitro.queueplayer
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class QueuePlayerPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { HashMap() }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("queueplayer")
+        }
+    }
+}

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

@@ -0,0 +1,113 @@
+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
+ * instantiating an ExoPlayer. [TrackPlayer.computeNextIndex] /
+ * [TrackPlayer.computePreviousIndex] are thin adapters that translate
+ * the Nitrogen-generated [RepeatMode] enum into [QueueSkipRepeatMode]
+ * and delegate.
+ *
+ * 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
+ * reordering in the spec.
+ */
+internal enum class QueueSkipRepeatMode(val rawValue: Int) {
+  OFF(0),
+  TRACK(1),
+  QUEUE(2)
+}
+
+internal object QueueSkipArithmetic {
+
+  /**
+   * Next-track index. Returns null when nothing should play next
+   * (empty queue, no next track under OFF/TRACK at the end, nothing
+   * currently playing).
+   *
+   * TRACK navigates identically to OFF: a user Next advances to the
+   * next track with no wrap, and repeat-one persists so the newly
+   * current track is the one that loops on natural end. Only the
+   * end-of-track auto-advance (handled in [TrackPlayer], not here)
+   * replays the current track under TRACK.
+   *
+   * `cur < 0` early-bails — when nothing is currently playing,
+   * skipToNext is a no-op; callers start playback explicitly via
+   * `setQueue + play` or `skipToIndex(0)`.
+   */
+  fun computeNext(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ): Int? {
+    if (trackCount <= 0 || currentIndex < 0) return null
+    return when (repeatMode) {
+      QueueSkipRepeatMode.OFF, QueueSkipRepeatMode.TRACK -> {
+        val next = currentIndex + 1
+        if (next < trackCount) next else null
+      }
+      QueueSkipRepeatMode.QUEUE -> {
+        val next = currentIndex + 1
+        if (next < trackCount) next else 0
+      }
+    }
+  }
+
+  /**
+   * Previous-track index. Same early-bail rules as [computeNext].
+   *
+   * OFF and TRACK both return null at index 0 (no previous track, no
+   * wrap). Apps that want the Apple-Music-style "tap Previous at
+   * track 0 restarts current" UX implement that in their button
+   * handler.
+   */
+  fun computePrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ): Int? {
+    if (trackCount <= 0 || currentIndex < 0) return null
+    return when (repeatMode) {
+      QueueSkipRepeatMode.OFF, QueueSkipRepeatMode.TRACK -> {
+        val prev = currentIndex - 1
+        if (prev >= 0) prev else null
+      }
+      QueueSkipRepeatMode.QUEUE -> {
+        if (currentIndex == 0) trackCount - 1 else currentIndex - 1
+      }
+    }
+  }
+
+  /**
+   * Whether the user-facing Next button should be enabled. Defined
+   * as `computeNext(...) != null` so all three repeat modes are
+   * handled in one place: OFF and TRACK are false at the last track
+   * (no wrap); QUEUE is always true with an active track (wraps).
+   */
+  fun canSkipNext(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ): Boolean = computeNext(trackCount, currentIndex, repeatMode) != null
+
+  /**
+   * Whether the user-facing Previous button should be enabled.
+   * Symmetric with [canSkipNext] — defined as `computePrevious(...)
+   * != null`, so all three repeat modes are handled in one place:
+   * OFF and TRACK are false at index 0 (no wrap); QUEUE is always
+   * true with an active track (wraps).
+   *
+   * **Apps that want the Apple-Music-style "tap Previous restarts
+   * when position > 3s" UX** should implement that in their button
+   * handler: read playback position, branch to `seekTo(0)` vs
+   * `skipToPrevious()` themselves. Lib intentionally ships the
+   * primitive (skip if there's a track to skip to), not the policy.
+   */
+  fun canSkipPrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ): Boolean = computePrevious(trackCount, currentIndex, repeatMode) != null
+}

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

@@ -0,0 +1,176 @@
+package com.margelo.nitro.queueplayer
+
+import kotlin.math.PI
+import kotlin.math.cos
+import kotlin.math.sin
+import kotlin.math.sqrt
+
+/**
+ * Iterative Cooley–Tukey radix-2 forward FFT. In-place over (real,
+ * imag) pairs of length n where n is a power of 2. No external deps.
+ *
+ * Produces the standard frequency-domain output: bin k of [0, n) gives
+ * the complex coefficient of frequency `k * sampleRate / n`. Bin 0 is
+ * DC; bin n/2 is Nyquist; the upper half is the conjugate-symmetric
+ * mirror for real-valued inputs.
+ *
+ * The single output buffer length we expose to consumers is
+ * `n / 2` magnitudes — bin n/2 (Nyquist) is dropped to keep the lib's
+ * `frame.fft.byteLength === fftSize / 2 * 4` contract tight across
+ * platforms.
+ */
+internal object RadixTwoFFT {
+
+  /**
+   * Maximum FFT length supported by the pre-computed twiddle tables.
+   * Must stay in lockstep with the public `VisualizerFftSize` union
+   * in `react-native-queue-player/src/types.ts` — the spec's upper
+   * bound is the source of truth; this constant is the iOS / Android
+   * implementation cap that backs it.
+   */
+  private const val MAX_FFT_SIZE = 2048
+
+  /**
+   * Pre-computed twiddle factors keyed by stage index, where
+   * stage index `s` corresponds to butterfly size `1 shl (s + 1)`
+   * (i.e. s=0 → size 2, s=1 → size 4, … s=10 → size 2048).
+   *
+   * `twiddleReal[s][j]` = cos(-2π · j / size), with j in [0, size/2).
+   * `twiddleImag[s][j]` = sin(-2π · j / size).
+   *
+   * Memory footprint: sum over s of (size/2) floats per table ×
+   * 2 tables × 4 bytes ≈ 16 KB total for MAX_FFT_SIZE = 2048.
+   */
+  private val twiddleReal: Array<FloatArray>
+  private val twiddleImag: Array<FloatArray>
+
+  init {
+    val stageCount = Integer.numberOfTrailingZeros(MAX_FFT_SIZE)
+    twiddleReal = Array(stageCount) { FloatArray(0) }
+    twiddleImag = Array(stageCount) { FloatArray(0) }
+    var size = 2
+    var stageIdx = 0
+    while (size <= MAX_FFT_SIZE) {
+      val half = size / 2
+      val angleStep = -2.0 * PI / size
+      val cosTable = FloatArray(half)
+      val sinTable = FloatArray(half)
+      var j = 0
+      while (j < half) {
+        val angle = angleStep * j
+        cosTable[j] = cos(angle).toFloat()
+        sinTable[j] = sin(angle).toFloat()
+        j++
+      }
+      twiddleReal[stageIdx] = cosTable
+      twiddleImag[stageIdx] = sinTable
+      size = size shl 1
+      stageIdx++
+    }
+  }
+
+  /**
+   * In-place forward FFT over a power-of-two-length pair of real +
+   * imaginary float arrays. Throws if `real.size != imag.size`,
+   * if size is not a power of two, or if size exceeds [MAX_FFT_SIZE].
+   */
+  fun forward(real: FloatArray, imag: FloatArray) {
+    val n = real.size
+    require(n == imag.size) { "real and imag arrays must have equal length, got ${real.size} vs ${imag.size}" }
+    require(n > 0 && (n and (n - 1)) == 0) { "FFT length must be a power of two, got $n" }
+    require(n <= MAX_FFT_SIZE) { "FFT length must be <= $MAX_FFT_SIZE, got $n" }
+    if (n == 1) return
+
+    bitReversePermute(real, imag)
+
+    var size = 2
+    var stageIdx = 0
+    while (size <= n) {
+      val half = size / 2
+      val cosTable = twiddleReal[stageIdx]
+      val sinTable = twiddleImag[stageIdx]
+      var k = 0
+      while (k < n) {
+        var j = 0
+        while (j < half) {
+          val wr = cosTable[j]
+          val wi = sinTable[j]
+          val a = k + j
+          val b = a + half
+          val tr = wr * real[b] - wi * imag[b]
+          val ti = wr * imag[b] + wi * real[b]
+          real[b] = real[a] - tr
+          imag[b] = imag[a] - ti
+          real[a] = real[a] + tr
+          imag[a] = imag[a] + ti
+          j++
+        }
+        k += size
+      }
+      size = size shl 1
+      stageIdx++
+    }
+  }
+
+  /**
+   * Compute the magnitude of bins [0, n/2). Caller must have already
+   * called [forward] on (real, imag); this just walks the lower half
+   * and writes `sqrt(real² + imag²) * 2 / n` to [out].
+   *
+   * The `2/n` scaling is the standard one-sided amplitude scaling
+   * for non-DC bins. DC (bin 0) is intentionally double-scaled by
+   * the same factor — pragmatic so callers can treat every bin's
+   * magnitude with the same units; trade-off is a 2× DC overshoot
+   * vs the strict spectral interpretation. The iOS `FFTProcessor`
+   * mirrors this DC double-scaling so cross-platform magnitudes
+   * coincide.
+   */
+  fun magnitudes(real: FloatArray, imag: FloatArray, out: FloatArray) {
+    val n = real.size
+    require(out.size == n / 2) { "out array must be n/2 floats, got ${out.size} for n=$n" }
+    val scale = 2f / n
+    var k = 0
+    while (k < out.size) {
+      val r = real[k]
+      val i = imag[k]
+      out[k] = sqrt(r * r + i * i) * scale
+      k++
+    }
+  }
+
+  /**
+   * Hann window of length n. Coefficient i is
+   * `0.5 * (1 - cos(2π · i / (n - 1)))`. Pre-multiply input samples by
+   * this before [forward] to reduce spectral leakage.
+   */
+  fun hannWindow(n: Int): FloatArray {
+    require(n > 1) { "Hann window requires n >= 2, got $n" }
+    val w = FloatArray(n)
+    val denom = (n - 1).toDouble()
+    var i = 0
+    while (i < n) {
+      w[i] = (0.5 * (1.0 - cos(2.0 * PI * i / denom))).toFloat()
+      i++
+    }
+    return w
+  }
+
+  private fun bitReversePermute(real: FloatArray, imag: FloatArray) {
+    val n = real.size
+    var j = 0
+    var i = 1
+    while (i < n) {
+      var bit = n shr 1
+      while (j and bit != 0) {
+        j = j xor bit
+        bit = bit shr 1
+      }
+      j = j or bit
+      if (i < j) {
+        val tr = real[i]; real[i] = real[j]; real[j] = tr
+        val ti = imag[i]; imag[i] = imag[j]; imag[j] = ti
+      }
+      i++
+    }
+  }
+}

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

@@ -0,0 +1,81 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Cross-channel de-duplicator for remote media-button commands (Bluetooth/AVRCP,
+ * notification, lock screen, Android Auto, wired headset).
+ *
+ * A single physical press can reach the service through more than one native
+ * route — the MediaSession `onMediaButtonEvent` callback and/or a legacy
+ * `ACTION_MEDIA_BUTTON` broadcast that lands in `onStartCommand` (directly or
+ * via a manifest-registered `MediaButtonReceiver`) — and Media3 can itself
+ * deliver one event twice on a single route (androidx/media#3083). Without
+ * de-duplication those fan out into multiple skips.
+ *
+ * The de-dup keys on RECEIPT TIME and CHANNEL — deliberately NOT on
+ * `KeyEvent.downTime`, which is unreliable for synthesised Bluetooth key events
+ * (frequently a constant 0). A downTime-keyed comparison that never expires
+ * suppresses every later press forever once the first one is cached, so only
+ * the first Next/Previous over Bluetooth ever fires.
+ *
+ * Rules, per command, anchored on the last EMITTED occurrence:
+ *  - a duplicate from a DIFFERENT channel within [crossWindowMs] is one press
+ *    fanned out across routes -> suppress.
+ *  - a duplicate from the SAME channel within [sameWindowMs] is a near-instant
+ *    redelivery -> suppress.
+ *  - everything else is emitted. Distinct presses are channel-consistent and
+ *    arrive far more than a window apart, so they always pass. The anchor
+ *    advances ONLY on emit, never on a suppressed event, so a burst of
+ *    duplicates cannot keep extending the window.
+ *
+ * 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
+ * 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).
+ */
+internal class RemoteCommandDeduper(
+  private val crossWindowMs: Long = DEFAULT_CROSS_WINDOW_MS,
+  private val sameWindowMs: Long = DEFAULT_SAME_WINDOW_MS,
+) {
+  /** The native route a media-button delivery arrived on. */
+  enum class Channel {
+    /** `MediaSession.Callback.onMediaButtonEvent`. */
+    SESSION_KEY,
+
+    /** `ACTION_MEDIA_BUTTON` broadcast reaching `Service.onStartCommand`. */
+    BROADCAST,
+  }
+
+  private data class Anchor(val channel: Channel, val uptimeMs: Long)
+
+  private val lastByCommand = HashMap<String, Anchor>()
+
+  /**
+   * @param command stable identity for the resolved transport command.
+   * @param channel the native route this delivery arrived on.
+   * @param nowUptimeMs caller passes `SystemClock.uptimeMillis()` (injected for tests).
+   * @return true if [command] should be acted on; false if it is a duplicate to drop.
+   */
+  @Synchronized
+  fun shouldEmit(command: String, channel: Channel, nowUptimeMs: Long): Boolean {
+    val last = lastByCommand[command]
+    if (last != null) {
+      val elapsed = nowUptimeMs - last.uptimeMs
+      val window = if (channel == last.channel) sameWindowMs else crossWindowMs
+      // Lower bound is a defensive guard: uptime is monotonic so elapsed is
+      // never negative in practice, but a negative would emit (bias to act).
+      if (elapsed in 0 until window) return false
+    }
+    lastByCommand[command] = Anchor(channel, nowUptimeMs)
+    return true
+  }
+
+  companion object {
+    /** Broadcast vs in-process delivery skew is tens of ms, occasionally ~100. */
+    const val DEFAULT_CROSS_WINDOW_MS = 200L
+
+    /** Same-channel redelivery is near-instant; deliberate same-channel double
+     *  presses are >= ~150 ms apart, so they pass. */
+    const val DEFAULT_SAME_WINDOW_MS = 80L
+  }
+}

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

@@ -0,0 +1,84 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.C
+import androidx.media3.common.audio.AudioProcessor
+import androidx.media3.common.audio.BaseAudioProcessor
+import androidx.media3.common.util.UnstableApi
+import java.nio.ByteBuffer
+
+/**
+ * Standalone Media3 [AudioProcessor] that applies a per-track linear
+ * gain to a Float32 PCM stream. No knowledge of the engine, the EQ
+ * stage, or the visualizer pipeline — purely "given a Float32 buffer,
+ * multiply by [linearGain]". The owning engine pushes a new gain via
+ * [setLinearGain] from its `Player.Listener.onMetadata` callback;
+ * `onMediaItemTransition` resets to unity until the next metadata
+ * arrival.
+ *
+ * Float32-only by design. [AudioPipelineRenderersFactory] opts the
+ * factory into `setEnableAudioFloatOutput(true)` at construction so
+ * Media3 propagates `enableFloatOutput = true` into `buildAudioSink`,
+ * and the resulting `DefaultAudioSink` produces `ENCODING_PCM_FLOAT`.
+ * Sources decoded to Int16 PCM transit through this processor
+ * untouched via [isActive] returning `false`, matching the documented
+ * non-Float32 no-op limitation in NOTES.md §25.
+ */
+@UnstableApi
+internal class ReplayGainAudioProcessor : BaseAudioProcessor() {
+
+  /**
+   * Live linear gain. Volatile because the audio render thread reads
+   * 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.
+   */
+  @Volatile
+  private var linearGain: Float = 1.0f
+
+  /**
+   * `true` when [onConfigure] saw `ENCODING_PCM_FLOAT`. Volatile for
+   * the same render-thread / main-thread split as [linearGain].
+   */
+  @Volatile
+  private var inputIsFloat: Boolean = false
+
+  /**
+   * Push a new linear gain. `1.0f` disables the processor's per-sample
+   * multiply via [isActive].
+   */
+  fun setLinearGain(value: Float) {
+    linearGain = value
+  }
+
+  override fun onConfigure(input: AudioProcessor.AudioFormat): AudioProcessor.AudioFormat {
+    inputIsFloat = (input.encoding == C.ENCODING_PCM_FLOAT)
+    // Pass-through: this stage doesn't change rate, channel count, or
+    // encoding. Returning [AudioProcessor.AudioFormat.NOT_SET] would
+    // tell Media3 the processor consumes the stream and drops the
+    // output AudioSink, which is wrong — RG is in-place.
+    return input
+  }
+
+  override fun isActive(): Boolean =
+    super.isActive() && linearGain != 1.0f && inputIsFloat
+
+  override fun queueInput(input: ByteBuffer) {
+    val gain = linearGain
+    val byteCount = input.remaining()
+    if (byteCount == 0) return
+    val out = replaceOutputBuffer(byteCount)
+    val inF = input.asFloatBuffer()
+    val outF = out.asFloatBuffer()
+    while (inF.hasRemaining()) {
+      outF.put(inF.get() * gain)
+    }
+    input.position(input.limit())
+    // Advance the byte-level position so [getOutput] hands back a
+    // buffer with the produced bytes between position and limit. The
+    // float-view writes mutate the underlying bytes but don't move
+    // the parent ByteBuffer's position.
+    out.position(byteCount)
+    out.flip()
+  }
+}