react-native-queue-player 1.0.0

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

@@ -0,0 +1,220 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.content.Intent
+import android.os.IBinder
+import android.os.PowerManager
+import android.os.PowerManager.WakeLock
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.MediaLibraryService
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactInstanceEventListener
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+import com.facebook.react.jstasks.HeadlessJsTaskContext.Companion.getInstance
+import com.facebook.react.jstasks.HeadlessJsTaskEventListener
+import java.util.concurrent.CopyOnWriteArraySet
+
+/**
+ * `MediaLibraryService` base that can also drive a JS task on cold-
+ * start. Subclasses override [getTaskConfig] to return a non-null
+ * [HeadlessJsTaskConfig] when the inbound intent should boot a JS
+ * handler (e.g. an Android Auto / Google Assistant
+ * `onPlayFromSearch` cold-wake before any Activity has started a
+ * React context). Default implementation returns `null` — the
+ * service runs as a normal `MediaLibraryService` with no JS task.
+ *
+ * The React-context lifecycle is handled here:
+ *  - If a React context already exists ([reactContext] non-null),
+ *    [startTask] schedules the headless task on it directly.
+ *  - Otherwise the service kicks the [ReactHost] into starting one
+ *    and schedules the task once `onReactContextInitialized` fires.
+ *
+ * Active JS task IDs are tracked so the service can `stopSelf` once
+ * every JS task has finished — important on devices where the OS
+ * is aggressive about reclaiming foreground services that have no
+ * remaining work.
+ *
+ * Subclasses receiving a [BroadcastReceiver]-routed intent that
+ * triggers a task should call [acquireWakeLockNow] before returning
+ * from `onReceive` so the device doesn't doze before the service
+ * binds.
+ */
+@UnstableApi
+public abstract class HeadlessJsMediaService :
+  MediaLibraryService(),
+  HeadlessJsTaskEventListener {
+
+  /**
+   * IDs of every JS task currently running for this service.
+   * Reads + writes happen from [onStartCommand] (main thread) and
+   * [onHeadlessJsTaskFinish] (also main per Headless contract);
+   * `CopyOnWriteArraySet` keeps the snapshot read in
+   * [stopSelf] cheap + lock-free.
+   */
+  internal val activeTasks: MutableSet<Int> = CopyOnWriteArraySet()
+
+  /**
+   * Latch flipped on the first task spawn so a re-entrant
+   * [onStartCommand] for the same wake doesn't double-start the JS
+   * handler. Reset is implicit — service destruction reclaims this
+   * field along with the rest of the instance.
+   */
+  private var initialized = false
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    val baseReturn = super.onStartCommand(intent, flags, startId)
+    val taskConfig = getTaskConfig(intent)
+    return if (!initialized && taskConfig != null) {
+      initialized = true
+      startTask(taskConfig)
+      // Wake intents need to be redelivered if the OS kills + restarts
+      // the service mid-spawn so the JS bridge boot completes.
+      START_REDELIVER_INTENT
+    } else {
+      // Defer to the base service's restart policy on every other
+      // path so MediaLibraryService's sticky behaviour is preserved.
+      baseReturn
+    }
+  }
+
+  /**
+   * Build a [HeadlessJsTaskConfig] for [intent] when the intent
+   * should trigger a JS-driven handler (e.g. an Auto-side
+   * `onPlayFromSearch` cold wake). Return `null` to ignore the
+   * intent at the headless layer — the service still runs as a
+   * `MediaLibraryService`, just without spawning a JS task.
+   *
+   * Default returns `null`. Subclasses override to opt in.
+   */
+  protected open fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig? = null
+
+  override fun onBind(intent: Intent?): IBinder? {
+    return super.onBind(intent)
+  }
+
+  /**
+   * Spawn [taskConfig] on the React context — creating one if the
+   * host hasn't already. Must be invoked on the UI thread; callers
+   * coming from a `BroadcastReceiver` should hop via
+   * `UiThreadUtil.runOnUiThread` first.
+   */
+  protected fun startTask(taskConfig: HeadlessJsTaskConfig) {
+    UiThreadUtil.assertOnUiThread()
+    val context = reactContext
+    if (context == null) {
+      createReactContextAndScheduleTask(taskConfig)
+    } else {
+      invokeStartTask(context, taskConfig)
+    }
+  }
+
+  private fun invokeStartTask(reactContext: ReactContext, taskConfig: HeadlessJsTaskConfig) {
+    val headlessJsTaskContext = getInstance(reactContext)
+    headlessJsTaskContext.addTaskEventListener(this)
+    UiThreadUtil.runOnUiThread {
+      val taskId = headlessJsTaskContext.startTask(taskConfig)
+      activeTasks.add(taskId)
+    }
+  }
+
+  override fun onDestroy() {
+    super.onDestroy()
+    reactContext?.let { context ->
+      val headlessJsTaskContext = getInstance(context)
+      headlessJsTaskContext.removeTaskEventListener(this)
+    }
+    wakeLock?.release()
+  }
+
+  override fun onHeadlessJsTaskStart(taskId: Int): Unit = Unit
+
+  override fun onHeadlessJsTaskFinish(taskId: Int) {
+    activeTasks.remove(taskId)
+    if (activeTasks.isEmpty()) {
+      stopSelf()
+    }
+  }
+
+  /**
+   * The host's [ReactHost]. Returns `null` when the host
+   * `Application` does not implement [ReactApplication] — production
+   * Expo / RN consumers always do; the null branch covers the
+   * Robolectric / unit-test path where the application is a stub.
+   */
+  protected val reactHost: ReactHost?
+    get() = (application as? ReactApplication)?.reactHost
+
+  /**
+   * The live [ReactContext] from the consumer app's [ReactHost], or
+   * `null` when no context has been created yet (the service kicks
+   * one off via [createReactContextAndScheduleTask] in that case) OR
+   * when the host application isn't a [ReactApplication] at all (e.g.
+   * unit-test stubs).
+   */
+  protected val reactContext: ReactContext?
+    get() = reactHost?.currentReactContext
+
+  private fun createReactContextAndScheduleTask(taskConfig: HeadlessJsTaskConfig) {
+    val host = reactHost ?: return
+    host.addReactInstanceEventListener(
+      object : ReactInstanceEventListener {
+        override fun onReactContextInitialized(context: ReactContext) {
+          invokeStartTask(context, taskConfig)
+          host.removeReactInstanceEventListener(this)
+        }
+      }
+    )
+    host.start()
+  }
+
+  public companion object {
+    /**
+     * Process-wide partial wake lock acquired before a
+     * `BroadcastReceiver`-routed task wakes the service so the
+     * device doesn't doze before [startTask] gets to bind. Reused
+     * across cold starts; released in [onDestroy].
+     */
+    @JvmStatic
+    @Volatile
+    public var wakeLock: WakeLock? = null
+
+    /**
+     * Maximum time the wake lock stays held before the OS releases
+     * it automatically. Bounds a leak if the service fails to bind
+     * + [onDestroy] never runs; comfortable headroom for the
+     * BroadcastReceiver-routed task to wake the service + cross
+     * into the foreground state where the foreground-service
+     * lifecycle takes over the keep-alive guarantee.
+     */
+    private const val WAKE_LOCK_TIMEOUT_MS: Long = 10_000
+
+    /**
+     * Hold a partial wake lock until the service can take over.
+     * Idempotent — re-entrancy from a fast double-wake holds at
+     * most one lock. Caller is responsible for ensuring the
+     * service eventually starts so [onDestroy] can release; the
+     * [WAKE_LOCK_TIMEOUT_MS] bound is the safety net for a failed
+     * start.
+     */
+    @JvmStatic
+    public fun acquireWakeLockNow(context: Context) {
+      val current = wakeLock
+      if (current != null && current.isHeld) return
+      val powerManager =
+        checkNotNull(context.getSystemService(POWER_SERVICE) as PowerManager)
+      wakeLock =
+        powerManager
+          .newWakeLock(
+            PowerManager.PARTIAL_WAKE_LOCK,
+            HeadlessJsMediaService::class.java.canonicalName
+          )
+          .also { lock ->
+            lock.setReferenceCounted(false)
+            lock.acquire(WAKE_LOCK_TIMEOUT_MS)
+          }
+    }
+  }
+}

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

