react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/android/src/main/java/com/audiobrowser/player/MediaSessionCommandManager.kt

@@ -4,26 +4,50 @@ import android.os.Bundle
 import androidx.media3.common.Player as MediaPlayer
 import androidx.media3.session.CommandButton
 import androidx.media3.session.MediaSession
-import androidx.media3.session.R
 import androidx.media3.session.SessionCommand
 import androidx.media3.session.SessionCommands
-import com.margelo.nitro.audiobrowser.NotificationButton
-import com.margelo.nitro.audiobrowser.NotificationButtonLayout
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
+import com.margelo.nitro.audiobrowser.RemoteButton
+import com.margelo.nitro.audiobrowser.RemoteButtonLayout
 import timber.log.Timber
 
+/**
+ * A slot's Media3 preference list: the requested slot, then OVERFLOW as a fallback.
+ *
+ * `slots` is a preference order, not a coordinate — Media3 places a button in the first slot in the
+ * list "that exists, isn't already occupied and that allows this type of button". Naming OVERFLOW
+ * second means a button whose primary position is unavailable on some surface demotes instead of
+ * disappearing, because every flattening
+ * (`CommandButton.getCustomLayoutFromMediaButtonPreferences`, run by both `MediaSessionLegacyStub`
+ * for Android Auto and the Android 13+ controls, and `DefaultMediaNotificationProvider` for the
+ * notification) keeps a button only if it won BACK, won FORWARD, or *contains* OVERFLOW.
+ */
+internal fun media3SlotsFor(slot: ButtonSlot): IntArray =
+  when (slot) {
+    ButtonSlot.BACK -> intArrayOf(CommandButton.SLOT_BACK, CommandButton.SLOT_OVERFLOW)
+    ButtonSlot.FORWARD -> intArrayOf(CommandButton.SLOT_FORWARD, CommandButton.SLOT_OVERFLOW)
+    ButtonSlot.OVERFLOW -> intArrayOf(CommandButton.SLOT_OVERFLOW)
+  }
+
 /**
  * MediaSession manager that handles command configuration and execution.
  *
  * Responsibilities:
- * - Maps player capabilities to MediaSession commands and notification layouts
+ * - Maps player capabilities to MediaSession commands
+ * - Builds the single, slot-annotated button layout published to every surface
  * - Updates MediaSession configuration and applies changes immediately
  * - Builds connection results for new MediaSession controllers
  * - Handles execution of custom MediaSession commands (jump actions)
- * - Maintains proper separation between global capabilities and notification-specific controls
  *
- * Initializes with sensible defaults: all global capabilities enabled, essential notification
- * controls only.
+ * Capabilities decide what the player can do; the button layout decides where those buttons sit.
+ * Placement never revokes a capability — a control left out of the layout still works from a
+ * Bluetooth remote or headset.
+ *
+ * There is ONE layout, published session-wide via `setMediaButtonPreferences`. Media3 fans it out:
+ * `MediaNotificationManager` renders it as the MediaStyle notification (Android 12 and below), and
+ * `MediaSessionLegacyStub` converts it into the platform PlaybackState plus the slot-reservation
+ * extras that Android Auto and the Android 13+ system media controls read. Publishing
+ * per-controller instead would reach neither, since Android Auto connects as a legacy controller.
  */
 class MediaSessionCommandManager {
 
@@ -31,59 +55,100 @@ class MediaSessionCommandManager {
     private const val CUSTOM_ACTION_JUMP_BACKWARD = "JUMP_BACKWARD"
     private const val CUSTOM_ACTION_JUMP_FORWARD = "JUMP_FORWARD"
     const val CUSTOM_ACTION_FAVORITE = "FAVORITE"
-  }
 
-  /** Current player commands configuration for external controllers */
-  var playerCommands: MediaPlayer.Commands = MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS
-    private set
+    /** Matches PlayerUpdateOptions.forwardJumpInterval/backwardJumpInterval */
+    private const val DEFAULT_JUMP_INTERVAL = 15.0
+  }
 
