react-native-queue-player 1.0.0

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

@@ -0,0 +1,222 @@
+package com.margelo.nitro.queueplayer
+
+import android.media.audiofx.DynamicsProcessing
+import android.os.Build
+import android.util.Log
+import androidx.annotation.RequiresApi
+import androidx.media3.common.C
+
+/**
+ * 10-band pre-EQ for API 28+ backed by [DynamicsProcessing].
+ *
+ * The audio session ID isn't known at construction time (ExoPlayer
+ * only surfaces it once the renderers are ready), so the engine
+ * holds gain state as the source of truth and applies it to the
+ * underlying [DynamicsProcessing] instance once [attach] runs.
+ * Pre-attach mutations from JS (`setBandGain`, `setAllBandGains`,
+ * `setEnabled`) are buffered and replayed.
+ *
+ * Bands are centred on [EqualizerPresets.frequencies]; the same
+ * pre-EQ chain is applied to every channel in the source so stereo
+ * (and 5.1 / 7.1) content gets coherent processing across channels.
+ *
+ * Multi-channel sources: the [DynamicsProcessing.Config] is built
+ * with `channelCount = 1` and the framework duplicates that single-
+ * channel pre-EQ chain across every real channel of the in-effect
+ * channel array at attach time. Subsequent gain mutations call
+ * [DynamicsProcessing.setPreEqBandAllChannelsTo], which fans the
+ * updated band config out to every channel in one shot. The
+ * [attach] `channelCount` parameter is therefore ignored on this
+ * backend — retained on the interface for future per-track engines.
+ *
+ * Threading: callers serialize externally — [attach] / [detach] /
+ * [setBandGain] / [setEnabled] run from the playback engine's
+ * audio-session-id listener executor, which delivers events single-
+ * threaded. The [DynamicsProcessing] instance is not guarded by an
+ * internal lock; cross-thread mutation is the caller's concern.
+ * [release] briefly blocks while the native effect tears down (a
+ * few ms typical, longer on slow devices) — callers may dispatch
+ * off-thread if a teardown burst risks a UI hitch.
+ */
+@RequiresApi(Build.VERSION_CODES.P)
+class EqualizerEngine : IEqualizerEngine {
+
+  companion object {
+    /** `AudioEffect` priority — 0 is the default for non-privileged effect clients. */
+    private const val PRIORITY = 0
+
+    private const val BAND_COUNT = 10
+
+    /** Per project spec — UI clamps band gain into this dB range. */
+    private const val MIN_GAIN_DB = -12f
+    private const val MAX_GAIN_DB = 12f
+
+    private const val LOG_TAG = "EqualizerEngine"
+  }
+
+  private val gainsDb: FloatArray = FloatArray(BAND_COUNT)
+  private var enabled: Boolean = false
+  /**
+   * One [DynamicsProcessing] instance per attached audio session.
+   * Crossfade-window callers can hold two simultaneously
+   * (outgoing + incoming legs) so EQ continuity is preserved
+   * across the fade. Single-session callers see exactly one entry.
+   */
+  private val instances: MutableMap<Int, DynamicsProcessing> = LinkedHashMap()
+  private var released: Boolean = false
+
+  /**
+   * Diff [sessionIds] against the current per-session map:
+   * release instances whose session is no longer present, and
+   * instantiate fresh `DynamicsProcessing` instances for new
+   * sessions carrying the engine's current band gains + enabled
+   * state.
+   *
+   * Detach-before-attach ordering for the released set so the
+   * `AudioEffect` framework releases the prior session's effect
+   * before any new one binds — avoids a brief contention window
+   * where two effects share a session ID during a stale cleanup.
+   *
+   * Returns the per-session attach result (true = constructed
+   * successfully; false = framework rejection or runtime
+   * exception). Existing sessions that survived the diff are
+   * marked `true` since their instance is already valid.
+   */
+  override fun attachAll(sessionIds: IntArray): Map<Int, Boolean> {
+    if (released) return emptyMap()
+    // Drop both ExoPlayer's `C.AUDIO_SESSION_ID_UNSET` (0) and
+    // AudioManager's `ERROR` (-1) sentinels — neither is a real
+    // session ID and constructing a `DynamicsProcessing` against
+    // them throws.
+    val incoming = sessionIds
+      .filter { it != C.AUDIO_SESSION_ID_UNSET && it != android.media.AudioManager.ERROR }
+      .toSet()
+    val current = instances.keys.toSet()
+
+    // Release sessions no longer present.
+    for (gone in current - incoming) {
+      instances.remove(gone)?.release()
+    }
+
+    val results = LinkedHashMap<Int, Boolean>()
+    for (id in incoming) {
+      if (instances.containsKey(id)) {
+        results[id] = true
+        continue
+      }
+      results[id] = try {
+        val config = DynamicsProcessing.Config.Builder(
+          DynamicsProcessing.VARIANT_FAVOR_FREQUENCY_RESOLUTION,
+          /* channelCount = */ 1,
+          /* preEqInUse = */ true, /* preEqBandCount = */ BAND_COUNT,
+          /* mbcInUse = */ false, /* mbcBandCount = */ 0,
+          /* postEqInUse = */ false, /* postEqBandCount = */ 0,
+          /* limiterInUse = */ false,
+        ).build()
+        val instance = DynamicsProcessing(PRIORITY, id, config)
+        instances[id] = instance
+        applyAllBandsToInstance(instance)
+        instance.setEnabled(enabled)
+        true
+      } catch (e: RuntimeException) {
+        Log.w(LOG_TAG, "DynamicsProcessing attach failed for session $id", e)
+        false
+      }
+    }
+    return results
+  }
+
+  /**
+   * Release every per-session instance + clear the map. Band
+   * gains + enabled state survive for the next [attachAll].
+   */
+  override fun detachAll() {
+    for (instance in instances.values) instance.release()
+    instances.clear()
+  }
+
+  /** True when the engine is attached to at least one audio session. */
+  override fun isAttached(): Boolean = instances.isNotEmpty()
+
+  /**
+   * Set the gain (dB) for [bandIndex]. Out-of-range indices are
+   * silently ignored. The gain is clamped to the project-wide
+   * [MIN_GAIN_DB], [MAX_GAIN_DB] band so values outside the
+   * documented spec can never reach the hardware.
+   */
+  override fun setBandGain(bandIndex: Int, gainDb: Float) {
+    if (released) return
+    if (bandIndex < 0 || bandIndex >= BAND_COUNT) return
+    val clamped = gainDb.coerceIn(MIN_GAIN_DB, MAX_GAIN_DB)
+    gainsDb[bandIndex] = clamped
+    val freqHz = EqualizerPresets.frequencies[bandIndex].toFloat()
+    // Fan to every active session-instance so a crossfade-window
+    // EQ change applies to both legs simultaneously.
+    for (instance in instances.values) {
+      val band = instance.getPreEqByChannelIndex(0).getBand(bandIndex)
+      band.cutoffFrequency = freqHz
+      band.gain = clamped
+      band.isEnabled = true
+      // Android's framework duplicates the band config across every
+      // real channel of the in-effect channel array.
+      instance.setPreEqBandAllChannelsTo(bandIndex, band)
+    }
+  }
+
+  /**
+   * Replace every band gain at once. Each entry is clamped to the
+   * project-wide range. Extra entries past [BAND_COUNT] are
+   * ignored; missing entries leave the previous value unchanged.
+   */
+  override fun setAllBandGains(gains: FloatArray) {
+    if (released) return
+    val n = minOf(gains.size, BAND_COUNT)
+    for (i in 0 until n) {
+      gainsDb[i] = gains[i].coerceIn(MIN_GAIN_DB, MAX_GAIN_DB)
+    }
+    for (instance in instances.values) applyAllBandsToInstance(instance)
+  }
+
+  /**
+   * Snapshot of current band gains (dB), low-to-high frequency.
+   * Remains callable after [release] for telemetry / diagnostics.
+   */
+  override fun getBandGains(): FloatArray = gainsDb.copyOf()
+
+  /**
+   * Toggle the global EQ stage. The hardware effect is bypassed
+   * when disabled — gains stay configured so re-enabling restores
+   * the prior curve without a re-set.
+   */
+  override fun setEnabled(value: Boolean) {
+    if (released) return
+    enabled = value
+    for (instance in instances.values) instance.setEnabled(value)
+  }
+
+  override fun isEnabled(): Boolean = enabled
+
+  /**
+   * Permanent teardown — releases every per-session
+   * `DynamicsProcessing` instance + clears state. Subsequent
+   * calls become no-ops.
+   */
+  override fun release() {
+    if (released) return
+    released = true
+    detachAll()
+  }
+
+  private fun applyAllBandsToInstance(instance: DynamicsProcessing) {
+    val freqs = EqualizerPresets.frequencies
+    val gains = gainsDb.copyOf()
+    for (i in 0 until BAND_COUNT) {
+      // The Config.Builder constructor enables the PreEq stage; per-band
+      // `isEnabled = true` plus `setPreEqBandAllChannelsTo` is what fans
+      // each band's gain out across every real channel of the in-effect
+      // channel array.
+      val band = DynamicsProcessing.EqBand(true, freqs[i].toFloat(), gains[i])
+      instance.setPreEqBandAllChannelsTo(i, band)
+    }
+  }
+}

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

