Merge "MediaSession2: Clean up TODOs under frameworks/base" into pi-dev

media/java/android/media/MediaController2.java

@@ -223,6 +223,7 @@ public class MediaController2 implements AutoCloseable {
          * @see #onPositionChanged(MediaController2, long, long)
          * @see #onBufferedPositionChanged(MediaController2, long)
          */
+        // TODO(jaewan): Use this (b/74316764)
         public void onCurrentMediaItemChanged(@NonNull MediaController2 controller,
                 @NonNull MediaItem2 item) { }
 
@@ -230,43 +231,43 @@ public class MediaController2 implements AutoCloseable {
          * Called when a playlist is changed.
          *
          * @param controller the controller for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param list new playlist
          * @param metadata new metadata
          */
         public void onPlaylistChanged(@NonNull MediaController2 controller,
-                @NonNull MediaPlaylistAgent mplc, @NonNull List<MediaItem2> list,
+                @NonNull MediaPlaylistAgent playlistAgent, @NonNull List<MediaItem2> list,
                 @Nullable MediaMetadata2 metadata) { }
 
         /**
          * Called when a playlist metadata is changed.
          *
          * @param controller the controller for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param metadata new metadata
          */
         public void onPlaylistMetadataChanged(@NonNull MediaController2 controller,
-                @NonNull MediaPlaylistAgent mplc, @Nullable MediaMetadata2 metadata) { }
+                @NonNull MediaPlaylistAgent playlistAgent, @Nullable MediaMetadata2 metadata) { }
 
         /**
          * Called when the shuffle mode is changed.
          *
          * @param controller the controller for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param shuffleMode repeat mode
          * @see MediaPlaylistAgent#SHUFFLE_MODE_NONE
          * @see MediaPlaylistAgent#SHUFFLE_MODE_ALL
          * @see MediaPlaylistAgent#SHUFFLE_MODE_GROUP
          */
         public void onShuffleModeChanged(@NonNull MediaController2 controller,
-                @NonNull MediaPlaylistAgent mplc,
+                @NonNull MediaPlaylistAgent playlistAgent,
                 @MediaPlaylistAgent.ShuffleMode int shuffleMode) { }
 
         /**
          * Called when the repeat mode is changed.
          *
          * @param controller the controller for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param repeatMode repeat mode
          * @see MediaPlaylistAgent#REPEAT_MODE_NONE
          * @see MediaPlaylistAgent#REPEAT_MODE_ONE
@@ -274,7 +275,7 @@ public class MediaController2 implements AutoCloseable {
          * @see MediaPlaylistAgent#REPEAT_MODE_GROUP
          */
         public void onRepeatModeChanged(@NonNull MediaController2 controller,
-                @NonNull MediaPlaylistAgent mplc,
+                @NonNull MediaPlaylistAgent playlistAgent,
                 @MediaPlaylistAgent.RepeatMode int repeatMode) { }
 
         /**
@@ -821,7 +822,9 @@ public class MediaController2 implements AutoCloseable {
     }
 
     /**
-     * Replace the media item at index in the playlist.
+     * Replace the media item at index in the playlist. This can be also used to update metadata of
+     * an item.
+     *
      * @param index the index of the item to replace
      * @param item the new item
      */
@@ -836,8 +839,7 @@ public class MediaController2 implements AutoCloseable {
      * @return index of the current item
      */
     public MediaItem2 getCurrentMediaItem() {
-        // TODO(jaewan): Rename provider API
+        return mProvider.getCurrentMediaItem_impl();
-        return mProvider.getCurrentPlaylistItem_impl();
     }
 
     /**
@@ -852,13 +854,11 @@ public class MediaController2 implements AutoCloseable {
     }
 
     public void skipToPreviousItem() {
-        // TODO(jaewan): fix this
+        mProvider.skipToPreviousItem_impl();
-        mProvider.skipToPrevious_impl();
     }
 
     public void skipToNextItem() {
-        // TODO(jaewan): fix this
+        mProvider.skipToNextItem_impl();
-        mProvider.skipToNext_impl();
     }
 
     public @RepeatMode int getRepeatMode() {

media/java/android/media/MediaLibraryService2.java

@@ -221,8 +221,8 @@ public abstract class MediaLibraryService2 extends MediaSessionService2 {
             }
 
             @Override
-            public Builder setPlaylistAgent(@NonNull MediaPlaylistAgent mplc) {
+            public Builder setPlaylistAgent(@NonNull MediaPlaylistAgent playlistAgent) {
-                return super.setPlaylistAgent(mplc);
+                return super.setPlaylistAgent(playlistAgent);
             }
 
             @Override

media/java/android/media/MediaPlaylistAgent.java

@@ -103,56 +103,56 @@ public abstract class MediaPlaylistAgent {
         /**
          * Called when a playlist is changed.
          *
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param list new playlist
          * @param metadata new metadata
          */
-        public void onPlaylistChanged(@NonNull MediaPlaylistAgent mplc,
+        public void onPlaylistChanged(@NonNull MediaPlaylistAgent playlistAgent,
                 @NonNull List<MediaItem2> list, @Nullable MediaMetadata2 metadata) { }
 
         /**
          * Called when a playlist metadata is changed.
          *
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param metadata new metadata
          */
-        public void onPlaylistMetadataChanged(@NonNull MediaPlaylistAgent mplc,
+        public void onPlaylistMetadataChanged(@NonNull MediaPlaylistAgent playlistAgent,
                 @Nullable MediaMetadata2 metadata) { }
 
         /**
          * Called when the shuffle mode is changed.
          *
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param shuffleMode repeat mode
          * @see #SHUFFLE_MODE_NONE
          * @see #SHUFFLE_MODE_ALL
          * @see #SHUFFLE_MODE_GROUP
          */
-        public void onShuffleModeChanged(@NonNull MediaPlaylistAgent mplc,
+        public void onShuffleModeChanged(@NonNull MediaPlaylistAgent playlistAgent,
                 @ShuffleMode int shuffleMode) { }
 
         /**
          * Called when the repeat mode is changed.
          *
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param repeatMode repeat mode
          * @see #REPEAT_MODE_NONE
          * @see #REPEAT_MODE_ONE
          * @see #REPEAT_MODE_ALL
          * @see #REPEAT_MODE_GROUP
          */
-        public void onRepeatModeChanged(@NonNull MediaPlaylistAgent mplc,
+        public void onRepeatModeChanged(@NonNull MediaPlaylistAgent playlistAgent,
                 @RepeatMode int repeatMode) { }
     }
 
-    public MediaPlaylistAgent(Context context) {
+    public MediaPlaylistAgent(@NonNull Context context) {
         // FYI, Need to have a context in the constructor for making this class be updatable
-        // TODO(jaewan) : implement this
+        // TODO(jaewan) : implement this (b/74090741)
     }
 
     /**
      * Register {@link PlaylistEventCallback} to listen changes in the underlying
-     * {@link MediaPlaylistAgent}, regardless of the change in the controller.
+     * {@link MediaPlaylistAgent}.
      *
      * @param executor a callback Executor
      * @param callback a PlaylistEventCallback
@@ -160,7 +160,7 @@ public abstract class MediaPlaylistAgent {
      */
     public final void registerPlaylistEventCallback(
             @NonNull @CallbackExecutor Executor executor, @NonNull PlaylistEventCallback callback) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -171,23 +171,23 @@ public abstract class MediaPlaylistAgent {
      */
     public final void unregisterPlaylistEventCallback(
             @NonNull PlaylistEventCallback callback) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     public final void notifyPlaylistChanged() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     public final void notifyPlaylistMetadataChanged() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     public final void notifyShuffleModeChanged() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     public final void notifyRepeatModeChanged() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -196,7 +196,7 @@ public abstract class MediaPlaylistAgent {
      * @return playlist, or null if none is set.
      */
     public @Nullable List<MediaItem2> getPlaylist() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
         return null;
     }
 
@@ -207,7 +207,7 @@ public abstract class MediaPlaylistAgent {
      * @param metadata metadata of the playlist
      */
     public void setPlaylist(@NonNull List<MediaItem2> list, @Nullable MediaMetadata2 metadata) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -216,7 +216,7 @@ public abstract class MediaPlaylistAgent {
      * @return metadata metadata of the playlist, or null if none is set
      */
     public @Nullable MediaMetadata2 getPlaylistMetadata() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
         return null;
     }
 
@@ -226,7 +226,7 @@ public abstract class MediaPlaylistAgent {
      * @param metadata metadata of the playlist
      */
     public void updatePlaylistMetadata(@Nullable MediaMetadata2 metadata) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -236,7 +236,7 @@ public abstract class MediaPlaylistAgent {
      * @param item media item to add
      */
     public void addPlaylistItem(int index, @NonNull MediaItem2 item) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -245,19 +245,18 @@ public abstract class MediaPlaylistAgent {
      * @param item media item to remove
      */
     public void removePlaylistItem(@NonNull MediaItem2 item) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
-     * Replaces the media item with the .
+     * Replace the media item at index in the playlist. This can be also used to update metadata of
-     * <p>
+     * an item.
-     * This can be used to update metadata of a MediaItem.
      *
-     * @param index index
+     * @param index the index of the item to replace
-     * @param item
+     * @param item the new item
      */
     public void replacePlaylistItem(int index, @NonNull MediaItem2 item) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -266,15 +265,15 @@ public abstract class MediaPlaylistAgent {
      * @param item media item to start playing from
      */
     public void skipToPlaylistItem(@NonNull MediaItem2 item) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     public void skipToPreviousItem() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     public void skipToNextItem() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -287,7 +286,7 @@ public abstract class MediaPlaylistAgent {
      * @see #REPEAT_MODE_GROUP
      */
     public @RepeatMode int getRepeatMode() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
         return REPEAT_MODE_NONE;
     }
 
@@ -301,7 +300,7 @@ public abstract class MediaPlaylistAgent {
      * @see #REPEAT_MODE_GROUP
      */
     public void setRepeatMode(@RepeatMode int repeatMode) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 
     /**
@@ -313,7 +312,7 @@ public abstract class MediaPlaylistAgent {
      * @see #SHUFFLE_MODE_GROUP
      */
     public @ShuffleMode int getShuffleMode() {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
         return SHUFFLE_MODE_NONE;
     }
 
@@ -326,6 +325,6 @@ public abstract class MediaPlaylistAgent {
      * @see #SHUFFLE_MODE_GROUP
      */
     public void setShuffleMode(@ShuffleMode int shuffleMode) {
-        // TODO(jaewan): implement this
+        // TODO(jaewan): implement this (b/74090741)
     }
 }

media/java/android/media/MediaSession2.java

@@ -26,9 +26,8 @@ import android.content.Intent;
 import android.media.MediaPlayerBase.BuffState;
 import android.media.MediaPlayerBase.PlayerEventCallback;
 import android.media.MediaPlayerBase.PlayerState;
-import android.media.session.MediaSession;
+import android.media.MediaSession2.PlaylistParams.RepeatMode;
-import android.media.session.MediaSession.Callback;
+import android.media.MediaSession2.PlaylistParams.ShuffleMode;
-import android.media.session.PlaybackState;
 import android.media.update.ApiLoader;
 import android.media.update.MediaSession2Provider;
 import android.media.update.MediaSession2Provider.BuilderBaseProvider;
@@ -193,7 +192,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#skipToPlaylistItem(MediaItem2)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -202,7 +201,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#setShuffleMode(int)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -211,7 +210,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#setRepeatMode(int)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -220,7 +219,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#addPlaylistItem(int, MediaItem2)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -229,7 +228,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#addPlaylistItem(int, MediaItem2)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -238,7 +237,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#replacePlaylistItem(int, MediaItem2)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -248,7 +247,7 @@ public class MediaSession2 implements AutoCloseable {
      * Command code for {@link MediaController2#getPlaylist()}. This will expose metadata
      * information to the controller.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -257,7 +256,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#setPlaylist(List, MediaMetadata2).
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -270,7 +269,7 @@ public class MediaSession2 implements AutoCloseable {
      * Command code for {@link MediaController2#setPlaylist(List, MediaMetadata2)} and
      * {@link MediaController2#updatePlaylistMetadata(MediaMetadata2)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -279,7 +278,7 @@ public class MediaSession2 implements AutoCloseable {
     /**
      * Command code for {@link MediaController2#updatePlaylistMetadata(MediaMetadata2)}.
      * <p>
-     * Command would be sent directly to the playlist controller if the session doesn't reject the
+     * Command would be sent directly to the playlist agent if the session doesn't reject the
      * request through the
      * {@link SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)}.
      */
@@ -416,10 +415,11 @@ public class MediaSession2 implements AutoCloseable {
     public interface OnDataSourceMissingHelper {
         /**
          * Called when a {@link MediaItem2} in the playlist didn't have a {@link DataSourceDesc}
-         * but it's needed now for preparing or playing it.
+         * but it's needed now for preparing or playing it. Returned data source descriptor will be
+         * sent to the player directly to prepare or play the contents.
          * <p>
-         * Returned data source descriptor will be sent to the player directly to prepare or play
+         * An exception may be thrown if the returned {@link DataSourceDesc} is duplicated in the
-         * the contents.
+         * playlist, so items cannot be differentiated.
          *
          * @param session the session for this event
          * @param item media item from the controller
@@ -713,7 +713,7 @@ public class MediaSession2 implements AutoCloseable {
          * <p>
          * During the preparation, a session should not hold audio focus in order to allow other
          * sessions play seamlessly. The state of playback should be updated to
-         * {@link PlaybackState#STATE_PAUSED} after the preparation is done.
+         * {@link MediaPlayerBase#PLAYER_STATE_PAUSED} after the preparation is done.
          * <p>
          * The playback of the prepared content should start in the later calls of
          * {@link MediaSession2#play()}.
@@ -738,9 +738,9 @@ public class MediaSession2 implements AutoCloseable {
          * An empty query indicates that the app may prepare any music. The implementation should
          * attempt to make a smart choice about what to play.
          * <p>
-         * The state of playback should be updated to {@link PlaybackState#STATE_PAUSED} after the
+         * The state of playback should be updated to {@link MediaPlayerBase#PLAYER_STATE_PAUSED}
-         * preparation is done. The playback of the prepared content should start in the later
+         * after the preparation is done. The playback of the prepared content should start in the
-         * calls of {@link MediaSession2#play()}.
+         * later calls of {@link MediaSession2#play()}.
          * <p>
          * Override {@link #onPlayFromSearch} to handle requests for starting playback without
          * preparation.
@@ -758,10 +758,10 @@ public class MediaSession2 implements AutoCloseable {
         /**
          * Called when a controller requested to prepare a specific media item represented by a URI
          * through {@link MediaController2#prepareFromUri(Uri, Bundle)}.
-         * <p></p>
+         * <p>
          * During the preparation, a session should not hold audio focus in order to allow
          * other sessions play seamlessly. The state of playback should be updated to
-         * {@link PlaybackState#STATE_PAUSED} after the preparation is done.
+         * {@link MediaPlayerBase#PLAYER_STATE_PAUSED} after the preparation is done.
          * <p>
          * The playback of the prepared content should start in the later calls of
          * {@link MediaSession2#play()}.
@@ -785,84 +785,85 @@ public class MediaSession2 implements AutoCloseable {
          * callbacks.
          *
          * @param session the controller for this event
-         * @param mpb the player for this event
+         * @param player the player for this event
          * @param item new item
          */
+        // TODO(jaewan): Use this (b/74316764)
         public void onCurrentMediaItemChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlayerBase mpb, @NonNull MediaItem2 item) { }
+                @NonNull MediaPlayerBase player, @NonNull MediaItem2 item) { }
 
         /**
          * Called when the player is <i>prepared</i>, i.e. it is ready to play the content
          * referenced by the given data source.
          * @param session the session for this event
-         * @param mpb the player for this event
+         * @param player the player for this event
          * @param item the media item for which buffering is happening
          */
-        public void onMediaPrepared(@NonNull MediaSession2 session, @NonNull MediaPlayerBase mpb,
+        public void onMediaPrepared(@NonNull MediaSession2 session, @NonNull MediaPlayerBase player,
                 @NonNull MediaItem2 item) { }
 
         /**
          * Called to indicate that the state of the player has changed.
          * See {@link MediaPlayerBase#getPlayerState()} for polling the player state.
          * @param session the session for this event
-         * @param mpb the player for this event
+         * @param player the player for this event
          * @param state the new state of the player.
          */
         public void onPlayerStateChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlayerBase mpb, @PlayerState int state) { }
+                @NonNull MediaPlayerBase player, @PlayerState int state) { }
 
         /**
          * Called to report buffering events for a data source.
          *
          * @param session the session for this event
-         * @param mpb the player for this event
+         * @param player the player for this event
          * @param item the media item for which buffering is happening.
          * @param state the new buffering state.
          */
         public void onBufferingStateChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlayerBase mpb, @NonNull MediaItem2 item, @BuffState int state) { }
+                @NonNull MediaPlayerBase player, @NonNull MediaItem2 item, @BuffState int state) { }
 
         /**
          * Called when a playlist is changed.
          *
          * @param session the session for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param list new playlist
          * @param metadata new metadata
          */
         public void onPlaylistChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlaylistAgent mplc, @NonNull List<MediaItem2> list,
+                @NonNull MediaPlaylistAgent playlistAgent, @NonNull List<MediaItem2> list,
                 @Nullable MediaMetadata2 metadata) { }
 
         /**
          * Called when a playlist metadata is changed.
          *
          * @param session the session for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param metadata new metadata
          */
         public void onPlaylistMetadataChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlaylistAgent mplc, @Nullable MediaMetadata2 metadata) { }
+                @NonNull MediaPlaylistAgent playlistAgent, @Nullable MediaMetadata2 metadata) { }
 
         /**
          * Called when the shuffle mode is changed.
          *
          * @param session the session for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param shuffleMode repeat mode
          * @see MediaPlaylistAgent#SHUFFLE_MODE_NONE
          * @see MediaPlaylistAgent#SHUFFLE_MODE_ALL
          * @see MediaPlaylistAgent#SHUFFLE_MODE_GROUP
          */
         public void onShuffleModeChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlaylistAgent mplc,
+                @NonNull MediaPlaylistAgent playlistAgent,
                 @MediaPlaylistAgent.ShuffleMode int shuffleMode) { }
 
         /**
          * Called when the repeat mode is changed.
          *
          * @param session the session for this event
-         * @param mplc playlist controller for this event
+         * @param playlistAgent playlist agent for this event
          * @param repeatMode repeat mode
          * @see MediaPlaylistAgent#REPEAT_MODE_NONE
          * @see MediaPlaylistAgent#REPEAT_MODE_ONE
@@ -870,7 +871,7 @@ public class MediaSession2 implements AutoCloseable {
          * @see MediaPlaylistAgent#REPEAT_MODE_GROUP
          */
         public void onRepeatModeChanged(@NonNull MediaSession2 session,
-                @NonNull MediaPlaylistAgent mplc,
+                @NonNull MediaPlaylistAgent playlistAgent,
                 @MediaPlaylistAgent.RepeatMode int repeatMode) { }
     }
 
@@ -915,12 +916,12 @@ public class MediaSession2 implements AutoCloseable {
          * Set the {@link MediaPlaylistAgent} for this session to manages playlist of the
          * underlying {@link MediaPlayerBase player}.
          *
-         * @param mplc a {@link MediaPlaylistAgent} that manages playlist of the
+         * @param playlistAgent a {@link MediaPlaylistAgent} that manages playlist of the
-         * {@code player.}
+         * {@code player}
          */
-        U setPlaylistAgent(@NonNull MediaPlaylistAgent mplc) {
+        U setPlaylistAgent(@NonNull MediaPlaylistAgent playlistAgent) {
             // TODO(jaewan): fix this
-            mProvider.setPlaylistController_impl(mplc);
+            mProvider.setPlaylistAgent_impl(playlistAgent);
             return (U) this;
         }
 
@@ -1007,8 +1008,8 @@ public class MediaSession2 implements AutoCloseable {
         }
 
         @Override
-        public Builder setPlaylistAgent(@NonNull MediaPlaylistAgent mplc) {
+        public Builder setPlaylistAgent(@NonNull MediaPlaylistAgent playlistAgent) {
-            return super.setPlaylistAgent(mplc);
+            return super.setPlaylistAgent(playlistAgent);
         }
 
         @Override
@@ -1345,10 +1346,13 @@ public class MediaSession2 implements AutoCloseable {
      *       Whenever it happens only one session was properly setup and others were all dummies.
      *       Android framework couldn't find the right session to dispatch media key event.
      *    2. Simplify session's lifecycle.
-     *       {@link MediaSession} can be available after all of {@link MediaSession#setFlags(int)},
+     *       {@link android.media.session.MediaSession} is available after all of
-     *       {@link MediaSession#setCallback(Callback)}, and
+     *       {@link android.media.session.MediaSession#setFlags(int)},
-     *       {@link MediaSession#setActive(boolean)}. It was common for an app to omit one, so
+     *       {@link android.media.session.MediaSession#setCallback(
-     *       framework had to add heuristics to figure out if an app is
+     *              android.media.session.MediaSession.Callback)},
+     *       and {@link android.media.session.MediaSession#setActive(boolean)}.
+     *       It was common for an app to omit one, so framework had to add heuristics to figure out
+     *       which should be the highest priority for handling media key event.
      * @hide
      */
     public MediaSession2(MediaSession2Provider provider) {
@@ -1369,14 +1373,14 @@ public class MediaSession2 implements AutoCloseable {
      * player on the {@link Handler} where the session is created on.
      *
      * @param player a {@link MediaPlayerBase} that handles actual media playback in your app.
-     * @param mplc a {@link MediaPlaylistAgent} that manages playlist of the
+     * @param playlistAgent a {@link MediaPlaylistAgent} that manages playlist of the
      * {@code player}
      * @param volumeProvider The provider that will receive volume button events. If
      * {@code null}, system will adjust the appropriate stream volume for this session's player.
      */
     public void updatePlayer(@NonNull MediaPlayerBase player,
-            @Nullable MediaPlaylistAgent mplc, @Nullable VolumeProvider2 volumeProvider) {
+            @Nullable MediaPlaylistAgent playlistAgent, @Nullable VolumeProvider2 volumeProvider) {
-        mProvider.updatePlayer_impl(player, mplc, volumeProvider);
+        mProvider.updatePlayer_impl(player, playlistAgent, volumeProvider);
     }
 
     @Override
@@ -1490,20 +1494,26 @@ public class MediaSession2 implements AutoCloseable {
 
     /**
      * Play playback
+     * <p>
+     * This calls {@link MediaPlayerBase#play()}.
      */
     public void play() {
         mProvider.play_impl();
     }
 
     /**
-     * Pause playback
+     * Pause playback.
+     * <p>
+     * This calls {@link MediaPlayerBase#pause()}.
      */
     public void pause() {
         mProvider.pause_impl();
     }
 
     /**
-     * Stop playback
+     * Stop playback, and reset the player to the initial state.
+     * <p>
+     * This calls {@link MediaPlayerBase#reset()}.
      */
     public void stop() {
         mProvider.stop_impl();
@@ -1513,8 +1523,10 @@ public class MediaSession2 implements AutoCloseable {
      * Request that the player prepare its playback. In other words, other sessions can continue
      * to play during the preparation of this session. This method can be used to speed up the
      * start of the playback. Once the preparation is done, the session will change its playback
-     * state to {@link PlaybackState#STATE_PAUSED}. Afterwards, {@link #play} can be called to
+     * state to {@link MediaPlayerBase#PLAYER_STATE_PAUSED}. Afterwards, {@link #play} can be called
-     * start playback.
+     * to start playback.
+     * <p>
+     * This calls {@link MediaPlayerBase#reset()}.
      */
     public void prepare() {
         mProvider.prepare_impl();
@@ -1666,15 +1678,15 @@ public class MediaSession2 implements AutoCloseable {
      * The helper will be run on the executor that you've specified by the
      * {@link Builder#setSessionCallback(Executor, SessionCallback)}.
      *
-     * @param helper a data source misisng helper.
+     * @param helper a data source missing helper.
-     * @throws IllegalStateException when the helper is set when the playlist controller is set
+     * @throws IllegalStateException when the helper is set when the playlist agent is set
      * @see #setPlaylist(List, MediaMetadata2)
      * @see SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, Command)
      * @see #COMMAND_CODE_PLAYLIST_ADD_ITEM
      * @see #COMMAND_CODE_PLAYLIST_REPLACE_ITEM
      */
     public void setOnDataSourceMissingHelper(@NonNull OnDataSourceMissingHelper helper) {
-        // TODO(jaewan): Implement (b/74090741)
+        // TODO(jaewan): Implement (b/74090741).
     }
 
     /**
@@ -1708,17 +1720,19 @@ public class MediaSession2 implements AutoCloseable {
     }
 
     /**
-     * Set a list of {@link MediaItem2} as the current play list.
+     * Set a list of {@link MediaItem2} as the current play list. Ensure uniqueness in the
+     * {@link MediaItem2} in the playlist so session can uniquely identity individual items.
      * <p>
      * You may specify a {@link MediaItem2} without {@link DataSourceDesc}. However, in that case,
      * you should set {@link OnDataSourceMissingHelper} for player to prepare.
      *
      * @param list A list of {@link MediaItem2} objects to set as a play list.
-     * @throws IllegalArgumentException if given {@param playlist} is null.
+     * @throws IllegalArgumentException if given list is {@code null}, or has duplicated media item.
      * @see #setOnDataSourceMissingHelper
      */
     public void setPlaylist(@NonNull List<MediaItem2> list, @Nullable MediaMetadata2 metadata) {
-        // TODO(jaewan): Implement (b/74174649)
+        // TODO(jaewan): Handle metadata here (b/74174649)
+        // TODO(jaewan): Handle list change (b/74326040)
     }
 
     /**
@@ -1733,13 +1747,11 @@ public class MediaSession2 implements AutoCloseable {
     }
 
     public void skipToPreviousItem() {
-        // TODO(jaewan): fix this
+        mProvider.skipToPreviousItem_impl();
-        mProvider.skipToPrevious_impl();
     }
 
     public void skipToNextItem() {
-        // TODO(jaewan): fix this
+        mProvider.skipToNextItem_impl();
-        mProvider.skipToNext_impl();
     }
 
     public MediaMetadata2 getPlaylistMetadata() {
@@ -1775,7 +1787,9 @@ public class MediaSession2 implements AutoCloseable {
     }
 
     /**
-     * Replace the media item at index in the playlist.
+     * Replace the media item at index in the playlist. This can be also used to update metadata of
+     * an item.
+     *
      * @param index the index of the item to replace
      * @param item the new item
      */
@@ -1789,7 +1803,7 @@ public class MediaSession2 implements AutoCloseable {
      * @return currently playing media item
      */
     public MediaItem2 getCurrentMediaItem() {
-        // TODO(jaewan): Rename provider API
+        // TODO(jaewan): Rename provider, and implement (b/74316764)
         return mProvider.getCurrentPlaylistItem_impl();
     }
 
@@ -1797,21 +1811,21 @@ public class MediaSession2 implements AutoCloseable {
         // TODO(jaewan): Implement (b/74174649)
     }
 
-    public int getRepeatMode() {
+    public @RepeatMode int getRepeatMode() {
         // TODO(jaewan): Implement (b/74118768)
         return 0;
     }
 
-    public void setRepeatMode(int repeatMode) {
+    public void setRepeatMode(@RepeatMode int repeatMode) {
         // TODO(jaewan): Implement (b/74118768)
     }
 
-    public int getShuffleMode() {
+    public @ShuffleMode int getShuffleMode() {
         // TODO(jaewan): Implement (b/74118768)
         return 0;
     }
 
-    public void setShuffleMode(int shuffleMode) {
+    public void setShuffleMode(@ShuffleMode int shuffleMode) {
         // TODO(jaewan): Implement (b/74118768)
     }
 }

media/java/android/media/update/MediaController2Provider.java

@@ -70,7 +70,7 @@ public interface MediaController2Provider extends TransportControlProvider {
     long getPosition_impl();
     float getPlaybackSpeed_impl();
     long getBufferedPosition_impl();
-    MediaItem2 getCurrentPlaylistItem_impl();
+    MediaItem2 getCurrentMediaItem_impl();
 
     interface PlaybackInfoProvider {
         int getPlaybackType_impl();

media/java/android/media/update/MediaSession2Provider.java

@@ -43,7 +43,7 @@ import java.util.concurrent.Executor;
  */
 public interface MediaSession2Provider extends TransportControlProvider {
     void close_impl();
-    void updatePlayer_impl(MediaPlayerBase player, MediaPlaylistAgent mplc,
+    void updatePlayer_impl(MediaPlayerBase player, MediaPlaylistAgent playlistAgent,
             VolumeProvider2 volumeProvider);
     MediaPlayerBase getPlayer_impl();
     VolumeProvider2 getVolumeProvider_impl();
@@ -123,7 +123,7 @@ public interface MediaSession2Provider extends TransportControlProvider {
 
     interface BuilderBaseProvider<T extends MediaSession2, C extends SessionCallback> {
         void setPlayer_impl(MediaPlayerBase player);
-        void setPlaylistController_impl(MediaPlaylistAgent mplc);
+        void setPlaylistAgent_impl(MediaPlaylistAgent playlistAgent);
         void setVolumeProvider_impl(VolumeProvider2 volumeProvider);
         void setSessionActivity_impl(PendingIntent pi);
         void setId_impl(String id);

media/java/android/media/update/TransportControlProvider.java

@@ -26,8 +26,8 @@ public interface TransportControlProvider {
     void play_impl();
     void pause_impl();
     void stop_impl();
-    void skipToPrevious_impl();
+    void skipToPreviousItem_impl();
-    void skipToNext_impl();
+    void skipToNextItem_impl();
 
     void prepare_impl();
     void fastForward_impl();

services/core/java/com/android/server/media/MediaSessionService.java

@@ -2086,7 +2086,7 @@ public class MediaSessionService extends SystemService implements Monitor {
 
         public SessionTokensListenerRecord(ISessionTokensListener listener, int userId) {
             mListener = listener;
-            // TODO should userId be mapped through mFullUserIds? (b/73597722)
+            // TODO(jaewan): should userId be mapped through mFullUserIds? (b/73597722)
             mUserId = userId;
         }