-  /** Current player commands configuration for notification controller */
-  var notificationPlayerCommands: MediaPlayer.Commands =
-    MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS
-    private set
+  /**
+   * Media3 ships numbered icons for 5, 10, 15 and 30 seconds; every other interval falls back to
+   * the unnumbered arrow.
+   *
+   * The match is exact, not rounded. A numbered icon is a claim about how far the button seeks, so
+   * a 14.6s interval must not draw "15" — it would promise a jump the player never makes. Better an
+   * honest arrow than a wrong number.
+   *
+   * The icon constant — not the drawable — is what a controller that renders its own UI reads, and
+   * it is carried through the legacy conversion Android Auto consumes. Building a button with only
+   * `setIconResId` leaves the constant at ICON_UNDEFINED, so the car has nothing to draw.
+   */
+  private fun jumpForwardIcon(seconds: Double): Int =
+    when (seconds) {
+      5.0 -> CommandButton.ICON_SKIP_FORWARD_5
+      10.0 -> CommandButton.ICON_SKIP_FORWARD_10
+      15.0 -> CommandButton.ICON_SKIP_FORWARD_15
+      30.0 -> CommandButton.ICON_SKIP_FORWARD_30
+      else -> CommandButton.ICON_SKIP_FORWARD
+    }
 
-  /** Current session commands configuration for external controllers */
-  lateinit var sessionCommands: SessionCommands
-    private set
+  private fun jumpBackwardIcon(seconds: Double): Int =
+    when (seconds) {
+      5.0 -> CommandButton.ICON_SKIP_BACK_5
+      10.0 -> CommandButton.ICON_SKIP_BACK_10
+      15.0 -> CommandButton.ICON_SKIP_BACK_15
+      30.0 -> CommandButton.ICON_SKIP_BACK_30
+      else -> CommandButton.ICON_SKIP_BACK
+    }
 
-  /** Current session commands configuration for notification */
-  lateinit var notificationSessionCommands: SessionCommands
+  /** Player commands available to every controller, derived from capabilities alone */
+  var playerCommands: MediaPlayer.Commands = MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS
     private set
 
-  /** Current custom layout configuration for external controllers */
-  lateinit var customLayout: List<CommandButton>
+  /** Session commands available to every controller, derived from capabilities alone */
+  lateinit var sessionCommands: SessionCommands
     private set
 
-  /** Current custom layout configuration for notification */
-  lateinit var notificationCustomLayout: List<CommandButton>
+  /** The single slot-annotated button layout, published to every surface */
+  lateinit var buttonPreferences: List<CommandButton>
     private set
 
   /** Stored state for rebuilding layout */
-  private var currentCapabilities: PlayerCapabilities = PlayerCapabilities(
-    play = null, pause = null, stop = null, seekTo = null,
-    skipToNext = null, skipToPrevious = null,
-    jumpForward = null, jumpBackward = null,
-    favorite = null,
-    shuffleMode = null, repeatMode = null, playbackRate = null
-  )
-  private var currentNotificationButtons: NotificationButtonLayout? = null
-  private var currentSearchAvailable: Boolean = false
+  private var currentCapabilities: PlayerCapabilities =
+    PlayerCapabilities(
+      play = null,
+      pause = null,
+      stop = null,
+      seekTo = null,
+      skipToNext = null,
+      skipToPrevious = null,
+      jumpForward = null,
+      jumpBackward = null,
+      favorite = null,
+      shuffleMode = null,
+      repeatMode = null,
+      playbackRate = null,
+    )
+  private var currentRemoteButtonLayout: RemoteButtonLayout? = null
   private var currentFavorited: Boolean? = null
+  private var currentForwardJumpInterval: Double = DEFAULT_JUMP_INTERVAL
+  private var currentBackwardJumpInterval: Double = DEFAULT_JUMP_INTERVAL
+
+  /** The Media3 player command behind each Capability (FAVORITE is a session command). */
+  private val capabilityPlayerCommands: Map<Capability, @MediaPlayer.Command Int> =
+    mapOf(
+      Capability.PLAY_PAUSE to MediaPlayer.COMMAND_PLAY_PAUSE,
+      Capability.STOP to MediaPlayer.COMMAND_STOP,
+      Capability.SEEK_TO to MediaPlayer.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM,
+      Capability.SKIP_TO_NEXT to MediaPlayer.COMMAND_SEEK_TO_NEXT,
+      Capability.SKIP_TO_PREVIOUS to MediaPlayer.COMMAND_SEEK_TO_PREVIOUS,
+      Capability.JUMP_FORWARD to MediaPlayer.COMMAND_SEEK_FORWARD,
+      Capability.JUMP_BACKWARD to MediaPlayer.COMMAND_SEEK_BACK,
+    )
 
