diff --git a/media/java/android/media/MediaController2.java b/media/java/android/media/MediaController2.java index 2a3967c1d07aa..133f4338b635d 100644 --- a/media/java/android/media/MediaController2.java +++ b/media/java/android/media/MediaController2.java @@ -748,7 +748,14 @@ public class MediaController2 implements AutoCloseable { } /** - * Return playlist from the session. + * Returns the cached playlist from + * {@link ControllerCallback#onPlaylistChanged(MediaController2, MediaPlaylistAgent, List, + * MediaMetadata2)}. + *
+ * This list may differ with the list that was specified with + * {@link #setPlaylist(List, MediaMetadata2)} depending on the {@link MediaPlaylistAgent} + * implementation. Use media items returned here for other playlist agent APIs such as + * {@link MediaPlaylistAgent#skipToPlaylistItem(MediaItem2)}. * * @return playlist. Can be {@code null} if the controller doesn't have enough permission. */ @@ -758,12 +765,19 @@ public class MediaController2 implements AutoCloseable { /** * Sets the playlist. + *
+ * Even when the playlist is successfully set, use the playlist returned from
+ * {@link #getPlaylist()} for playlist APIs such as {@link #skipToPlaylistItem(MediaItem2)}.
+ * Otherwise the session in the remote process can't distinguish between media items.
*
* @param list playlist
* @param metadata metadata of the playlist
+ * @see #getPlaylist()
+ * @see ControllerCallback#onPlaylistChanged(
+ * MediaController2, MediaPlaylistAgent, List, MediaMetadata2)
*/
public void setPlaylist(@NonNull List
* If you want to support background playback, {@link MediaSessionService2} is preferred
- * instead. With it, your playback can be revived even after you've finished playback. See
+ * instead. With it, your playback can be revived even after playback is finished. See
* {@link MediaSessionService2} for details.
*
* A session can be obtained by {@link Builder}. The owner of the session may pass its session token
@@ -254,7 +254,7 @@ public class MediaSession2 implements AutoCloseable {
public static final int COMMAND_CODE_PLAYLIST_GET_LIST = 18;
/**
- * Command code for {@link MediaController2#setPlaylist(List, MediaMetadata2).
+ * Command code for {@link MediaController2#setPlaylist(List, MediaMetadata2)}.
*
* Command would be sent directly to the playlist agent if the session doesn't reject the
* request through the
@@ -263,7 +263,7 @@ public class MediaSession2 implements AutoCloseable {
public static final int COMMAND_CODE_PLAYLIST_SET_LIST = 19;
/**
- * Command code for {@link MediaController2#getPlaylistMetadata()} ()}. This will expose
+ * Command code for {@link MediaController2#getPlaylistMetadata()}. This will expose
* metadata information to the controller.
* *
* Command code for {@link MediaController2#setPlaylist(List, MediaMetadata2)} and
@@ -827,7 +827,11 @@ public class MediaSession2 implements AutoCloseable {
@NonNull MediaPlayerBase player, @NonNull MediaItem2 item, @BuffState int state) { }
/**
- * Called when a playlist is changed.
+ * Called when a playlist is changed from the {@link MediaPlaylistAgent}.
+ *
+ * This is called when the underlying agent has called
+ * {@link MediaPlaylistAgent.PlaylistEventCallback#onPlaylistChanged(MediaPlaylistAgent,
+ * List, MediaMetadata2)}.
*
* @param session the session for this event
* @param playlistAgent playlist agent for this event
@@ -1681,7 +1685,7 @@ public class MediaSession2 implements AutoCloseable {
*
* If it's not set, playback wouldn't happen for the item without data source descriptor.
*
- * The helper will be run on the executor that you've specified by the
+ * The helper will be run on the executor that was specified by
* {@link Builder#setSessionCallback(Executor, SessionCallback)}.
*
* @param helper a data source missing helper.
@@ -1705,40 +1709,46 @@ public class MediaSession2 implements AutoCloseable {
}
/**
- * Return the playlist which is lastly set.
+ * Returns the playlist from the {@link MediaPlaylistAgent}.
+ *
+ * This list may differ with the list that was specified with
+ * {@link #setPlaylist(List, MediaMetadata2)} depending on the {@link MediaPlaylistAgent}
+ * implementation. Use media items returned here for other playlist agent APIs such as
+ * {@link MediaPlaylistAgent#skipToPlaylistItem(MediaItem2)}.
*
* @return playlist
+ * @see MediaPlaylistAgent#getPlaylist()
+ * @see SessionCallback#onPlaylistChanged(
+ * MediaSession2, MediaPlaylistAgent, List, MediaMetadata2)
*/
public List
- * You may specify a {@link MediaItem2} without {@link DataSourceDesc}. However, in that case,
- * you should set {@link OnDataSourceMissingHelper} for player to prepare.
+ * This may be an asynchronous call, and {@link MediaPlaylistAgent} may keep the copy of the
+ * list. Wait for {@link SessionCallback#onPlaylistChanged(MediaSession2, MediaPlaylistAgent,
+ * List, MediaMetadata2)} to know the operation finishes.
+ *
+ * You may specify a {@link MediaItem2} without {@link DataSourceDesc}. In that case,
+ * {@link MediaPlaylistAgent} has responsibility to dynamically query {@link DataSourceDesc}
+ * when such media item is ready for preparation or play. Default implementation needs
+ * {@link OnDataSourceMissingHelper} for such case.
*
* @param list A list of {@link MediaItem2} objects to set as a play list.
- * @throws IllegalArgumentException if given list is {@code null}, or has duplicated media item.
+ * @throws IllegalArgumentException if given list is {@code null}, or has duplicated media
+ * items.
+ * @see MediaPlaylistAgent#setPlaylist(List, MediaMetadata2)
+ * @see SessionCallback#onPlaylistChanged(
+ * MediaSession2, MediaPlaylistAgent, List, MediaMetadata2)
* @see #setOnDataSourceMissingHelper
*/
public void setPlaylist(@NonNull List