react-native-queue-player 1.0.0

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

@@ -0,0 +1,34 @@
+package com.margelo.nitro.queueplayer
+
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Process-wide store for the active [ReplayGainMode]. Written by
+ * `TrackPlayer.setReplayGainMode` from the JS bridge thread; read on
+ * two paths:
+ * - The engines' metadata-listener path — after `onTracksChanged`
+ *   parses container `Format.metadata` (or `onMetadata` parses
+ *   in-stream samples), the gain push selects `track` vs `album`
+ *   tags via this mode.
+ * - The JS-driven `setReplayGainMode` path — `TrackPlayer` writes
+ *   the new mode, then asks each active engine to
+ *   `recomputeReplayGainFromConfig` so a mid-track flip lands within
+ *   ~1 audio buffer without waiting for fresh metadata.
+ *
+ * Mirrors [VisualizationGate]'s shape — a process-wide singleton
+ * fronting an atomic primitive — but holds an enum rather than a
+ * boolean. `AtomicReference` covers concurrent reads / writes without
+ * needing an external lock.
+ *
+ * Default `ReplayGainMode.OFF` so an unconfigured player applies no
+ * gain.
+ */
+internal object ReplayGainConfig {
+  private val mode = AtomicReference(ReplayGainMode.OFF)
+
+  fun getMode(): ReplayGainMode = mode.get()
+
+  fun setMode(value: ReplayGainMode) {
+    mode.set(value)
+  }
+}

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

@@ -0,0 +1,44 @@
+package com.margelo.nitro.queueplayer
+
+/**
+ * Parsed ReplayGain tag values for a single track. All four fields
+ * are independent — a track may carry only track tags, only album
+ * tags, or both. The Opus container guard returns nil from
+ * `ReplayGainExtractor.extract(...)` rather than producing a
+ * `ReplayGainData` with one nil pair.
+ *
+ * `Float` rather than `Double` because Media3 audio processors operate
+ * on Float32 PCM; the gain pushed into [ReplayGainAudioProcessor] is a
+ * Float, and converting at the JS-bridge boundary instead of inside
+ * the audio path keeps the processor allocation-free.
+ *
+ * Strict mode (`.album` requires album tag, `.track` requires track
+ * tag) means there is no fallback — see [selectGain].
+ */
+data class ReplayGainData(
+  val trackGainDb: Float?,
+  val trackPeak: Float?,
+  val albumGainDb: Float?,
+  val albumPeak: Float?,
+) {
+  /**
+   * Strict mode-aware selector. See NOTES.md §25.
+   *
+   * - [ReplayGainMode.OFF]: returns `(null, null)` (no-op).
+   * - [ReplayGainMode.TRACK]: returns `(trackGainDb, trackPeak)` —
+   *   both may be null when the track tag is absent.
+   * - [ReplayGainMode.ALBUM]: returns `(albumGainDb, albumPeak)` —
+   *   both may be null when the album tag is absent. No fallback
+   *   to track gain.
+   *
+   * Caller computes `linearGain = 10^(gainDb / 20)` and clip-caps via
+   * peak when both are non-null. When `gainDb` is null the caller
+   * treats RG as inactive for this track (`linearGain = 1.0f`,
+   * `replayGainActive = false`).
+   */
+  fun selectGain(mode: ReplayGainMode): Pair<Float?, Float?> = when (mode) {
+    ReplayGainMode.OFF -> null to null
+    ReplayGainMode.TRACK -> trackGainDb to trackPeak
+    ReplayGainMode.ALBUM -> albumGainDb to albumPeak
+  }
+}

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