@@ -0,0 +1,213 @@
+package com.margelo.nitro.queueplayer
+
+import android.media.audiofx.Equalizer
+import android.util.Log
+import androidx.media3.common.C
+import kotlin.math.abs
+import kotlin.math.roundToInt
+
+/**
+ * 10-band pre-EQ for API <28 backed by the platform-legacy
+ * `android.media.audiofx.Equalizer`. The legacy class exposes a
+ * platform-defined number of bands (often 5, sometimes 10) at
+ * platform-defined centre frequencies — the engine queries the
+ * available bands on attach and maps each of our 10 ISO targets
+ * (see [EqualizerPresets.frequencies]) to the closest available
+ * legacy band index.
+ *
+ * Multiple of our bands may collapse onto the same legacy band
+ * when the device exposes fewer than 10 — last writer wins per
+ * legacy band, which matches the platform's own behaviour when a
+ * UI tries to drive a sparser hardware EQ from a denser model.
+ *
+ * Gain is in dB at the public surface; the legacy `Equalizer`
+ * uses millibels (1 dB = 100 mB) — conversion happens at the
+ * boundary. Range is the project-wide [MIN_GAIN_DB, MAX_GAIN_DB]
+ * regardless of what the device's own range allows; values are
+ * also clamped to the device's reported `getBandLevelRange()` to
+ * avoid IllegalArgumentException on aggressive devices.
+ *
+ * Threading: methods are called from the service main looper.
+ * [release] briefly blocks while the native effect tears down.
+ */
+class EqualizerLegacyEngine : IEqualizerEngine {
+
+  companion object {
+    private const val PRIORITY = 0
+    private const val BAND_COUNT = 10
+    private const val MIN_GAIN_DB = -12f
+    private const val MAX_GAIN_DB = 12f
+    private const val MILLIBELS_PER_DB = 100
+    private const val LOG_TAG = "EqualizerLegacyEngine"
+
+    /**
+     * Pure-function band mapping — extracted so unit tests can pin
+     * the closest-centre selection without standing up a real
+     * `Equalizer` instance. For each of our 10 ISO target
+     * frequencies, find the legacy band whose centre frequency
+     * (returned in milli-Hz by the platform `Equalizer.getCenterFreq`)
+     * is closest. Tied distances resolve to the lower band index.
+     */
+    fun mapOurBandsToLegacy(numBands: Int, getCenterFreqMHz: (Int) -> Long): IntArray {
+      val mapping = IntArray(BAND_COUNT)
+      val ourFreqsHz = EqualizerPresets.frequencies
+      for (i in 0 until BAND_COUNT) {
+        val targetMHz = ourFreqsHz[i] * 1_000L
+        var bestIdx = 0
+        var bestDist = Long.MAX_VALUE
+        for (b in 0 until numBands) {
+          val dist = abs(getCenterFreqMHz(b) - targetMHz)
+          if (dist < bestDist) {
+            bestDist = dist
+            bestIdx = b
+          }
+        }
+        mapping[i] = bestIdx
+      }
+      return mapping
+    }
+  }
+
+  /**
+   * Per-session equalizer instance + the per-device-derived
+   * mapping & gain bounds latched at attach time. Each session
+   * derives independently so AOSP-fork variance across sessions
+   * is handled correctly.
+   */
+  private data class Slot(
+    val equalizer: Equalizer,
+    val ourToLegacyBand: IntArray,
+    val deviceMinMb: Short,
+    val deviceMaxMb: Short,
+  )
+
+  private val gainsDb: FloatArray = FloatArray(BAND_COUNT)
+  private var enabled: Boolean = false
+  private val instances: MutableMap<Int, Slot> = LinkedHashMap()
+  private var released: Boolean = false
+
+  /**
+   * Diff [sessionIds] against the current per-session map.
+   * Releases instances no longer present, instantiates fresh
+   * `Equalizer` instances for new sessions carrying the engine's
+   * current band gains + enabled state. Returns per-session
+   * attach result.
+   */
+  override fun attachAll(sessionIds: IntArray): Map<Int, Boolean> {
+    if (released) return emptyMap()
+    // Drop both ExoPlayer's `C.AUDIO_SESSION_ID_UNSET` (0) and
+    // AudioManager's `ERROR` (-1) sentinels — neither is a real
+    // session ID and constructing an `Equalizer` against them throws.
+    val incoming = sessionIds
+      .filter { it != C.AUDIO_SESSION_ID_UNSET && it != android.media.AudioManager.ERROR }
+      .toSet()
+    val current = instances.keys.toSet()
+
+    for (gone in current - incoming) {
+      instances.remove(gone)?.equalizer?.release()
+    }
+
+    val results = LinkedHashMap<Int, Boolean>()
+    for (id in incoming) {
+      if (instances.containsKey(id)) {
+        results[id] = true
+        continue
+      }
+      results[id] = attachOne(id)
+    }
+    return results
+  }
+
+  private fun attachOne(audioSessionId: Int): Boolean {
+    var instance: Equalizer? = null
+    return try {
+      instance = Equalizer(PRIORITY, audioSessionId)
+      val numBands = instance.numberOfBands.toInt()
+      if (numBands <= 0) {
+        Log.w(LOG_TAG, "Equalizer reported 0 bands for session $audioSessionId; skipping attach")
+        instance.release()
+        return false
+      }
+      val range = instance.bandLevelRange
+      val mapping = mapOurBandsToLegacy(numBands) { idx ->
+        instance!!.getCenterFreq(idx.toShort()).toLong()
+      }
+      val slot = Slot(
+        equalizer = instance,
+        ourToLegacyBand = mapping,
+        deviceMinMb = range[0],
+        deviceMaxMb = range[1],
+      )
+      instances[audioSessionId] = slot
+      applyAllBandsToSlot(slot)
+      instance.enabled = enabled
+      true
+    } catch (e: RuntimeException) {
+      Log.w(LOG_TAG, "Equalizer attach failed for session $audioSessionId", e)
+      instance?.release()
+      false
+    }
+  }
+
+  override fun detachAll() {
+    for (slot in instances.values) slot.equalizer.release()
+    instances.clear()
+  }
+
+  override fun isAttached(): Boolean = instances.isNotEmpty()
+
+  override fun setBandGain(bandIndex: Int, gainDb: Float) {
+    if (released) return
+    if (bandIndex < 0 || bandIndex >= BAND_COUNT) return
+    val clamped = gainDb.coerceIn(MIN_GAIN_DB, MAX_GAIN_DB)
+    gainsDb[bandIndex] = clamped
+    for (slot in instances.values) {
+      val legacyBand = slot.ourToLegacyBand[bandIndex].toShort()
+      slot.equalizer.setBandLevel(legacyBand, dbToMillibelsClamped(clamped, slot))
+    }
+  }
+
+  override fun setAllBandGains(gains: FloatArray) {
+    if (released) return
+    val n = minOf(gains.size, BAND_COUNT)
+    for (i in 0 until n) {
+      gainsDb[i] = gains[i].coerceIn(MIN_GAIN_DB, MAX_GAIN_DB)
+    }
+    for (slot in instances.values) applyAllBandsToSlot(slot)
+  }
+
+  override fun getBandGains(): FloatArray = gainsDb.copyOf()
+
+  override fun setEnabled(value: Boolean) {
+    if (released) return
+    enabled = value
+    for (slot in instances.values) slot.equalizer.enabled = value
+  }
+
+  override fun isEnabled(): Boolean = enabled
+
+  override fun release() {
+    if (released) return
+    released = true
+    detachAll()
+  }
+
+  private fun applyAllBandsToSlot(slot: Slot) {
+    for (i in 0 until BAND_COUNT) {
+      val legacyBand = slot.ourToLegacyBand[i].toShort()
+      slot.equalizer.setBandLevel(legacyBand, dbToMillibelsClamped(gainsDb[i], slot))
+    }
+  }
+
+  /**
+   * Convert dB → millibels, then clamp to the device-reported
+   * legacy range. The device clamp is defensive: most chips report
+   * ±1500 mB but a few outliers go ±900 or ±1800 and would throw
+   * `IllegalArgumentException` on out-of-range writes.
+   */
+  private fun dbToMillibelsClamped(gainDb: Float, slot: Slot): Short {
+    val raw = (gainDb * MILLIBELS_PER_DB).roundToInt()
+    val clamped = raw.coerceIn(slot.deviceMinMb.toInt(), slot.deviceMaxMb.toInt())
+    return clamped.toShort()
+  }
+}

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

