USB exclusive mode — bit-perfect output to USB DACs

.github/release-tag.txt

@@ -0,0 +1 @@
+v0.7.5-usb-beta.3

.github/workflows/usb-beta-release.yml

@@ -0,0 +1,136 @@
+name: USB Beta Release
+
+# Builds signed release APKs and publishes them as a GitHub Release.
+# Two triggers:
+#  - manual dispatch (tag comes from the input), or
+#  - a push that changes .github/release-tag.txt (tag comes from that file) — this
+#    lets a release be cut from an environment that can push the branch but cannot
+#    call the workflow-dispatch API or push tags.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (also used in the APK file names)'
+        required: true
+        default: 'v0.7.5-usb-beta.1'
+  push:
+    branches:
+      - claude/new-session-lpe3cm
+    paths:
+      - '.github/release-tag.txt'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: usb-beta-release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Resolve release tag
+        id: tag
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          if [ -n "${INPUT_TAG}" ]; then
+            TAG="${INPUT_TAG}"
+          else
+            TAG="$(tr -d '[:space:]' < .github/release-tag.txt)"
+          fi
+          if [ -z "${TAG}" ]; then
+            echo "No release tag resolved" >&2
+            exit 1
+          fi
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v6
+
+      # Same cache key as nightly-apk.yml: beta releases and nightlies share one
+      # signature, so update-installs work across them.
+      - name: Cache nightly keystore
+        id: cache-keystore
+        uses: actions/cache@v5
+        with:
+          path: vz-pixelplay.jks
+          key: ${{ runner.os }}-nightly-keystore-vz-pixelplay
+
+      - name: Generate nightly keystore if not cached
+        if: steps.cache-keystore.outputs.cache-hit != 'true'
+        run: |
+          keytool -genkey -v -keystore vz-pixelplay.jks -alias pixelplay-nightly-key -keyalg RSA -keysize 4096 -validity 10000 \
+            -storepass 994273 -keypass 994273 \
+            -dname "CN=PixelPlay Nightly, OU=Dev, O=PixelPlay, L=World, S=World, C=US"
+
+      - name: Create keystore.properties
+        run: |
+          echo "storePassword=994273" > keystore.properties
+          echo "keyAlias=pixelplay-nightly-key" >> keystore.properties
+          echo "keyPassword=994273" >> keystore.properties
+
+      - name: Build release APKs
+        run: gradle :app:assembleRelease -Ppixelplay.enableAbiSplits=true
+
+      - name: Verify split APKs
+        run: |
+          BUILD_TOOLS_VERSION="$(ls "$ANDROID_HOME/build-tools" | sort -V | tail -n 1)"
+          for apk in \
+            app/build/outputs/apk/release/app-arm64-v8a-release.apk \
+            app/build/outputs/apk/release/app-armeabi-v7a-release.apk
+          do
+            "$ANDROID_HOME/build-tools/$BUILD_TOOLS_VERSION/aapt2" dump badging "$apk" >/dev/null
+            "$ANDROID_HOME/build-tools/$BUILD_TOOLS_VERSION/apksigner" verify --verbose "$apk"
+          done
+
+      - name: Stage release assets
+        env:
+          RELEASE_TAG: ${{ steps.tag.outputs.tag }}
+        run: |
+          mkdir -p release-assets
+          cp app/build/outputs/apk/release/app-arm64-v8a-release.apk \
+            "release-assets/PixelPlay-${RELEASE_TAG}-arm64-v8a.apk"
+          cp app/build/outputs/apk/release/app-armeabi-v7a-release.apk \
+            "release-assets/PixelPlay-${RELEASE_TAG}-armeabi-v7a.apk"
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag }}
+          name: 'USB Exclusive Mode (bit-perfect) — ${{ steps.tag.outputs.tag }}'
+          prerelease: true
+          files: release-assets/*.apk
+          body: |
+            Beta build of **USB exclusive mode**: PixelPlay claims a USB DAC directly
+            (libusb, no root) and streams at the track's native sample rate and bit
+            depth — bit-perfect, bypassing the Android mixer. Validated on a FiiO
+            BTR17 up to 768 kHz.
+
+            **Install:** download the `arm64-v8a` APK (fits virtually all phones;
+            `armeabi-v7a` is only for very old 32-bit devices), open it on the phone
+            and allow installing from unknown sources.
+
+            **Signature note:** this build is signed with the CI test key (same as the
+            nightly builds). It cannot update-install over a copy of PixelPlay signed
+            with a different key — uninstall that one first, or install alongside a
+            `.debug` test build (different application id, no conflict).
+
+            **Usage:** Settings → Playback → USB Audio → enable *USB exclusive mode*,
+            plug in the DAC, grant the USB permission. The Now Playing screen shows
+            `USB • <bit>/<rate>` while bit-perfect output is active, and the DAC's own
+            display follows the track's sample rate.
+
+            Full feature documentation: `docs/usb-exclusive-mode.md` in the repo.

.gitignore

@@ -33,6 +33,7 @@ app/release/
 wear/build/
 wear/release/
 shared/build/
+usbaudio/build/
 baselineprofile/build/
 
 misc.xml

app/build.gradle.kts

@@ -301,6 +301,7 @@ dependencies {
 
     // Projects
     implementation(project(":shared"))
+    implementation(project(":usbaudio"))
 
     // Testing (Unit)
     testImplementation(libs.junit.jupiter.api)

app/src/main/AndroidManifest.xml

@@ -35,6 +35,11 @@
     <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
     <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
 
+    <!-- USB DAC exclusive mode (optional: the app works fully without USB host support). -->
+    <uses-feature
+        android:name="android.hardware.usb.host"
+        android:required="false" />
+
     <application
         android:name=".PixelPlayApplication"
         android:allowBackup="true"

app/src/main/java/com/theveloper/pixelplay/data/preferences/UserPreferencesRepository.kt

@@ -22,6 +22,7 @@ import com.theveloper.pixelplay.data.model.Playlist
 import com.theveloper.pixelplay.data.model.SortOption
 import com.theveloper.pixelplay.data.model.StorageFilter
 import com.theveloper.pixelplay.data.model.TransitionSettings
+import com.theveloper.pixelplay.data.usb.UsbRememberedDevice
 import javax.inject.Inject
 import javax.inject.Singleton
 import kotlinx.coroutines.flow.Flow
@@ -140,6 +141,10 @@ class UserPreferencesRepository @Inject constructor(
         val KEEP_PLAYING_IN_BACKGROUND = booleanPreferencesKey("keep_playing_in_background")
         val IS_CROSSFADE_ENABLED = booleanPreferencesKey("is_crossfade_enabled")
         val HI_FI_MODE_ENABLED = booleanPreferencesKey("hi_fi_mode_enabled")
+        val USB_EXCLUSIVE_MODE_ENABLED = booleanPreferencesKey("usb_exclusive_mode_enabled")
+        val USB_REMEMBERED_DEVICES = stringPreferencesKey("usb_remembered_devices_json")
+        val USB_EXCLUSIVE_MAX_VOLUME_ACK = booleanPreferencesKey("usb_exclusive_max_volume_ack")
+        val USB_FIXED_VOLUME_OUTPUT = booleanPreferencesKey("usb_fixed_volume_output")
         val CROSSFADE_DURATION = intPreferencesKey("crossfade_duration")
         val CUSTOM_GENRES = stringSetPreferencesKey("custom_genres")
         val CUSTOM_GENRE_ICONS = stringPreferencesKey("custom_genre_icons")
@@ -349,6 +354,40 @@ class UserPreferencesRepository @Inject constructor(
         dataStore.edit { it[PreferencesKeys.HI_FI_MODE_ENABLED] = enabled }
     }
 
+    val usbExclusiveModeEnabledFlow: Flow<Boolean> =
+        pref { it[PreferencesKeys.USB_EXCLUSIVE_MODE_ENABLED] ?: false }
+
+    suspend fun setUsbExclusiveModeEnabled(enabled: Boolean) {
+        dataStore.edit { it[PreferencesKeys.USB_EXCLUSIVE_MODE_ENABLED] = enabled }
+    }
+
+    /** Remembered USB DACs keyed by [com.theveloper.pixelplay.data.usb.UsbDeviceInfo.key]. */
+    val usbRememberedDevicesFlow: Flow<Map<String, UsbRememberedDevice>> =
+        pref { decodeJsonPref(it, PreferencesKeys.USB_REMEMBERED_DEVICES, emptyMap()) }
+
+    suspend fun rememberUsbDevice(key: String, device: UsbRememberedDevice) {
+        editJsonMap<UsbRememberedDevice>(PreferencesKeys.USB_REMEMBERED_DEVICES) { put(key, device) }
+    }
+
+    suspend fun forgetUsbDevice(key: String) {
+        editJsonMap<UsbRememberedDevice>(PreferencesKeys.USB_REMEMBERED_DEVICES) { remove(key) }
+    }
+
+    val usbExclusiveMaxVolumeAckFlow: Flow<Boolean> =
+        pref { it[PreferencesKeys.USB_EXCLUSIVE_MAX_VOLUME_ACK] ?: false }
+
+    suspend fun setUsbExclusiveMaxVolumeAck(acknowledged: Boolean) {
+        dataStore.edit { it[PreferencesKeys.USB_EXCLUSIVE_MAX_VOLUME_ACK] = acknowledged }
+    }
+
+    /** Purist mode: always full-scale output on volume-less DACs (no software gain stage). */
+    val usbFixedVolumeOutputFlow: Flow<Boolean> =
+        pref { it[PreferencesKeys.USB_FIXED_VOLUME_OUTPUT] ?: false }
+
+    suspend fun setUsbFixedVolumeOutput(fixed: Boolean) {
+        dataStore.edit { it[PreferencesKeys.USB_FIXED_VOLUME_OUTPUT] = fixed }
+    }
+
     val keepPlayingInBackgroundFlow: Flow<Boolean> =
         pref { it[PreferencesKeys.KEEP_PLAYING_IN_BACKGROUND] ?: true }
 