@@ -0,0 +1,97 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Lifecycle + state-mutation surface shared by [EqualizerEngine]
+ * (API 28+, `DynamicsProcessing`) and [EqualizerLegacyEngine]
+ * (API <28, legacy `Equalizer`). The HybridObject in
+ * `Equalizer.kt` picks one impl on construction and routes every
+ * call through the interface; consumers never see which backend
+ * is active.
+ *
+ * Threading: methods are called from the service main looper.
+ */
+interface IEqualizerEngine {
+
+  /**
+   * Attach the engine to every session ID in [sessionIds],
+   * detaching from any session ID currently attached but no
+   * longer present in the new array. Diffing semantics so the
+   * caller can fire this method with the fresh `IntArray` from
+   * `PlaybackEngine.addAudioSessionIdListener` on every change
+   * without per-ID bookkeeping.
+   *
+   * Single-session callers pass a 1-element array. Crossfade-
+   * window callers pass the 2-element [outgoing, incoming]
+   * array; both sessions end up holding their own
+   * `DynamicsProcessing` (or legacy `Equalizer` AudioEffect)
+   * instance carrying identical band gains so EQ continuity is
+   * preserved across the fade.
+   *
+   * Returns the per-session attach result so callers can log /
+   * diagnose individual session failures. An empty input array
+   * is equivalent to [detachAll].
+   */
+  fun attachAll(sessionIds: IntArray): Map<Int, Boolean>
+
+  /**
+   * Release every active per-session instance. Band-gain +
+   * enabled state survive — a subsequent [attachAll] re-attaches
+   * the same configured EQ to whichever sessions arrive next.
+   */
+  fun detachAll()
+
+  /**
+   * Attach to a single [audioSessionId]. Convenience wrapper
+   * around [attachAll] for legacy single-session callers; the
+   * crossfade-engine path goes through [attachAll] directly.
+   *
+   * Returns `true` on success, `false` when the underlying
+   * audio-effect framework rejects the session — failure leaves
+   * the engine cleanly detached so a retry on a fresh session
+   * ID is safe.
+   *
+   * [channelCount] is ignored on both backends — modern fans
+   * out internally via `setPreEqBandAllChannelsTo`, legacy is
+   * session-wide.
+   */
+  fun attach(audioSessionId: Int, channelCount: Int = 2): Boolean =
+    attachAll(intArrayOf(audioSessionId))[audioSessionId] ?: false
+
+  /**
+   * Convenience wrapper for legacy single-session callers —
+   * equivalent to [detachAll] when only one session is held.
+   */
+  fun detach() = detachAll()
+
+  /** True when the engine is attached to at least one audio session. */
+  fun isAttached(): Boolean
+
+  /**
+   * Set the gain (dB) for [bandIndex] in [0, 10). Out-of-range
+   * indices are silently ignored. The gain is clamped to the
+   * project-wide spec range so values outside the documented spec
+   * can never reach the hardware.
+   */
+  fun setBandGain(bandIndex: Int, gainDb: Float)
+
+  /**
+   * Replace every band gain at once. Each entry is clamped to the
+   * project-wide spec range. Extra entries past 10 are ignored;
+   * missing entries leave the previous value unchanged.
+   */
+  fun setAllBandGains(gains: FloatArray)
+
+  /**
+   * Snapshot of current band gains (dB), low-to-high frequency
+   * indexed by [EqualizerPresets.frequencies]. Remains callable
+   * after [release] for telemetry / diagnostics.
+   */
+  fun getBandGains(): FloatArray
+
+  fun setEnabled(value: Boolean)
+
+  fun isEnabled(): Boolean
+
+  /** Permanent teardown — subsequent calls become no-ops. */
+  fun release()
+}

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

