react-native-queue-player 1.0.0

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

@@ -0,0 +1,66 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.ForwardingSimpleBasePlayer
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * `MediaSession`-stable wrapper around a [CrossfadeEngine]'s two
+ * underlying `ExoPlayer` instances.
+ *
+ * `MediaSession.Builder` binds to a single Player for its lifetime
+ * — but inside [CrossfadeEngine] the leading / standby legs swap
+ * roles at every fade midpoint. Without a forwarding wrapper the
+ * session would either stay bound to a now-standby player
+ * (lock-screen scrubber freezes mid-fade) or require a noisy
+ * `setPlayer(...)` mid-fade swap (controller reconnect glitch).
+ *
+ * `ForwardingSimpleBasePlayer` (Media3 1.4+) is the supported
+ * runtime-swappable Player base. The legacy `ForwardingPlayer`
+ * stores the wrapped player in a `private final` field that every
+ * base method reads directly — overriding `getWrappedPlayer()`
+ * does NOT route base-class calls. Use this class for any
+ * runtime-swappable Player binding.
+ *
+ * Mid-fade role swap: this wrapper invalidates its cached state
+ * via [invalidateState] so `MediaSession` consumers see the
+ * post-swap leading leg's view. Outside fade windows the wrapped
+ * delegate stays put.
+ */
+@UnstableApi
+internal class CrossfadeForwardingPlayer(
+  private val engine: CrossfadeEngine,
+) : ForwardingSimpleBasePlayer(engine.leadingPlayer) {
+
+  /**
+   * Re-target the wrapped player to the engine's new leading leg
+   * after a `CrossfadeEngine.swapRoles()` flips `currentRoleIsA`.
+   *
+   * `ForwardingSimpleBasePlayer.setPlayer(...)` is the supported
+   * runtime-swap entry point — `invalidateState()` alone only
+   * refreshes cached state from the still-bound construction-time
+   * leg. Pair `setPlayer` with `invalidateState` so the new leg's
+   * state propagates to `MediaSession` consumers immediately
+   * instead of after the next state-changing event.
+   */
+  fun onRoleSwapped() {
+    setPlayer(engine.leadingPlayer)
+    invalidateState()
+  }
+
+  /**
+   * Re-target the wrapped player to the engine's standby (incoming)
+   * leg the instant a crossfade begins. MediaSession publishes the
+   * standby leg's `MediaMetadataCompat` + `PlaybackState` so the
+   * lock-screen / Auto / BT scrubber + title/artwork flip to the
+   * incoming track from 00:00 the moment it starts audibly
+   * playing. The standby `ExoPlayer` instance becomes the new
+   * leading on `swapRoles` at fade-end, so the [onRoleSwapped]
+   * re-bind a moment later is a no-op (already pointing at the
+   * same instance).
+   */
+  fun onCrossfadeBegin() {
+    setPlayer(engine.standbyPlayer)
+    invalidateState()
+  }
+}

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

