react-native-queue-player 1.0.0

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/AirPlayTxtParser.kt

@@ -0,0 +1,203 @@
+package com.margelo.nitro.queueplayer.cast.airplay
+
+/**
+ * Parse the TXT records emitted by AirPlay receivers into the typed
+ * fields the picker UI consumes. Both `_raop._tcp.` and `_airplay._tcp.`
+ * carry essentially the same set of records, with the keys we care
+ * about being:
+ *
+ * - `am=` — model identifier (e.g. `"AppleTV5,3"`, `"AudioAccessory1,1"`,
+ *   `"AirportExpress2,1"`, `"Speaker1,1"`). The leading word maps to
+ *   `extras.deviceClass` and the picker uses it to pick the right icon.
+ * - `model=` — alternative HomePod-style model string. Sometimes
+ *   present alongside `am=`, sometimes the only model field. Treated
+ *   as a fallback for `am=`.
+ * - `vs=` — server version (e.g. `"360.20"`). Diagnostic only — surfaced
+ *   in `extras["serverVersion"]` for power users / debugging.
+ * - `features=` — hex bitfield (e.g. `"0x4A7FCA00,0x1C340"`) describing
+ *   protocol capabilities. We care about:
+ *   - **bit 27** — AirPlay 2 support. When set, the receiver speaks AP2
+ *     and we surface `extras["supportsAirPlay2"] = "true"`.
+ *   - **bit 19** — pairing required (HomePod, modern Apple TVs). When
+ *     set, `Receiver.capabilities.requiresPairing = true`.
+ * - `deviceid=` — MAC-address-shaped stable identifier
+ *   (e.g. `"AA:BB:CC:DD:EE:FF"`). Used by `AirPlayDiscovery` to dedupe
+ *   the same physical receiver across `_raop._tcp.` and `_airplay._tcp.`
+ *   advertisements.
+ *
+ * Source for the bit definitions: shairport-sync `mdns_features` table
+ * and Apple's AirPlay 2 protocol writeups.
+ *
+ * Returned by [parse] as a [Parsed] data class. Failures degrade
+ * gracefully — an unparsable TXT field becomes a `null` or sensible
+ * default rather than throwing, because a single garbled receiver should
+ * not break discovery for the rest of the LAN.
+ */
+internal object AirPlayTxtParser {
+
+    /**
+     * Result of parsing a TXT record bag. Mirrors the fields the
+     * `AirPlayDiscovery` layer needs to construct a [com.margelo.nitro.queueplayer.cast.Receiver].
+     *
+     * @property deviceId Stable hardware id from `deviceid=`. `null` if
+     *   the receiver did not advertise it (rare). Used for cross-service
+     *   dedupe.
+     * @property deviceClass One of `"speaker" | "tv" | "display" |
+     *   "phone" | "computer" | "unknown"`, derived from `am=` / `model=`.
+     * @property requiresPairing `true` when features bit 19 is set
+     *   (HomePod / modern Apple TV).
+     * @property supportsAirPlay2 `true` when features bit 27 is set.
+     * @property serverVersion The `vs=` value verbatim, or `null`.
+     * @property modelString The `am=` or `model=` value verbatim, used
+     *   for [com.margelo.nitro.queueplayer.cast.Receiver.extras] under
+     *   the `"model"` key.
+     */
+    data class Parsed(
+        val deviceId: String?,
+        val deviceClass: String,
+        val requiresPairing: Boolean,
+        val supportsAirPlay2: Boolean,
+        val serverVersion: String?,
+        val modelString: String?,
+    )
+
+    /**
+     * Parse a TXT record bag (key/value, all values byte arrays from
+     * NsdManager).  Caller is responsible for decoding bytes to strings;
+     * NsdManager hands strings on API 21+ via
+     * `NsdServiceInfo.attributes` once the trailing API 33 wrinkle is
+     * accounted for.
+     *
+     * @param attrs The TXT record map already decoded to UTF-8 strings.
+     *   Keys are case-sensitive — AirPlay implementations are
+     *   inconsistent so we look up under both `am` / `AM` etc.
+     */
+    fun parse(attrs: Map<String, String?>): Parsed {
+        val deviceId = lookupCaseInsensitive(attrs, "deviceid")?.uppercase()
+        val am = lookupCaseInsensitive(attrs, "am")
+        val model = lookupCaseInsensitive(attrs, "model")
+        val vs = lookupCaseInsensitive(attrs, "vs")
+        val features = lookupCaseInsensitive(attrs, "features")
+        val manufacturer = lookupCaseInsensitive(attrs, "manufacturer")
+
+        val featureBits = parseFeatures(features)
+        val supportsAirPlay2 = featureBitSet(featureBits, AIRPLAY2_BIT)
+        val requiresPairing = featureBitSet(featureBits, PAIRING_REQUIRED_BIT)
+
+        return Parsed(
+            deviceId = deviceId,
+            deviceClass = mapDeviceClass(am ?: model, manufacturer),
+            requiresPairing = requiresPairing,
+            supportsAirPlay2 = supportsAirPlay2,
+            serverVersion = vs,
+            modelString = am ?: model,
+        )
+    }
+
+    /**
+     * Map an AirPlay model string to one of the documented device-class
+     * strings. The first lower-case token (`"AudioAccessory"`,
+     * `"AppleTV"`, `"AirportExpress"`, `"Speaker"`, `"iMac"`, `"iPhone"`,
+     * etc.) drives the classification. Anything we don't recognise
+     * falls through to `"unknown"`.
+     */
+    private fun mapDeviceClass(modelString: String?, manufacturer: String?): String {
+        if (!modelString.isNullOrBlank()) {
+            val token = modelString.takeWhile { it.isLetter() }.lowercase()
+            val fromToken = when (token) {
+                "audioaccessory",          // HomePod, HomePod mini
+                "speaker",                 // shairport-sync default
+                "airportexpress",          // AirPort Express
+                "raop",                    // generic RAOP receivers
+                "homepod",                 // some firmware reports this
+                "audio" -> "speaker"
+
+                "appletv",
+                "atv" -> "tv"
+
+                "mac",                     // Mac17,4 etc (bare "Mac" prefix)
+                "imac",
+                "macbook",
+                "macbookpro",
+                "macbookair",
+                "macmini",
+                "macpro",
+                "macstudio",
+                "computer" -> "computer"
+
+                "iphone" -> "phone"
+
+                "ipad",
+                "display",
+                "studiodisplay",
+                "promac",                  // Pro Display XDR variants
+                "monitor" -> "display"
+
+                else -> null
+            }
+            if (fromToken != null) return fromToken
+        }
+
+        // Third-party devices (Samsung, Bose, etc.) use product model IDs
+        // that don't follow Apple naming. Fall back to manufacturer if
+        // available — audio-brand manufacturers advertising AirPlay are
+        // overwhelmingly speakers/soundbars.
+        if (!manufacturer.isNullOrBlank()) {
+            val mfr = manufacturer.lowercase()
+            if (mfr in SPEAKER_MANUFACTURERS) return "speaker"
+            if (mfr in TV_MANUFACTURERS) return "tv"
+        }
+
+        return "unknown"
+    }
+
+    private val SPEAKER_MANUFACTURERS = setOf(
+        "samsung", "bose", "sonos", "denon", "harman", "jbl",
+        "bang & olufsen", "bang&olufsen", "b&o", "marantz",
+        "yamaha", "bluesound", "devialet", "naim", "libratone",
+        "ikea", "belkin",
+    )
+
+    private val TV_MANUFACTURERS = setOf(
+        "lg", "vizio", "roku", "hisense", "tcl",
+    )
+
+    /**
+     * Parse the `features=` field. The wire format is one or two
+     * comma-separated 32-bit hex words (`"0xHHHHHHHH"` or
+     * `"0xHHHHHHHH,0xHHHHHHHH"`). The first word holds bits 0..31, the
+     * second word holds bits 32..63. We pack the result into a single
+     * `Long` because we only need bits in the low 32 (bits 19 and 27).
+     *
+     * Returns `0L` if the field is missing or malformed — equivalent
+     * to "no features advertised", which is a safe default.
+     */
+    private fun parseFeatures(raw: String?): Long {
+        if (raw.isNullOrBlank()) return 0L
+        val words = raw.split(",").map { it.trim() }
+        if (words.isEmpty()) return 0L
+        val low = parseHexWord(words[0])
+        val high = if (words.size >= 2) parseHexWord(words[1]) else 0L
+        return (high shl 32) or (low and 0xFFFFFFFFL)
+    }
+
+    private fun parseHexWord(word: String): Long {
+        val cleaned = word.removePrefix("0x").removePrefix("0X")
+        return runCatching { java.lang.Long.parseLong(cleaned, 16) }.getOrDefault(0L)
+    }
+
+    private fun featureBitSet(bits: Long, bit: Int): Boolean =
+        (bits and (1L shl bit)) != 0L
+
+    private fun lookupCaseInsensitive(map: Map<String, String?>, key: String): String? {
+        // NsdManager attribute keys are usually lower-cased, but
+        // shairport-sync and a handful of third-party receivers use
+        // mixed case. Walk the map once instead of allocating a new
+        // case-folded copy.
+        map.entries.firstOrNull { it.key.equals(key, ignoreCase = true) }?.let { return it.value }
+        return null
+    }
+
+    private const val PAIRING_REQUIRED_BIT = 19
+    private const val AIRPLAY2_BIT = 27
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/AirplayJNI.kt

@@ -0,0 +1,106 @@
+package com.margelo.nitro.queueplayer.cast.airplay
+
+/**
+ * JNI surface for the native libraop library. Methods are registered
+ * via `JNI_OnLoad` in airplay_jni.cpp using RegisterNatives.
+ *
+ * Session lifecycle: [nativeOpen] → [nativeConnect] → send/control → [nativeDisconnect] → [nativeDestroy].
+ * The handle returned by [nativeOpen] is an opaque pointer (Long); pass it to every subsequent call.
+ */
+object AirplayJNI {
+
+    /** RAOP codec constants (maps to raop_codec_t). */
+    const val CODEC_PCM = 0
+    const val CODEC_ALAC_RAW = 1
+    const val CODEC_ALAC = 2
+    const val CODEC_AAC = 3
+    const val CODEC_AAC_ELC = 4
+
+    /** RAOP crypto constants (maps to raop_crypto_t). */
+    const val CRYPTO_CLEAR = 0
+    const val CRYPTO_RSA = 1
+
+    /** RAOP state constants (maps to raop_state_t). */
+    const val STATE_DOWN = 0
+    const val STATE_FLUSHING = 1
+    const val STATE_FLUSHED = 2
+    const val STATE_STREAMING = 3
+
+    /**
+     * `true` when libraop.so loaded successfully. ABIs without prebuilt
+     * native libs (armeabi-v7a, x86) report `false`, and callers must
+     * skip every JNI entry rather than crash with `UnsatisfiedLinkError`.
+     */
+    @JvmStatic
+    val isAvailable: Boolean = try {
+      System.loadLibrary("raop")
+      true
+    } catch (t: Throwable) {
+      android.util.Log.w("AirplayJNI", "libraop.so unavailable on this ABI: $t")
+      false
+    }
+
+    // -- Library info --
+
+    @JvmStatic external fun nativeVersion(): String
+    @JvmStatic external fun nativeInitSsl(): Boolean
+
+    // -- Session lifecycle --
+
+    /**
+     * Create a RAOP client session. Returns a handle (opaque pointer), or 0 on failure.
+     */
+    @JvmStatic external fun nativeOpen(
+        host: String, port: Int,
+        codec: Int, frameLen: Int, latencyFrames: Int,
+        crypto: Int, auth: Boolean,
+        sampleRate: Int, sampleSize: Int, channels: Int,
+        volume: Float,
+    ): Long
+
+    @JvmStatic external fun nativeConnect(handle: Long, host: String, port: Int): Boolean
+    @JvmStatic external fun nativeDisconnect(handle: Long): Boolean
+    @JvmStatic external fun nativeDestroy(handle: Long)
+
+    // -- Audio streaming (ring-buffer API) --
+
+    /** Feed PCM bytes into the ring buffer. Returns bytes consumed (== length, or 0 if full). */
+    @JvmStatic external fun nativeFeedPcm(handle: Long, data: ByteArray, offset: Int, length: Int): Int
+
+    /** Total PCM bytes successfully sent to the RAOP receiver (for position tracking). */
+    @JvmStatic external fun nativeBytesSent(handle: Long): Long
+
+    /** Bytes waiting in the ring buffer, not yet sent. Used for hasPendingData(). */
+    @JvmStatic external fun nativeRingAvailable(handle: Long): Int
+
+    // -- Audio streaming (legacy, kept for compatibility) --
+
+    @JvmStatic external fun nativeAcceptFrames(handle: Long): Boolean
+    @JvmStatic external fun nativeSendChunk(handle: Long, data: ByteArray, offset: Int, length: Int): Boolean
+    @JvmStatic external fun nativePause(handle: Long)
+    @JvmStatic external fun nativeStop(handle: Long)
+    @JvmStatic external fun nativeFlush(handle: Long): Boolean
+
+    // -- Configuration --
+
+    @JvmStatic external fun nativeGetLastRtspStatus(handle: Long): Int
+    @JvmStatic external fun nativeSetPassword(handle: Long, password: String?)
+    @JvmStatic external fun nativeSetDeviceName(handle: Long, name: String)
+
+    // -- Volume & metadata --
+
+    @JvmStatic external fun nativeSetVolume(handle: Long, volume: Float): Boolean
+    @JvmStatic external fun nativeSetProgressMs(handle: Long, elapsed: Int, duration: Int): Boolean
+    @JvmStatic external fun nativeGetProgressMs(handle: Long): Long
+    @JvmStatic external fun nativeSetDaap(handle: Long, title: String?, artist: String?, album: String?): Boolean
+    @JvmStatic external fun nativeSetArtwork(handle: Long, imageData: ByteArray, length: Int, contentType: String): Boolean
+
+    // -- State queries --
+
+    @JvmStatic external fun nativeIsConnected(handle: Long): Boolean
+    @JvmStatic external fun nativeIsPlaying(handle: Long): Boolean
+    @JvmStatic external fun nativeGetState(handle: Long): Int
+    @JvmStatic external fun nativeGetLatency(handle: Long): Int
+    @JvmStatic external fun nativeGetSampleRate(handle: Long): Int
+    @JvmStatic external fun nativeKeepalive(handle: Long): Boolean
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/MulticastLockHolder.kt

@@ -0,0 +1,75 @@
+package com.margelo.nitro.queueplayer.cast.airplay
+
+import android.content.Context
+import android.net.wifi.WifiManager
+
+/**
+ * Refcounted wrapper around `WifiManager.MulticastLock`. Holding a
+ * multicast lock is a hard requirement for NSD discovery on AirPlay's
+ * mDNS-based services — without it, the Wi-Fi chip silently drops
+ * multicast packets and the discovery callback never sees the receivers
+ * even though `_raop._tcp.` is being broadcast on the LAN.
+ *
+ * Refcounting matters because both `_raop._tcp.` and `_airplay._tcp.`
+ * discoveries are run in parallel from the same `AirPlayDiscovery`,
+ * and a future `:android-cast-dlna` would also want a multicast lock.
+ * Acquiring the lock twice and releasing it twice should leave the lock
+ * held while at least one caller still wants it.
+ *
+ * Thread-safe: every public method synchronizes on this instance because
+ * the underlying `MulticastLock` is not itself thread-safe.
+ *
+ * @property context Application context. Used to grab the
+ *   `WifiManager` system service. Pass the application context, not an
+ *   activity context — the lock survives across activities.
+ */
+internal class MulticastLockHolder(context: Context) {
+
+    private val wifiManager: WifiManager =
+        context.applicationContext.getSystemService(Context.WIFI_SERVICE) as WifiManager
+
+    private var lock: WifiManager.MulticastLock? = null
+    private var refCount: Int = 0
+
+    /**
+     * Acquire a reference. The first call creates the underlying
+     * `MulticastLock` and acquires it; subsequent calls just bump the
+     * refcount.
+     */
+    @Synchronized
+    fun acquire() {
+        if (refCount == 0) {
+            lock = wifiManager.createMulticastLock(LOCK_TAG).apply {
+                setReferenceCounted(false)
+                acquire()
+            }
+        }
+        refCount++
+    }
+
+    /**
+     * Release a reference. The last call releases and clears the
+     * underlying lock. Safe to call when refcount is already 0 — the
+     * lock is just absent.
+     */
+    @Synchronized
+    fun release() {
+        if (refCount == 0) return
+        refCount--
+        if (refCount == 0) {
+            lock?.let { if (it.isHeld) it.release() }
+            lock = null
+        }
+    }
+
+    /**
+     * Diagnostic — `true` while the underlying lock is held. Used by
+     * tests; production code should not branch on this.
+     */
+    @Synchronized
+    fun isHeld(): Boolean = lock?.isHeld == true
+
+    private companion object {
+        const val LOCK_TAG = "rntp-airplay-discovery"
+    }
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/chromecast/CastMediaItemConverter.kt

@@ -0,0 +1,67 @@
+package com.margelo.nitro.queueplayer.cast.chromecast
+
+import androidx.media3.cast.MediaItemConverter
+import androidx.media3.common.MediaItem
+import androidx.media3.common.util.UnstableApi
+import com.google.android.gms.cast.MediaInfo
+import com.google.android.gms.cast.MediaQueueItem
+import androidx.media3.common.MediaMetadata as Media3Metadata
+import com.google.android.gms.cast.MediaMetadata as CastMetadata
+
+/**
+ * Translates the receiver's queue items into Media3 [MediaItem]s so the
+ * MediaSession notification + lockscreen render the cast track's
+ * metadata while a [CastPlayer] drives the session.
+ *
+ * The receiver queue is loaded via `RemoteMediaClient.queueLoad`
+ * ([ChromecastSession.load]) rather than `CastPlayer.setMediaItems`, so
+ * CastPlayer's content-id map is empty and its current-item slot would
+ * be `MediaItem.EMPTY` without this converter. [toMediaItem] is the sole
+ * source of each item's metadata for the session surface; it reads back
+ * the Cast [CastMetadata] keys that [MediaInfoBuilder] wrote.
+ */
+@UnstableApi
+internal class CastMediaItemConverter : MediaItemConverter {
+
+  override fun toMediaItem(mediaQueueItem: MediaQueueItem): MediaItem {
+    val info: MediaInfo? = mediaQueueItem.media
+    val castMeta: CastMetadata? = info?.metadata
+
+    val metadata = Media3Metadata.Builder()
+      .setTitle(castMeta?.getString(CastMetadata.KEY_TITLE))
+      .setArtist(castMeta?.getString(CastMetadata.KEY_ARTIST))
+      .setAlbumTitle(castMeta?.getString(CastMetadata.KEY_ALBUM_TITLE))
+      .apply { castMeta?.images?.firstOrNull()?.url?.let { setArtworkUri(it) } }
+      .build()
+
+    val contentId = info?.contentId.orEmpty()
+    // The URI is carried only for item identity in CastPlayer's timeline;
+    // the receiver decodes the stream, so this is never opened locally.
+    return MediaItem.Builder()
+      .setMediaId(contentId)
+      .apply { if (contentId.isNotEmpty()) setUri(contentId) }
+      .setMediaMetadata(metadata)
+      .build()
+  }
+
+  override fun toMediaQueueItem(mediaItem: MediaItem): MediaQueueItem {
+    // Not exercised by this integration — the queue is pushed to the
+    // receiver via ChromecastSession.load → RemoteMediaClient.queueLoad,
+    // never via CastPlayer.setMediaItems. Provide a minimal valid item
+    // so the interface contract holds if CastPlayer ever calls it.
+    val uri = mediaItem.localConfiguration?.uri?.toString() ?: mediaItem.mediaId
+    val castMeta = CastMetadata(CastMetadata.MEDIA_TYPE_MUSIC_TRACK).apply {
+      mediaItem.mediaMetadata.title?.let { putString(CastMetadata.KEY_TITLE, it.toString()) }
+      mediaItem.mediaMetadata.artist?.let { putString(CastMetadata.KEY_ARTIST, it.toString()) }
+      mediaItem.mediaMetadata.albumTitle?.let {
+        putString(CastMetadata.KEY_ALBUM_TITLE, it.toString())
+      }
+    }
+    val info = MediaInfo.Builder(uri)
+      .setStreamType(MediaInfo.STREAM_TYPE_BUFFERED)
+      .setContentType("application/octet-stream")
+      .setMetadata(castMeta)
+      .build()
+    return MediaQueueItem.Builder(info).setAutoplay(true).build()
+  }
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/chromecast/CastVolumeForwardingPlayer.kt

@@ -0,0 +1,156 @@
+package com.margelo.nitro.queueplayer.cast.chromecast
+
+import android.os.SystemClock
+import androidx.media3.common.DeviceInfo
+import androidx.media3.common.ForwardingPlayer
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import kotlin.math.pow
+import kotlin.math.roundToInt
+
+/**
+ * Wraps the receiver's `RemoteCastPlayer` so the system + lock-screen hardware
+ * volume rocker gets fine-grained, perceptually-even control over the Chromecast
+ * device volume.
+ *
+ * The Cast route's native model is ~20 LINEAR steps over the receiver's
+ * `0.0..1.0` device volume (5% per press). Receivers apply their own steep curve,
+ * so the audible range collapses into the bottom of that scale — a couple of
+ * presses span silent→loud and the rest of the bar is dead. This wrapper
+ * advertises a finer [STEP_COUNT]-step remote [DeviceInfo] and maps each step
+ * through a compressive taper ([GAMMA] > 1) so equal presses produce roughly
+ * equal loudness changes, concentrating resolution at the quiet end where
+ * perceived loudness moves fastest. Steps map to `0.0..1.0` and are applied via
+ * [setReceiverVolume] (the receiver's device-volume plane).
+ *
+ * The wrapper only exists while a Chromecast session is bound to the
+ * `MediaSession`, so it always reports remote device volume. The step is tracked
+ * locally as the authoritative value (no dependence on the asynchronous receiver
+ * echo, so rapid presses increment cleanly); a volume change made on the receiver
+ * itself is not reflected until the next app-side change.
+ */
+@UnstableApi
+internal class CastVolumeForwardingPlayer(
+  player: Player,
+  routingControllerId: String?,
+  private val setReceiverVolume: (Float) -> Unit,
+  private val receiverVolume: () -> Float,
+) : ForwardingPlayer(player) {
+
+  private val remoteDeviceInfo: DeviceInfo =
+    DeviceInfo.Builder(DeviceInfo.PLAYBACK_TYPE_REMOTE)
+      .setMinVolume(0)
+      .setMaxVolume(STEP_COUNT)
+      .apply { routingControllerId?.let { setRoutingControllerId(it) } }
+      .build()
+
+  // [trackedStep] + [lastApplyMs] are read-modified-written together (getDeviceVolume
+  // resyncs, applyStep advances) without being atomic across the two fields. That is
+  // safe because Media3 routes device-volume commands to the player on a single
+  // (application/main) thread; `@Volatile` only publishes each field to the readback.
+
+  /** Locally-tracked current step; `-1` until first resolved from the receiver. */
+  @Volatile
+  private var trackedStep: Int = -1
+
+  /** `elapsedRealtime` of the last rocker-driven change; gates the resync. */
+  @Volatile
+  private var lastApplyMs: Long = 0L
+
+  override fun getDeviceInfo(): DeviceInfo = remoteDeviceInfo
+
+  override fun getAvailableCommands(): Player.Commands =
+    Player.Commands.Builder()
+      .addAll(super.getAvailableCommands())
+      .add(Player.COMMAND_GET_DEVICE_VOLUME)
+      .add(Player.COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS)
+      .add(Player.COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS)
+      .build()
+
+  override fun isCommandAvailable(command: Int): Boolean =
+    command in DEVICE_VOLUME_COMMANDS || super.isCommandAvailable(command)
+
+  override fun getDeviceVolume(): Int {
+    val receiver = receiverVolume()
+    // The locally-tracked step is authoritative while the rocker is in active
+    // use — the receiver echo lags rapid presses, so re-reading it would snap
+    // the step backwards mid-adjust. Once the rocker has been idle past
+    // [RESYNC_IDLE_MS], adopt the receiver's reported volume so a change made on
+    // the receiver itself (its own remote / the Home app) re-syncs the rocker.
+    if (!receiver.isNaN() &&
+      (trackedStep < 0 || SystemClock.elapsedRealtime() - lastApplyMs > RESYNC_IDLE_MS)
+    ) {
+      trackedStep = volumeToStep(receiver)
+    }
+    return trackedStep.coerceAtLeast(0)
+  }
+
+  override fun setDeviceVolume(volume: Int, flags: Int) = applyStep(volume)
+
+  override fun increaseDeviceVolume(flags: Int) = applyStep(getDeviceVolume() + 1)
+
+  override fun decreaseDeviceVolume(flags: Int) = applyStep(getDeviceVolume() - 1)
+
+  // The receiver advertises the legacy no-flags device-volume commands too, so
+  // route them through the same taper rather than letting `ForwardingPlayer`
+  // forward them raw to the receiver (which would skip the curve and clip the
+  // 0..STEP_COUNT value against the receiver's own ~20-step scale).
+  @Deprecated("Superseded by the (volume, flags) variant; both apply the taper.")
+  override fun setDeviceVolume(volume: Int) = applyStep(volume)
+
+  @Deprecated("Superseded by the (flags) variant; both apply the taper.")
+  override fun increaseDeviceVolume() = applyStep(getDeviceVolume() + 1)
+
+  @Deprecated("Superseded by the (flags) variant; both apply the taper.")
+  override fun decreaseDeviceVolume() = applyStep(getDeviceVolume() - 1)
+
+  private fun applyStep(step: Int) {
+    val clamped = step.coerceIn(0, STEP_COUNT)
+    trackedStep = clamped
+    lastApplyMs = SystemClock.elapsedRealtime()
+    setReceiverVolume(stepToVolume(clamped))
+  }
+
+  companion object {
+    /**
+     * Hardware-rocker step count over the receiver's device volume. ~30 leaves
+     * enough resolution at the quiet end after the taper without a sluggish
+     * rocker. Tunable; receiver-agnostic.
+     */
+    const val STEP_COUNT = 30
+
+    /**
+     * Compressive taper exponent ( > 1 ). Concentrates steps at the quiet end
+     * where perceived loudness changes fastest, so equal presses feel even.
+     * Tunable; deliberately receiver-agnostic (no per-device constant). The
+     * receiver quantizes device volume to a coarser grid than the lowest steps
+     * resolve to, so the bottom one or two presses may land on the same audible
+     * level — acceptable next to the dead range the taper reclaims higher up.
+     */
+    const val GAMMA = 2.5f
+
+    /**
+     * Idle gap after which [getDeviceVolume] adopts the receiver's reported
+     * volume instead of the locally-tracked step, so a change made on the
+     * receiver itself re-syncs once the rocker is no longer in active use.
+     */
+    private const val RESYNC_IDLE_MS = 1_500L
+
+    private val DEVICE_VOLUME_COMMANDS = setOf(
+      Player.COMMAND_GET_DEVICE_VOLUME,
+      Player.COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS,
+      Player.COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS,
+    )
+
+    /** Map a rocker step (`0..STEP_COUNT`) to receiver volume (`0.0..1.0`). */
+    fun stepToVolume(step: Int): Float =
+      (step.coerceIn(0, STEP_COUNT).toFloat() / STEP_COUNT).pow(GAMMA)
+
+    /** Inverse of [stepToVolume]: receiver volume (`0.0..1.0`) to nearest step. */
+    fun volumeToStep(volume: Float): Int {
+      if (volume.isNaN()) return 0
+      val frac = volume.coerceIn(0f, 1f).pow(1f / GAMMA)
+      return (frac * STEP_COUNT).roundToInt().coerceIn(0, STEP_COUNT)
+    }
+  }
+}