feat: implement volume guard to snapshot media volume for USB exclusive audio anchors

Author: cwuom

app/src/main/java/moe/ouom/neriplayer/core/player/usb/sink/UsbExclusiveAudioSink.kt

@@ -52,6 +52,7 @@ import moe.ouom.neriplayer.core.player.lifecycle.stopPlaybackAfterUsbExclusiveNa
 import moe.ouom.neriplayer.core.player.lifecycle.tryRecoverUsbExclusivePlaybackAfterNativeTransferFailure
 import moe.ouom.neriplayer.core.player.usb.path.UsbExclusiveAudioPathTracker
 import moe.ouom.neriplayer.core.player.usb.session.UsbExclusiveSessionController
+import moe.ouom.neriplayer.core.player.usb.system.UsbExclusiveBackgroundAudioAnchorVolumeGuard
 import moe.ouom.neriplayer.core.player.usb.system.UsbExclusiveSystemSoundGuard
 import moe.ouom.neriplayer.core.player.usb.system.usbExclusiveEffectiveNativeVolume
 import moe.ouom.neriplayer.core.player.usb.system.usbExclusiveFloatSampleForNativePipeline
@@ -1498,6 +1499,9 @@ internal class UsbExclusiveAudioSink(
     }
 
     private fun readMusicVolumeFractionFromSystem(): Float {
+        UsbExclusiveBackgroundAudioAnchorVolumeGuard.currentVolumeFractionOrNull()?.let {
+            return it
+        }
         val manager = audioManager ?: return 1f
         return runCatching {
             val minVolume = manager.getStreamMinVolume(AudioManager.STREAM_MUSIC)

app/src/main/java/moe/ouom/neriplayer/core/player/usb/system/UsbExclusiveBackgroundAudioAnchor.kt

@@ -21,6 +21,7 @@ internal object UsbExclusiveBackgroundAudioAnchor {
         val track: AudioTrack,
         val spec: UsbExclusiveBackgroundAudioAnchorSpec,
         val silence: ByteArray,
+        val volumeGuardToken: UsbExclusiveBackgroundAudioAnchorVolumeGuardToken?,
         var streamWriterRunning: AtomicBoolean? = null,
         var streamWriter: Thread? = null
     )
@@ -36,7 +37,12 @@ internal object UsbExclusiveBackgroundAudioAnchor {
             }
             releaseLocked("replace_unusable:$reason")
 
-            val created = createAnchor(context, reason) ?: return false
+            val volumeGuardToken = UsbExclusiveBackgroundAudioAnchorVolumeGuard.acquire(context)
+            val created = createAnchor(context, reason, volumeGuardToken)
+            if (created == null) {
+                UsbExclusiveBackgroundAudioAnchorVolumeGuard.release(volumeGuardToken)
+                return false
+            }
             activeAnchor = created
             return resume(created, reason)
         }
@@ -56,9 +62,13 @@ internal object UsbExclusiveBackgroundAudioAnchor {
         }
     }
 