@@ -0,0 +1,100 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/**
+ * SharedPreferences-backed persistence for user-defined equalizer
+ * presets. Keys live under [PREFS_NAME] / [STORE_KEY] as a single
+ * JSON object — `{ "MyPreset": [0.0, 1.5, ...], "Studio": [...] }`
+ * — so a snapshot is one small read on the playback service main
+ * looper.
+ *
+ * Malformed JSON (manual edit, partial write across versions)
+ * resolves to an empty preset list rather than throwing — the
+ * recovery path is "user re-saves their preset" rather than a crash.
+ *
+ * Threading: SharedPreferences is documented thread-safe for
+ * individual edits, but the load-modify-write sequence in [save]
+ * and [delete] is not atomic across threads on its own. Both
+ * methods take an internal lock so concurrent writers don't drop
+ * each other's edits. Reads ([loadAll]) don't take the lock —
+ * they snapshot whatever is most recently committed.
+ *
+ * Durability: [save] uses `commit()` (synchronous fsync) so a
+ * caller that returns successfully has guaranteed on-disk state;
+ * [delete] uses `apply()` (queued write) — a lost-delete on
+ * process kill is recoverable by re-deleting.
+ */
+internal class CustomPresetStore(context: Context) {
+
+  companion object {
+    private const val PREFS_NAME = "com.queueplayer.equalizer"
+    private const val STORE_KEY = "customPresets"
+    private const val LOG_TAG = "CustomPresetStore"
+  }
+
+  private val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+  private val writeLock = Any()
+
+  /**
+   * Persist [name] → [gains]. Overwrites a same-name entry.
+   * Caller is responsible for length validation; the store does
+   * not constrain band count.
+   */
+  fun save(name: String, gains: FloatArray) {
+    synchronized(writeLock) {
+      val current = loadRaw()
+      current.put(name, gainsToJsonArray(gains))
+      prefs.edit().putString(STORE_KEY, current.toString()).commit()
+    }
+  }
+
+  /** Remove the named preset; no-op if absent. */
+  fun delete(name: String) {
+    synchronized(writeLock) {
+      val current = loadRaw()
+      if (!current.has(name)) return
+      current.remove(name)
+      prefs.edit().putString(STORE_KEY, current.toString()).apply()
+    }
+  }
+
+  /**
+   * Snapshot every persisted preset as [EqualizerPreset] (with
+   * `builtin = false`). Order is unspecified — the consumer
+   * typically merges these with the built-in list and sorts at
+   * the JS layer.
+   */
+  fun loadAll(): List<EqualizerPreset> {
+    val raw = loadRaw()
+    val result = mutableListOf<EqualizerPreset>()
+    val keys = raw.keys()
+    while (keys.hasNext()) {
+      val name = keys.next()
+      val arr = raw.optJSONArray(name) ?: continue
+      val gains = DoubleArray(arr.length()) { i -> arr.optDouble(i, 0.0) }
+      result.add(EqualizerPreset(name = name, gains = gains, builtin = false))
+    }
+    return result
+  }
+
+  private fun loadRaw(): JSONObject {
+    val stored = prefs.getString(STORE_KEY, null) ?: return JSONObject()
+    return try {
+      JSONObject(stored)
+    } catch (e: JSONException) {
+      Log.w(LOG_TAG, "Custom preset JSON failed to parse; falling back to empty store", e)
+      JSONObject()
+    }
+  }
+
+  private fun gainsToJsonArray(gains: FloatArray): JSONArray {
+    val arr = JSONArray()
+    for (g in gains) arr.put(g.toDouble())
+    return arr
+  }
+}

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

