react-native-queue-player 1.1.2 → 2.0.0

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

@@ -4,6 +4,7 @@ import android.content.Context
 import android.media.AudioFocusRequest
 import android.media.AudioManager
 import android.os.Build
+import android.util.Log
 import androidx.annotation.MainThread
 import androidx.annotation.RequiresApi
 import androidx.media3.common.AudioAttributes
@@ -281,24 +282,54 @@ internal class CrossfadeEngine(
     if (duckActive) userVolume * DUCK_MULTIPLIER else userVolume
 
   /**
-   * Threading: AudioManager dispatches the focus callback on the
-   * Looper attached to the main thread by default (no Handler
-   * passed to the builder), so this lands on the same dispatcher
-   * the engine expects for every other call.
+   * Set for the duration of the two `pause()` calls a focus loss makes.
+   *
+   * This engine sets `handleAudioFocus = false` and owns focus itself, so
+   * Media3 never stamps a focus pause with its audio-focus reason: `pause()`
+   * dispatches `onPlayWhenReadyChanged(false, USER_REQUEST)` inline, and the
+   * delegate stamps whatever reason the last callback carried. While this is
+   * set the leading listener reports `AUDIO_FOCUS_LOSS` instead — the reason
+   * Media3 would have used, which the delegate maps to an interruption — so a
+   * phone call does not arrive as "the user pressed pause". Reporting the
+   * loss before the pauses does not work: the state is still PLAYING then, so
+   * that report is deduplicated and the pause's own reason overwrites it.
+   */
+  private var pausingForFocusLoss = false
+
+  private fun pauseForFocusLoss() {
+    pausingForFocusLoss = true
+    try {
+      playerA.pause()
+      playerB.pause()
+    } finally {
+      pausingForFocusLoss = false
+    }
+  }
+
+  /**
+   * Threading: AudioManager dispatches the focus callback on the Looper
+   * attached to the main thread by default (no Handler passed to the
+   * builder), so this lands on the same dispatcher the engine expects for
+   * every other call.
    */
   private val focusListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
     when (focusChange) {
       AudioManager.AUDIOFOCUS_LOSS -> {
         pausedByFocusLoss = false
         duckActive = false
-        playerA.pause()
-        playerB.pause()
+        // Cancel before pausing. The fade ramp runs on wall-clock time and is
+        // not gated on isPlaying, so pausing the legs alone leaves it running
+        // through the interruption: it finishes during the call and swaps
+        // roles, and playback resumes on the wrong leg with the session
+        // pointing at the other one.
+        cancelFade()
+        pauseForFocusLoss()
       }
       AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
         pausedByFocusLoss = leadingPlayer.isPlaying
         duckActive = false
-        playerA.pause()
-        playerB.pause()
+        cancelFade()
+        pauseForFocusLoss()
       }
       AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
         // Notification ping over media etc. — Media3's
@@ -348,7 +379,6 @@ internal class CrossfadeEngine(
   private val leadingPlayerListener = object : Player.Listener {
     override fun onPlaybackStateChanged(playbackState: Int) {
       if (released) return
-      delegate?.onStateMaybeChanged(this@CrossfadeEngine, playWhenReadyReason = null)
       if (playbackState == Player.STATE_ENDED) {
         // Leading player ended naturally — if a fade was in flight
         // it didn't complete in time. Cancel the ramp, snap
@@ -357,13 +387,21 @@ internal class CrossfadeEngine(
         if (fadeJob?.isActive == true) {
           cancelFadeAndPromoteStandby()
         }
+        // End signal before the generic state callback, as in GaplessEngine.
         delegate?.onPlaybackEnded(this@CrossfadeEngine)
       }
+      delegate?.onStateMaybeChanged(this@CrossfadeEngine, playWhenReadyReason = null)
     }
 
     override fun onPlayWhenReadyChanged(playWhenReady: Boolean, reason: Int) {
       if (released) return
-      delegate?.onStateMaybeChanged(this@CrossfadeEngine, playWhenReadyReason = reason)
+      val effectiveReason =
+        if (pausingForFocusLoss && !playWhenReady) {
+          Player.PLAY_WHEN_READY_CHANGE_REASON_AUDIO_FOCUS_LOSS
+        } else {
+          reason
+        }
+      delegate?.onStateMaybeChanged(this@CrossfadeEngine, playWhenReadyReason = effectiveReason)
     }
 
     override fun onIsPlayingChanged(isPlaying: Boolean) {
@@ -374,6 +412,9 @@ internal class CrossfadeEngine(
 
     override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
       if (released) return
+      // The leg moved on: a later visit to the index whose preroll failed is
+      // a fresh visit (a repeat-all wrap, a skip back) and arms again.
+      armFailedForIndex = -1
       delegate?.onTrackTransition(this@CrossfadeEngine, reason)
     }
 
@@ -395,7 +436,22 @@ internal class CrossfadeEngine(
 
     override fun onPlayerError(error: PlaybackException) {
       if (released) return
-      delegate?.onError(this@CrossfadeEngine, error)
+      // A failure mid-fade is the outgoing track failing on its way out, and
+      // the incoming one is already prerolled and audible. Promote it, exactly
+      // as a leading leg that *ends* mid-fade does above — there is nothing
+      // worth retrying about a track that was seconds from being discarded,
+      // and rebuilding it would restart it under a ramp that is still running,
+      // leaving two legs audible.
+      if (fadeJob?.isActive == true) {
+        // Logged on the way out: a permanent failure here — a codec or a
+        // malformed container — leaves no other trace, and "the audio glitched
+        // at a track boundary" is undiagnosable without it.
+        Log.w("RNQP.CrossfadeEngine", "leading leg failed mid-fade; promoting standby", error)
+        cancelFadeAndPromoteStandby()
+        return
+      }
+      delegate?.onError(
+        this@CrossfadeEngine, error, failedIndex = leadingPlayer.currentMediaItemIndex)
     }
   }
 
@@ -419,8 +475,16 @@ internal class CrossfadeEngine(
       // decide whether to skip / retry; the leading leg keeps
       // playing.
       if (released) return
+      // Before the cancel: it clears the standby leg's items, and an empty
+      // timeline reports the masking index 0 rather than the track that
+      // failed — which would spend track 0's retry budget and name its url.
+      val failedIndex = standbyPlayer.currentMediaItemIndex
+      // The boundary keeps its own disarm marker. `cancelFade` clears
+      // `standbyArmed`, so without this the next poll tick re-arms the same
+      // failing source and keeps re-prerolling it for the rest of the track.
+      armFailedForIndex = leadingPlayer.currentMediaItemIndex
       cancelFade()
-      delegate?.onError(this@CrossfadeEngine, error)
+      delegate?.onError(this@CrossfadeEngine, error, failedIndex = failedIndex)
     }
   }
 
@@ -507,15 +571,6 @@ internal class CrossfadeEngine(
 
   // --- PlaybackEngine: lifecycle ---
 
-  override suspend fun prepare(
-    mediaItems: List<MediaItem>,
-    startIndex: Int,
-    startPositionMs: Long,
-  ) {
-    leadingPlayer.setMediaItems(mediaItems, startIndex, startPositionMs)
-    leadingPlayer.prepare()
-  }
-
   override fun release() {
     if (released) return
     released = true
@@ -524,7 +579,7 @@ internal class CrossfadeEngine(
     // state, so a mid-fade revert emit here would surface a
     // spurious onTrackChange to the OUTGOING leg of a fade that
     // the consumer no longer cares about.
-    cancelFade(emitRevert = false)
+    cancelFade(emitRevert = false, rebindWrapper = false)
     stopArmingPoll()
     audioManager.abandonAudioFocusRequest(focusRequest)
     // [leadingPlayerListener] / [standbyPlayerListener] are
@@ -573,18 +628,33 @@ internal class CrossfadeEngine(
     // [standbyArmed] could remain true against an empty / unrelated
     // queue and [maybeArmCrossfade] would early-return forever.
     standbyArmed = false
+    armFailedForIndex = -1
     leadingPlayer.setMediaItems(items, startIndex, startPositionMs)
     leadingPlayer.prepare()
     standbyPlayer.stop()
     standbyPlayer.clearMediaItems()
     standbyPlayer.volume = 0f
     // Empty queue — no boundaries to arm. Stop the poll until
-    // play() restarts it.
+    // play() restarts it, and park the leg: draining is not pausing, so
+    // `playWhenReady` would otherwise carry into the next queue seated here.
     if (items.isEmpty()) {
       stopArmingPoll()
+      leadingPlayer.pause()
     }
   }
 
+  override fun settlePendingFade() {
+    // `emitRevert = true`: the caller keeps playing what the leading leg holds
+    // rather than seating a new active track, so without the revert the audio
+    // returns to the outgoing track while the canonical index still names the
+    // incoming one, and no track change follows to correct it.
+    cancelFade(emitRevert = true)
+  }
+
+  override fun settlePendingFadeByPromoting() {
+    if (fadeJob?.isActive == true) cancelFadeAndPromoteStandby()
+  }
+
   override fun addMediaItems(items: List<MediaItem>, insertBefore: Int) {
     // Queue mutation invalidates the standby leg's pre-loaded
     // future. Cancel any in-flight fade before mutating the
@@ -593,17 +663,22 @@ internal class CrossfadeEngine(
     // emitRevert=false: the TrackPlayer mutation body recomputes the
     // canonical index, so a mid-fade revert here would clobber it.
     cancelFade(emitRevert = false)
+    // The failed-preroll marker is an index; after a mutation it may name a
+    // different track.
+    armFailedForIndex = -1
     leadingPlayer.addMediaItems(insertBefore, items)
   }
 
   override fun removeMediaItems(indices: IntArray) {
     cancelFade(emitRevert = false)
+    armFailedForIndex = -1
     val sorted = indices.toMutableList().apply { sortDescending() }
     for (i in sorted) leadingPlayer.removeMediaItem(i)
   }
 
   override fun moveMediaItem(fromIndex: Int, toIndex: Int) {
     cancelFade(emitRevert = false)
+    armFailedForIndex = -1
     leadingPlayer.moveMediaItem(fromIndex, toIndex)
   }
 
@@ -826,13 +901,58 @@ internal class CrossfadeEngine(
     recomputeLegFromConfig(isA = false)
   }
 
+  /**
+   * Resolves the consumer's ReplayGain claim over the queue entry at a
+   * given index. Installed by [TrackPlayer] at engine construction and
+   * invoked on every read rather than cached: a `setQueue` carrying
+   * corrected values then takes effect at the next recompute, with no
+   * cache to invalidate at the wrong moment.
+   *
+   * A `null` return means the consumer supplied nothing for that entry
+   * and the file's own tags stand. A non-null result with a `null`
+   * [SuppliedReplayGain.data] means the consumer claimed the track and
+   * gave nothing usable — a different state, and one the merge has to
+   * be able to tell apart.
+   */
+  internal var suppliedReplayGainResolver: ((Int) -> SuppliedReplayGain?)? = null
+
+  /**
+   * The ReplayGain a leg's current item actually plays with: the
+   * consumer's claim where there is one, that leg's cached tags
+   * otherwise. Every read of ReplayGain on this engine goes through
+   * here, so the merge lands before the first value reaches the audio
+   * or a listener.
+   *
+   * Per leg, because each leg holds its own item and its own processor.
+   * The index is that leg's own `currentMediaItemIndex`, which is
+   * meaningful for both legs: [armCrossfade] loads the FULL queue onto
+   * standby rather than the tail, so both legs count in the same global
+   * index space as the consumer-supplied queue.
+   */
+  private fun effectiveReplayGainData(isA: Boolean): ReplayGainData? {
+    val player = if (isA) playerA else playerB
+    val cached = if (isA) cachedReplayGainDataA else cachedReplayGainDataB
+    // An empty timeline reports index 0, which would name the first
+    // queue entry for a leg holding no items at all — the standby leg
+    // before it is armed. Nothing is claimed until there is an item for
+    // the index to mean something.
+    val supplied = if (player.mediaItemCount == 0) null
+                   else suppliedReplayGainResolver?.invoke(player.currentMediaItemIndex)
+    return ReplayGainData.merge(
+      suppliedClaimed = supplied != null,
+      supplied = supplied?.data,
+      detected = cached,
+    )
+  }
+
   @MainThread
   private fun recomputeLegFromConfig(isA: Boolean) {
     val mode = ReplayGainConfig.getMode()
+    val gain = computeLinearGain(effectiveReplayGainData(isA), mode)
     if (isA) {
-      replayGainProcessorA.setLinearGain(computeLinearGain(cachedReplayGainDataA, mode))
+      replayGainProcessorA.setLinearGain(gain)
     } else {
-      replayGainProcessorB.setLinearGain(computeLinearGain(cachedReplayGainDataB, mode))
+      replayGainProcessorB.setLinearGain(gain)
     }
   }
 
@@ -862,18 +982,19 @@ internal class CrossfadeEngine(
   }
 
   /**
-   * Snapshot the LEADING leg's cached [ReplayGainData] for the
+   * Snapshot the ReplayGain the LEADING leg's item plays with, for the
    * [NowPlayingFormatExtractor] surface. The active item from JS's
    * point of view is always the leading leg's current item except
    * during the fade window — at which point [activePlayer] flips to
-   * standby and this read should follow. Returns `null` when no
-   * usable RG tags have been parsed yet for the active leg's track.
+   * standby and this read should follow. Returns `null` when nothing is
+   * supplied for the active leg's track and no usable RG tags have been
+   * parsed for it either.
    */
   override fun currentReplayGainData(): ReplayGainData? =
-    if (activePlayer === playerA) cachedReplayGainDataA else cachedReplayGainDataB
+    effectiveReplayGainData(isA = activePlayer === playerA)
 
   /**
-   * `true` when the active leg's cached data carries a tag for the
+   * `true` when the active leg's ReplayGain carries a tag for the
    * current [ReplayGainConfig.getMode]. Used by the NowPlayingFormat
    * path to populate `replayGainActive`.
    */
@@ -932,37 +1053,43 @@ internal class CrossfadeEngine(
     return null
   }
 
-  // --- PlaybackEngine: handoff ---
-
-  override suspend fun handoff(to: PlaybackEngine, atTrackBoundary: Boolean) {
-    // Engine handoff (gapless ↔ crossfade swap at TrackPlayer
-    // level) is wired in the swapEngine path on PlaybackService
-    // alongside this engine's own boundary detection. The
-    // crossfade-to-other-engine handoff lives at PlaybackService
-    // because TrackPlayer holds the canonical queue model that
-    // the receiving engine needs.
-    throw NotImplementedError(
-      "PlaybackEngine.handoff is driven by PlaybackService.swapEngine; do not call directly"
-    )
-  }
-
   // --- Fade orchestration ---
 
   /**
-   * Cancel any in-flight fade and snap the leading leg back to
-   * full volume + drop the standby leg's item. Called from manual
-   * skip / pause / seek paths and the route-degradation callback.
+   * Cancel any in-flight fade and snap the leading leg back to full volume +
+   * drop the standby leg's item. Called from manual skip / pause / seek paths
+   * and the route-degradation callback. [emitRevert] controls the JS-facing
+   * revert only. Re-binding the MediaSession wrapper is not optional and is
+   * governed by [rebindWrapper], which only [release] clears — see the note on
+   * the revert block below.
    */
-  internal fun cancelFade(emitRevert: Boolean = true) {
+  internal fun cancelFade(emitRevert: Boolean = true, rebindWrapper: Boolean = true) {
     val job = fadeJob
     val wasMidFade = job?.isActive == true
     val leadingIdx = leadingPlayer.currentMediaItemIndex
     fadeJob = null
     job?.cancel()
+    // Disarm as well as cancel. [standbyArmed] is what stops
+    // [maybeArmCrossfade] arming twice for one track, so leaving it set
+    // after a cancel means it stays set for the rest of the session: every later
+    // arm attempt returns early and each boundary becomes a hard cut, with
+    // nothing surfaced and no way back except a seek, skip or new queue.
+    // Cancelling before the preroll settles leaves it set with no fade job
+    // to clear it, which is the window a pause lands in.
+    standbyArmed = false
     leadingPlayer.volume = userVolume
     standbyPlayer.volume = 0f
     standbyPlayer.stop()
     standbyPlayer.clearMediaItems()
+    if (wasMidFade && rebindWrapper) {
+      // Re-bind first and unconditionally. A mid-fade cancel stops and clears
+      // the standby leg, but the fade's start already pointed the session at
+      // it, so leaving the binding alone hands the lock screen, notification,
+      // AVRCP and Android Auto a player with no items — a blank surface and a
+      // dead scrubber while audio continues on the leading leg. This is
+      // independent of whether JS wants a revert event.
+      onCrossfadeCancel?.invoke()
+    }
     if (wasMidFade && emitRevert) {
       // Mid-fade cancel: fade-start fired `onCrossfadeBegin` →
       // delegate moved JS-facing state to the incoming leg. Revert
@@ -976,7 +1103,6 @@ internal class CrossfadeEngine(
       // track state, so an intermediate revert here would surface
       // a spurious onTrackChange to the OUTGOING leg of a fade
       // the consumer no longer cares about).
-      onCrossfadeCancel?.invoke()
       delegate?.onCrossfadeCancel(this, leadingIdx)
     }
   }
@@ -1057,7 +1183,7 @@ internal class CrossfadeEngine(
     // listener (which forwards onTrackTransition / onPlaybackStateChanged
     // / onIsPlayingChanged / onPlayerError to the engine delegate)
     // fires from the player that's now leading. Without this the
-    // listeners stay glued to playerA / playerB and post-swap events
+    // listeners stay attached to playerA / playerB and post-swap events
     // route to the wrong listener, swallowing track transitions on
     // the new leading leg.
     //
@@ -1117,6 +1243,14 @@ internal class CrossfadeEngine(
     armingJob = null
   }
 
+  /**
+   * The leading index whose standby preroll failed. Arming is skipped for
+   * that boundary so one failing source is not re-prerolled on every poll
+   * tick; cleared when the leading leg transitions and on every queue
+   * mutation, since the index is only meaningful for this visit to it.
+   */
+  private var armFailedForIndex: Int = -1
+
   /**
    * Decide whether to arm the standby preroll + run the fade based
    * on the leading leg's current position relative to its
@@ -1125,6 +1259,7 @@ internal class CrossfadeEngine(
    */
   private fun maybeArmCrossfade() {
     if (standbyArmed) return
+    if (leadingPlayer.currentMediaItemIndex == armFailedForIndex) return
     if (fadeJob?.isActive == true) return
     if (!leadingPlayer.isPlaying) return
     if (crossfadeDurationMs <= 0L) return
@@ -1252,8 +1387,8 @@ internal class CrossfadeEngine(
     // forwarding wrapper to the standby `ExoPlayer` so MediaSession's
     // auto-published metadata + scrubber flip to the incoming
     // track from 00:00 the moment it begins audibly playing. Then
-    // notify the delegate to fire JS-facing `onTrackChange` +
-    // refresh `MediaSessionCompat` extras.
+    // notify the delegate to fire JS-facing `onTrackChange`, refresh the
+    // now-playing format and recompute skip capability.
     onCrossfadeBegin?.invoke()
     delegate?.onCrossfadeBegin(this, incomingIdx)
   }

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

@@ -7,6 +7,8 @@ import androidx.media3.common.util.UnstableApi
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
 
 /**
  * 10-band parametric equalizer HybridObject. Picks
@@ -182,7 +184,11 @@ class Equalizer @JvmOverloads constructor(
   internal fun setEnabledInternal(enabled: Boolean) {
     if (engine.isEnabled() == enabled) return
     engine.setEnabled(enabled)
-    onEnabledChangeListeners.forEach { it(enabled) }
+    // Emit what the engine committed, not what was asked for: a released
+    // engine drops the call, and `onEnabledChange` registration replays
+    // `engine.isEnabled()`, so emitting the request here would hand
+    // subscribers a value `isEnabled()` contradicts.
+    onEnabledChangeListeners.forEach { it(engine.isEnabled()) }
   }
 
   internal fun setBandGainInternal(index: Int, gainDb: Float) {
@@ -233,26 +239,36 @@ class Equalizer @JvmOverloads constructor(
   }
 
   // --- JS-facing async surface ---
+  //
+  // Every mutation of the engine runs on the main looper: `attachAll` is
+  // driven there by the playback engine's session-id listener, and running
+  // the setters on the `Promise.async` pool alongside it let a setter iterate
+  // an instance the looper had just released, two setters interleave their
+  // band writes, or a setter miss an instance an attach was inserting. One
+  // executor for all of it closes those.
 
   override fun setEnabled(enabled: Boolean): Promise<Unit> =
-    Promise.async { setEnabledInternal(enabled) }
+    Promise.async { withContext(Dispatchers.Main.immediate) { setEnabledInternal(enabled) } }
 
   override fun isEnabled(): Boolean = engine.isEnabled()
 
   override fun getBands(): Array<EqualizerBand> = currentBandsSnapshot()
 
   override fun setBandGain(index: Double, gainDb: Double): Promise<Unit> =
-    Promise.async { setBandGainInternal(index.toInt(), gainDb.toFloat()) }
+    Promise.async {
+      withContext(Dispatchers.Main.immediate) { setBandGainInternal(index.toInt(), gainDb.toFloat()) }
+    }
 
   override fun setAllBandGains(gains: DoubleArray): Promise<Unit> =
     Promise.async {
       val asFloats = FloatArray(gains.size) { i -> gains[i].toFloat() }
-      setAllBandGainsInternal(asFloats)
+      withContext(Dispatchers.Main.immediate) { setAllBandGainsInternal(asFloats) }
     }
 
   override fun applyPreset(name: String): Promise<Unit> =
     Promise.async {
-      if (!applyPresetInternal(name)) {
+      val applied = withContext(Dispatchers.Main.immediate) { applyPresetInternal(name) }
+      if (!applied) {
         throw IllegalArgumentException("Equalizer preset not found: $name")
       }
     }
@@ -288,13 +304,17 @@ class Equalizer @JvmOverloads constructor(
       if (EqualizerPresets.getByName(name) != null) {
         throw IllegalArgumentException("Cannot overwrite built-in preset: $name")
       }
-      saveCustomPresetInternal(name)
+      // The gains are read on the looper that writes them; the `commit` to
+      // preferences stays off it.
+      val gains = withContext(Dispatchers.Main.immediate) { engine.getBandGains() }
+      customPresetStore?.save(name, gains)
     }
 
   override fun deleteCustomPreset(name: String): Promise<Unit> =
     Promise.async { deleteCustomPresetInternal(name) }
 
-  override fun reset(): Promise<Unit> = Promise.async { resetInternal() }
+  override fun reset(): Promise<Unit> =
+    Promise.async { withContext(Dispatchers.Main.immediate) { resetInternal() } }
 
   override fun onBandChange(
     callback: (bands: Array<EqualizerBand>) -> Unit

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

@@ -5,6 +5,7 @@ import android.os.Build
 import android.util.Log
 import androidx.annotation.RequiresApi
 import androidx.media3.common.C
+import java.util.concurrent.ConcurrentHashMap
 
 /**
  * 10-band pre-EQ for API 28+ backed by [DynamicsProcessing].
@@ -29,11 +30,16 @@ import androidx.media3.common.C
  * [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.
+ * Threading: not serialised. [attachAll] / [detachAll] run on the
+ * service main looper from the audio-session-id listener, and on the
+ * thread constructing an [Equalizer] (its init wires the engine, and
+ * the listener registration replays the current session ids
+ * synchronously). [setBandGain] / [setAllBandGains] / [setEnabled] run
+ * on the `Promise.async` pool, so two JS calls may run concurrently;
+ * [isEnabled] / [getBandGains] run synchronously on the JS thread.
+ * `instances` is a `ConcurrentHashMap` and the flags are `@Volatile`,
+ * which rules out structural corruption and stale reads. What remains
+ * is documented on the fields.
  * [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.
@@ -54,16 +60,26 @@ class EqualizerEngine : IEqualizerEngine {
     private const val LOG_TAG = "EqualizerEngine"
   }
 
+  // Written by the setters and by attach, all on the main looper:
+  // `Equalizer` hops every JS-facing mutation there, and the playback
+  // engine's session-id listener drives attach there. Nothing touches
+  // this off the looper.
   private val gainsDb: FloatArray = FloatArray(BAND_COUNT)
-  private var enabled: Boolean = false
+  @Volatile 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.
+   * Iteration order is never relied on: the attach diff is set
+   * arithmetic and every other loop applies one operation per entry.
+   * Inserts use `putIfAbsent` and removals go through `remove`, so two
+   * attaches racing on one session release the loser instead of
+   * leaking it, and a detach cannot drop an instance inserted between
+   * its iteration and its clear.
    */
-  private val instances: MutableMap<Int, DynamicsProcessing> = LinkedHashMap()
-  private var released: Boolean = false
+  private val instances: MutableMap<Int, DynamicsProcessing> = ConcurrentHashMap()
+  @Volatile private var released: Boolean = false
 
   /**
    * Diff [sessionIds] against the current per-session map:
@@ -104,6 +120,7 @@ class EqualizerEngine : IEqualizerEngine {
         results[id] = true
         continue
       }
+      var instance: DynamicsProcessing? = null
       results[id] = try {
         val config = DynamicsProcessing.Config.Builder(
           DynamicsProcessing.VARIANT_FAVOR_FREQUENCY_RESOLUTION,
@@ -113,13 +130,18 @@ class EqualizerEngine : IEqualizerEngine {
           /* postEqInUse = */ false, /* postEqBandCount = */ 0,
           /* limiterInUse = */ false,
         ).build()
-        val instance = DynamicsProcessing(PRIORITY, id, config)
-        instances[id] = instance
+        instance = DynamicsProcessing(PRIORITY, id, config)
         applyAllBandsToInstance(instance)
         instance.setEnabled(enabled)
+        // Insert only once the instance is fully configured, so a throw
+        // above leaves no entry for isAttached() to report. A concurrent
+        // attach that got here first keeps its instance; ours is released.
+        val existing = instances.putIfAbsent(id, instance)
+        if (existing != null) instance.release()
         true
       } catch (e: RuntimeException) {
         Log.w(LOG_TAG, "DynamicsProcessing attach failed for session $id", e)
+        instance?.release()
         false
       }
     }
@@ -131,8 +153,7 @@ class EqualizerEngine : IEqualizerEngine {
    * gains + enabled state survive for the next [attachAll].
    */
   override fun detachAll() {
-    for (instance in instances.values) instance.release()
-    instances.clear()
+    for (id in instances.keys) instances.remove(id)?.release()
   }
 
   /** True when the engine is attached to at least one audio session. */