-    private fun createAnchor(context: Context, reason: String): ActiveAnchor? {
+    private fun createAnchor(
+        context: Context,
+        reason: String,
+        volumeGuardToken: UsbExclusiveBackgroundAudioAnchorVolumeGuardToken?
+    ): ActiveAnchor? {
         for (spec in usbExclusiveBackgroundAudioAnchorSpecs()) {
-            val anchor = createAnchor(context, reason, spec)
+            val anchor = createAnchor(context, reason, spec, volumeGuardToken)
             if (anchor != null) return anchor
         }
         NPLogger.w(TAG, "no compatible silent media anchor reason=$reason")
@@ -68,7 +78,8 @@ internal object UsbExclusiveBackgroundAudioAnchor {
     private fun createAnchor(
         context: Context,
         reason: String,
-        spec: UsbExclusiveBackgroundAudioAnchorSpec
+        spec: UsbExclusiveBackgroundAudioAnchorSpec,
+        volumeGuardToken: UsbExclusiveBackgroundAudioAnchorVolumeGuardToken?
     ): ActiveAnchor? {
         val channelMask = when (spec.channelCount) {
             1 -> AudioFormat.CHANNEL_OUT_MONO
@@ -111,7 +122,12 @@ internal object UsbExclusiveBackgroundAudioAnchor {
             releaseTrack(track)
             return null
         }
-        return ActiveAnchor(track = track, spec = spec, silence = silence)
+        return ActiveAnchor(
+            track = track,
+            spec = spec,
+            silence = silence,
+            volumeGuardToken = volumeGuardToken
+        )
     }
 
     private fun resolveBufferBytes(
@@ -247,6 +263,7 @@ internal object UsbExclusiveBackgroundAudioAnchor {
         anchor.streamWriter = null
         anchor.streamWriterRunning = null
         releaseTrack(anchor.track)
+        UsbExclusiveBackgroundAudioAnchorVolumeGuard.release(anchor.volumeGuardToken)
         NPLogger.i(TAG, "released silent media anchor reason=$reason spec=${anchor.spec.name}")
     }
 

app/src/main/java/moe/ouom/neriplayer/core/player/usb/system/UsbExclusiveBackgroundAudioAnchorVolumeGuard.kt

@@ -0,0 +1,77 @@
+package moe.ouom.neriplayer.core.player.usb.system
+
+import android.content.Context
+import android.media.AudioManager
+
+internal data class UsbExclusiveBackgroundAudioAnchorVolumeGuardToken(
+    val generation: Long
+)
+
+internal class UsbExclusiveBackgroundAudioAnchorVolumeGuardState {
+    private data class ActiveSnapshot(
+        val token: UsbExclusiveBackgroundAudioAnchorVolumeGuardToken,
+        val volumeFraction: Float
+    )
+
+    private var nextGeneration = 0L
+    private var activeSnapshot: ActiveSnapshot? = null
+
+    fun acquire(volumeFraction: Float): UsbExclusiveBackgroundAudioAnchorVolumeGuardToken {
+        val token = UsbExclusiveBackgroundAudioAnchorVolumeGuardToken(++nextGeneration)
+        activeSnapshot = ActiveSnapshot(
+            token = token,
+            volumeFraction = volumeFraction.coerceIn(0f, 1f)
+        )
+        return token
+    }
+
+    fun currentVolumeFractionOrNull(): Float? = activeSnapshot?.volumeFraction
+
+    fun release(token: UsbExclusiveBackgroundAudioAnchorVolumeGuardToken) {
+        if (activeSnapshot?.token == token) {
+            activeSnapshot = null
+        }
+    }
+}
+
+internal object UsbExclusiveBackgroundAudioAnchorVolumeGuard {
+    private val lock = Any()
+    private val state = UsbExclusiveBackgroundAudioAnchorVolumeGuardState()
+
+    fun acquire(context: Context): UsbExclusiveBackgroundAudioAnchorVolumeGuardToken? {
+        val volumeFraction = readMusicVolumeFraction(context) ?: return null
+        return synchronized(lock) {
+            state.acquire(volumeFraction)
+        }
+    }
+
+    fun currentVolumeFractionOrNull(): Float? {
+        return synchronized(lock) {
+            state.currentVolumeFractionOrNull()
+        }
+    }
+
+    fun release(token: UsbExclusiveBackgroundAudioAnchorVolumeGuardToken?) {
+        if (token == null) return
+        synchronized(lock) {
+            state.release(token)
+        }
+    }
+
+    private fun readMusicVolumeFraction(context: Context): Float? {
+        val audioManager = context.applicationContext
+            .getSystemService(Context.AUDIO_SERVICE) as? AudioManager
+            ?: return null
+        return runCatching {
+            val minVolume = audioManager.getStreamMinVolume(AudioManager.STREAM_MUSIC)
+            val maxVolume = audioManager.getStreamMaxVolume(AudioManager.STREAM_MUSIC)
+            val currentVolume = audioManager.getStreamVolume(AudioManager.STREAM_MUSIC)
+            val range = maxVolume - minVolume
+            if (range <= 0) {
+                null
+            } else {
+                ((currentVolume - minVolume).toFloat() / range.toFloat()).coerceIn(0f, 1f)
+            }
+        }.getOrNull()
+    }
+}

app/src/test/java/moe/ouom/neriplayer/core/player/usb/system/UsbExclusiveBackgroundAudioAnchorVolumeGuardTest.kt

@@ -0,0 +1,44 @@
+package moe.ouom.neriplayer.core.player.usb.system
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class UsbExclusiveBackgroundAudioAnchorVolumeGuardTest {
+
+    @Test
+    fun `anchor keeps the pre-anchor USB volume snapshot active`() {
+        val state = UsbExclusiveBackgroundAudioAnchorVolumeGuardState()
+        val token = state.acquire(0.92f)
+
+        assertEquals(0.92f, state.currentVolumeFractionOrNull() ?: -1f, 0.0001f)
+
+        state.release(token)
+
+        assertNull(state.currentVolumeFractionOrNull())
+    }
+
+    @Test
+    fun `stale anchor release cannot clear a newer volume snapshot`() {
+        val state = UsbExclusiveBackgroundAudioAnchorVolumeGuardState()
+        val firstToken = state.acquire(0.92f)
+        val secondToken = state.acquire(0.67f)
+
+        state.release(firstToken)
+
+        assertEquals(0.67f, state.currentVolumeFractionOrNull() ?: -1f, 0.0001f)
+
+        state.release(secondToken)
+
+        assertNull(state.currentVolumeFractionOrNull())
+    }
+
+    @Test
+    fun `anchor snapshot is constrained to valid media volume bounds`() {
+        val state = UsbExclusiveBackgroundAudioAnchorVolumeGuardState()
+
+        state.acquire(2f)
+
+        assertEquals(1f, state.currentVolumeFractionOrNull() ?: -1f, 0.0001f)
+    }
+}