@@ -0,0 +1,59 @@
+package com.margelo.nitro.queueplayer
+
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Thread-safe registry of event-listener callbacks, keyed by stable
+ * numeric IDs so individual subscribers can dispose without
+ * disturbing the others.
+ *
+ * `CopyOnWriteArrayList` gives lock-free iteration during concurrent
+ * add/remove (fire rounds + register/unregister can happen on
+ * different threads); `AtomicLong` produces collision-free ids
+ * without an explicit lock.
+ *
+ * Mirrors the iOS `ListenerRegistry.swift`.
+ */
+internal class ListenerRegistry<T> {
+    private data class Entry<T>(val id: Long, val callback: T)
+
+    private val entries = CopyOnWriteArrayList<Entry<T>>()
+    private val nextId = AtomicLong(0)
+
+    /** Register a callback and return its stable ID for later removal. */
+    fun add(callback: T): Long {
+        val id = nextId.incrementAndGet()
+        entries.add(Entry(id, callback))
+        return id
+    }
+
+    /** Remove the callback with the given ID. Returns true if found. */
+    fun remove(id: Long): Boolean {
+        val entry = entries.firstOrNull { it.id == id } ?: return false
+        // Linear scan acceptable; listener counts are O(few).
+        return entries.remove(entry)
+    }
+
+    /** Remove all registered callbacks. */
+    fun clear() = entries.clear()
+
+    /** Invoke `action` for every registered callback. CopyOnWrite makes
+     * iteration safe under concurrent mutation. */
+    fun forEach(action: (T) -> Unit) {
+        for (entry in entries) action(entry.callback)
+    }
+
+    /** True when no callbacks are registered. Handy for skipping
+     * per-tick work (progress observer body) when nothing's listening. */
+    val isEmpty: Boolean get() = entries.isEmpty()
+
+    /**
+     * True when the given id is still registered. Used by deferred
+     * auto-fire paths (e.g. `onSkipCapabilityChange`) to skip the
+     * callback when the subscriber disposed between registration
+     * and the deferred fire — avoids calling into an unmounted
+     * React component's `setSnapshot`.
+     */
+    fun contains(id: Long): Boolean = entries.any { it.id == id }
+}