react-native-queue-player 1.0.0

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

@@ -0,0 +1,281 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.net.Uri
+import androidx.annotation.VisibleForTesting
+import androidx.media3.common.MediaItem
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DefaultDataSource
+import androidx.media3.datasource.DefaultHttpDataSource
+import androidx.media3.exoplayer.source.DefaultMediaSourceFactory
+import androidx.media3.exoplayer.source.MediaSource
+import androidx.media3.extractor.DefaultExtractorsFactory
+
+/**
+ * Builder utility for ExoPlayer [MediaItem] arrays and the
+ * [MediaSource.Factory] that plays them. Android mirror of
+ * `ios/AVQueueBuilder.swift`.
+ *
+ * iOS attaches HTTP headers per-AVURLAsset via an options dict;
+ * Media3 attaches them at the [DefaultHttpDataSource.Factory] level
+ * — one factory serves every network request, so headers are
+ * player-wide. That matches our [PlayerConfig] shape (no per-track
+ * header override) and lines up with which names
+ * [DefaultHttpDataSource.Factory.setDefaultRequestProperties] as the
+ * integration point. Per-track headers would require a custom
+ * MediaSource.Factory reading per-item metadata extras — tracked as
+ * a backlog item if Subsonic-style per-request signing ever lands.
+ *
+ * `file://` URIs transparently route through [DefaultDataSource]
+ * without touching the HTTP factory — matches iOS's file-URL
+ * short-circuit + (local files opt out of the lookahead
+ * cache too).
+ */
+@UnstableApi
+object MediaItemBuilder {
+
+  /**
+   * Build the [MediaItem] list for the player's queue, attaching a
+   * [MediaMetadata] per item so Media3 mirrors title / artist / album /
+   * artwork / duration to the MediaSession surface (lock-screen,
+   * notification, Bluetooth/AVRCP) without further work.
+   *
+   * MIME hint: when [lookaheadCache] reports a Content-Type for a
+   * track's URL (captured during a prior prefetch), it is passed via
+   * [MediaItem.Builder.setMimeType] so Media3's MediaSourceFactory
+   * picks the right extractor immediately instead of byte-sniffing.
+   * URL-derived MIME is the fallback for `http(s)://` paths whose
+   * extension is recognisable. MIME capture is queue-build-time;
+   * later prefetch hits do not retroactively refresh items.
+   *
+   * [Uri.parse] is total — invalid URLs do not produce null here,
+   * they produce items that fail at load time via the listener's
+   * error channel.
+   */
+  fun buildMediaItems(
+    context: Context,
+    tracks: List<TrackItem>,
+    lookaheadCache: LookaheadCache? = null
+  ): List<MediaItem> {
+    return tracks.map { track ->
+      val builder = MediaItem.Builder()
+        // mediaId is consumer-facing — Media3 surfaces it on
+        // notifications + MediaSession. Never used internally for
+        // identity / lookup; Media3's Player.currentMediaItemIndex
+        // is the authoritative queue position. Empty string is
+        // Media3's documented default when track.id is omitted.
+        .setMediaId(track.id ?: "")
+        .setUri(Uri.parse(track.url))
+        .setMediaMetadata(buildMetadata(context, track))
+      val mime = resolveMimeTypeForBuild(track.url, lookaheadCache)
+      if (mime != null) builder.setMimeType(mime)
+      builder.build()
+    }
+  }
+
+  /**
+   * Build the [MediaMetadata] attached to each MediaItem. Empty-string
+   * coerce on title/artist/album keeps Android OEM skins on the
+   * artwork-present render path (null fields drop the notification
+   * controls on Xiaomi / Oppo / Realme). Duration is set only when
+   * positive — omitting it hides the lock-screen scrubber rather than
+   * rendering `0:00 / 0:00`. Missing/empty/whitespace artworkUrl
+   * substitutes the bundled placeholder via `android.resource://` URI
+   * so Media3's BitmapLoader resolves it once per process rather than
+   * cloning a byte[] into every MediaMetadata.
+   */
+  private fun buildMetadata(context: Context, track: TrackItem): MediaMetadata {
+    val builder = MediaMetadata.Builder()
+      .setTitle(track.title.orEmpty())
+      .setArtist(track.artist.orEmpty())
+      .setAlbumTitle(track.album.orEmpty())
+
+    val artworkUrl = track.artworkUrl?.trim()
+    val artworkUri = if (!artworkUrl.isNullOrEmpty()) {
+      // Rewrite private `file://` paths through the lib's exported
+      // `ArtworkContentProvider` so cross-process controllers (Android
+      // Auto's gearhead, Wear, Assistant) can resolve the cover in
+      // their own process. `http(s)://` and `content://` URIs pass
+      // through unchanged.
+      ArtworkContentProvider.mapFileUri(Uri.parse(artworkUrl))
+    } else {
+      placeholderArtworkUri(context)
+    }
+    builder.setArtworkUri(artworkUri)
+
+    val duration = track.duration
+    if (duration != null && duration > 0) {
+      builder.setDurationMs((duration * 1000).toLong())
+    }
+
+    return builder.build()
+  }
+
+  /**
+   * URI for the bundled placeholder artwork in `res/raw/`. Cached
+   * per-process; the integer resource ID is package-stable at runtime
+   * so the URI string is identical across calls.
+   */
+  private fun placeholderArtworkUri(context: Context): Uri {
+    cachedPlaceholderUri?.let { return it }
+    synchronized(this) {
+      cachedPlaceholderUri?.let { return it }
+      val uri = Uri.parse(
+        "android.resource://${context.packageName}/${R.raw.rnqp_placeholder}"
+      )
+      cachedPlaceholderUri = uri
+      return uri
+    }
+  }
+
+  @Volatile
+  private var cachedPlaceholderUri: Uri? = null
+
+  /**
+   * Resolve the MIME hint for a queue-build pass. The lookahead
+   * cache wins when it has captured a Content-Type from prefetch.
+   * URL-derived hints are restricted to `http(s)://` scheme — local
+   * `file://`, `asset://`, `content://` URIs bypass the lookahead
+   * cache entirely; setting MIME on them is a no-op at best and
+   * could mis-cue Media3 at worst.
+   */
+  @VisibleForTesting
+  internal fun resolveMimeTypeForBuild(
+    url: String,
+    lookaheadCache: LookaheadCache?
+  ): String? {
+    lookaheadCache?.mimeTypeFor(url)?.let { return it }
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      return null
+    }
+    return CacheMimeTypes.fromUrl(url)
+  }
+
+  /**
+   * Construct the [MediaSource.Factory] used by the ExoPlayer built
+   * in [TrackPlayer.configureInternal]. Reads the [PlayerConfig]'s
+   * HTTP headers + User-Agent and wires them onto the underlying
+   * [DefaultHttpDataSource.Factory] so every remote fetch carries
+   * the consumer app's auth.
+   *
+   * When [lookaheadCache] is non-null, the bare HTTP factory is
+   * wrapped via [LookaheadCache.wrapDataSourceFactory]
+   * so remote reads transparently populate + serve from the on-disk
+   * LRU cache. file:// / asset:// / content:// URIs continue to bypass
+   * the cache because [DefaultDataSource] dispatches them through
+   * built-in DataSources before consulting the HTTP factory.
+   */
+  fun buildMediaSourceFactory(
+    context: Context,
+    config: PlayerConfig,
+    lookaheadCache: LookaheadCache? = null
+  ): MediaSource.Factory {
+    return buildMediaSourceFactoryRaw(
+      context = context,
+      headers = config.httpHeaders,
+      userAgent = config.userAgent,
+      networkTimeoutMs = effectiveNetworkTimeoutMs(config.networkTimeoutMs),
+      lookaheadCache = lookaheadCache
+    )
+  }
+
+  /**
+   * Primitive-arg factory builder. Mirrors iOS's @_spi(QueuePlayerTests)
+   * `AVQueueBuilder.makeItemRaw` — tests call this with primitive maps
+   * instead of constructing a Nitrogen-generated [PlayerConfig].
+   */
+  @VisibleForTesting
+  internal fun buildMediaSourceFactoryRaw(
+    context: Context,
+    headers: Map<String, String>?,
+    userAgent: String?,
+    networkTimeoutMs: Int = DEFAULT_NETWORK_TIMEOUT_MS,
+    lookaheadCache: LookaheadCache? = null
+  ): MediaSource.Factory {
+    val httpFactory = buildHttpFactory(headers, userAgent, networkTimeoutMs)
+    val networkFactory: DataSource.Factory =
+      lookaheadCache?.wrapDataSourceFactory(httpFactory) ?: httpFactory
+    val dataSourceFactory = DefaultDataSource.Factory(context, networkFactory)
+    // Enable constant-bitrate seeking so CBR MP3 / ADTS / AMR streams (common
+    // for transcoded audio the server reports as length-unknown) become
+    // seekable and expose an estimated duration. Without this ExoPlayer treats
+    // them as unseekable and a seekTo silently collapses to the track start.
+    // Positions are bitrate-approximated (accurate enough for scrubbing).
+    val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)
+    return DefaultMediaSourceFactory(context, extractorsFactory)
+      .setDataSourceFactory(dataSourceFactory)
+  }
+
+  /**
+   * Build a bare [DefaultHttpDataSource.Factory] from a config's
+   * headers + User-Agent + read-timeout. Exposed so the proactive
+   * prefetcher ([LookaheadCacheWriter]) can construct its own
+   * `CacheDataSource` from the same auth context as the player.
+   * Both the player factory and the writer factory share the same
+   * underlying [LookaheadCache.simpleCache], so cache reads + writes
+   * remain coherent.
+   *
+   * Read timeout: defaults to 30000 ms (vs Media3's 8s default).
+   * The longer timeout tolerates slow-spin-up servers (e.g. Subsonic
+   * on spun-down disks needing ~20s to respond). Connect timeout
+   * stays at Media3's 8s default — TCP handshake is unaffected by
+   * disk spin-up.
+   */
+  fun buildHttpFactory(
+    headers: Map<String, String>?,
+    userAgent: String?,
+    networkTimeoutMs: Int = DEFAULT_NETWORK_TIMEOUT_MS
+  ): DefaultHttpDataSource.Factory {
+    val merged = mergeHttpRequestProperties(headers, userAgent)
+    return DefaultHttpDataSource.Factory().apply {
+      if (merged.isNotEmpty()) {
+        setDefaultRequestProperties(merged)
+      }
+      // Subsonic-behind-reverse-proxy deployments redirect
+      // http→https (or vice versa) for auth flows; disabling
+      // cross-protocol redirects silently truncates downloads
+      // partway through a redirect.
+      setAllowCrossProtocolRedirects(true)
+      setReadTimeoutMs(networkTimeoutMs)
+    }
+  }
+
+  /**
+   * Lib-clamped network timeout in ms. Defaults to 30000 (30s),
+   * clamped to [1000, 60000]. Mirrors the cross-platform contract
+   * documented in `PlayerConfig.networkTimeoutMs`. iOS exposes the
+   * same field but doesn't honour it (AVPlayer drives loads via
+   * CFNetwork; no public timeout knob).
+   */
+  internal fun effectiveNetworkTimeoutMs(raw: Double?): Int {
+    val ms = (raw?.toInt() ?: DEFAULT_NETWORK_TIMEOUT_MS)
+    return ms.coerceIn(MIN_NETWORK_TIMEOUT_MS, MAX_NETWORK_TIMEOUT_MS)
+  }
+
+  const val DEFAULT_NETWORK_TIMEOUT_MS: Int = 30_000
+  private const val MIN_NETWORK_TIMEOUT_MS: Int = 1_000
+  private const val MAX_NETWORK_TIMEOUT_MS: Int = 60_000
+
+  /**
+   * Merge [PlayerConfig.httpHeaders] with an explicit user-agent
+   * into the single request-properties map that
+   * [DefaultHttpDataSource.Factory.setDefaultRequestProperties]
+   * accepts. The explicit `userAgent` argument wins over any
+   * `User-Agent` key already present in `headers`. Empty / null
+   * user-agent leaves any header-dict `User-Agent` untouched,
+   * matching the iOS `httpOptionsRaw` semantics.
+   */
+  @VisibleForTesting
+  internal fun mergeHttpRequestProperties(
+    headers: Map<String, String>?,
+    userAgent: String?
+  ): Map<String, String> {
+    val merged = headers?.toMutableMap() ?: mutableMapOf()
+    if (!userAgent.isNullOrEmpty()) {
+      merged["User-Agent"] = userAgent
+    }
+    return merged
+  }
+}

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

