react-native-queue-player 1.0.0

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

@@ -0,0 +1,70 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.Player
+
+/**
+ * Pure-Kotlin translator from ExoPlayer's `(playbackState,
+ * isPlaying, playWhenReady, playbackSuppressionReason, hasTracks,
+ * currentTrackIndex)` tuple to the library's [PlayerState] enum.
+ *
+ * Extracted from [TrackPlayer.getStateInternal] so every branch is
+ * unit-testable without a live ExoPlayer. Matches the pattern of
+ * [QueueSkipArithmetic] + [QueueMutationArithmetic] — TrackPlayer
+ * is a thin adapter that reads the live player's state and
+ * delegates the translation here.
+ */
+internal object TransportStateTranslator {
+
+  /**
+   * Translate a full ExoPlayer state snapshot into [PlayerState].
+   *
+   * - No tracks loaded ([hasTracks] false OR [currentTrackIndex]
+   *   `< 0`) → `NONE`. Pre-empts the raw `playbackState` read
+   *   because Media3 can briefly retain `STATE_ENDED` after
+   *   `setMediaItems(emptyList())` until the player transitions
+   *   itself to idle.
+   * - `STATE_IDLE` (with tracks) → `PAUSED` (iOS parity —
+   *   paused-with-queue vs nothing-loaded are different user-
+   *   observable states).
+   * - `STATE_BUFFERING` → `BUFFERING`.
+   * - `STATE_READY` + `isPlaying` → `PLAYING`.
+   * - `STATE_READY` + `playWhenReady` + non-zero suppression
+   *   reason → `BUFFERING` (transient focus-loss / unsuitable-
+   *   output stall; iOS parity via
+   *   `AVPlayer.waitingToPlayAtSpecifiedRate`).
+   * - `STATE_READY` otherwise → `PAUSED`.
+   * - `STATE_ENDED` → `ENDED`.
+   * - unknown playbackState → `NONE` (defensive total; Media3 may
+   *   add future states).
+   */
+  fun translate(
+    playbackState: Int,
+    isPlaying: Boolean,
+    playWhenReady: Boolean,
+    playbackSuppressionReason: Int,
+    hasTracks: Boolean,
+    currentTrackIndex: Int
+  ): PlayerState {
+    // Lib canonical state takes precedence over the underlying
+    // ExoPlayer's `playbackState`. After `clearQueue` the player
+    // can briefly retain `STATE_ENDED` (Media3 doesn't auto-
+    // transition to `STATE_IDLE` when the playlist drains via
+    // `setMediaItems(emptyList())`), so reading the raw
+    // `playbackState` would surface `ENDED` for an empty queue.
+    // The library-facing contract is: nothing loaded → `NONE`.
+    if (!hasTracks || currentTrackIndex < 0) return PlayerState.NONE
+    return when (playbackState) {
+      Player.STATE_IDLE -> PlayerState.PAUSED
+      Player.STATE_BUFFERING -> PlayerState.BUFFERING
+      Player.STATE_READY -> when {
+        isPlaying -> PlayerState.PLAYING
+        playWhenReady &&
+          playbackSuppressionReason != Player.PLAYBACK_SUPPRESSION_REASON_NONE ->
+          PlayerState.BUFFERING
+        else -> PlayerState.PAUSED
+      }
+      Player.STATE_ENDED -> PlayerState.ENDED
+      else -> PlayerState.NONE
+    }
+  }
+}

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

@@ -0,0 +1,9 @@
+package com.margelo.nitro.queueplayer
+
+internal object UrlSchemes {
+  /** Returns true for http(s) URLs; false for file/data/content/asset etc. */
+  fun isRemote(url: String): Boolean {
+    val lower = url.lowercase()
+    return lower.startsWith("http://") || lower.startsWith("https://")
+  }
+}

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