@@ -0,0 +1,348 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.os.Build
+import androidx.media3.common.C
+import androidx.media3.common.util.UnstableApi
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.Promise
+
+/**
+ * 10-band parametric equalizer HybridObject. Picks
+ * [EqualizerEngine] (API 28+, `DynamicsProcessing`) or
+ * [EqualizerLegacyEngine] (API <28, legacy `Equalizer`) at
+ * construction; consumers see a single surface regardless of
+ * backend.
+ *
+ * The engine is parameterised on the audio session ID, which
+ * arrives later from the playback service when ExoPlayer publishes
+ * its `Format`. Until then the engine buffers band gains + enabled
+ * state — JS callers can configure presets and bands freely; the
+ * configuration applies the moment the service-level attach to the
+ * session ID runs.
+ *
+ * The JS-facing methods that mutate state return `Promise<Unit>`
+ * via `Promise.async` per the spec, but each delegates to a
+ * synchronous `*Internal` method that owns the actual mutation.
+ * Unit tests target the synchronous core; the async wrapper is a
+ * JS-interface adapter and is exercised at integration via demo
+ * Maestro.
+ *
+ * Listener registries follow the same shape as other event
+ * listeners on this lib: stable numeric IDs returned via the
+ * cancel closure so individual subscribers can dispose without
+ * disturbing the others.
+ */
+@UnstableApi
+@DoNotStrip
+class Equalizer @JvmOverloads constructor(
+  /**
+   * Optional Context override for the persistent preset store.
+   * `null` (the default Nitro construction path) resolves to
+   * [NitroModules.applicationContext] at first store access.
+   * Pass an explicit Context when constructing this Hybrid
+   * outside the React Native bridge — e.g. unit tests, or a
+   * future consumer-app override that wants a different
+   * SharedPreferences scope.
+   */
+  storeContext: Context? = null,
+) : HybridEqualizerSpec() {
+
+  companion object {
+    /**
+     * The most recently constructed [Equalizer] instance.
+     * `PlaybackService` reaches for this on engine boot so it
+     * can wire `IEqualizerEngine` to ExoPlayer's audio session
+     * without threading the Hybrid reference through Nitro's
+     * JNI bridge. JS callers consume `getEqualizer()` which
+     * caches the same Hybrid singleton in `clients.ts`, so the
+     * static reference and the JS-visible instance always
+     * coincide in practice.
+     */
+    @JvmStatic
+    @Volatile
+    internal var current: Equalizer? = null
+  }
+
+  private val storeContextOverride: Context? = storeContext
+
+  /**
+   * Module-internal escape hatch so the playback service can wire
+   * the engine to ExoPlayer's audio session ID at attach time.
+   * Pure JS-facing callers must not reach for this property.
+   *
+   * Declared BEFORE the `init` block + `sessionIdSubscription` so
+   * the field initializer runs first. The init body calls
+   * `current?.unwireFromPlaybackEngine()` on the prior Equalizer
+   * instance — which dereferences that prior instance's `engine`.
+   * Kotlin runs property initializers + init blocks in source
+   * order; placing this val above `init` guarantees any
+   * fully-constructed instance always has a non-null `engine`
+   * before another construction can reach it through the static
+   * `current` pointer. Past failure: NPE on
+   * `IEqualizerEngine.detachAll()` when two Nitro Hybrid
+   * constructions raced.
+   */
+  internal val engine: IEqualizerEngine =
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+      EqualizerEngine()
+    } else {
+      EqualizerLegacyEngine()
+    }
+
+  /**
+   * Cancel closure for the engine audio-session-ID subscription
+   * installed by [wireToPlaybackEngine]. Held so a re-wire (engine
+   * swap during configure) tears the prior subscription down before
+   * resubscribing.
+   */
+  private var sessionIdSubscription: (() -> Unit)? = null
+
+  init {
+    // A second Equalizer construction (test order, hot-restart) tears
+    // the prior instance's playback wiring down before it loses the
+    // static reference — otherwise the prior instance's
+    // `sessionIdSubscription` keeps firing against a service that
+    // calls `Equalizer.current.unwire` on the new instance only.
+    current?.unwireFromPlaybackEngine()
+    current = this
+    // Late-construction recovery: same pattern as Visualizer.
+    // PlaybackService's onCreate fires `Equalizer.current?.wire(...)`
+    // unconditionally; if this Hybrid was constructed AFTER that
+    // call, the wire is silently lost. Re-wire here so the engine
+    // session-ID listener actually fires.
+    PlaybackService.activeEngine?.let { wireToPlaybackEngine(it) }
+  }
+
+  private val onBandChangeListeners = ListenerRegistry<(Array<EqualizerBand>) -> Unit>()
+  private val onEnabledChangeListeners = ListenerRegistry<(Boolean) -> Unit>()
+
+  /**
+   * Custom-preset persistence resolved lazily because
+   * [NitroModules.applicationContext] may be null on construction
+   * if the React Native runtime hasn't installed the bridge yet.
+   * Returns null when neither the override nor the Nitro bridge
+   * provides a Context — surfaces as "no custom presets" rather
+   * than a crash.
+   */
+  private val customPresetStore: CustomPresetStore? by lazy {
+    val ctx = storeContextOverride ?: NitroModules.applicationContext
+    ctx?.let { CustomPresetStore(it) }
+  }
+
+  // --- Engine lifecycle wiring ---
+
+  /**
+   * Subscribe to [playbackEngine]'s audio session ID changes.
+   * Forwards the full session-id snapshot from
+   * `PlaybackEngine.addAudioSessionIdListener` to
+   * `IEqualizerEngine.attachAll`. The engine diffs its per-session
+   * map against the new array — single-session gapless callers see
+   * one ID and one attached `DynamicsProcessing` (or legacy
+   * `Equalizer`) instance; crossfade-window callers see
+   * `[outgoing, incoming]` and the engine holds two simultaneous
+   * instances so EQ continuity survives the fade. A re-wire (e.g.
+   * configure rebuilding the playback engine) tears the prior
+   * subscription down before resubscribing so the engine
+   * reattaches cleanly.
+   *
+   * Channel count is ignored on both backends. The modern backend's
+   * `setPreEqBandAllChannelsTo` fans each band write out to every real
+   * channel of the in-effect channel array; the legacy `Equalizer`
+   * AudioEffect is session-wide.
+   */
+  internal fun wireToPlaybackEngine(playbackEngine: PlaybackEngine) {
+    unwireFromPlaybackEngine()
+    sessionIdSubscription = playbackEngine.addAudioSessionIdListener { sessionIds ->
+      // Forward the full session-id snapshot — the engine diffs
+      // its per-session map against the new array and attaches /
+      // detaches per-instance accordingly. Crossfade-window
+      // callers receive [outgoing, incoming] and the engine
+      // holds two simultaneous DynamicsProcessing instances; a
+      // single-session caller receives one ID and the engine
+      // holds exactly one.
+      val sanitised = sessionIds.filter { it != C.AUDIO_SESSION_ID_UNSET }.toIntArray()
+      engine.attachAll(sanitised)
+    }
+  }
+
+  /**
+   * Tear down any active subscription and detach the engine from
+   * every underlying audio session. Gain + enabled state survive
+   * — a subsequent [wireToPlaybackEngine] re-attaches the same
+   * configured EQ to whichever sessions are presented next.
+   */
+  internal fun unwireFromPlaybackEngine() {
+    sessionIdSubscription?.invoke()
+    sessionIdSubscription = null
+    engine.detachAll()
+  }
+
+  // --- Synchronous core ---
+
+  internal fun setEnabledInternal(enabled: Boolean) {
+    if (engine.isEnabled() == enabled) return
+    engine.setEnabled(enabled)
+    onEnabledChangeListeners.forEach { it(enabled) }
+  }
+
+  internal fun setBandGainInternal(index: Int, gainDb: Float) {
+    engine.setBandGain(index, gainDb)
+    fireBandChange()
+  }
+
+  /**
+   * Applies the gains as-is — the engine's documented contract is
+   * "extra entries past 10 are ignored, missing entries hold the
+   * previous value", so a short array partial-updates rather than
+   * zero-padding.
+   */
+  internal fun setAllBandGainsInternal(gains: FloatArray) {
+    engine.setAllBandGains(gains)
+    fireBandChange()
+  }
+
+  /**
+   * Returns `true` when the named preset existed and was applied.
+   * The async surface ([applyPreset]) translates a `false` return
+   * into an `IllegalArgumentException` so JS callers see a Promise
+   * rejection on a typo; this `Boolean` form remains available for
+   * callers that want a non-throwing apply (e.g. [resetInternal]
+   * which always passes a known-good name).
+   */
+  internal fun applyPresetInternal(name: String): Boolean {
+    val builtin = EqualizerPresets.getByName(name)
+    if (builtin != null) {
+      engine.setAllBandGains(builtin)
+      fireBandChange()
+      return true
+    }
+    val customGains = customPresetStore?.loadAll()
+      ?.firstOrNull { it.name == name }
+      ?.gains
+    if (customGains != null) {
+      val asFloats = FloatArray(customGains.size) { i -> customGains[i].toFloat() }
+      engine.setAllBandGains(asFloats)
+      fireBandChange()
+      return true
+    }
+    return false
+  }
+
+  internal fun resetInternal() {
+    applyPresetInternal("Flat")
+  }
+
+  // --- JS-facing async surface ---
+
+  override fun setEnabled(enabled: Boolean): Promise<Unit> =
+    Promise.async { 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()) }
+
+  override fun setAllBandGains(gains: DoubleArray): Promise<Unit> =
+    Promise.async {
+      val asFloats = FloatArray(gains.size) { i -> gains[i].toFloat() }
+      setAllBandGainsInternal(asFloats)
+    }
+
+  override fun applyPreset(name: String): Promise<Unit> =
+    Promise.async {
+      if (!applyPresetInternal(name)) {
+        throw IllegalArgumentException("Equalizer preset not found: $name")
+      }
+    }
+
+  override fun getPresets(): Array<EqualizerPreset> {
+    val builtin = builtinPresetsArray()
+    val custom = (customPresetStore?.loadAll() ?: emptyList())
+      .sortedBy { it.name }
+    if (custom.isEmpty()) return builtin
+    return Array(builtin.size + custom.size) { i ->
+      if (i < builtin.size) builtin[i] else custom[i - builtin.size]
+    }
+  }
+
+  /**
+   * Persist the current band gains as [name]. Overwrites a same-
+   * name custom preset. Names that collide with a built-in preset
+   * are rejected at the JS-facing [saveCustomPreset] entry point;
+   * this internal core does not re-check.
+   */
+  internal fun saveCustomPresetInternal(name: String) {
+    val store = customPresetStore ?: return
+    store.save(name, engine.getBandGains())
+  }
+
+  /** Remove the named custom preset; no-op if absent. */
+  internal fun deleteCustomPresetInternal(name: String) {
+    customPresetStore?.delete(name)
+  }
+
+  override fun saveCustomPreset(name: String): Promise<Unit> =
+    Promise.async {
+      if (EqualizerPresets.getByName(name) != null) {
+        throw IllegalArgumentException("Cannot overwrite built-in preset: $name")
+      }
+      saveCustomPresetInternal(name)
+    }
+
+  override fun deleteCustomPreset(name: String): Promise<Unit> =
+    Promise.async { deleteCustomPresetInternal(name) }
+
+  override fun reset(): Promise<Unit> = Promise.async { resetInternal() }
+
+  override fun onBandChange(
+    callback: (bands: Array<EqualizerBand>) -> Unit
+  ): () -> Unit {
+    val id = onBandChangeListeners.add(callback)
+    // Seed the new subscriber with the current snapshot so
+    // consumers don't have to call getBands first. Spec contract.
+    callback(currentBandsSnapshot())
+    return { onBandChangeListeners.remove(id) }
+  }
+
+  override fun onEnabledChange(callback: (enabled: Boolean) -> Unit): () -> Unit {
+    val id = onEnabledChangeListeners.add(callback)
+    callback(engine.isEnabled())
+    return { onEnabledChangeListeners.remove(id) }
+  }
+
+  // --- Helpers ---
+
+  private fun fireBandChange() {
+    if (onBandChangeListeners.isEmpty) return
+    val snapshot = currentBandsSnapshot()
+    onBandChangeListeners.forEach { it(snapshot) }
+  }
+
+  private fun currentBandsSnapshot(): Array<EqualizerBand> {
+    val freqs = EqualizerPresets.frequencies
+    val gains = engine.getBandGains()
+    return Array(freqs.size) { i ->
+      EqualizerBand(
+        frequencyHz = freqs[i].toDouble(),
+        gainDb = gains[i].toDouble(),
+      )
+    }
+  }
+
+  private fun builtinPresetsArray(): Array<EqualizerPreset> {
+    val names = EqualizerPresets.getNames()
+    return Array(names.size) { i ->
+      val name = names[i]
+      val gains = EqualizerPresets.getByName(name)!!
+      EqualizerPreset(
+        name = name,
+        gains = DoubleArray(gains.size) { j -> gains[j].toDouble() },
+        builtin = true,
+      )
+    }
+  }
+}