@@ -0,0 +1,76 @@
+package com.margelo.nitro.queueplayer
+
+import android.net.Uri
+import androidx.media3.common.MediaItem
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * Convert a lib-level [BrowseItem] into a Media3 [MediaItem] for
+ * delivery through the `MediaLibrarySession.Callback` browse
+ * surface. Pure data mapping — no AVFoundation / IO. Maps the
+ * native `BrowseDataProvider` cache + `SearchResultCache` entries
+ * into the `ListenableFuture<LibraryResult<...>>` shapes Media3
+ * expects from the browse + search callbacks.
+ *
+ * The browse-vs-playable axis maps onto Media3's
+ * [MediaMetadata.MEDIA_TYPE_*] convention:
+ *  - [BrowseItem.playable] `true` → `IS_PLAYABLE = true`,
+ *    `IS_BROWSABLE = false`, `mediaType = MEDIA_TYPE_MUSIC`.
+ *  - [BrowseItem.hasChildren] `true` → `IS_BROWSABLE = true`,
+ *    `IS_PLAYABLE = false`, `mediaType = MEDIA_TYPE_FOLDER_MIXED`.
+ *  - Both flags `true` (consumer error per the BrowseItem contract,
+ *    but defensively handled): both `IS_*` flags set; `mediaType`
+ *    defaults to `MEDIA_TYPE_MIXED`. Media3 controllers treat this
+ *    as a "branch-or-leaf" entry and pick whichever the UI surface
+ *    can render.
+ *  - Both `false` (an item that is neither tappable nor browsable,
+ *    e.g. a header-style row): both `IS_*` flags `false`,
+ *    `mediaType = MEDIA_TYPE_MIXED`. Useful only for spacer rows;
+ *    most consumers won't emit these.
+ *
+ * Artwork: when [BrowseItem.artworkUrl] is non-null + non-empty,
+ * the URI is set on [MediaMetadata.Builder.setArtworkUri]. Private
+ * `file://` paths route through [ArtworkContentProvider.mapFileUri]
+ * so cross-process media controllers (Android Auto's gearhead, Wear,
+ * Assistant) can resolve them in their own process via the lib's
+ * exported provider — `http(s)://` and `content://` URIs pass
+ * through unchanged.
+ */
+@UnstableApi
+object MediaItemMapper {
+
+  /** Map a single [BrowseItem] to a Media3 [MediaItem]. */
+  fun toMediaItem(item: BrowseItem): MediaItem {
+    val metadata = MediaMetadata.Builder()
+      .setTitle(item.title)
+      .apply {
+        item.subtitle?.takeIf { it.isNotEmpty() }?.let(::setSubtitle)
+        item.artworkUrl
+          ?.takeIf { it.isNotEmpty() }
+          ?.let { setArtworkUri(ArtworkContentProvider.mapFileUri(Uri.parse(it))) }
+      }
+      .setIsBrowsable(item.hasChildren == true)
+      .setIsPlayable(item.playable)
+      .setMediaType(mediaTypeFor(item))
+      .build()
+    return MediaItem.Builder()
+      .setMediaId(item.id)
+      .setMediaMetadata(metadata)
+      .build()
+  }
+
+  /** Map a list of [BrowseItem]s. */
+  fun toMediaItems(items: List<BrowseItem>): List<MediaItem> =
+    items.map { toMediaItem(it) }
+
+  private fun mediaTypeFor(item: BrowseItem): Int {
+    val isBrowsable = item.hasChildren == true
+    val isPlayable = item.playable
+    return when {
+      isPlayable && !isBrowsable -> MediaMetadata.MEDIA_TYPE_MUSIC
+      isBrowsable && !isPlayable -> MediaMetadata.MEDIA_TYPE_FOLDER_MIXED
+      else -> MediaMetadata.MEDIA_TYPE_MIXED
+    }
+  }
+}

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