@@ -0,0 +1,35 @@
+package com.margelo.nitro.queueplayer
+
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * Process-wide store for `PlayerConfig.visualizationEnabled`. Written
+ * by `TrackPlayer.configureInternal` on every configure call (per the
+ * universal auto-destroy contract every configure rebuilds the engine,
+ * so the engine's field-init read at construction time always picks up
+ * the latest flag).
+ *
+ * - `GaplessEngine` / `CrossfadeEngine` read `isEnabled()` at field-init
+ *   to decide whether the renderers factory wires a
+ *   `MultiplexingAudioBufferSink` Tee through
+ *   `AudioPipelineRenderersFactory` (enabled, default) or omits it
+ *   (disabled — no Tee in the AudioSink chain, no `RadixTwoFFT`
+ *   allocation).
+ * - `Visualizer.subscribe(...)` reads `isEnabled()` to decide whether to
+ *   register the subscription or fire `onError(visualizationDisabled)`
+ *   immediately.
+ *
+ * `AtomicBoolean` covers concurrent reads from the JS bridge thread
+ * (subscribe) and writes from the main thread (configure). The pattern
+ * mirrors iOS's stateLock-covered `visualizationEnabled` on
+ * `AudioTapProvider`.
+ */
+internal object VisualizationGate {
+  private val enabledFlag = AtomicBoolean(true)
+
+  fun isEnabled(): Boolean = enabledFlag.get()
+
+  fun setEnabled(value: Boolean) {
+    enabledFlag.set(value)
+  }
+}

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

