From 7289186c937245a4f328f4c9b6e9cda34129306a Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Mon, 15 May 2023 18:20:16 +0100
Subject: [PATCH] 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
---
 .../android/exoplayer2/ForwardingPlayer.java  | 12 +++++++
 .../com/google/android/exoplayer2/Player.java | 35 +++++++++++++++++++
 .../android/exoplayer2/SimpleBasePlayer.java  | 12 +++++++
 3 files changed, 59 insertions(+)

diff --git a/library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java b/library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java
index 63224a193d0..221d774a2ce 100644
--- a/library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java
+++ b/library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java
@@ -149,6 +149,18 @@ public void moveMediaItems(int fromIndex, int toIndex, int newIndex) {
     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) {
diff --git a/library/common/src/main/java/com/google/android/exoplayer2/Player.java b/library/common/src/main/java/com/google/android/exoplayer2/Player.java
index 0b48223bb80..7ed3f035e5b 100644
--- a/library/common/src/main/java/com/google/android/exoplayer2/Player.java
+++ b/library/common/src/main/java/com/google/android/exoplayer2/Player.java
@@ -41,6 +41,7 @@
 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 @@ default void onMetadata(Metadata metadata) {}
    *   <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;
@@ -2043,6 +2046,38 @@ default void onMetadata(Metadata metadata) {}
    */
   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.
    *
diff --git a/library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java b/library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java
index 4ac783bc930..3b26a1cbf88 100644
--- a/library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java
+++ b/library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java
@@ -2144,6 +2144,18 @@ public final void moveMediaItems(int fromIndex, int toIndex, int newIndex) {
         });
   }
 
+  @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();