+  // Declared above `init` deliberately: `init` calls `buildPlayerCommands`, which reads
+  // `capabilityPlayerCommands`. Kotlin initializes properties in textual order, so this val must
+  // precede the init block or it would still be null when the constructor runs (NPE).
   init {
     // Initialize with defaults matching PlayerUpdateOptions (all capabilities enabled)
     val defaultCapabilities = currentCapabilities
 
     playerCommands = buildPlayerCommands(defaultCapabilities)
-    notificationPlayerCommands = buildPlayerCommands(defaultCapabilities)
-
-    val (extSessionCommands, extCustomLayout) =
-      buildSessionCommandsAndLayout(defaultCapabilities, searchAvailable = false, favorited = null)
-    sessionCommands = extSessionCommands
-    customLayout = extCustomLayout
-
-    notificationSessionCommands = extSessionCommands
-    notificationCustomLayout = extCustomLayout
+    sessionCommands = buildSessionCommands(defaultCapabilities, searchAvailable = false)
+    buttonPreferences =
+      buildButtonPreferences(
+        deriveButtonSlots(defaultCapabilities, layout = null),
+        favorited = null,
+      )
   }
 
   /**
@@ -91,60 +156,74 @@ class MediaSessionCommandManager {
    *
    * @param mediaSession The MediaSession to configure
    * @param capabilities Global capabilities that enable commands for ALL MediaSession controllers
-   *   (Bluetooth, Android Auto, lock screen, notification, etc.). All capabilities are enabled
-   *   by default - only false values disable them.
-   * @param notificationButtons Slot-based button layout for notifications. When null, button layout
-   *   is derived from capabilities using smart defaults.
+   *   (Bluetooth, Android Auto, lock screen, notification, etc.). All capabilities are enabled by
+   *   default - only false values disable them.
+   * @param remoteButtonLayout Button layout, published to every surface — the notification, Android
+   *   Auto, and the Android 13+ system media controls. When null the layout is derived from
+   *   capabilities using smart defaults.
    * @param searchAvailable Whether search functionality is configured and available
+   * @param forwardJumpInterval Seconds per forward jump; selects the button's icon constant
+   * @param backwardJumpInterval Seconds per backward jump; selects the button's icon constant
    *
-   * Manager initializes with defaults: all global capabilities, limited notification capabilities.
+   * Manager initializes with defaults: all capabilities enabled, default placement.
    */
   fun updateMediaSession(
     mediaSession: MediaSession,
     capabilities: PlayerCapabilities,
-    notificationButtons: NotificationButtonLayout?,
+    remoteButtonLayout: RemoteButtonLayout?,
     searchAvailable: Boolean,
-    favorited: Boolean? = null,
+    forwardJumpInterval: Double = DEFAULT_JUMP_INTERVAL,
+    backwardJumpInterval: Double = DEFAULT_JUMP_INTERVAL,
   ) {
-    // Store state for future rebuilds
+    // Store state for future rebuilds. The favorite state is deliberately NOT reset here: options
+    // and favorites change independently, and rebuilding the layout as un-favorited would blank the
+    // heart on every updateOptions() call until the next track change happened to refresh it.
     currentCapabilities = capabilities
-    currentNotificationButtons = notificationButtons
-    currentSearchAvailable = searchAvailable
-    currentFavorited = favorited
+    currentRemoteButtonLayout = remoteButtonLayout
+    currentForwardJumpInterval = forwardJumpInterval
+    currentBackwardJumpInterval = backwardJumpInterval
 
-    // Build commands for external controllers (global capabilities)
+    // Commands gate on capabilities only — placement never revokes one, so a control left out of
+    // the layout still works from a Bluetooth remote or headset.
     playerCommands = buildPlayerCommands(capabilities)
-    val (extSessionCommands, extCustomLayout) =
-      buildSessionCommandsAndLayout(capabilities, searchAvailable, favorited)
-    sessionCommands = extSessionCommands
-    customLayout = extCustomLayout
-
-    // Build notification button preferences with explicit slots
-    val (notifSessionCommands, notifButtonPrefs) =
-      buildNotificationButtonPreferences(
-        capabilities,
-        notificationButtons,
-        searchAvailable,
-        favorited,
-      )
-    notificationSessionCommands = notifSessionCommands
-    notificationCustomLayout = notifButtonPrefs
+    sessionCommands = buildSessionCommands(capabilities, searchAvailable)
+    buttonPreferences =
+      buildButtonPreferences(deriveButtonSlots(capabilities, remoteButtonLayout), currentFavorited)
+
+    // Push the rebuilt commands to already-connected controllers — buildConnectionResult only
+    // serves controllers that connect later, and an Android Auto session lives until the car shuts
+    // down. Granted before the layout broadcast so a newly-added button arrives with its command
+    // already available; Media3 disables buttons whose backing command is missing.
+    mediaSession.connectedControllers.forEach {
+      mediaSession.setAvailableCommands(it, sessionCommands, playerCommands)
+    }
+
+    publishButtonPreferences(mediaSession)
+  }
 