@@ -0,0 +1,240 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.ArrayBuffer
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * FFT extractor HybridObject. Each subscribe call attaches a
+ * per-subscription [FFTProcessorTee] to the active playback engine's
+ * `bufferSinks` accumulator; Tee callbacks fire on the audio render
+ * thread, marshal frames as Nitro [ArrayBuffer]s, and fire onFrame on
+ * the JS-bridge thread.
+ *
+ * Lifecycle mirrors the Equalizer hybrid: the static `current`
+ * reference plus `wireToPlaybackEngine` / `unwireFromPlaybackEngine`
+ * lets `PlaybackService` rewire the visualizer to the active engine
+ * across configure() rebuilds + crossfade engine swaps without
+ * threading the Hybrid reference through Nitro's JNI bridge.
+ *
+ * Subscribers attached BEFORE wireToPlaybackEngine queue locally and
+ * attach the moment the engine arrives. Subscribers added AFTER the
+ * engine is wired attach immediately. Detach cleanly handles either
+ * state.
+ */
+@UnstableApi
+@DoNotStrip
+class Visualizer : HybridVisualizerSpec() {
+
+  companion object {
+    /**
+     * The most recently constructed [Visualizer] instance.
+     * `PlaybackService` reaches for this on engine boot to rewire
+     * the FFT pipeline to the active engine. JS callers consume
+     * `getVisualizer()` 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: Visualizer? = null
+  }
+
+  private data class Subscription(
+    val id: Long,
+    val processor: FFTProcessorTee,
+    // Flipped true by the disposer before it detaches the sink. Every queued
+    // emit task checks it, so frames already marshaled onto the emit executor
+    // are dropped instead of firing onFrame after dispose() returned.
+    val disposed: AtomicBoolean,
+  )
+
+  private val subscriptions = CopyOnWriteArrayList<Subscription>()
+  private val nextSubscriptionId = AtomicLong(1L)
+
+  /**
+   * Single-threaded executor that runs every JS-bridge `onFrame` call.
+   * The render thread builds a fresh ArrayBuffer per emit (which copies
+   * out of the processor's scratch arrays) and posts the bridge call
+   * here so a slow JS handler cannot back-pressure audio output.
+   * Daemon thread — dies with the process; no explicit shutdown.
+   */
+  private val emitExecutor = Executors.newSingleThreadExecutor { r ->
+    Thread(r, "rnqp-visualizer-emit").apply { isDaemon = true }
+  }
+
+  private val engineWireLock = Any()
+
+  @Volatile
+  private var engine: PlaybackEngine? = null
+
+  init {
+    // Mirror Equalizer pattern: a second Visualizer construction tears
+    // the prior instance's playback wiring down before it loses the
+    // static reference, so its sink-dispatching processors don't keep
+    // firing into JS callbacks bound to a torn-down JS context.
+    current?.let {
+      it.unwireFromPlaybackEngine()
+      it.disposeAllSubscriptions()
+    }
+    current = this
+    // Late-construction recovery: if the PlaybackService already has
+    // an active engine, wire to it now. Without this, a Hybrid
+    // constructed AFTER service onCreate's `Visualizer.current?` no-op
+    // wire never receives any engine reference, and subscribers added
+    // through `subscribe()` never reach the engine's bufferSinks.
+    // Guarded by `engineWireLock` so a concurrent service-side
+    // `swapEngineInternal` cannot swap `activeEngine` between the read
+    // and the wire.
+    synchronized(engineWireLock) {
+      PlaybackService.activeEngine?.let { wireToPlaybackEngine(it) }
+    }
+  }
+
+  override fun subscribe(
+    config: VisualizerConfig,
+    onFrame: (frame: VisualizerFrame) -> Unit,
+    onError: (reason: VisualizerErrorReason) -> Unit,
+  ): () -> Unit {
+    // Pin-at-configure visualization-disabled gate. The flag is
+    // written by `TrackPlayer.configureInternal` from
+    // `PlayerConfig.visualizationEnabled`. When false, fire onError
+    // on the emit executor (matches the cross-thread JS dispatch
+    // shape used for normal frames) and return a no-op dispose; the
+    // subscription is not registered, so `getSubscriberCount()`
+    // stays accurate.
+    if (!VisualizationGate.isEnabled()) {
+      emitExecutor.execute {
+        onError(VisualizerErrorReason.VISUALIZATION_DISABLED)
+      }
+      return { /* no-op dispose */ }
+    }
+    val fftSize = config.fftSize.toInt()
+    val intervalMs = config.updateIntervalMs.toInt()
+    val includeSamples = config.includeSamples ?: false
+
+    // Set by the disposer; read inside the emit closure so a frame already
+    // queued on the single-threaded executor at dispose time is dropped
+    // instead of crossing the JS bridge after the subscription is gone.
+    val disposed = AtomicBoolean(false)
+
+    val processor = FFTProcessorTee(
+      fftSize = fftSize,
+      intervalMs = intervalMs,
+      includeSamples = includeSamples,
+    ) { magnitudes, samples, sampleRate ->
+      // Render thread: copy the scratch arrays into ArrayBuffers
+      // immediately — the ArrayBuffer carries an independent direct
+      // ByteBuffer, so the processor is free to overwrite the source
+      // arrays on the next emit. Then post the JS-bridge crossing onto
+      // the emit executor so a slow JS handler cannot stall audio.
+      val fftBuffer = floatArrayToArrayBuffer(magnitudes)
+      val samplesBuffer = samples?.let { floatArrayToArrayBuffer(it) }
+      val sampleRateD = sampleRate.toDouble()
+      emitExecutor.execute {
+        // Drop frames queued before dispose — the disposer sets this flag
+        // before detaching, so anything still sitting in the executor queue
+        // short-circuits here rather than firing onFrame post-dispose.
+        if (disposed.get()) return@execute
+        val frame = VisualizerFrame(
+          fft = fftBuffer,
+          samples = samplesBuffer,
+          sampleRate = sampleRateD,
+        )
+        onFrame(frame)
+      }
+    }
+
+    val sub = Subscription(
+      id = nextSubscriptionId.getAndIncrement(),
+      processor = processor,
+      disposed = disposed,
+    )
+    subscriptions.add(sub)
+    engine?.attachAudioBufferSink(processor)
+
+    return {
+      // Mark disposed BEFORE detaching so any task already queued on the emit
+      // executor short-circuits (see the closure above) instead of firing
+      // onFrame after this returns.
+      disposed.set(true)
+      // Detach from the engine first so the Tee fan-out stops calling
+      // into this processor before the subscription record disappears.
+      // Removing-then-detaching would leave a window where an unwire
+      // running on another thread takes its `subscriptions` snapshot
+      // without this entry, then nulls `engine` before the disposer
+      // can detach — leaking the processor in the engine's sink list.
+      engine?.detachAudioBufferSink(processor)
+      subscriptions.remove(sub)
+    }
+  }
+
+  override fun getSubscriberCount(): Double = subscriptions.size.toDouble()
+
+  /**
+   * Module-internal escape hatch so the playback service can wire
+   * the FFT pipeline to ExoPlayer's audio chain at attach time.
+   * Pure JS-facing callers must not reach for this property.
+   *
+   * Replays every queued subscription's processor onto the new
+   * engine's `bufferSinks` accumulator. A re-wire (configure()
+   * rebuilding the playback engine, or crossfade engine swap) tears
+   * the prior engine's attachments down before resubscribing.
+   */
+  internal fun wireToPlaybackEngine(playbackEngine: PlaybackEngine) {
+    unwireFromPlaybackEngine()
+    engine = playbackEngine
+    for (sub in subscriptions) {
+      playbackEngine.attachAudioBufferSink(sub.processor)
+    }
+  }
+
+  internal fun unwireFromPlaybackEngine() {
+    val e = engine ?: return
+    for (sub in subscriptions) {
+      e.detachAudioBufferSink(sub.processor)
+    }
+    engine = null
+  }
+
+  private fun disposeAllSubscriptions() {
+    val e = engine
+    for (sub in subscriptions) {
+      e?.detachAudioBufferSink(sub.processor)
+    }
+    subscriptions.clear()
+  }
+
+  /**
+   * Wrap [values] in a fresh direct `ArrayBuffer` for delivery to JS.
+   *
+   * Allocates a new `ByteBuffer.allocateDirect` per call: at
+   * `fftSize=2048` + `includeSamples=true` + `updateIntervalMs=16`
+   * the steady-state allocation rate is ~768 KB/s of off-heap
+   * (DirectByteBuffer) memory across magnitudes + samples. Acceptable
+   * at typical configs; consumers chasing very low intervalMs at
+   * fftSize=2048 should expect proportionally higher GC pressure on
+   * the audio render thread.
+   *
+   * Write each float directly via `bb.putFloat()` advancing bb's
+   * own position. The derived `bb.asFloatBuffer().put(values)` form
+   * appears to write to bb's underlying storage on JVM but does not
+   * propagate the bytes through `ArrayBuffer.wrap` on Android's
+   * emulator backend — observed empirically: post-FFT magnitudes
+   * surface as all-zero on the JS side, even though `bb.getFloat(0)`
+   * reads back the right value on the Kotlin side. The explicit
+   * putFloat loop sidesteps the whole class of issue.
+   */
+  private fun floatArrayToArrayBuffer(values: FloatArray): ArrayBuffer {
+    val bb = ByteBuffer.allocateDirect(values.size * 4).order(ByteOrder.nativeOrder())
+    for (v in values) bb.putFloat(v)
+    bb.rewind()
+    return ArrayBuffer.wrap(bb)
+  }
+}

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

@@ -0,0 +1,63 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.audio.AudioProcessor
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.audio.TeeAudioProcessor
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * Constructs the visualizer Tee — a single [TeeAudioProcessor] whose
+ * downstream [TeeAudioProcessor.AudioBufferSink] is a
+ * [MultiplexingAudioBufferSink] fanning out to every visualizer
+ * subscriber the engine has accumulated in [bufferSinks].
+ *
+ * One builder per ExoPlayer leg. The CrossfadeEngine constructs two
+ * (leading + standby); the GaplessEngine constructs one. Each
+ * builder owns its own mux registry so [primeNewSink] can replay
+ * the most recent flush params onto a late-attaching subscriber —
+ * Media3 fires `MultiplexingAudioBufferSink.flush(rate, channels,
+ * encoding)` exactly once per AudioSink lifetime, so a sink that
+ * arrives after that flush would otherwise receive `handleBuffer`
+ * chunks with no encoding context.
+ */
+@UnstableApi
+internal class VisualizerTeeBuilder(
+  private val bufferSinks: CopyOnWriteArrayList<TeeAudioProcessor.AudioBufferSink>,
+) {
+
+  /**
+   * Lifetime invariant: one mux per AudioSink. ExoPlayer constructs a
+   * single AudioSink per `ExoPlayer.Builder.build()`, so this list
+   * caps at 1 (gapless leg, one builder) for the builder's lifetime.
+   * Crossfade has two legs, two builders, one mux each. Entries are
+   * never removed.
+   */
+  private val muxes = CopyOnWriteArrayList<MultiplexingAudioBufferSink>()
+
+  /**
+   * The Tee processor wired into the engine's audio-processor array.
+   * Always-on for every playback regardless of subscriber count — the
+   * cost is documented zero (one virtual dispatch + a buffer position
+   * advance per chunk) when the multiplexing sink's fan-out list is
+   * empty.
+   */
+  val audioProcessor: AudioProcessor
+
+  init {
+    val mux = MultiplexingAudioBufferSink(bufferSinks)
+    muxes.add(mux)
+    audioProcessor = TeeAudioProcessor(mux)
+  }
+
+  /**
+   * Replay the most recent flush params from every mux this builder
+   * has produced onto [sink]. Called by the engine immediately after
+   * adding `sink` to the shared `bufferSinks` accumulator so a
+   * subscriber that arrives after Media3's one-shot `flush` still
+   * receives the encoding context every subsequent `handleBuffer`
+   * needs.
+   */
+  fun primeNewSink(sink: TeeAudioProcessor.AudioBufferSink) {
+    for (mux in muxes) mux.primeNewSink(sink)
+  }
+}

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

@@ -0,0 +1,103 @@
+package com.margelo.nitro.queueplayer
+
+import android.os.Bundle
+import android.provider.MediaStore
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * Parse a Google Assistant / Android Auto voice-search Bundle into
+ * a lib-level [MediaSearchRequest]. Inputs come from the legacy
+ * `MediaSession.Callback.onPlayFromSearch(query, extras)` callback;
+ * Assistant routes "Hey Google, play X" + tile / app voice queries
+ * through there with a structured extras Bundle that carries the
+ * focus type (artist / album / song / playlist / genre) and the
+ * named slot that produced the focus.
+ *
+ * Defensive: every extras key is optional. Missing extras / unknown
+ * focus types fall through to `null` fields, leaving consumers to
+ * fuzzy-match on the raw `query` text.
+ *
+ * Reference: [Google Voice Actions for Media](
+ * https://developer.android.com/training/wearables/data/voice-search).
+ */
+@UnstableApi
+object VoiceSearchExtrasParser {
+
+  /**
+   * Voice-search extra carrying the playlist name. Assistant and
+   * Android Auto still send this key on "play my <playlist>" queries.
+   * Held as a literal because the `MediaStore` constant for it is
+   * deprecated — the deprecation targets the MediaStore Playlists
+   * provider, not this intent extra — and the platform ships no
+   * replacement constant. The wire value is stable across releases.
+   */
+  private const val EXTRA_MEDIA_PLAYLIST = "android.intent.extra.playlist"
+
+  /**
+   * Build a [MediaSearchRequest] from the raw `(query, extras)`
+   * pair Assistant hands to `onPlayFromSearch`.
+   *
+   * - `query`: the user's spoken / typed text. Always present;
+   *   empty string is a valid input meaning "no constraint".
+   * - `extras`: nullable Bundle carrying the focus taxonomy. When
+   *   null or empty, the returned request has `type == null` and
+   *   every named-slot field null.
+   */
+  fun parse(query: String, extras: Bundle?): MediaSearchRequest {
+    if (extras == null) {
+      return MediaSearchRequest(
+        query = query,
+        type = null,
+        artist = null,
+        album = null,
+        song = null,
+        playlist = null,
+        genre = null,
+        origin = MediaSearchOrigin.ANDROID_ASSISTANT,
+        reference = null,
+        playShuffled = null,
+        playbackRepeatMode = null,
+        resumePlayback = null,
+        playbackSpeed = null,
+        releaseDate = null,
+        // iOS-only; Google Assistant App Actions schema has no
+        // equivalent queue-position slot.
+        playbackQueueLocation = null
+      )
+    }
+    val focus = extras.getString(MediaStore.EXTRA_MEDIA_FOCUS)
+    val type = mediaSearchTypeFor(focus)
+    return MediaSearchRequest(
+      query = query,
+      type = type,
+      artist = extras.getString(MediaStore.EXTRA_MEDIA_ARTIST),
+      album = extras.getString(MediaStore.EXTRA_MEDIA_ALBUM),
+      song = extras.getString(MediaStore.EXTRA_MEDIA_TITLE),
+      playlist = extras.getString(EXTRA_MEDIA_PLAYLIST),
+      genre = extras.getString(MediaStore.EXTRA_MEDIA_GENRE),
+      origin = MediaSearchOrigin.ANDROID_ASSISTANT,
+      reference = null,
+      playShuffled = null,
+      playbackRepeatMode = null,
+      resumePlayback = null,
+      playbackSpeed = null,
+      releaseDate = null,
+      // iOS-only; Google Assistant App Actions schema has no
+      // equivalent queue-position slot.
+      playbackQueueLocation = null
+    )
+  }
+
+  /** Map an `EXTRA_MEDIA_FOCUS` MIME-type string onto our enum.
+   *  Unknown focus types — including the catch-all
+   *  `vnd.android.cursor.item/&#42;` (star) Assistant emits when no
+   *  slot was recognised — return null. */
+  internal fun mediaSearchTypeFor(focus: String?): MediaSearchType? = when (focus) {
+    "vnd.android.cursor.item/artist" -> MediaSearchType.ARTIST
+    "vnd.android.cursor.item/album" -> MediaSearchType.ALBUM
+    "vnd.android.cursor.item/audio" -> MediaSearchType.SONG
+    "vnd.android.cursor.item/playlist" -> MediaSearchType.PLAYLIST
+    "vnd.android.cursor.item/genre" -> MediaSearchType.GENRE
+    else -> null
+  }
+}