@@ -0,0 +1,209 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.Metadata
+import androidx.media3.common.MimeTypes
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.container.MdtaMetadataEntry
+import androidx.media3.extractor.metadata.id3.TextInformationFrame
+import androidx.media3.extractor.metadata.vorbis.VorbisComment
+
+/**
+ * Pure parser that walks a Media3 [Metadata] and produces a
+ * [ReplayGainData] when any of the four ReplayGain tags is present.
+ * Returns `null` for Opus containers — `OpusHead.output_gain` is
+ * decoder-applied; tag-applied gain on top is double-correction.
+ *
+ * Tag-format coverage:
+ * - **MP3 ID3v2 TXXX**: [TextInformationFrame] with `id == "TXXX"`,
+ *   description in [TextInformationFrame.description], value in
+ *   [TextInformationFrame.values] (first entry).
+ * - **FLAC / OGG-Vorbis**: [VorbisComment] with the bare tag name
+ *   in [VorbisComment.key].
+ * - **MP4 / M4A iTunes-style atoms**: [MdtaMetadataEntry] with the
+ *   colon-prefixed atom key (e.g. `com.apple.iTunes:replaygain_track_gain`)
+ *   and a UTF-8 string payload in [MdtaMetadataEntry.value].
+ *
+ * Parser tolerance per NOTES.md §25 — `" dB"` suffix optional, `+/-`
+ * prefix optional, U+2212 minus sign normalised, period decimal,
+ * whitespace tolerant, NaN/Inf rejected. Tag-name match is
+ * case-insensitive.
+ */
+@UnstableApi
+internal object ReplayGainExtractor {
+
+  // Tag descriptions matched (case-insensitive).
+  internal const val TRACK_GAIN_KEY = "REPLAYGAIN_TRACK_GAIN"
+  internal const val TRACK_PEAK_KEY = "REPLAYGAIN_TRACK_PEAK"
+  internal const val ALBUM_GAIN_KEY = "REPLAYGAIN_ALBUM_GAIN"
+  internal const val ALBUM_PEAK_KEY = "REPLAYGAIN_ALBUM_PEAK"
+
+  /**
+   * Walk every entry in [metadata] and parse any ReplayGain tags.
+   * Returns `null` when [mimeType] identifies an Opus container or
+   * when no usable ReplayGain tag was found.
+   *
+   * [mimeType] is the active [androidx.media3.common.Format.sampleMimeType]
+   * (or container MIME when sample MIME is unavailable). The Opus
+   * guard matches `audio/opus` and `audio/ogg` case-insensitively.
+   */
+  fun extract(metadata: Metadata?, mimeType: String?): ReplayGainData? {
+    if (metadata == null) return null
+    if (isOpusContainer(mimeType)) return null
+
+    var trackGainDb: Float? = null
+    var trackPeak: Float? = null
+    var albumGainDb: Float? = null
+    var albumPeak: Float? = null
+
+    for (i in 0 until metadata.length()) {
+      val entry = metadata.get(i)
+      val (canonical, raw) = canonicalKeyAndValue(entry) ?: continue
+      when (canonical) {
+        TRACK_GAIN_KEY -> parseGainDb(raw)?.let { trackGainDb = it }
+        TRACK_PEAK_KEY -> parsePeak(raw)?.let { trackPeak = it }
+        ALBUM_GAIN_KEY -> parseGainDb(raw)?.let { albumGainDb = it }
+        ALBUM_PEAK_KEY -> parsePeak(raw)?.let { albumPeak = it }
+      }
+    }
+
+    if (trackGainDb == null && trackPeak == null
+       && albumGainDb == null && albumPeak == null) {
+      return null
+    }
+    return ReplayGainData(
+      trackGainDb = trackGainDb,
+      trackPeak = trackPeak,
+      albumGainDb = albumGainDb,
+      albumPeak = albumPeak,
+    )
+  }
+
+  // region Key + value extraction
+
+  /**
+   * Map a Media3 [Metadata.Entry] to one of the four ReplayGain tag
+   * names plus its raw string value. Returns `null` when the entry
+   * isn't a ReplayGain tag we recognise.
+   *
+   * Container shapes:
+   * - [TextInformationFrame] with `id == "TXXX"`: description is the
+   *   user tag name, first `values` entry is the payload.
+   * - [VorbisComment]: `key` is the bare tag name, `value` is the
+   *   payload.
+   * - [MdtaMetadataEntry]: `key` is colon-prefixed
+   *   (`com.apple.iTunes:replaygain_track_gain`); the `value` byte
+   *   array is UTF-8-decoded.
+   */
+  internal fun canonicalKeyAndValue(entry: Metadata.Entry): Pair<String, String>? {
+    val rawKey: String
+    val rawValue: String
+    when (entry) {
+      is TextInformationFrame -> {
+        if (entry.id != "TXXX") return null
+        rawKey = entry.description ?: return null
+        rawValue = entry.values.firstOrNull() ?: return null
+      }
+      is VorbisComment -> {
+        rawKey = entry.key
+        rawValue = entry.value
+      }
+      is MdtaMetadataEntry -> {
+        rawKey = entry.key
+        rawValue = String(entry.value, Charsets.UTF_8)
+      }
+      else -> return null
+    }
+    val canonical = canonicalKeyForName(rawKey) ?: return null
+    return canonical to rawValue
+  }
+
+  /**
+   * Strip a leading `namespace:` prefix (e.g. `com.apple.iTunes:`)
+   * and uppercase-match the suffix against the four known tag
+   * names. Returns the canonical constant or `null` when no match.
+   */
+  internal fun canonicalKeyForName(rawKey: String): String? {
+    val upper = rawKey.uppercase()
+    val colonIdx = upper.lastIndexOf(':')
+    val suffix = if (colonIdx >= 0) upper.substring(colonIdx + 1) else upper
+    return when (suffix) {
+      TRACK_GAIN_KEY -> TRACK_GAIN_KEY
+      TRACK_PEAK_KEY -> TRACK_PEAK_KEY
+      ALBUM_GAIN_KEY -> ALBUM_GAIN_KEY
+      ALBUM_PEAK_KEY -> ALBUM_PEAK_KEY
+      else -> null
+    }
+  }
+
+  // endregion
+
+  // region Opus container guard
+
+  /**
+   * Best-effort container detection. Matches `audio/opus` and
+   * `audio/ogg` (the Opus-in-Ogg container). Streaming endpoints
+   * that serve Opus over a content-typed URL without a recognised
+   * MIME bypass this guard and may double-correct against
+   * `OpusHead.output_gain`; documented in NOTES.md §25.
+   */
+  internal fun isOpusContainer(mimeType: String?): Boolean {
+    if (mimeType == null) return false
+    val lower = mimeType.lowercase()
+    return lower == MimeTypes.AUDIO_OPUS || lower == "audio/ogg"
+  }
+
+  // endregion
+
+  // region Gain + peak parsing
+
+  /**
+   * Parse a `REPLAYGAIN_*_GAIN` string (e.g. `"-6.54 dB"`,
+   * `"+3.21"`, `"−1.0 dB"` with U+2212 minus) into a Float dB.
+   * Returns `null` for unparseable / NaN / Inf inputs.
+   */
+  internal fun parseGainDb(rawInput: String): Float? {
+    var trimmed = rawInput.trim()
+    if (trimmed.isEmpty()) return null
+
+    // Normalise U+2212 MINUS SIGN → ASCII '-'.
+    trimmed = trimmed.replace('−', '-')
+
+    // Strip case-insensitive trailing "dB" + any whitespace separator.
+    val lower = trimmed.lowercase()
+    if (lower.endsWith("db")) {
+      trimmed = trimmed.substring(0, trimmed.length - 2).trim()
+    }
+    if (trimmed.isEmpty()) return null
+
+    // Collapse extra-internal whitespace per NOTES.md §25 — some
+    // taggers emit `"- 6.54"` (sign-digit) or `"-6 .54"` (digit-
+    // decimal). `Float.parseFloat` rejects both; collapsing makes
+    // them parse.
+    trimmed = trimmed.filterNot { it.isWhitespace() }
+
+    // Reject comma decimals (RG2 spec — period only).
+    if (trimmed.contains(',')) return null
+
+    val value = trimmed.toFloatOrNull() ?: return null
+    if (value.isNaN() || value.isInfinite()) return null
+    return value
+  }
+
+  /**
+   * Parse a `REPLAYGAIN_*_PEAK` string (linear, period decimal).
+   * Returns `null` for unparseable / NaN / Inf / out-of-range
+   * values, or for the encoder-default sentinels (peak `< 0.001`
+   * or peak exactly `1.0`, both signal the analyser didn't run).
+   */
+  internal fun parsePeak(rawInput: String): Float? {
+    val trimmed = rawInput.trim()
+    val value = trimmed.toFloatOrNull() ?: return null
+    if (value.isNaN() || value.isInfinite()) return null
+    if (value < 0f || value > 2.0f) return null
+    if (value < 0.001f) return null
+    if (value == 1.0f) return null
+    return value
+  }
+
+  // endregion
+}

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