-    // Derive notification player commands from the buttons that will be shown
-    notificationPlayerCommands = buildNotificationPlayerCommands(capabilities, notificationButtons)
+  /**
+   * Publishes the layout. Media3 fans it out to the MediaStyle notification (Android 12 and below)
+   * and to the platform PlaybackState plus slot-reservation extras (Android Auto and the Android
+   * 13+ system media controls).
+   *
+   * Both calls are required. The session-wide call is the only one that reaches Android Auto, which
+   * connects as a legacy controller rather than a Media3 one. But it stops at
+   * `setPlatformMediaButtonPreferences`, which recomputes the legacy custom layout and only
+   * re-broadcasts when the reservation flags themselves change — it never refreshes the
+   * PlaybackState carrying the custom actions. Only the notification-controller overload calls
+   * `updateLegacySessionPlaybackState`, so without it a reordering that leaves the flags untouched
+   * sits invisible until some unrelated playback event republishes the state.
+   */
+  private fun publishButtonPreferences(mediaSession: MediaSession) {
+    Timber.Forest.d(
+      "Publishing ${buttonPreferences.size} button preferences: " +
+        "${buttonPreferences.map { it.displayName }}"
+    )
+    mediaSession.setMediaButtonPreferences(buttonPreferences)
 
-    // Apply media button preferences to notification controller
     mediaSession.mediaNotificationControllerInfo?.let { controllerInfo ->
-      mediaSession.setMediaButtonPreferences(controllerInfo, notifButtonPrefs)
-      mediaSession.setAvailableCommands(
-        controllerInfo,
-        notificationSessionCommands,
-        notificationPlayerCommands,
-      )
+      mediaSession.setMediaButtonPreferences(controllerInfo, buttonPreferences)
     }
-
-    // Broadcast updated layout to all external controllers (Android Auto, etc.)
-    mediaSession.setCustomLayout(customLayout)
   }
 
   /**
@@ -162,29 +241,16 @@ class MediaSessionCommandManager {
 
     currentFavorited = favorited
 
-    // Rebuild external controller layout with new favorite state
-    val (extSessionCommands, extCustomLayout) =
-      buildSessionCommandsAndLayout(currentCapabilities, currentSearchAvailable, favorited)
-    sessionCommands = extSessionCommands
-    customLayout = extCustomLayout
-    Timber.Forest.d("Built external customLayout with ${customLayout.size} buttons")
-
-    // Rebuild notification button preferences with new favorite state
-    val (notifSessionCommands, notifButtonPrefs) =
-      buildNotificationButtonPreferences(
-        currentCapabilities,
-        currentNotificationButtons,
-        currentSearchAvailable,
+    // Only the heart's icon and label change, so the commands stay as they are.
+    buttonPreferences =
+      buildButtonPreferences(
+        deriveButtonSlots(currentCapabilities, currentRemoteButtonLayout),
         favorited,
       )
-    notificationSessionCommands = notifSessionCommands
-    notificationCustomLayout = notifButtonPrefs
 
-    // Apply updated button preferences to notification controller
-    mediaSession.mediaNotificationControllerInfo?.let { controllerInfo ->
-      Timber.Forest.d("Updating notification controller button preferences")
-      mediaSession.setMediaButtonPreferences(controllerInfo, notificationCustomLayout)
-    }
+    // Republish so already-connected surfaces (Android Auto especially) flip the heart — without
+    // this it stays stale for the life of the connection.
+    publishButtonPreferences(mediaSession)
   }
 
   /**
@@ -195,7 +261,7 @@ class MediaSessionCommandManager {
    */
   fun buildConnectionResult(session: MediaSession): MediaSession.ConnectionResult {
     return MediaSession.ConnectionResult.AcceptedResultBuilder(session)
-      .setCustomLayout(customLayout)
+      .setMediaButtonPreferences(buttonPreferences)
       .setAvailableSessionCommands(sessionCommands)
       .setAvailablePlayerCommands(playerCommands)
       .build()
@@ -238,60 +304,31 @@ class MediaSessionCommandManager {
   private fun buildPlayerCommands(capabilities: PlayerCapabilities): MediaPlayer.Commands {
     val playerCommandsBuilder = MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS.buildUpon()
 
-    // Commands to remove - start with always-disabled commands
-    val disabledCommands =
-      mutableSetOf<@MediaPlayer.Command Int>(
-        // Always filter out direct media item commands to avoid dual-command confusion
-        // This forces MediaSession to only use the "smart" commands we can control via capabilities
-        MediaPlayer.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM,
-        MediaPlayer.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM,
-      )
-
-    // Only disable jump commands if capabilities are explicitly disabled (false)
-    if (capabilities.jumpForward == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_SEEK_FORWARD)
-    }
-    if (capabilities.jumpBackward == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_SEEK_BACK)
-    }
-
-    // Check each capability and add commands to remove if explicitly disabled
-    // Both play and pause must be disabled to remove PLAY_PAUSE command
-    if (capabilities.play == false && capabilities.pause == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_PLAY_PAUSE)
-    }
-
-    if (capabilities.stop == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_STOP)
-    }
-
-    if (capabilities.seekTo == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM)
-    }
-
-    if (capabilities.skipToNext == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_SEEK_TO_NEXT)
-    }
-
-    if (capabilities.skipToPrevious == false) {
-      disabledCommands.add(MediaPlayer.COMMAND_SEEK_TO_PREVIOUS)
-    }
+    // Always filter out direct media item commands to avoid dual-command confusion.
+    // This forces MediaSession to only use the "smart" commands we can control via capabilities.
+    playerCommandsBuilder.remove(MediaPlayer.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
+    playerCommandsBuilder.remove(MediaPlayer.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
 
-    // Remove disabled commands from the builder
-    disabledCommands.forEach { command ->
-      playerCommandsBuilder.remove(command)
-      Timber.Forest.d("Removed command: $command")
+    capabilityPlayerCommands.forEach { (capability, command) ->
+      if (!capabilities.isEnabled(capability)) {
+        playerCommandsBuilder.remove(command)
+        Timber.Forest.d("Removed command: $command ($capability disabled)")
+      }
     }
 
     return playerCommandsBuilder.build()
   }
 
-  private fun buildSessionCommandsAndLayout(
+  /**
+   * Session commands for every controller. Registered for each capability-allowed custom button
+   * whether or not the layout places it — placement governs where a button appears, not whether its
+   * command exists. Media3 disables a button whose backing command is missing, so every button the
+   * layout can produce must have its command here.
+   */
+  private fun buildSessionCommands(
     capabilities: PlayerCapabilities,
     searchAvailable: Boolean,
-    favorited: Boolean?,
-  ): Pair<SessionCommands, List<CommandButton>> {
-    val customLayoutButtons = mutableListOf<CommandButton>()
+  ): SessionCommands {
     val sessionCommandsBuilder =
       MediaSession.ConnectionResult.DEFAULT_SESSION_AND_LIBRARY_COMMANDS.buildUpon()
 
@@ -302,277 +339,84 @@ class MediaSessionCommandManager {
       Timber.Forest.d("Removed search commands - search not configured")
     }
 
-    // Create custom command buttons for jump commands (required for notification visibility)
-    // All capabilities enabled by default - only false disables
-    if (capabilities.jumpBackward != false) {
-      val jumpBackCommand = SessionCommand(CUSTOM_ACTION_JUMP_BACKWARD, Bundle())
-      customLayoutButtons.add(
-        CommandButton.Builder()
-          .setDisplayName("Jump Backward")
-          .setSessionCommand(jumpBackCommand)
-          .setIconResId(R.drawable.media3_icon_skip_back)
-          .build()
-      )
-      sessionCommandsBuilder.add(jumpBackCommand)
-    }
-
-    if (capabilities.jumpForward != false) {
-      val jumpForwardCommand = SessionCommand(CUSTOM_ACTION_JUMP_FORWARD, Bundle())
-      customLayoutButtons.add(
-        CommandButton.Builder()
-          .setDisplayName("Jump Forward")
-          .setSessionCommand(jumpForwardCommand)
-          .setIconResId(R.drawable.media3_icon_skip_forward)
-          .build()
-      )
-      sessionCommandsBuilder.add(jumpForwardCommand)
-    }
+    RemoteButton.entries
+      .filter { capabilities.allows(it) }
+      .mapNotNull { customCommandFor(it) }
+      .forEach { sessionCommandsBuilder.add(it) }
 
-    // Add favorite button when FAVORITE capability is not disabled
-    if (capabilities.favorite != false) {
-      val heartIcon =
-        if (favorited == true) {
-          CommandButton.ICON_HEART_FILLED
-        } else {
-          CommandButton.ICON_HEART_UNFILLED
-        }
-      val displayName = if (favorited == true) "Remove from favorites" else "Add to favorites"
-      val favoriteCommand = SessionCommand(CUSTOM_ACTION_FAVORITE, Bundle())
-
-      customLayoutButtons.add(
-        CommandButton.Builder(heartIcon)
-          .setDisplayName(displayName)
-          .setSessionCommand(favoriteCommand)
-          .build()
-      )
-      sessionCommandsBuilder.add(favoriteCommand)
-      Timber.Forest.d("Added favorite button - favorited=$favorited")
-    }
-
-    return Pair(sessionCommandsBuilder.build(), customLayoutButtons)
+    return sessionCommandsBuilder.build()
   }
 
   /**
-   * Builds notification button preferences with explicit slot assignments. If notificationButtons
-   * is null, derives button layout from capabilities.
+   * The custom command behind a session-command-backed button, or null for the player-command ones
+   * (skip). Single source for both the command a button carries and the SessionCommands registry,
+   * so a published button can never be missing the command that makes it work — Media3 silently
+   * disables buttons whose backing command is unavailable.
    */
-  private fun buildNotificationButtonPreferences(
-    capabilities: PlayerCapabilities,
-    notificationButtons: NotificationButtonLayout?,
-    searchAvailable: Boolean,
-    favorited: Boolean?,
-  ): Pair<SessionCommands, List<CommandButton>> {
-    val buttons = mutableListOf<CommandButton>()
-    val sessionCommandsBuilder =
-      MediaSession.ConnectionResult.DEFAULT_SESSION_AND_LIBRARY_COMMANDS.buildUpon()
+  private fun customCommandFor(button: RemoteButton): SessionCommand? =
+    when (button) {
+      RemoteButton.JUMP_BACKWARD -> SessionCommand(CUSTOM_ACTION_JUMP_BACKWARD, Bundle())
+      RemoteButton.JUMP_FORWARD -> SessionCommand(CUSTOM_ACTION_JUMP_FORWARD, Bundle())
+      RemoteButton.FAVORITE -> SessionCommand(CUSTOM_ACTION_FAVORITE, Bundle())
+      RemoteButton.SKIP_TO_PREVIOUS,
+      RemoteButton.SKIP_TO_NEXT -> null
+    }
 
-    // Remove search commands if search is not configured
-    if (!searchAvailable) {
-      sessionCommandsBuilder.remove(SessionCommand.COMMAND_CODE_LIBRARY_SEARCH)
-      sessionCommandsBuilder.remove(SessionCommand.COMMAND_CODE_LIBRARY_GET_SEARCH_RESULT)
+  /**
+   * The Media3 player command behind a player-command-backed button; null for the custom ones. Both
+   * this and [customCommandFor] enumerate every button rather than using `else`, so adding one
+   * fails the build until it has been given an action on both sides.
+   */
+  private fun playerCommandFor(button: RemoteButton): Int? =
+    when (button) {
+      RemoteButton.SKIP_TO_PREVIOUS -> MediaPlayer.COMMAND_SEEK_TO_PREVIOUS
+      RemoteButton.SKIP_TO_NEXT -> MediaPlayer.COMMAND_SEEK_TO_NEXT
+      RemoteButton.JUMP_BACKWARD,
+      RemoteButton.JUMP_FORWARD,
+      RemoteButton.FAVORITE -> null
     }
 
-    // Helper to create a CommandButton for a NotificationButton with specific slot
-    // Only creates button if the corresponding capability is not disabled
-    fun createButton(button: NotificationButton, slot: Int): CommandButton? {
-      return when (button) {
-        NotificationButton.SKIP_TO_PREVIOUS -> {
-          if (capabilities.skipToPrevious != false) {
-            CommandButton.Builder(CommandButton.ICON_PREVIOUS)
-              .setDisplayName("Previous")
-              .setPlayerCommand(MediaPlayer.COMMAND_SEEK_TO_PREVIOUS)
-              .setSlots(slot)
-              .build()
-          } else null
-        }
-        NotificationButton.SKIP_TO_NEXT -> {
-          if (capabilities.skipToNext != false) {
-            CommandButton.Builder(CommandButton.ICON_NEXT)
-              .setDisplayName("Next")
-              .setPlayerCommand(MediaPlayer.COMMAND_SEEK_TO_NEXT)
-              .setSlots(slot)
-              .build()
-          } else null
-        }
-        NotificationButton.JUMP_BACKWARD -> {
-          if (capabilities.jumpBackward != false) {
-            val command = SessionCommand(CUSTOM_ACTION_JUMP_BACKWARD, Bundle())
-            sessionCommandsBuilder.add(command)
-            CommandButton.Builder()
-              .setDisplayName("Jump Backward")
-              .setSessionCommand(command)
-              .setIconResId(R.drawable.media3_icon_skip_back)
-              .setSlots(slot)
-              .build()
-          } else null
-        }
-        NotificationButton.JUMP_FORWARD -> {
-          if (capabilities.jumpForward != false) {
-            val command = SessionCommand(CUSTOM_ACTION_JUMP_FORWARD, Bundle())
-            sessionCommandsBuilder.add(command)
-            CommandButton.Builder()
-              .setDisplayName("Jump Forward")
-              .setSessionCommand(command)
-              .setIconResId(R.drawable.media3_icon_skip_forward)
-              .setSlots(slot)
-              .build()
-          } else null
-        }
-        NotificationButton.FAVORITE -> {
-          if (capabilities.favorite != false) {
-            val heartIcon =
+  /** The single definition of a control's icon and label, shared by every surface. */
+  private fun buttonFor(button: RemoteButton, favorited: Boolean?): CommandButton.Builder {
+    val builder =
+      when (button) {
+        RemoteButton.SKIP_TO_PREVIOUS ->
+          CommandButton.Builder(CommandButton.ICON_PREVIOUS).setDisplayName("Previous")
+        RemoteButton.SKIP_TO_NEXT ->
+          CommandButton.Builder(CommandButton.ICON_NEXT).setDisplayName("Next")
+        RemoteButton.JUMP_BACKWARD ->
+          CommandButton.Builder(jumpBackwardIcon(currentBackwardJumpInterval))
+            .setDisplayName("Jump Backward")
+        RemoteButton.JUMP_FORWARD ->
+          CommandButton.Builder(jumpForwardIcon(currentForwardJumpInterval))
+            .setDisplayName("Jump Forward")
+        RemoteButton.FAVORITE ->
+          CommandButton.Builder(
               if (favorited == true) CommandButton.ICON_HEART_FILLED
               else CommandButton.ICON_HEART_UNFILLED
-            val displayName = if (favorited == true) "Remove from favorites" else "Add to favorites"
-            val command = SessionCommand(CUSTOM_ACTION_FAVORITE, Bundle())
-            sessionCommandsBuilder.add(command)
-            CommandButton.Builder(heartIcon)
-              .setDisplayName(displayName)
-              .setSessionCommand(command)
-              .setSlots(slot)
-              .build()
-          } else null
-        }
-      }
-    }
-
-    if (notificationButtons != null) {
-      // Use explicit slot configuration
-      notificationButtons.back?.let { btn ->
-        createButton(btn, CommandButton.SLOT_BACK)?.let { buttons.add(it) }
-      }
-      notificationButtons.forward?.let { btn ->
-        createButton(btn, CommandButton.SLOT_FORWARD)?.let { buttons.add(it) }
-      }
-      notificationButtons.backSecondary?.let { btn ->
-        createButton(btn, CommandButton.SLOT_BACK_SECONDARY)?.let { buttons.add(it) }
-      }
-      notificationButtons.forwardSecondary?.let { btn ->
-        createButton(btn, CommandButton.SLOT_FORWARD_SECONDARY)?.let { buttons.add(it) }
-      }
-      notificationButtons.overflow?.forEach { btn ->
-        createButton(btn, CommandButton.SLOT_OVERFLOW)?.let { buttons.add(it) }
-      }
-    } else {
-      // Derive from capabilities with default slot mapping
-      // All capabilities enabled by default - only false disables
-      val hasSkipPrevious = capabilities.skipToPrevious != false
-      val hasSkipNext = capabilities.skipToNext != false
-
-      // Back slot: skip-to-previous, or jump-backward if no skip
-      if (hasSkipPrevious) {
-        createButton(NotificationButton.SKIP_TO_PREVIOUS, CommandButton.SLOT_BACK)?.let {
-          buttons.add(it)
-        }
-      } else if (capabilities.jumpBackward != false) {
-        createButton(NotificationButton.JUMP_BACKWARD, CommandButton.SLOT_BACK)?.let {
-          buttons.add(it)
-        }
-      }
-
-      // Forward slot: skip-to-next, or jump-forward if no skip
-      if (hasSkipNext) {
-        createButton(NotificationButton.SKIP_TO_NEXT, CommandButton.SLOT_FORWARD)?.let {
-          buttons.add(it)
-        }
-      } else if (capabilities.jumpForward != false) {
-        createButton(NotificationButton.JUMP_FORWARD, CommandButton.SLOT_FORWARD)?.let {
-          buttons.add(it)
-        }
+            )
+            .setDisplayName(if (favorited == true) "Remove from favorites" else "Add to favorites")
       }
 
-      // Secondary slots for jump buttons if skip buttons are present
-      if (hasSkipPrevious && capabilities.jumpBackward != false) {
-        createButton(NotificationButton.JUMP_BACKWARD, CommandButton.SLOT_BACK_SECONDARY)?.let {
-          buttons.add(it)
-        }
-      }
-      if (hasSkipNext && capabilities.jumpForward != false) {
-        createButton(NotificationButton.JUMP_FORWARD, CommandButton.SLOT_FORWARD_SECONDARY)?.let {
-          buttons.add(it)
-        }
-      }
-
-      // Overflow: favorite
-      if (capabilities.favorite != false) {
-        createButton(NotificationButton.FAVORITE, CommandButton.SLOT_OVERFLOW)?.let {
-          buttons.add(it)
-        }
-      }
-    }
-
-    Timber.Forest.d("Built notification button preferences: ${buttons.map { it.displayName }}")
-    return Pair(sessionCommandsBuilder.build(), buttons)
+    return customCommandFor(button)?.let { builder.setSessionCommand(it) }
+      ?: playerCommandFor(button)?.let { builder.setPlayerCommand(it) }
+      ?: builder
   }
 
   /**
-   * Builds player commands for the notification controller based on the button layout. This enables
-   * the commands needed for the buttons that will be shown.
+   * Assembles the CommandButtons for an already-derived slot layout (see [deriveButtonSlots] — the
+   * slots are pre-filtered by Capability).
+   *
+   * Each button gets its requested slot followed by OVERFLOW as a fallback. `slots` is an ordered
+   * preference list, and every surface caps how many buttons it renders — a head unit, the
+   * collapsed notification, the Android 13+ media controls all truncate differently. Without a
+   * fallback a button that loses its preferred slot disappears entirely instead of demoting.
    */
-  private fun buildNotificationPlayerCommands(
-    capabilities: PlayerCapabilities,
-    notificationButtons: NotificationButtonLayout?,
-  ): MediaPlayer.Commands {
-    val builder = MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS.buildUpon()
-
-    // Always remove direct media item commands to avoid dual-command confusion
-    builder.remove(MediaPlayer.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
-    builder.remove(MediaPlayer.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
-
-    // Determine which buttons will be shown
-    val showSkipPrevious: Boolean
-    val showSkipNext: Boolean
-    val showJumpBackward: Boolean
-    val showJumpForward: Boolean
-
-    if (notificationButtons != null) {
-      showSkipPrevious =
-        notificationButtons.back == NotificationButton.SKIP_TO_PREVIOUS ||
-          notificationButtons.backSecondary == NotificationButton.SKIP_TO_PREVIOUS
-      showSkipNext =
-        notificationButtons.forward == NotificationButton.SKIP_TO_NEXT ||
-          notificationButtons.forwardSecondary == NotificationButton.SKIP_TO_NEXT
-      showJumpBackward =
-        notificationButtons.back == NotificationButton.JUMP_BACKWARD ||
-          notificationButtons.backSecondary == NotificationButton.JUMP_BACKWARD
-      showJumpForward =
-        notificationButtons.forward == NotificationButton.JUMP_FORWARD ||
-          notificationButtons.forwardSecondary == NotificationButton.JUMP_FORWARD
-    } else {
-      // Default derivation from capabilities
-      // All capabilities enabled by default - only false disables
-      showSkipPrevious = capabilities.skipToPrevious != false
-      showSkipNext = capabilities.skipToNext != false
-      showJumpBackward = capabilities.jumpBackward != false
-      showJumpForward = capabilities.jumpForward != false
-    }
-
-    // Enable/disable commands based on what buttons are shown and capabilities
-    if (!showSkipPrevious || capabilities.skipToPrevious == false) {
-      builder.remove(MediaPlayer.COMMAND_SEEK_TO_PREVIOUS)
-    }
-    if (!showSkipNext || capabilities.skipToNext == false) {
-      builder.remove(MediaPlayer.COMMAND_SEEK_TO_NEXT)
-    }
-    if (!showJumpBackward || capabilities.jumpBackward == false) {
-      builder.remove(MediaPlayer.COMMAND_SEEK_BACK)
-    }
-    if (!showJumpForward || capabilities.jumpForward == false) {
-      builder.remove(MediaPlayer.COMMAND_SEEK_FORWARD)
-    }
-
-    // Other commands based on global capabilities
-    // Both play and pause must be disabled to remove PLAY_PAUSE
-    if (capabilities.play == false && capabilities.pause == false) {
-      builder.remove(MediaPlayer.COMMAND_PLAY_PAUSE)
-    }
-    if (capabilities.stop == false) {
-      builder.remove(MediaPlayer.COMMAND_STOP)
-    }
-    if (capabilities.seekTo == false) {
-      builder.remove(MediaPlayer.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM)
+  private fun buildButtonPreferences(
+    slots: List<SlottedButton>,
+    favorited: Boolean?,
+  ): List<CommandButton> =
+    slots.map { (button, slot) ->
+      buttonFor(button, favorited).setSlots(*media3SlotsFor(slot)).build()
     }
-
-    return builder.build()
-  }
 }