@@ -0,0 +1,66 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Tracks fixed playback-progress milestones (25/50/75/90%) for the
+ * current track playthrough. Pure + deterministic (no Media3), so it
+ * unit-tests directly.
+ *
+ * A threshold emits only when forward playback crosses it: [seek] moves
+ * the baseline WITHOUT emitting (so thresholds a seek jumps over are
+ * suppressed), the first [tick] only establishes the baseline (so a
+ * mid-track start doesn't back-fire), and each threshold emits at most
+ * once per playthrough. [reset] begins a new playthrough (track change /
+ * repeat-one loop). With no computable duration (<= 0) nothing fires.
+ */
+internal class MilestoneTracker {
+  private val fired = HashSet<Int>()
+  private var lastFraction: Double? = null
+
+  /** Begin a fresh playthrough. */
+  fun reset() {
+    fired.clear()
+    lastFraction = null
+  }
+
+  /** Move the baseline to a seek target and CONSUME (without emitting)
+   *  every threshold at/below it — those were jumped, not played, so they
+   *  must not fire this playthrough. Consuming into `fired` (rather than
+   *  only moving the baseline) makes the suppress robust against a
+   *  progress tick that observes the post-seek position around the same
+   *  time as the seek. */
+  fun seek(durationSec: Double, positionSec: Double) {
+    val frac = fraction(durationSec, positionSec)
+    if (frac == null) {
+      lastFraction = null
+      return
+    }
+    for (m in MILESTONES) {
+      if (m / 100.0 <= frac) fired.add(m)
+    }
+    lastFraction = frac
+  }
+
+  /** Advance from a progress tick; returns the milestones crossed by
+   *  forward playback since the previous observation, ascending. */
+  fun tick(durationSec: Double, positionSec: Double): List<Int> {
+    val frac = fraction(durationSec, positionSec) ?: return emptyList()
+    val prev = lastFraction
+    if (prev == null) {
+      lastFraction = frac
+      return emptyList()
+    }
+    val crossed = MILESTONES.filter { m ->
+      m !in fired && prev < m / 100.0 && m / 100.0 <= frac
+    }
+    fired.addAll(crossed)
+    lastFraction = frac
+    return crossed
+  }
+
+  private fun fraction(durationSec: Double, positionSec: Double): Double? =
+    if (durationSec > 0) positionSec / durationSec else null
+
+  companion object {
+    val MILESTONES = listOf(25, 50, 75, 90)
+  }
+}

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

@@ -0,0 +1,64 @@
+package com.margelo.nitro.queueplayer
+
+import android.net.Uri
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
+import androidx.media3.datasource.HttpDataSource
+import androidx.media3.datasource.TransferListener
+
+/**
+ * Wraps an HTTP-capable [DataSource.Factory] so each `open(DataSpec)`
+ * call surfaces the response `Content-Type` header to a sink callback.
+ *
+ * Mirrors the iOS lookahead cache's Content-Type-derived file
+ * extension behaviour: the Android cache stores spans (Media3 owns
+ * the on-disk format), so the symmetric move is to record the MIME
+ * type observed during prefetch and let the playback path pass it
+ * to Media3 via [androidx.media3.common.MediaItem.Builder.setMimeType].
+ *
+ * The wrapper is transparent for non-HTTP underlying sources (file://,
+ * asset://) — it forwards every call through and skips MIME capture.
+ */
+@UnstableApi
+internal class MimeCapturingDataSourceFactory(
+  private val upstream: DataSource.Factory,
+  private val onMime: (uri: String, contentType: String?) -> Unit
+) : DataSource.Factory {
+  override fun createDataSource(): DataSource =
+    MimeCapturingDataSource(upstream.createDataSource(), onMime)
+}
+
+@UnstableApi
+internal class MimeCapturingDataSource(
+  private val delegate: DataSource,
+  private val onMime: (uri: String, contentType: String?) -> Unit
+) : DataSource {
+
+  override fun addTransferListener(transferListener: TransferListener) {
+    delegate.addTransferListener(transferListener)
+  }
+
+  override fun open(dataSpec: DataSpec): Long {
+    val length = delegate.open(dataSpec)
+    val httpDelegate = delegate as? HttpDataSource ?: return length
+    // HTTP headers are case-insensitive; Media3 normalises but
+    // some servers / proxies emit lowercase. Accept either.
+    val contentType = httpDelegate.responseHeaders["Content-Type"]?.firstOrNull()
+      ?: httpDelegate.responseHeaders["content-type"]?.firstOrNull()
+    onMime(dataSpec.uri.toString(), contentType)
+    return length
+  }
+
+  override fun read(buffer: ByteArray, offset: Int, length: Int): Int =
+    delegate.read(buffer, offset, length)
+
+  override fun getUri(): Uri? = delegate.uri
+
+  override fun close() {
+    delegate.close()
+  }
+
+  override fun getResponseHeaders(): Map<String, List<String>> =
+    delegate.responseHeaders
+}

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

@@ -0,0 +1,92 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.audio.TeeAudioProcessor
+import java.nio.ByteBuffer
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * Single [TeeAudioProcessor.AudioBufferSink] that fans every
+ * `flush` + `handleBuffer` callback out to a list of downstream
+ * sinks. The lib needs this because [TeeAudioProcessor] only takes
+ * ONE sink at construction; we want N visualizer subscribers + zero
+ * cost when the list is empty.
+ *
+ * The list is the engine's own `bufferSinks` accumulator (passed by
+ * reference). The Visualizer Hybrid manages list mutation via the
+ * engine's `attachAudioBufferSink` / `detachAudioBufferSink` API; the
+ * mux just walks the snapshot at each callback. The list is a
+ * [CopyOnWriteArrayList] so iteration is stable even when a
+ * subscriber detaches mid-stream.
+ *
+ * `flush` is forwarded once per sink with the current sample rate /
+ * channel count / encoding so each downstream sink can size its
+ * buffers correctly. `handleBuffer` hands each downstream sink an
+ * independent [ByteBuffer.duplicate] so a slow consumer cannot leave
+ * the shared view in a partially-consumed state for the next sink.
+ *
+ * Late-attach contract: Media3 fires `flush` once per AudioSink
+ * lifetime, typically when `DefaultAudioSink.configure` runs against
+ * the first decoded buffer. A subscriber that attaches AFTER that
+ * point would otherwise receive `handleBuffer` chunks with no prior
+ * `flush(rate, channels, encoding)` call and no way to size its
+ * decoder. The mux caches the most recent flush params in
+ * [lastFlush] (a single [FlushParams] reference, written
+ * `@Volatile` so the three fields publish atomically — no torn-
+ * triple risk vs three separate volatile ints) and replays them via
+ * [primeNewSink] when the engine's attach path adds a sink. If
+ * [lastFlush] is still null (no flush has fired yet on this mux)
+ * the new sink simply waits for the next live flush, which it will
+ * receive directly via the normal fan-out.
+ */
+@UnstableApi
+internal class MultiplexingAudioBufferSink(
+  private val sinks: CopyOnWriteArrayList<TeeAudioProcessor.AudioBufferSink>,
+) : TeeAudioProcessor.AudioBufferSink {
+
+  private data class FlushParams(val sampleRateHz: Int, val channelCount: Int, val encoding: Int)
+
+  @Volatile
+  private var lastFlush: FlushParams? = null
+
+  override fun flush(sampleRateHz: Int, channelCount: Int, encoding: Int) {
+    lastFlush = FlushParams(sampleRateHz, channelCount, encoding)
+    for (sink in sinks) {
+      sink.flush(sampleRateHz, channelCount, encoding)
+    }
+  }
+
+  override fun handleBuffer(buffer: ByteBuffer) {
+    if (sinks.isEmpty()) return
+    for (sink in sinks) {
+      // duplicate() shares storage but gives each sink its own
+      // position + limit + mark, so per-sink reads are independent.
+      sink.handleBuffer(buffer.duplicate())
+    }
+  }
+
+  /**
+   * Replay the most recent `flush(rate, channels, encoding)` onto a
+   * sink that just attached, so it has the encoding context every
+   * subsequent [handleBuffer] needs to decode incoming PCM. No-op
+   * when no flush has fired yet on this mux — the sink will be
+   * driven directly by the next live flush via the fan-out loop.
+   *
+   * Caller must accept idempotent flush: if the engine attach happens
+   * to interleave with a live `flush()` (the new sink lands in
+   * [sinks] before the loop reaches it AND `primeNewSink` runs after
+   * the loop), the sink may receive two `flush(rate, channels,
+   * encoding)` calls back-to-back with identical params. Downstream
+   * sinks treat repeat-flush as a state-reset, not a true no-op:
+   * [FFTProcessorTee] zeroes its ring + writeIdx + lastEmitNs on
+   * every flush call, so a double-flush forfeits up to one
+   * `fftSize`-worth of accumulated audio — acceptable because a
+   * sink that just attached has no historic accumulation to lose,
+   * and the next handleBuffer will refill the ring within
+   * `fftSize / sampleRate` seconds.
+   */
+  internal fun primeNewSink(sink: TeeAudioProcessor.AudioBufferSink) {
+    val params = lastFlush ?: return
+    sink.flush(params.sampleRateHz, params.channelCount, params.encoding)
+  }
+}

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