@@ -0,0 +1,34 @@
+package com.margelo.nitro.queueplayer
+
+import kotlin.math.min
+import kotlin.math.pow
+
+/**
+ * Pure gain math per NOTES.md §25. Selects the `(gainDb, peak)` pair
+ * from [data] under [mode] (strict, no fallback), then:
+ *
+ * ```
+ * linearGain = pow(10, gainDb / 20)
+ * if peak != null and peak > 0.001 and peak != 1.0:
+ *   linearGain = min(linearGain, 1.0 / peak)
+ * ```
+ *
+ * Returns `1.0f` (unity) whenever the selected mode's gain tag is
+ * absent — RG is inactive for that track. Mirrors the iOS
+ * `AudioTapProvider.computeLinearGain(data:mode:)` contract so a tag
+ * fixture parses to the same linear gain on both platforms.
+ *
+ * Encoder-default sentinels (`peak == 1.0` and `peak < 0.001`) bypass
+ * the peak-based clip cap. The extractor returns `null` for both
+ * already, but defending here keeps the math correct against any
+ * future caller that bypasses the extractor.
+ */
+internal fun computeLinearGain(data: ReplayGainData?, mode: ReplayGainMode): Float {
+  val (gainDb, peak) = data?.selectGain(mode) ?: (null to null)
+  if (gainDb == null) return 1.0f
+  var raw = 10.0.pow(gainDb.toDouble() / 20.0).toFloat()
+  if (peak != null && peak > 0.001f && peak != 1.0f) {
+    raw = min(raw, 1.0f / peak)
+  }
+  return raw
+}

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