@@ -0,0 +1,45 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Built-in 10-band equalizer presets keyed by display name.
+ *
+ * 10 ISO-standard centre frequencies (Hz) span the audible spectrum
+ * from sub-bass (31) to high treble (16k). Each preset's gains array
+ * is in dB, one entry per band, ordered low-to-high to match
+ * [frequencies].
+ *
+ * Presets are stored in a [LinkedHashMap] so [getNames] returns the
+ * canonical chip-display order. The presets are read-only constants —
+ * consumer-side custom presets live in [CustomPresetStore].
+ */
+object EqualizerPresets {
+
+  val frequencies: List<Int> = listOf(
+    31, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000,
+  )
+
+  private val presets: Map<String, FloatArray> = linkedMapOf(
+    "Flat"           to floatArrayOf( 0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f),
+    "Reference"      to floatArrayOf( 4.0f,  4.0f,  2.0f,  1.0f,  0.0f,  0.0f,  2.0f,  3.0f,  1.0f, -2.0f),
+    "Bass Boost"     to floatArrayOf( 6.0f,  5.0f,  3.0f,  1.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f),
+    "Bass Reducer"   to floatArrayOf(-6.0f, -5.0f, -3.0f, -1.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f),
+    "Treble Boost"   to floatArrayOf( 0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  2.0f,  4.0f,  5.0f,  6.0f),
+    "Treble Reducer" to floatArrayOf( 0.0f,  0.0f,  0.0f,  0.0f,  0.0f,  0.0f, -2.0f, -4.0f, -5.0f, -6.0f),
+    "V-Shaped"       to floatArrayOf( 5.0f,  4.0f,  2.0f,  0.0f, -2.0f, -3.0f, -1.0f,  2.0f,  4.0f,  5.0f),
+    "Vocal Boost"    to floatArrayOf(-3.0f, -2.0f,  0.0f,  1.0f,  2.0f,  3.0f,  4.0f,  3.0f,  1.0f,  0.0f),
+    "Spoken Word"    to floatArrayOf(-6.0f, -4.0f, -2.0f,  0.0f,  2.0f,  4.0f,  4.0f,  3.0f, -1.0f, -3.0f),
+    "Late Night"     to floatArrayOf( 6.0f,  5.0f,  2.0f,  1.0f,  1.0f,  2.0f,  3.0f,  2.0f,  3.0f,  5.0f),
+    "Acoustic"       to floatArrayOf( 3.0f,  2.0f,  1.0f,  0.0f,  0.0f,  1.0f,  2.0f,  3.0f,  2.0f,  1.0f),
+    "Rock"           to floatArrayOf( 5.0f,  3.0f, -2.0f, -3.0f, -1.0f,  2.0f,  4.0f,  5.0f,  5.0f,  5.0f),
+    "Hip-Hop"        to floatArrayOf( 5.0f,  5.0f,  3.0f,  1.0f, -1.0f,  0.0f,  1.0f,  3.0f,  4.0f,  5.0f),
+    "Small Speakers" to floatArrayOf( 5.0f,  6.0f,  3.0f,  0.0f,  0.0f,  1.0f,  2.0f,  4.0f,  5.0f,  6.0f),
+    "Jazz"           to floatArrayOf( 3.0f,  2.0f,  0.0f,  1.0f,  2.0f,  1.0f,  0.0f,  1.0f,  2.0f,  3.0f),
+    "Electronic"     to floatArrayOf( 5.0f,  4.0f,  2.0f,  0.0f, -2.0f,  1.0f,  2.0f,  3.0f,  4.0f,  6.0f),
+  )
+
+  /** Returns the gain array (dB) for [name], or null if unknown. */
+  fun getByName(name: String): FloatArray? = presets[name]?.copyOf()
+
+  /** Display names in canonical chip-display order. */
+  fun getNames(): List<String> = presets.keys.toList()
+}

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

