Clarify docs on Player.setMediaItem(s) and replaceMediaItem(s)

These methods sound similar, but have different behaviour. This change
tries to make the distinction clearer, and sign-post from one to the
other.

#minor-release

Issue: androidx/media#910
PiperOrigin-RevId: 595701540

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

@@ -2173,6 +2173,9 @@ default void onMetadata(Metadata metadata) {}
    * Clears the playlist, adds the specified {@linkplain MediaItem media items} and resets the
    * position to the default position.
    *
+   * <p>To replace a span of media items (possibly seamlessly) without clearing the playlist, use
+   * {@link #replaceMediaItems}.
+   *
    * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2183,6 +2186,9 @@ default void onMetadata(Metadata metadata) {}
   /**
    * Clears the playlist and adds the specified {@linkplain MediaItem media items}.
    *
+   * <p>To replace a span of media items (possibly seamlessly) without clearing the playlist, use
+   * {@link #replaceMediaItems}.
+   *
    * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2196,6 +2202,9 @@ default void onMetadata(Metadata metadata) {}
   /**
    * Clears the playlist and adds the specified {@linkplain MediaItem media items}.
    *
+   * <p>To replace a span of media items (possibly seamlessly) without clearing the playlist, use
+   * {@link #replaceMediaItems}.
+   *
    * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2215,6 +2224,9 @@ default void onMetadata(Metadata metadata) {}
    * Clears the playlist, adds the specified {@link MediaItem} and resets the position to the
    * default position.
    *
+   * <p>To replace a media item (possibly seamlessly) without clearing the playlist, use {@link
+   * #replaceMediaItem}.
+   *
    * <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEM} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2225,6 +2237,9 @@ default void onMetadata(Metadata metadata) {}
   /**
    * Clears the playlist and adds the specified {@link MediaItem}.
    *
+   * <p>To replace a media item (possibly seamlessly) without clearing the playlist, use {@link
+   * #replaceMediaItem}.
+   *
    * <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEM} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2237,6 +2252,9 @@ default void onMetadata(Metadata metadata) {}
   /**
    * Clears the playlist and adds the specified {@link MediaItem}.
    *
+   * <p>To replace a media item (possibly seamlessly) without clearing the playlist, use {@link
+   * #replaceMediaItem}.
+   *
    * <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEM} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2323,6 +2341,10 @@ default void onMetadata(Metadata metadata) {}
   /**
    * Replaces the media item at the given index of the playlist.
    *
+   * <p>Implementations of this method may attempt to seamlessly continue playback if the currently
+   * playing media item is replaced with a compatible one (e.g. same URL, only metadata has
+   * changed).
+   *
    * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
    * #getAvailableCommands() available}.
    *
@@ -2335,6 +2357,10 @@ default void onMetadata(Metadata metadata) {}
   /**
    * Replaces the media items at the given range of the playlist.
    *
+   * <p>Implementations of this method may attempt to seamlessly continue playback if the currently
+   * playing media item is replaced with a compatible one (e.g. same URL, only metadata has
+   * changed).
+   *
    * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
    * #getAvailableCommands() available}.
    *