@@ -0,0 +1,72 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Per-query cache of search results, populated by the JS-side
+ * search responder + read by `onGetSearchResult` on the
+ * `MediaLibrarySession.Callback`. Keyed on the raw query string —
+ * matching what `MediaBrowser.search(query)` and
+ * `MediaBrowser.getSearchResult(query, ...)` thread through.
+ *
+ * Concurrency: backed by [ConcurrentHashMap] so the JS responder
+ * thread (callback dispatch) can write while a controller's reader
+ * thread (Media3's library executor) is paginating an in-flight
+ * query.
+ *
+ * Eviction: simple — when a new result list arrives for a query,
+ * the prior entry is replaced. `clear()` drops everything (e.g. on
+ * a fresh BrowseSnapshot push, the consumer might want to clear
+ * stale results — call site decides).
+ */
+@UnstableApi
+class SearchResultCache {
+
+  private val results = ConcurrentHashMap<String, List<BrowseItem>>()
+
+  /** Replace the cached results for [query]. Empty list keeps the
+   *  query in the cache as "answered with zero results". */
+  fun setResults(query: String, items: List<BrowseItem>) {
+    results[query] = items.toList()
+  }
+
+  /** Drop the cached results for [query], if any. Used when the
+   *  caller wants to force a fresh JS dispatch on the next
+   *  `onSearch`. */
+  fun clearResults(query: String) {
+    results.remove(query)
+  }
+
+  /** Drop every cached query. */
+  fun clear() {
+    results.clear()
+  }
+
+  /** Read the full result list for [query], or `null` when the
+   *  query hasn't been answered yet. */
+  fun getResults(query: String): List<BrowseItem>? = results[query]
+
+  /** Page slice for [query]. Returns empty list when no entry is
+   *  cached for the query. Pagination semantics match
+   *  [BrowseDataProvider.getChildren]: 0-based page, `pageSize <= 0`
+   *  treats as unbounded, negative page returns empty,
+   *  out-of-range page returns empty, partial last page returns
+   *  the tail. */
+  fun getPage(query: String, page: Int, pageSize: Int): List<BrowseItem> {
+    val full = results[query] ?: return emptyList()
+    if (pageSize <= 0) return full
+    if (page < 0) return emptyList()
+    val from = page * pageSize
+    if (from >= full.size) return emptyList()
+    val to = (from + pageSize).coerceAtMost(full.size)
+    return full.subList(from, to)
+  }
+
+  /** Total item count cached for [query]. Returned by
+   *  `notifySearchResultChanged`. Returns 0 when no entry. */
+  fun count(query: String): Int = results[query]?.size ?: 0
+
+  /** True when [query] has been answered (even with zero results). */
+  fun hasResults(query: String): Boolean = results.containsKey(query)
+}

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

@@ -0,0 +1,167 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.C
+import androidx.media3.common.ForwardingSimpleBasePlayer
+import androidx.media3.common.PlaybackParameters
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.MediaSession
+import com.google.common.util.concurrent.Futures
+import com.google.common.util.concurrent.ListenableFuture
+
+/**
+ * `MediaSession`-stable wrapper that intercepts external-controller
+ * transport commands before they reach the underlying player.
+ *
+ * The session binds to this one wrapper for its lifetime; [retarget]
+ * swaps the wrapped delegate as the active engine (gapless / crossfade)
+ * or cast player changes, so the session's bound player identity never
+ * churns. `ForwardingSimpleBasePlayer` (Media3 1.5+) is the supported
+ * runtime-swappable Player base — the same one [CrossfadeForwardingPlayer]
+ * uses — and exposes the `handle*` overrides that replace the deprecated
+ * `MediaSession.Callback.onPlayerCommandRequest`.
+ *
+ * A controller command routes session → the matching `handle*` override.
+ * The JS bridge drives the underlying engine player directly and never
+ * reaches this wrapper, so [isControllerRequest] gates interception to
+ * genuine external-controller requests (lock screen / Auto / Assistant /
+ * Bluetooth), leaving any internal mutation to fall straight through.
+ *
+ * Two behaviours preserved from the old callback:
+ *  - Queue-aware skip: a controller skip-next / skip-prev runs the lib's
+ *    queue arithmetic via [PlaybackService.MediaSessionCommandHandler] and
+ *    vetoes Media3's default seek when the lib handled it.
+ *  - System-reason stamping: play / pause / seek / speed commands stamp
+ *    `system` on the state-change channel before the command executes.
+ */
+@UnstableApi
+internal class SessionCommandForwardingPlayer(
+  initialPlayer: Player,
+  private val session: () -> MediaSession?,
+  private val commandHandler: () -> PlaybackService.MediaSessionCommandHandler?,
+) : ForwardingSimpleBasePlayer(initialPlayer) {
+
+  /**
+   * Jump intervals (ms) for interval-skip mode, read on each controller
+   * seek-forward/back so a runtime `setRemoteControls` change takes effect
+   * without rebuilding the player. `@Volatile` — set from the main thread,
+   * read on the application thread during a controller command.
+   */
+  @Volatile var forwardJumpMs: Long = 15_000
+  @Volatile var backwardJumpMs: Long = 15_000
+
+  /**
+   * Mirrors the `clampSeekToBuffered` player config for the controller
+   * interval-skip path so a lock-screen skip-forward obeys the same clamp as a
+   * JS `seekTo`. When enabled, an interval skip-forward on an unknown-duration
+   * source (`duration <= 0`, a live / open-ended stream) is capped at the
+   * buffered position rather than jumping into the unbuffered void. `@Volatile`
+   * — set from the main thread, read on the application thread during a seek.
+   */
+  @Volatile var clampSeekToBuffered: Boolean = false
+
+  /**
+   * Point the wrapped delegate at [player] — the active engine's session
+   * player or a cast player — and refresh cached state. The same
+   * runtime-swap entry point [CrossfadeForwardingPlayer] uses; keeps the
+   * session bound to this stable wrapper across engine and cast
+   * transitions instead of churning `MediaSession.setPlayer`.
+   */
+  fun retarget(player: Player) {
+    setPlayer(player)
+    invalidateState()
+  }
+
+  override fun handleSeek(
+    mediaItemIndex: Int,
+    positionMs: Long,
+    @Player.Command seekCommand: Int,
+  ): ListenableFuture<*> {
+    if (!isControllerRequest()) {
+      return super.handleSeek(mediaItemIndex, positionMs, seekCommand)
+    }
+    return when (seekCommand) {
+      Player.COMMAND_SEEK_TO_NEXT,
+      Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM ->
+        if (commandHandler()?.onSkipToNextCommand() == true) Futures.immediateVoidFuture()
+        else super.handleSeek(mediaItemIndex, positionMs, seekCommand)
+      Player.COMMAND_SEEK_TO_PREVIOUS,
+      Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM ->
+        if (commandHandler()?.onSkipToPreviousCommand() == true) Futures.immediateVoidFuture()
+        else super.handleSeek(mediaItemIndex, positionMs, seekCommand)
+      // Interval-skip mode: recompute the target with the runtime jump interval
+      // rather than the wrapped player's build-time seek increment, so the value
+      // is adjustable at runtime.
+      Player.COMMAND_SEEK_FORWARD -> {
+        commandHandler()?.onTransportCommand()
+        // No-op on a loaded-but-unseekable track so a lock-screen skip can't
+        // reset it to the start (mirrors seekToInternal's seekability guard).
+        if (isLoadedAndUnseekable()) return Futures.immediateVoidFuture()
+        val raw = currentPosition + forwardJumpMs
+        val dur = duration
+        var target = if (dur != C.TIME_UNSET && raw > dur) dur else raw
+        // Mirror seekTo's `clampSeekToBuffered`: cap at the buffered edge when
+        // the target is past what's downloaded (a fully-buffered track reports
+        // buffered >= target, so nothing is capped).
+        if (clampSeekToBuffered) {
+          val buffered = bufferedPosition
+          if (buffered != C.TIME_UNSET && buffered > 0L && target > buffered) {
+            target = buffered
+          }
+        }
+        // Forward the computed absolute target as an in-item seek. Passing the
+        // original COMMAND_SEEK_FORWARD would route the wrapped player to
+        // seekForward(), discarding target and jumping by its own build-time
+        // seekForwardIncrement — defeating the runtime interval.
+        super.handleSeek(
+          mediaItemIndex,
+          target.coerceAtLeast(0L),
+          Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM,
+        )
+      }
+      Player.COMMAND_SEEK_BACK -> {
+        commandHandler()?.onTransportCommand()
+        if (isLoadedAndUnseekable()) return Futures.immediateVoidFuture()
+        super.handleSeek(
+          mediaItemIndex,
+          (currentPosition - backwardJumpMs).coerceAtLeast(0L),
+          Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM,
+        )
+      }
+      else -> {
+        commandHandler()?.onTransportCommand()
+        super.handleSeek(mediaItemIndex, positionMs, seekCommand)
+      }
+    }
+  }
+
+  // True once the current item is loaded (STATE_READY / ENDED) AND confirmed
+  // unseekable — the state in which a raw seek would reset to the start. During
+  // initial buffering the window isn't populated yet, so an early skip isn't
+  // blocked.
+  private fun isLoadedAndUnseekable(): Boolean {
+    val loaded = playbackState == Player.STATE_READY || playbackState == Player.STATE_ENDED
+    return loaded && !isCurrentMediaItemSeekable
+  }
+
+  override fun handleSetPlayWhenReady(playWhenReady: Boolean): ListenableFuture<*> {
+    if (isControllerRequest()) commandHandler()?.onTransportCommand()
+    return super.handleSetPlayWhenReady(playWhenReady)
+  }
+
+  override fun handleSetPlaybackParameters(
+    playbackParameters: PlaybackParameters,
+  ): ListenableFuture<*> {
+    if (isControllerRequest()) commandHandler()?.onTransportCommand()
+    return super.handleSetPlaybackParameters(playbackParameters)
+  }
+
+  /**
+   * True while a controller-triggered Player method is executing.
+   * `getControllerForCurrentRequest` is non-null only for the duration
+   * of a controller-originated call on the application thread, which is
+   * exactly when the `handle*` overrides run.
+   */
+  private fun isControllerRequest(): Boolean =
+    session()?.controllerForCurrentRequest != null
+}