@@ -0,0 +1,173 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.C
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.audio.TeeAudioProcessor
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * Per-subscriber visualizer processor. Implements
+ * [TeeAudioProcessor.AudioBufferSink] so it can attach to the engine's
+ * `bufferSinks` accumulator and receive raw post-decode PCM frames
+ * from the audio chain (PRE the OS-level audiofx EQ, since Tee sits
+ * inside the AudioSink processor chain).
+ *
+ * Multi-channel input is mixed to mono before windowing — visualisers
+ * only ever care about the summed signal, and FFT compute scales
+ * linearly in n.
+ *
+ * Frame emission is throttled to `intervalMs` regardless of how
+ * frequently `handleBuffer` fires — the audio render thread feeds us
+ * at chunk cadence (typically a few ms apart for a 44.1 kHz stream),
+ * far faster than any visualiser needs.
+ */
+@UnstableApi
+internal class FFTProcessorTee(
+  private val fftSize: Int,
+  private val intervalMs: Int,
+  private val includeSamples: Boolean,
+  private val onFrame: (magnitudes: FloatArray, samples: FloatArray?, sampleRate: Int) -> Unit,
+) : TeeAudioProcessor.AudioBufferSink {
+
+  init {
+    require(fftSize > 1 && (fftSize and (fftSize - 1)) == 0) {
+      "fftSize must be a power of two > 1, got $fftSize"
+    }
+    require(intervalMs > 0) { "intervalMs must be > 0, got $intervalMs" }
+  }
+
+  // 2× ring so we can copy the latest fftSize-sample window without
+  // worrying about mid-window wraparound. AudioBufferSink callbacks
+  // are synchronous on the audio render thread — single-writer,
+  // single-reader, no synchronization needed. Length is a power of
+  // two so wrap is a free bitmask.
+  private val ring = FloatArray(fftSize * 2)
+  private val ringMask: Int = ring.size - 1
+  private var writeIdx = 0L
+
+  private val window = RadixTwoFFT.hannWindow(fftSize)
+  private val real = FloatArray(fftSize)
+  private val imag = FloatArray(fftSize)
+  // Output buffers handed to the consumer each emit. The consumer's
+  // contract is "build any external snapshot (e.g. ArrayBuffer)
+  // synchronously inside onFrame"; subsequent emits overwrite these
+  // arrays in place so the render-thread allocation cost stays at
+  // zero per frame.
+  private val magsOut = FloatArray(fftSize / 2)
+  private val samplesOut: FloatArray? = if (includeSamples) FloatArray(fftSize) else null
+
+  private var sampleRate: Int = 44100
+  private var channelCount: Int = 2
+  private var encoding: Int = C.ENCODING_PCM_16BIT
+  private var bytesPerFrame: Int = 4 // 2 channels × 2 bytes
+  private var bytesPerSampleCached: Int = 2
+
+  private var lastEmitNs: Long = 0L
+
+  override fun flush(sampleRateHz: Int, channelCount: Int, encoding: Int) {
+    this.sampleRate = sampleRateHz
+    this.channelCount = channelCount.coerceAtLeast(1)
+    this.encoding = encoding
+    val sampleSize = bytesPerSample(encoding)
+    this.bytesPerSampleCached = sampleSize
+    this.bytesPerFrame = sampleSize * this.channelCount
+    // Reset write index on stream change so the ring doesn't carry
+    // samples from the previous track / sample-rate config across.
+    writeIdx = 0L
+    lastEmitNs = 0L
+  }
+
+  override fun handleBuffer(buffer: ByteBuffer) {
+    if (bytesPerFrame == 0 || bytesPerSampleCached == 0) return // unsupported encoding
+    // Read via a duplicated view so the source buffer's position +
+    // byte order are not mutated. Media3 documents the input as a
+    // duplicated read-only buffer, but local-mutating it would
+    // surprise any future consumer that relied on the contract.
+    val view = buffer.duplicate().order(ByteOrder.nativeOrder())
+    val frameCount = view.remaining() / bytesPerFrame
+    var idxLo = (writeIdx and ringMask.toLong()).toInt()
+    var i = 0
+    while (i < frameCount) {
+      ring[idxLo] = readMonoSample(view)
+      idxLo = (idxLo + 1) and ringMask
+      i++
+    }
+    writeIdx += frameCount.toLong()
+
+    if (writeIdx < fftSize) return
+    val nowNs = System.nanoTime()
+    if (nowNs - lastEmitNs < intervalMs * 1_000_000L) return
+    lastEmitNs = nowNs
+
+    emitFrame()
+  }
+
+  private fun emitFrame() {
+    // Latest fftSize samples ending at writeIdx - 1.
+    val startLo = ((writeIdx - fftSize) and ringMask.toLong()).toInt()
+    var i = 0
+    while (i < fftSize) {
+      val s = ring[(startLo + i) and ringMask]
+      samplesOut?.set(i, s)
+      real[i] = s * window[i]
+      imag[i] = 0f
+      i++
+    }
+    RadixTwoFFT.forward(real, imag)
+    RadixTwoFFT.magnitudes(real, imag, magsOut)
+    // Hand the scratch buffers to the consumer; the consumer must
+    // build any persistent snapshot (e.g. an ArrayBuffer copy)
+    // synchronously inside onFrame — subsequent emits overwrite
+    // these arrays in place.
+    onFrame(magsOut, samplesOut, sampleRate)
+  }
+
+  /**
+   * Read one mono-mixed sample from the next frame in [buffer]. Pulls
+   * `channelCount` samples in the active encoding, normalises each to
+   * [-1, 1] Float32, and averages them. Buffer position advances by
+   * `bytesPerFrame`.
+   *
+   * Supported encodings: PCM_16BIT, PCM_24BIT_PACKED, PCM_32BIT,
+   * PCM_FLOAT. Other encodings advance the position without producing
+   * a sample (returns 0); the audio chain doesn't typically deliver
+   * those to AudioSink.
+   */
+  private fun readMonoSample(buffer: ByteBuffer): Float {
+    var sum = 0f
+    var ch = 0
+    while (ch < channelCount) {
+      sum += when (encoding) {
+        C.ENCODING_PCM_16BIT -> buffer.short.toFloat() / Short.MAX_VALUE.toFloat()
+        C.ENCODING_PCM_FLOAT -> buffer.float
+        C.ENCODING_PCM_32BIT -> buffer.int.toFloat() / Int.MAX_VALUE.toFloat()
+        C.ENCODING_PCM_24BIT -> read24BitPacked(buffer)
+        else -> {
+          // Skip unknown encoding: advance position by sample size guess.
+          buffer.position(buffer.position() + bytesPerSample(encoding))
+          0f
+        }
+      }
+      ch++
+    }
+    return sum / channelCount
+  }
+
+  private fun read24BitPacked(buffer: ByteBuffer): Float {
+    // Three bytes little-endian (native order on Android), sign-extend
+    // the high byte to int, normalise by 2^23.
+    val b0 = buffer.get().toInt() and 0xFF
+    val b1 = buffer.get().toInt() and 0xFF
+    val b2 = buffer.get().toInt() // sign bit
+    val v = (b2 shl 16) or (b1 shl 8) or b0
+    return v.toFloat() / 8_388_608f // 2^23
+  }
+
+  private fun bytesPerSample(encoding: Int): Int = when (encoding) {
+    C.ENCODING_PCM_16BIT -> 2
+    C.ENCODING_PCM_24BIT -> 3
+    C.ENCODING_PCM_32BIT, C.ENCODING_PCM_FLOAT -> 4
+    else -> 0
+  }
+}