@@ -0,0 +1,37 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.DefaultMediaNotificationProvider
+
+/**
+ * Custom [androidx.media3.session.MediaNotification.Provider] that
+ * pins the lib's NotificationChannel ID + notification ID so the
+ * media-style foreground notification posts under the channel created
+ * by [PlaybackService.onCreate].
+ *
+ * Subclassing [DefaultMediaNotificationProvider] (rather than building
+ * a provider from scratch) keeps the standard prev / play-pause / next
+ * compact-view rendering, the expanded-view artwork + scrub progress,
+ * and Media3's default action-mapping behaviour. The compact-view
+ * button priority is expressed by the session's
+ * `setMediaButtonPreferences(...)` builder call; this provider reads
+ * those preferences directly.
+ *
+ * Artwork loading is wired separately on the [androidx.media3.session.MediaSession]
+ * via `setBitmapLoader(...)` — the provider routes artwork requests
+ * through that loader chain
+ * ([PlaceholderFallbackBitmapLoader] →
+ *  [androidx.media3.session.CacheBitmapLoader] →
+ *  [androidx.media3.datasource.DataSourceBitmapLoader]) so the
+ * notification always receives a bitmap, never the system "music note"
+ * generic.
+ */
+@UnstableApi
+internal class NotificationProvider(context: Context) :
+  DefaultMediaNotificationProvider(
+    context,
+    NotificationIdProvider { PlaybackService.NOTIFICATION_ID },
+    PlaybackService.NOTIFICATION_CHANNEL_ID,
+    R.string.rnqp_playback_channel_name,
+  )