app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt

@@ -53,6 +53,8 @@ import com.theveloper.pixelplay.data.preferences.ThemePreferencesRepository
 import com.theveloper.pixelplay.data.preferences.UserPreferencesRepository
 import com.theveloper.pixelplay.data.repository.MusicRepository
 import com.theveloper.pixelplay.data.service.player.DualPlayerEngine
+import com.theveloper.pixelplay.data.usb.UsbExclusiveModeController
+import com.theveloper.pixelplay.data.usb.UsbExclusiveState
 import com.theveloper.pixelplay.data.service.player.TransitionController
 import com.theveloper.pixelplay.ui.glancewidget.PlayerActions
 import com.theveloper.pixelplay.utils.AlbumArtUtils
@@ -63,6 +65,8 @@ import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
@@ -168,6 +172,8 @@ class MusicService : MediaLibraryService() {
     @Inject
     lateinit var listeningStatsTracker: ListeningStatsTracker
     @Inject
+    lateinit var usbExclusiveModeController: UsbExclusiveModeController
+    @Inject
     @AppScope
     lateinit var appScope: CoroutineScope
 
@@ -188,6 +194,9 @@ class MusicService : MediaLibraryService() {
     private val controllerLastBrowsedParent = mutableMapOf<String, String>()
     private val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
     private var keepPlayingInBackground = true
+    // Set when the USB DAC vanished while playing; a re-attach of a remembered device
+    // with auto-resume then continues playback.
+    private var usbResumeAfterReattach = false
     private var isManualShuffleEnabled = false
     private var persistentShuffleEnabled = false
     // Holds the previous main-thread UncaughtExceptionHandler so we can restore it in onDestroy.
@@ -338,13 +347,33 @@ class MusicService : MediaLibraryService() {
         replayGainProcessor.onTransitionFinished()
     }
 
+    /**
+     * Wraps the player for the media session while USB exclusive mode is engaged so the
+     * phone's volume keys reach the DAC (hardware feature unit or software gain stage).
+     * Reuses the existing wrapper when the underlying player hasn't changed, so the
+     * identity check below keeps working.
+     */
+    private var usbVolumePlayerWrapper: com.theveloper.pixelplay.data.service.player.usb.UsbDeviceVolumePlayer? = null
+
+    private fun sessionPlayerFor(player: Player): Player {
+        if (usbExclusiveModeController.activeSession == null) {
+            usbVolumePlayerWrapper = null
+            return player
+        }
+        usbVolumePlayerWrapper?.takeIf { it.wrappedPlayer === player }?.let { return it }
+        return com.theveloper.pixelplay.data.service.player.usb.UsbDeviceVolumePlayer(
+            player, usbExclusiveModeController
+        ).also { usbVolumePlayerWrapper = it }
+    }
+
     private fun publishMediaSessionPlayer(player: Player, logMessage: String) {
         val session = mediaSession ?: return
+        val target = sessionPlayerFor(player)
         val oldPlayer = session.player
-        if (oldPlayer !== player) {
+        if (oldPlayer !== target) {
             oldPlayer.removeListener(playerListener)
-            session.player = player
-            player.addListener(playerListener)
+            session.player = target
+            target.addListener(playerListener)
         }
 
         Timber.tag("MusicService").d(logMessage)
@@ -507,6 +536,42 @@ class MusicService : MediaLibraryService() {
             }
         }
 
+        // USB exclusive mode: attach/detach the bit-perfect sink as the controller's session
+        // comes and goes. The engine rebuild preserves queue/position (same as Hi-Fi toggle).
+        serviceScope.launch {
+            usbExclusiveModeController.state.collect { state ->
+                val session = when (state) {
+                    is UsbExclusiveState.Ready, is UsbExclusiveState.Active ->
+                        usbExclusiveModeController.activeSession
+                    else -> null
+                }
+                engine.setUsbExclusiveMode(
+                    session,
+                    usbExclusiveModeController::onSinkFormatChanged,
+                    usbExclusiveModeController::onSessionDead
+                )
+
+                // Re-attach of a remembered device after an unplug: offer to resume by
+                // actually resuming, mirroring the headset-reconnect behavior.
+                if (state is UsbExclusiveState.Ready && usbResumeAfterReattach) {
+                    usbResumeAfterReattach = false
+                    val remembered = userPreferencesRepository.usbRememberedDevicesFlow.first()
+                    if (remembered[state.device.key]?.autoResume == true) {
+                        mediaSession?.player?.play()
+                    }
+                }
+            }
+        }
+        // DAC unplugged mid-playback: pause immediately; the state collector above swaps the
+        // engine back to the normal output path without losing the queue.
+        serviceScope.launch {
+            usbExclusiveModeController.sessionLost.collect {
+                val player = mediaSession?.player
+                usbResumeAfterReattach = player?.playWhenReady == true
+                player?.pause()
+            }
+        }
+
         serviceScope.launch {
             userPreferencesRepository.resumeOnHeadsetReconnectFlow.collect { enabled ->
                 resumeOnHeadsetReconnectEnabled = enabled
@@ -528,10 +593,16 @@ class MusicService : MediaLibraryService() {
             }
         }
 
-        // ReplayGain preference collectors
+        // ReplayGain preference collectors. ReplayGain scales the player volume, which the
+        // bit-perfect USB path must never do — gate it on exclusive mode being inactive.
         serviceScope.launch {
-            userPreferencesRepository.replayGainEnabledFlow.collect { enabled ->
-                replayGainProcessor.setEnabled(enabled)
+            combine(
+                userPreferencesRepository.replayGainEnabledFlow,
+                usbExclusiveModeController.state
+            ) { enabled, usbState ->
+                enabled && usbState !is UsbExclusiveState.Ready && usbState !is UsbExclusiveState.Active
+            }.distinctUntilChanged().collect { effectiveEnabled ->
+                replayGainProcessor.setEnabled(effectiveEnabled)
                 // Re-apply to current track when toggled
                 replayGainProcessor.apply(mediaSession?.player?.currentMediaItem)
             }