From d55b33474e0ba15b4e664de0bd4b616598a8d058 Mon Sep 17 00:00:00 2001
From: ibaker <ibaker@google.com>
Date: Thu, 4 Jan 2024 07:39:05 -0800
Subject: [PATCH] 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
(cherry picked from commit 95e742948ca0d7490cb016c1026827b8369fc8ab)
---
 .../java/androidx/media3/common/Player.java   | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/libraries/common/src/main/java/androidx/media3/common/Player.java b/libraries/common/src/main/java/androidx/media3/common/Player.java
index 9c444e5d97..a93cf1b663 100644
--- a/libraries/common/src/main/java/androidx/media3/common/Player.java
+++ b/libraries/common/src/main/java/androidx/media3/common/Player.java
@@ -2152,6 +2152,9 @@ public interface Player {
    * 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}.
    *
@@ -2162,6 +2165,9 @@ public interface Player {
   /**
    * 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}.
    *
@@ -2175,6 +2181,9 @@ public interface Player {
   /**
    * 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}.
    *
@@ -2194,6 +2203,9 @@ public interface Player {
    * 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}.
    *
@@ -2204,6 +2216,9 @@ public interface Player {
   /**
    * 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}.
    *
@@ -2216,6 +2231,9 @@ public interface Player {
   /**
    * 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}.
    *
@@ -2302,6 +2320,10 @@ public interface Player {
   /**
    * 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}.
    *
@@ -2314,6 +2336,10 @@ public interface Player {
   /**
    * 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}.
    *