Add Player.replaceMediaItem(s)

This methods allows to replace single items or a range of items directly
without using separate operations for add and remove. The advantage is
more readable code for apps and the potential for player
implementations to optimize this process (e.g. only replace values
without interrupting playback).

The current change just introduces the API with its default behavior.
The default logic will be removed again in the future in favor of
better logic in the Player implementations.

Issue: google/ExoPlayer#8046
PiperOrigin-RevId: 532151471
(cherry picked from commit 7289186c937245a4f328f4c9b6e9cda34129306a)

library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java

@@ -149,6 +149,18 @@ public class ForwardingPlayer implements Player {
     player.moveMediaItems(fromIndex, toIndex, newIndex);
   }
 
+  /** Calls {@link Player#replaceMediaItem(int, MediaItem)} on the delegate. */
+  @Override
+  public void replaceMediaItem(int index, MediaItem mediaItem) {
+    player.replaceMediaItem(index, mediaItem);
+  }
+
+  /** Calls {@link Player#replaceMediaItems(int, int, List)} on the delegate. */
+  @Override
+  public void replaceMediaItems(int fromIndex, int toIndex, List<MediaItem> mediaItems) {
+    player.replaceMediaItems(fromIndex, toIndex, mediaItems);
+  }
+
   /** Calls {@link Player#removeMediaItem(int)} on the delegate. */
   @Override
   public void removeMediaItem(int index) {

library/common/src/main/java/com/google/android/exoplayer2/Player.java

@@ -41,6 +41,7 @@ import com.google.android.exoplayer2.util.Size;
 import com.google.android.exoplayer2.util.Util;
 import com.google.android.exoplayer2.video.VideoSize;
 import com.google.common.base.Objects;
+import com.google.common.collect.ImmutableList;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
@@ -1742,6 +1743,8 @@ public interface Player {
    *   <li>{@link #setMediaItems(List)}
    *   <li>{@link #setMediaItems(List, boolean)}
    *   <li>{@link #setMediaItems(List, int, long)}
+   *   <li>{@link #replaceMediaItem(int, MediaItem)}
+   *   <li>{@link #replaceMediaItems(int, int, List)}
    * </ul>
    */
   int COMMAND_CHANGE_MEDIA_ITEMS = 20;
@@ -2044,6 +2047,38 @@ public interface Player {
   void moveMediaItems(int fromIndex, int toIndex, int newIndex);
 
   /**
+   * Replaces the media item at the given index of the playlist.
+   *
+   * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
+   * #getAvailableCommands() available}.
+   *
+   * @param index The index at which to replace the media item. If the index is larger than the size
+   *     of the playlist, the request is ignored.
+   * @param mediaItem The new {@link MediaItem}.
+   */
+  default void replaceMediaItem(int index, MediaItem mediaItem) {
+    replaceMediaItems(
+        /* fromIndex= */ index, /* toIndex= */ index + 1, ImmutableList.of(mediaItem));
+  }
+
+  /**
+   * Replaces the media items at the given range of the playlist.
+   *
+   * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
+   * #getAvailableCommands() available}.
+   *
+   * @param fromIndex The start of the range. If the index is larger than the size of the playlist,
+   *     the request is ignored.
+   * @param toIndex The first item not to be included in the range (exclusive). If the index is
+   *     larger than the size of the playlist, items up to the end of the playlist are replaced.
+   * @param mediaItems The {@linkplain MediaItem media items} to replace the range with.
+   */
+  default void replaceMediaItems(int fromIndex, int toIndex, List<MediaItem> mediaItems) {
+    addMediaItems(toIndex, mediaItems);
+    removeMediaItems(fromIndex, toIndex);
+  }
+
+  /**
    * Removes the media item at the given index of the playlist.
    *
    * <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain

library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java

@@ -2145,6 +2145,18 @@ public abstract class SimpleBasePlayer extends BasePlayer {
   }
 
   @Override
+  public final void replaceMediaItem(int index, MediaItem mediaItem) {
+    replaceMediaItems(
+        /* fromIndex= */ index, /* toIndex= */ index + 1, ImmutableList.of(mediaItem));
+  }
+
+  @Override
+  public final void replaceMediaItems(int fromIndex, int toIndex, List<MediaItem> mediaItems) {
+    addMediaItems(toIndex, mediaItems);
+    removeMediaItems(fromIndex, toIndex);
+  }
+
+  @Override
   public final void removeMediaItems(int fromIndex, int toIndex) {
     verifyApplicationThreadAndInitState();
     checkArgument(fromIndex >= 0 && toIndex >= fromIndex);