Document custom commands in the DefaultMediaNotificationProvider

Issue: #103
#minor-release
PiperOrigin-RevId: 458465479

Author: marcbaechinger

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

@@ -69,6 +69,14 @@
  *   <li>{@link MediaController#COMMAND_SEEK_TO_NEXT} to seek to the next item.
  * </ul>
  *
+ * <h2>Custom commands</h2>
+ *
+ * Custom actions are sent to the session under the hood. You can receive them by overriding the
+ * session callback method {@link MediaSession.Callback#onCustomCommand(MediaSession, ControllerInfo
+ * controller, SessionCommand, Bundle)}. This is useful because starting with Android 13, the System
+ * UI notification sends commands directly to the session. So handling the custom commands on the
+ * session level allows you to handle them at the same callback for all API levels.
+ *
  * <h2>Drawables</h2>
  *
  * The drawables used can be overridden by drawables with the same names defined the application.
@@ -219,6 +227,14 @@ public final boolean handleCustomCommand(MediaSession session, String action, Bu
    * 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
+   * commands to the available commands when a controller {@linkplain
+   * MediaSession.Callback#onConnect(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, ControllerInfo)}
+   * also.
+   *
    * @param playerCommands The available player commands.
    * @param customLayout The {@linkplain MediaSession#setCustomLayout(List) custom layout of
    *     commands}.