Add media button preferences

This adds the API surface for media button preferences in MediaSession
and MediaController. It closely mimics the existing custom layout
infrastructure (which it will replace eventually).

Compat logic:
 - Session:
     - When converting to platform custom actions, prefer to use
       media button preferences if both are set.
     - When connecting to an older Media3 controller, send the
       media button preferences as custom layout instead.
 - Controller:
     - Maintain a single resolved media button preferences field.
     - For Media3 controller receiving both values, prefer media
       button preferences over custom layouts.

Missing functionality:
 - The conversion from/to custom layout and platform custom actions
   does not take the slot preferences into account yet.

PiperOrigin-RevId: 686950100

Author: tonihei

libraries/session/src/main/aidl/androidx/media3/session/IMediaController.aidl

@@ -49,7 +49,8 @@ oneway interface IMediaController {
   void onExtrasChanged(int seq, in Bundle extras) = 3011;
   void onSessionActivityChanged(int seq, in PendingIntent pendingIntent) = 3013;
   void onError(int seq, in Bundle sessionError) = 3014;
-  // Next Id for MediaController: 3015
+  void onSetMediaButtonPreferences(int seq, in List<Bundle> commandButtonList) = 3015;
+  // Next Id for MediaController: 3016
 
   void onChildrenChanged(
       int seq, String parentId, int itemCount, in @nullable Bundle libraryParams) = 4000;

libraries/session/src/main/java/androidx/media3/session/ConnectionState.java

@@ -58,6 +58,8 @@
 
   public final ImmutableList<CommandButton> customLayout;
 
+  public final ImmutableList<CommandButton> mediaButtonPreferences;
+
   @Nullable public final Token platformToken;
 
   public final ImmutableList<CommandButton> commandButtonsForMediaItems;
@@ -68,6 +70,7 @@ public ConnectionState(
       IMediaSession sessionBinder,
       @Nullable PendingIntent sessionActivity,
       ImmutableList<CommandButton> customLayout,
+      ImmutableList<CommandButton> mediaButtonPreferences,
       ImmutableList<CommandButton> commandButtonsForMediaItems,
       SessionCommands sessionCommands,
       Player.Commands playerCommandsFromSession,
@@ -81,6 +84,7 @@ public ConnectionState(
     this.sessionBinder = sessionBinder;
     this.sessionActivity = sessionActivity;
     this.customLayout = customLayout;
+    this.mediaButtonPreferences = mediaButtonPreferences;
     this.commandButtonsForMediaItems = commandButtonsForMediaItems;
     this.sessionCommands = sessionCommands;
     this.playerCommandsFromSession = playerCommandsFromSession;
@@ -95,6 +99,7 @@ public ConnectionState(
   private static final String FIELD_SESSION_BINDER = Util.intToStringMaxRadix(1);
   private static final String FIELD_SESSION_ACTIVITY = Util.intToStringMaxRadix(2);
   private static final String FIELD_CUSTOM_LAYOUT = Util.intToStringMaxRadix(9);
+  private static final String FIELD_MEDIA_BUTTON_PREFERENCES = Util.intToStringMaxRadix(14);
   private static final String FIELD_COMMAND_BUTTONS_FOR_MEDIA_ITEMS = Util.intToStringMaxRadix(13);
   private static final String FIELD_SESSION_COMMANDS = Util.intToStringMaxRadix(3);
   private static final String FIELD_PLAYER_COMMANDS_FROM_SESSION = Util.intToStringMaxRadix(4);
@@ -106,7 +111,7 @@ public ConnectionState(
   private static final String FIELD_IN_PROCESS_BINDER = Util.intToStringMaxRadix(10);
   private static final String FIELD_PLATFORM_TOKEN = Util.intToStringMaxRadix(12);
 
-  // Next field key = 14
+  // Next field key = 15
 
   public Bundle toBundleForRemoteProcess(int controllerInterfaceVersion) {
     Bundle bundle = new Bundle();
@@ -118,6 +123,21 @@ public Bundle toBundleForRemoteProcess(int controllerInterfaceVersion) {
           FIELD_CUSTOM_LAYOUT,
           BundleCollectionUtil.toBundleArrayList(customLayout, CommandButton::toBundle));
     }
+    if (!mediaButtonPreferences.isEmpty()) {
+      if (controllerInterfaceVersion >= 7) {
+        bundle.putParcelableArrayList(
+            FIELD_MEDIA_BUTTON_PREFERENCES,
+            BundleCollectionUtil.toBundleArrayList(
+                mediaButtonPreferences, CommandButton::toBundle));
+      } else {
+        // Controller doesn't support media button preferences, send the list as a custom layout.
+        // TODO: b/332877990 - More accurately reflect media button preferences as custom layout.
+        bundle.putParcelableArrayList(
+            FIELD_CUSTOM_LAYOUT,
+            BundleCollectionUtil.toBundleArrayList(
+                mediaButtonPreferences, CommandButton::toBundle));
+      }
+    }
     if (!commandButtonsForMediaItems.isEmpty()) {
       bundle.putParcelableArrayList(
           FIELD_COMMAND_BUTTONS_FOR_MEDIA_ITEMS,
@@ -166,11 +186,20 @@ public static ConnectionState fromBundle(Bundle bundle) {
     IBinder sessionBinder = checkNotNull(BundleCompat.getBinder(bundle, FIELD_SESSION_BINDER));
     @Nullable PendingIntent sessionActivity = bundle.getParcelable(FIELD_SESSION_ACTIVITY);
     @Nullable
-    List<Bundle> commandButtonArrayList = bundle.getParcelableArrayList(FIELD_CUSTOM_LAYOUT);
+    List<Bundle> customLayoutArrayList = bundle.getParcelableArrayList(FIELD_CUSTOM_LAYOUT);
     ImmutableList<CommandButton> customLayout =
-        commandButtonArrayList != null
+        customLayoutArrayList != null
+            ? BundleCollectionUtil.fromBundleList(
+                b -> CommandButton.fromBundle(b, sessionInterfaceVersion), customLayoutArrayList)
+            : ImmutableList.of();
+    @Nullable
+    List<Bundle> mediaButtonPreferencesArrayList =
+        bundle.getParcelableArrayList(FIELD_MEDIA_BUTTON_PREFERENCES);
+    ImmutableList<CommandButton> mediaButtonPreferences =
+        mediaButtonPreferencesArrayList != null
             ? BundleCollectionUtil.fromBundleList(
-                b -> CommandButton.fromBundle(b, sessionInterfaceVersion), commandButtonArrayList)
+                b -> CommandButton.fromBundle(b, sessionInterfaceVersion),
+                mediaButtonPreferencesArrayList)
             : ImmutableList.of();
     @Nullable
     List<Bundle> commandButtonsForMediaItemsArrayList =
@@ -212,6 +241,7 @@ public static ConnectionState fromBundle(Bundle bundle) {
         IMediaSession.Stub.asInterface(sessionBinder),
         sessionActivity,
         customLayout,
+        mediaButtonPreferences,
         commandButtonsForMediaItems,
         sessionCommands,
         playerCommandsFromSession,

libraries/session/src/main/java/androidx/media3/session/DefaultMediaNotificationProvider.java

@@ -51,7 +51,6 @@
 import com.google.common.util.concurrent.ListenableFuture;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.util.Arrays;
-import java.util.List;
 import java.util.concurrent.CancellationException;
 import java.util.concurrent.ExecutionException;
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
@@ -299,19 +298,20 @@ private DefaultMediaNotificationProvider(Builder builder) {
   @Override
   public final MediaNotification createNotification(
       MediaSession mediaSession,
-      ImmutableList<CommandButton> customLayout,
+      ImmutableList<CommandButton> mediaButtonPreferences,
       MediaNotification.ActionFactory actionFactory,
       Callback onNotificationChangedCallback) {
     ensureNotificationChannel();
 
-    ImmutableList.Builder<CommandButton> customLayoutWithEnabledCommandButtonsOnly =
+    // TODO: b/332877990 - More accurately reflect media button preferences in the notification.
+    ImmutableList.Builder<CommandButton> mediaButtonPreferencesWithEnabledCommandButtonsOnly =
         new ImmutableList.Builder<>();
-    for (int i = 0; i < customLayout.size(); i++) {
-      CommandButton button = customLayout.get(i);
+    for (int i = 0; i < mediaButtonPreferences.size(); i++) {
+      CommandButton button = mediaButtonPreferences.get(i);
       if (button.sessionCommand != null
           && button.sessionCommand.commandCode == SessionCommand.COMMAND_CODE_CUSTOM
           && button.isEnabled) {
-        customLayoutWithEnabledCommandButtonsOnly.add(customLayout.get(i));
+        mediaButtonPreferencesWithEnabledCommandButtonsOnly.add(mediaButtonPreferences.get(i));
       }
     }
     Player player = mediaSession.getPlayer();
@@ -325,7 +325,7 @@ public final MediaNotification createNotification(
             getMediaButtons(
                 mediaSession,
                 player.getAvailableCommands(),
-                customLayoutWithEnabledCommandButtonsOnly.build(),
+                mediaButtonPreferencesWithEnabledCommandButtonsOnly.build(),
                 !Util.shouldShowPlayButton(
                     player, mediaSession.getShowPlayButtonIfPlaybackIsSuppressed())),
             builder,
@@ -424,26 +424,26 @@ public final void setSmallIcon(@DrawableRes int smallIconResourceId) {
    * be customized by defining the index of the command in compact view of up to 3 commands in their
    * extras with key {@link DefaultMediaNotificationProvider#COMMAND_KEY_COMPACT_VIEW_INDEX}.
    *
-   * <p>To make the custom layout and commands work, you need to {@linkplain
-   * MediaSession#setCustomLayout(List) set the custom layout of commands} and add the custom
+   * <p>To make the media button preferences and custom commands work, you need to {@linkplain
+   * MediaSession#setMediaButtonPreferences set the media button preferences} and add the custom
    * commands to the available commands when a controller {@linkplain
    * MediaSession.Callback#onConnect(MediaSession, MediaSession.ControllerInfo) connects to the
-   * session}. Controllers that connect after you called {@link MediaSession#setCustomLayout(List)}
-   * need the custom command set in {@link MediaSession.Callback#onPostConnect(MediaSession,
-   * MediaSession.ControllerInfo)} also.
+   * session}. Controllers that connect after you called {@link
+   * MediaSession#setMediaButtonPreferences} need the custom command set in {@link
+   * MediaSession.Callback#onPostConnect(MediaSession, MediaSession.ControllerInfo)} too.
    *
    * @param session The media session.
    * @param playerCommands The available player commands.
-   * @param customLayout The {@linkplain MediaSession#setCustomLayout(List) custom layout of
-   *     commands}.
+   * @param mediaButtonPreferences The {@linkplain MediaSession#setMediaButtonPreferences media
+   *     button preferences}.
    * @param showPauseButton Whether the notification should show a pause button (e.g., because the
    *     player is currently playing content), otherwise show a play button to start playback.
    * @return The ordered list of command buttons to be placed on the notification.
    */
   protected ImmutableList<CommandButton> getMediaButtons(
       MediaSession session,
       Player.Commands playerCommands,
-      ImmutableList<CommandButton> customLayout,
+      ImmutableList<CommandButton> mediaButtonPreferences,
       boolean showPauseButton) {
     // Skip to previous action.
     ImmutableList.Builder<CommandButton> commandButtons = new ImmutableList.Builder<>();
@@ -488,8 +488,8 @@ protected ImmutableList<CommandButton> getMediaButtons(
               .setDisplayName(context.getString(R.string.media3_controls_seek_to_next_description))
               .build());
     }
-    for (int i = 0; i < customLayout.size(); i++) {
-      CommandButton button = customLayout.get(i);
+    for (int i = 0; i < mediaButtonPreferences.size(); i++) {
+      CommandButton button = mediaButtonPreferences.get(i);
       if (button.sessionCommand != null
           && button.sessionCommand.commandCode == SessionCommand.COMMAND_CODE_CUSTOM) {
         commandButtons.add(button);

libraries/session/src/main/java/androidx/media3/session/LegacyConversions.java

@@ -1495,13 +1495,12 @@ public static SessionCommands convertToSessionCommands(
   }
 
   /**
-   * Converts {@link CustomAction} in the {@link PlaybackStateCompat} to the custom layout which is
-   * the list of the {@link CommandButton}.
+   * Converts {@link CustomAction} in the {@link PlaybackStateCompat} to media button preferences.
    *
-   * @param state playback state
-   * @return custom layout. Always non-null.
+   * @param state The {@link PlaybackStateCompat}.
+   * @return The media button preferences.
    */
-  public static ImmutableList<CommandButton> convertToCustomLayout(
+  public static ImmutableList<CommandButton> convertToMediaButtonPreferences(
       @Nullable PlaybackStateCompat state) {
     if (state == null) {
       return ImmutableList.of();
@@ -1510,7 +1509,7 @@ public static ImmutableList<CommandButton> convertToCustomLayout(
     if (customActions == null) {
       return ImmutableList.of();
     }
-    ImmutableList.Builder<CommandButton> layout = new ImmutableList.Builder<>();
+    ImmutableList.Builder<CommandButton> mediaButtonPreferences = new ImmutableList.Builder<>();
     for (CustomAction customAction : customActions) {
       String action = customAction.getAction();
       @Nullable Bundle extras = customAction.getExtras();
@@ -1521,15 +1520,16 @@ public static ImmutableList<CommandButton> convertToCustomLayout(
                   MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
                   /* defaultValue= */ CommandButton.ICON_UNDEFINED)
               : CommandButton.ICON_UNDEFINED;
+      // TODO: b/332877990 - Set appropriate slots based on available player commands.
       CommandButton button =
           new CommandButton.Builder(icon, customAction.getIcon())
               .setSessionCommand(new SessionCommand(action, extras == null ? Bundle.EMPTY : extras))
               .setDisplayName(customAction.getName())
               .setEnabled(true)
               .build();
-      layout.add(button);
+      mediaButtonPreferences.add(button);
     }
-    return layout.build();
+    return mediaButtonPreferences.build();
   }
 
   /** Converts {@link AudioAttributesCompat} into {@link AudioAttributes}. */

libraries/session/src/main/java/androidx/media3/session/MediaController.java

@@ -409,6 +409,8 @@ default ListenableFuture<SessionResult> onSetCustomLayout(
     /**
      * Called when the {@linkplain #getCustomLayout() custom layout} changed.
      *
+     * <p>This method will be deprecated, prefer to use {@link #onMediaButtonPreferencesChanged}.
+     *
      * <p>The custom layout can change when either the session {@linkplain
      * MediaSession#setCustomLayout changes the custom layout}, or when the session {@linkplain
      * MediaSession#setAvailableCommands(MediaSession.ControllerInfo, SessionCommands, Commands)
@@ -424,6 +426,25 @@ default ListenableFuture<SessionResult> onSetCustomLayout(
     @UnstableApi
     default void onCustomLayoutChanged(MediaController controller, List<CommandButton> layout) {}
 
+    /**
+     * Called when the {@linkplain #getMediaButtonPreferences() media button preferences} changed.
+     *
+     * <p>The media button preferences can change when either the session {@linkplain
+     * MediaSession#setMediaButtonPreferences changes the media button preferences}, or when the
+     * session {@linkplain MediaSession#setAvailableCommands(MediaSession.ControllerInfo,
+     * SessionCommands, Commands) changes the available commands} for a controller that affect
+     * whether buttons of the media button preferences are enabled or disabled.
+     *
+     * <p>Note that the {@linkplain CommandButton#isEnabled enabled} flag is set to {@code false} if
+     * the available commands do not allow to use a button.
+     *
+     * @param controller The controller.
+     * @param mediaButtonPreferences The ordered list of {@linkplain CommandButton command buttons}.
+     */
+    @UnstableApi
+    default void onMediaButtonPreferencesChanged(
+        MediaController controller, List<CommandButton> mediaButtonPreferences) {}
+
     /**
      * Called when the available session commands are changed by session.
      *
@@ -1094,6 +1115,8 @@ public final ListenableFuture<SessionResult> sendCustomCommand(
   /**
    * Returns the custom layout.
    *
+   * <p>This method will be deprecated, prefer to use {@link #getMediaButtonPreferences()} instead.
+   *
    * <p>After being connected, a change of the custom layout is reported with {@link
    * Listener#onCustomLayoutChanged(MediaController, List)}.
    *
@@ -1104,8 +1127,24 @@ public final ListenableFuture<SessionResult> sendCustomCommand(
    */
   @UnstableApi
   public final ImmutableList<CommandButton> getCustomLayout() {
+    return getMediaButtonPreferences();
+  }
+
+  /**
+   * Returns the media button preferences.
+   *
+   * <p>After being connected, a change of the media button preferences is reported with {@link
+   * Listener#onMediaButtonPreferencesChanged(MediaController, List)}.
+   *
+   * <p>Note that the {@linkplain CommandButton#isEnabled enabled} flag is set to {@code false} if
+   * the available commands do not allow to use a button.
+   *
+   * @return The media button preferences.
+   */
+  @UnstableApi
+  public final ImmutableList<CommandButton> getMediaButtonPreferences() {
     verifyApplicationThread();
-    return isConnected() ? impl.getCustomLayout() : ImmutableList.of();
+    return isConnected() ? impl.getMediaButtonPreferences() : ImmutableList.of();
   }
 
   /**
@@ -2168,7 +2207,7 @@ private void verifyApplicationThread() {
 
     ListenableFuture<SessionResult> sendCustomCommand(SessionCommand command, Bundle args);
 
-    ImmutableList<CommandButton> getCustomLayout();
+    ImmutableList<CommandButton> getMediaButtonPreferences();
 
     ImmutableList<CommandButton> getCommandButtonsForMediaItem(MediaItem mediaItem);