Recommend ForwardingSimpleBasePlayer in ForwardingPlayer javadoc

Also add an explicit warning about how fiddly `ForwardingPlayer` can be
to use correctly.

PiperOrigin-RevId: 700698032

libraries/common/src/main/java/androidx/media3/common/ForwardingPlayer.java

@@ -30,6 +30,25 @@ import java.util.List;
 /**
  * A {@link Player} that forwards method calls to another {@link Player}. Applications can use this
  * class to suppress or modify specific operations, by overriding the respective methods.
+ *
+ * <p>Subclasses must ensure they maintain consistency with the {@link Player} interface, including
+ * interactions with {@link Player.Listener}, which can be quite fiddly. For example, if removing an
+ * available {@link Player.Command} and disabling the corresponding method, subclasses need to:
+ *
+ * <ul>
+ *   <li>Override {@link #isCommandAvailable(int)} and {@link #getAvailableCommands()}
+ *   <li>Override and no-op the method itself
+ *   <li>Override {@link #addListener(Listener)} and wrap the provided {@link Player.Listener} with
+ *       an implementation that drops calls to {@link
+ *       Player.Listener#onAvailableCommandsChanged(Commands)} and {@link
+ *       Player.Listener#onEvents(Player, Events)} if they were only triggered by a change in
+ *       command availability that is 'invisible' after the command removal.
+ * </ul>
+ *
+ * <p>Many customization use-cases are instead better served by {@link ForwardingSimpleBasePlayer},
+ * which allows subclasses to more concisely modify the behavior of an operation, or disallow a
+ * {@link Player.Command}. In many cases {@link ForwardingSimpleBasePlayer} should be used in
+ * preference to {@code ForwardingPlayer}.
  */
 @UnstableApi
 public class ForwardingPlayer implements Player {