Merge "MediaPlayerBase API" (7f1bceb3) · Commits · e / os / android_frameworks_base

api/current.txt

+51 −6

Original line number	Diff line number	Diff line
		@@ -23336,7 +23336,7 @@ package android.media {
		field public static final int REGULAR_CODECS = 0; // 0x0
		}

		public class MediaController2 implements java.lang.AutoCloseable {
		public class MediaController2 implements java.lang.AutoCloseable android.media.MediaPlaylistController {
		ctor public MediaController2(android.content.Context, android.media.SessionToken2, java.util.concurrent.Executor, android.media.MediaController2.ControllerCallback);
		method public void addPlaylistItem(int, android.media.MediaItem2);
		method public void adjustVolume(int, int);
		@@ -23363,6 +23363,7 @@ package android.media {
		method public void prepareFromSearch(java.lang.String, android.os.Bundle);
		method public void prepareFromUri(android.net.Uri, android.os.Bundle);
		method public void removePlaylistItem(android.media.MediaItem2);
		method public void replacePlaylistItem(int, android.media.MediaItem2);
		method public void rewind();
		method public void seekTo(long);
		method public void sendCustomCommand(android.media.MediaSession2.Command, android.os.Bundle, android.os.ResultReceiver);
		@@ -24463,14 +24464,56 @@ package android.media {
		public abstract class MediaPlayerBase implements java.lang.AutoCloseable {
		ctor public MediaPlayerBase();
		method public abstract android.media.AudioAttributes getAudioAttributes();
		method public long getBufferedPosition();
		method public abstract int getBufferingState();
		method public abstract android.media.DataSourceDesc getCurrentDataSource();
		method public long getCurrentPosition();
		method public long getDuration();
		method public float getMaxPlayerVolume();
		method public float getPlaybackSpeed();
		method public abstract int getPlayerState();
		method public abstract float getPlayerVolume();
		method public boolean isReversePlaybackSupported();
		method public abstract void loopCurrent(boolean);
		method public abstract void pause();
		method public abstract void play();
		method public abstract void prepare();
		method public abstract void registerPlayerEventCallback(java.util.concurrent.Executor, android.media.MediaPlayerBase.PlayerEventCallback);
		method public abstract void seekTo(long);
		method public abstract void setAudioAttributes(android.media.AudioAttributes);
		field public static final int STATE_ERROR = 0; // 0x0
		field public static final int STATE_IDLE = 0; // 0x0
		field public static final int STATE_PAUSED = 0; // 0x0
		field public static final int STATE_PLAYING = 0; // 0x0
		method public abstract void setDataSource(android.media.DataSourceDesc);
		method public abstract void setNextDataSource(android.media.DataSourceDesc);
		method public abstract void setNextDataSources(java.util.List<android.media.DataSourceDesc>);
		method public abstract void setPlaybackSpeed(float);
		method public abstract void setVolume(float);
		method public abstract void skipToNext();
		method public abstract void unregisterPlayerEventCallback(android.media.MediaPlayerBase.PlayerEventCallback);
		field public static final int BUFFERING_STATE_BUFFERING_AND_PLAYABLE = 1; // 0x1
		field public static final int BUFFERING_STATE_BUFFERING_AND_STARVED = 2; // 0x2
		field public static final int BUFFERING_STATE_BUFFERING_COMPLETE = 3; // 0x3
		field public static final int BUFFERING_STATE_UNKNOWN = 0; // 0x0
		field public static final int PLAYER_STATE_ERROR = 3; // 0x3
		field public static final int PLAYER_STATE_IDLE = 0; // 0x0
		field public static final int PLAYER_STATE_PAUSED = 1; // 0x1
		field public static final int PLAYER_STATE_PLAYING = 2; // 0x2
		field public static final long UNKNOWN_TIME = -1L; // 0xffffffffffffffffL
		}

		public static abstract class MediaPlayerBase.PlayerEventCallback {
		ctor public MediaPlayerBase.PlayerEventCallback();
		method public void onBufferingStateChanged(android.media.MediaPlayerBase, android.media.DataSourceDesc, int);
		method public void onCurrentDataSourceChanged(android.media.MediaPlayerBase, android.media.DataSourceDesc);
		method public void onMediaPrepared(android.media.MediaPlayerBase, android.media.DataSourceDesc);
		method public void onPlayerStateChanged(android.media.MediaPlayerBase, int);
		}

		public abstract interface MediaPlaylistController {
		method public abstract void addPlaylistItem(int, android.media.MediaItem2);
		method public abstract android.media.MediaItem2 getCurrentPlaylistItem();
		method public abstract java.util.List<android.media.MediaItem2> getPlaylist();
		method public abstract void removePlaylistItem(android.media.MediaItem2);
		method public abstract void replacePlaylistItem(int, android.media.MediaItem2);
		method public abstract void skipToPlaylistItem(android.media.MediaItem2);
		}

		public class MediaRecorder implements android.media.AudioRouting {
		@@ -24749,7 +24792,7 @@ package android.media {
		method public abstract void onScanCompleted(java.lang.String, android.net.Uri);
		}

		public class MediaSession2 implements java.lang.AutoCloseable {
		public class MediaSession2 implements java.lang.AutoCloseable android.media.MediaPlaylistController {
		method public void addPlaylistItem(int, android.media.MediaItem2);
		method public void close();
		method public void editPlaylistItem(android.media.MediaItem2);
		@@ -24765,6 +24808,7 @@ package android.media {
		method public void play();
		method public void prepare();
		method public void removePlaylistItem(android.media.MediaItem2);
		method public void replacePlaylistItem(int, android.media.MediaItem2);
		method public void rewind();
		method public void seekTo(long);
		method public void sendCustomCommand(android.media.MediaSession2.Command, android.os.Bundle);
		@@ -24819,6 +24863,7 @@ package android.media {

		public static final class MediaSession2.Builder {
		ctor public MediaSession2.Builder(android.content.Context, android.media.MediaPlayerBase);
		ctor public MediaSession2.Builder(android.content.Context, android.media.MediaPlayerBase, android.media.MediaPlaylistController);
		method public android.media.MediaSession2 build();
		method public android.media.MediaSession2.Builder setId(java.lang.String);
		method public android.media.MediaSession2.Builder setSessionActivity(android.app.PendingIntent);

media/java/android/media/MediaController2.java

+15 −8

Original line number	Diff line number	Diff line
		@@ -371,7 +371,7 @@ public class MediaController2 implements AutoCloseable, MediaPlaylistController
		* 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 MediaPlayerBase#STATE_PAUSED}. Afterwards, {@link #play} can be called to
		* state to {@link MediaPlayerBase#PLAYER_STATE_PAUSED}. Afterwards, {@link #play} can be called to
		* start playback.
		*/
		public void prepare() {
		@@ -479,7 +479,7 @@ public class MediaController2 implements AutoCloseable, MediaPlaylistController
		* Request that the player prepare playback for a specific media id. 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 MediaPlayerBase#STATE_PAUSED}. Afterwards,
		* will change its playback state to {@link MediaPlayerBase#PLAYER_STATE_PAUSED}. Afterwards,
		* {@link #play} can be called to start playback. If the preparation is not needed,
		* {@link #playFromMediaId} can be directly called without this method.
		*
		@@ -496,7 +496,7 @@ public class MediaController2 implements AutoCloseable, MediaPlaylistController
		* query should be treated as a request to prepare any music. 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 MediaPlayerBase#STATE_PAUSED}. Afterwards,
		* change its playback state to {@link MediaPlayerBase#PLAYER_STATE_PAUSED}. Afterwards,
		* {@link #play} can be called to start playback. If the preparation is not needed,
		* {@link #playFromSearch} can be directly called without this method.
		*
		@@ -512,7 +512,7 @@ public class MediaController2 implements AutoCloseable, MediaPlaylistController
		* Request that the player prepare playback for a specific {@link Uri}. 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 MediaPlayerBase#STATE_PAUSED}. Afterwards,
		* session will change its playback state to {@link MediaPlayerBase#PLAYER_STATE_PAUSED}. Afterwards,
		* {@link #play} can be called to start playback. If the preparation is not needed,
		* {@link #playFromUri} can be directly called without this method.
		*
		@@ -702,15 +702,22 @@ public class MediaController2 implements AutoCloseable, MediaPlaylistController
		*<p>
		* If index is same as the current index of the playlist, current playback
		* will be stopped and playback moves to next source in the list.
		*
		* @throws IllegalArgumentException if the play list is null
		* @throws IndexOutOfBoundsException if index is outside play list range
		*/
		@Override
		public void removePlaylistItem(@NonNull MediaItem2 item) {
		mProvider.removePlaylistItem_impl(item);
		}

		/**
		* Replace the media item at index in the playlist.
		* @param index the index of the item to replace
		* @param item the new item
		*/
		@Override
		public void replacePlaylistItem(int index, @NonNull MediaItem2 item) {
		mProvider.replacePlaylistItem_impl(index, item);
		}

		/**
		* Inserts the media item to the play list at position index.
		* <p>

media/java/android/media/MediaPlayerBase.java

+168 −105

Original line number	Diff line number	Diff line
		@@ -34,214 +34,277 @@ public abstract class MediaPlayerBase implements AutoCloseable {
		/**
		* @hide
		*/
		@IntDef({STATE_IDLE, STATE_PAUSED, STATE_PLAYING, STATE_ERROR})
		@IntDef({
		PLAYER_STATE_IDLE,
		PLAYER_STATE_PAUSED,
		PLAYER_STATE_PLAYING,
		PLAYER_STATE_ERROR })
		@Retention(RetentionPolicy.SOURCE)
		public @interface State {}
		public @interface PlayerState {}

		/**
		* @hide
		*/
		@IntDef({
		BUFFERING_STATE_UNKNOWN,
		BUFFERING_STATE_BUFFERING_AND_PLAYABLE,
		BUFFERING_STATE_BUFFERING_AND_STARVED,
		BUFFERING_STATE_BUFFERING_COMPLETE })
		@Retention(RetentionPolicy.SOURCE)
		public @interface BuffState {}

		/**
		* State when the player is idle, and needs configuration to start playback.
		*/
		public static final int STATE_IDLE = 0;
		public static final int PLAYER_STATE_IDLE = 0;

		/**
		* State when the player's playback is paused
		*/
		public static final int STATE_PAUSED = 0;
		public static final int PLAYER_STATE_PAUSED = 1;

		/**
		* State when the player's playback is ongoing
		*/
		public static final int STATE_PLAYING = 0;
		public static final int PLAYER_STATE_PLAYING = 2;

		/**
		* State when the player is in error state and cannot be recovered self.
		*/
		public static final int STATE_ERROR = 0;
		public static final int PLAYER_STATE_ERROR = 3;

		/**
		* Unspecified media player error.
		* @hide
		* Buffering state is unknown.
		*/
		public static final int MEDIA_ERROR_UNKNOWN = MediaPlayer2.MEDIA_ERROR_UNKNOWN;
		public static final int BUFFERING_STATE_UNKNOWN = 0;

		/**
		* The video is streamed and its container is not valid for progressive
		* playback i.e the video's index (e.g moov atom) is not at the start of the
		* file.
		* @hide
		* Buffering state indicating the player is buffering but enough has been buffered
		* for this player to be able to play the content.
		* See {@link #getBufferedPosition()} for how far is buffered already.
		*/
		public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK =
		MediaPlayer2.MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK;
		public static final int BUFFERING_STATE_BUFFERING_AND_PLAYABLE = 1;

		/**
		* File or network related operation errors.
		* @hide
		* Buffering state indicating the player is buffering, but the player is currently starved
		* for data, and cannot play.
		*/
		public static final int MEDIA_ERROR_IO = MediaPlayer2.MEDIA_ERROR_IO;
		public static final int BUFFERING_STATE_BUFFERING_AND_STARVED = 2;

		/**
		* Bitstream is not conforming to the related coding standard or file spec.
		* @hide
		* Buffering state indicating the player is done buffering, and the remainder of the content is
		* available for playback.
		*/
		public static final int MEDIA_ERROR_MALFORMED = MediaPlayer2.MEDIA_ERROR_MALFORMED;
		public static final int BUFFERING_STATE_BUFFERING_COMPLETE = 3;

		/**
		* Bitstream is conforming to the related coding standard or file spec, but
		* the media framework does not support the feature.
		* @hide
		* Starts or resumes playback.
		*/
		public static final int MEDIA_ERROR_UNSUPPORTED = MediaPlayer2.MEDIA_ERROR_UNSUPPORTED;
		public abstract void play();

		/**
		* Some operation takes too long to complete, usually more than 3-5 seconds.
		* @hide
		* Prepares the player for playback.
		* See {@link PlayerEventCallback#onMediaPrepared(MediaPlayerBase, DataSourceDesc)} for being
		* notified when the preparation phase completed. During this time, the player may allocate
		* resources required to play, such as audio and video decoders.
		*/
		public static final int MEDIA_ERROR_TIMED_OUT = MediaPlayer2.MEDIA_ERROR_TIMED_OUT;
		public abstract void prepare();

		/**
		* Callbacks to listens to the changes in {@link PlaybackState2} and error.
		* @hide
		* Pauses playback.
		*/
		public static abstract class EventCallback {
		public abstract void pause();

		/**
		* Called when {@link PlaybackState2} for this player is changed.
		*
		*/
		public void onPlaybackStateChanged(PlaybackState2 state) { }
		public abstract void skipToNext();

		/**
		* Called to indicate an error.
		*
		* @param mediaId optional mediaId to indicate error
		* @param what what
		* @param extra
		* Moves the playback head to the specified position
		* @param pos the new playback position expressed in ms.
		*/
		public void onError(@Nullable String mediaId, int what, int extra) { }
		}
		public abstract void seekTo(long pos);

		public static final long UNKNOWN_TIME = -1;

		// Transport controls that session will send command directly to this player.
		/**
		* Start or resumes playback
		* Returns the current playback head position.
		* @return the current play position in ms, or {@link #UNKNOWN_TIME} if unknown.
		*/
		public abstract void play();
		public long getCurrentPosition() { return UNKNOWN_TIME; }

		/**
		* @hide
		* Returns the duration of the current data source, or {@link #UNKNOWN_TIME} if unknown.
		* @return the duration in ms, or {@link #UNKNOWN_TIME}.
		*/
		public abstract void prepare();
		public long getDuration() { return UNKNOWN_TIME; }

		/**
		* Pause playback
		* Returns the duration of the current data source, or {@link #UNKNOWN_TIME} if unknown.
		* @return the duration in ms, or {@link #UNKNOWN_TIME}.
		*/
		public abstract void pause();
		public long getBufferedPosition() { return UNKNOWN_TIME; }

		/**
		* @hide
		* Returns the current player state.
		* See also {@link PlayerEventCallback#onPlayerStateChanged(MediaPlayerBase, int)} for
		* notification of changes.
		* @return the current player state
		*/
		public abstract void stop();
		public abstract @PlayerState int getPlayerState();

		/**
		* @hide
		* Returns the current buffering state of the player.
		* During buffering, see {@link #getBufferedPosition()} for the quantifying the amount already
		* buffered.
		* @return the buffering state.
		*/
		public abstract void skipToPrevious();
		public abstract @BuffState int getBufferingState();

		/**
		* @hide
		* Sets the {@link AudioAttributes} to be used during the playback of the media.
		*
		* @param attributes non-null <code>AudioAttributes</code>.
		*/
		public abstract void skipToNext();
		public abstract void setAudioAttributes(@NonNull AudioAttributes attributes);

		/**
		* @hide
		* Returns AudioAttributes that media player has.
		*/
		public abstract void seekTo(long pos);
		public abstract @Nullable AudioAttributes getAudioAttributes();

		/**
		* @hide
		* Sets the data source to be played.
		* @param dsd
		*/
		public abstract void fastForward();
		public abstract void setDataSource(@NonNull DataSourceDesc dsd);

		/**
		* @hide
		* Sets the data source that will be played immediately after the current one is done playing.
		* @param dsd
		*/
		public abstract void rewind();
		public abstract void setNextDataSource(@NonNull DataSourceDesc dsd);

		/**
		* @hide
		* Sets the list of data sources that will be sequentially played after the current one. Each
		* data source is played immediately after the previous one is done playing.
		* @param dsds
		*/
		public abstract PlaybackState2 getPlaybackState();
		public abstract void setNextDataSources(@NonNull List<DataSourceDesc> dsds);

		/**
		* Return player state.
		*
		* @return player state
		* @see #STATE_IDLE
		* @see #STATE_PLAYING
		* @see #STATE_PAUSED
		* @see #STATE_ERROR
		* Returns the current data source.
		* @return the current data source, or null if none is set, or none available to play.
		*/
		public abstract @State int getPlayerState();
		public abstract @Nullable DataSourceDesc getCurrentDataSource();

		/**
		* Sets the {@link AudioAttributes} to be used during the playback of the media.
		*
		* @param attributes non-null <code>AudioAttributes</code>.
		* Configures the player to loop on the current data source.
		* @param loop true if the current data source is meant to loop.
		*/
		public abstract void setAudioAttributes(@NonNull AudioAttributes attributes);
		public abstract void loopCurrent(boolean loop);

		/**
		* Returns AudioAttributes that media player has.
		* Sets the playback speed.
		* A value of 1.0f is the default playback value.
		* A negative value indicates reverse playback, check {@link #isReversePlaybackSupported()}
		* before using negative values.<br>
		* After changing the playback speed, it is recommended to query the actual speed supported
		* by the player, see {@link #getPlaybackSpeed()}.
		* @param speed
		*/
		public abstract @Nullable AudioAttributes getAudioAttributes();
		public abstract void setPlaybackSpeed(float speed);

		/**
		* @hide
		* Returns the actual playback speed to be used by the player when playing.
		* Note that it may differ from the speed set in {@link #setPlaybackSpeed(float)}.
		* @return the actual playback speed
		*/
		public abstract void addPlaylistItem(int index, MediaItem2 item);
		public float getPlaybackSpeed() { return 1.0f; }

		/**
		* @hide
		* Indicates whether reverse playback is supported.
		* Reverse playback is indicated by negative playback speeds, see
		* {@link #setPlaybackSpeed(float)}.
		* @return true if reverse playback is supported.
		*/
		public abstract void removePlaylistItem(MediaItem2 item);
		public boolean isReversePlaybackSupported() { return false; }

		/**
		* @hide
		* Sets the volume of the audio of the media to play, expressed as a linear multiplier
		* on the audio samples.
		* Note that this volume is specific to the player, and is separate from stream volume
		* used across the platform.<br>
		* A value of 0.0f indicates muting, a value of 1.0f is the nominal unattenuated and unamplified
		* gain. See {@link #getMaxPlayerVolume()} for the volume range supported by this player.
		* @param volume a value between 0.0f and {@link #getMaxPlayerVolume()}.
		*/
		public abstract void setPlaylist(List<MediaItem2> playlist);
		public abstract void setVolume(float volume);

		/**
		* @hide
		* Returns the current volume of this player to this player.
		* Note that it does not take into account the associated stream volume.
		* @return the player volume.
		*/
		public abstract List<MediaItem2> getPlaylist();
		public abstract float getPlayerVolume();

		/**
		* @hide
		* @return the maximum volume that can be used in {@link #setVolume(float)}.
		*/
		public abstract void setCurrentPlaylistItem(MediaItem2 item);
		public float getMaxPlayerVolume() { return 1.0f; }

		/**
		* @hide
		* Adds a callback to be notified of events for this player.
		* @param e the {@link Executor} to be used for the events.
		* @param cb the callback to receive the events.
		*/
		public abstract void setPlaylistParams(PlaylistParams params);
		public abstract void registerPlayerEventCallback(@NonNull Executor e,
		@NonNull PlayerEventCallback cb);

		/**
		* @hide
		* Removes a previously registered callback for player events
		* @param cb the callback to remove
		*/
		public abstract PlaylistParams getPlaylistParams();
		public abstract void unregisterPlayerEventCallback(@NonNull PlayerEventCallback cb);

		/**
		* Register a {@link EventCallback}.
		*
		* @param executor a callback executor
		* @param callback a EventCallback
		* @hide
		* A callback class to receive notifications for events on the media player.
		* See {@link MediaPlayerBase#registerPlayerEventCallback(Executor, PlayerEventCallback)} to
		* register this callback.
		*/
		public static abstract class PlayerEventCallback {
		/**
		* Called when the player's curretn data source has changed.
		* @param mpb the player whose data source changed.
		* @param dsd the new current data source.
		*/
		public abstract void registerEventCallback(@NonNull @CallbackExecutor Executor executor,
		@NonNull EventCallback callback);
		public void onCurrentDataSourceChanged(@NonNull MediaPlayerBase mpb,
		@Nullable DataSourceDesc dsd) { }
		/**
		* Called when the player is <i>prepared</i>, i.e. it is ready to play the content
		* referenced by the given data source.
		* @param mpb the player that is prepared.
		* @param dsd the data source that the player is prepared to play.
		*/
		public void onMediaPrepared(@NonNull MediaPlayerBase mpb, @NonNull DataSourceDesc dsd) { }

		/**
		* Unregister previously registered {@link EventCallback}.
		*
		* @param callback a EventCallback
		* @hide
		* Called to indicate that the state of the player has changed.
		* See {@link MediaPlayerBase#getPlayerState()} for polling the player state.
		* @param mpb the player whose state has changed.
		* @param state the new state of the player.
		*/
		public void onPlayerStateChanged(@NonNull MediaPlayerBase mpb, @PlayerState int state) { }

		/**
		* Called to report buffering events for a data source.
		* @param mpb the player that is buffering
		* @param dsd the data source for which buffering is happening.
		* @param state the new buffering state.
		*/
		public abstract void unregisterEventCallback(@NonNull EventCallback callback);
		public void onBufferingStateChanged(@NonNull MediaPlayerBase mpb,
		@NonNull DataSourceDesc dsd, @BuffState int state) { }
		}

		}

media/java/android/media/MediaPlaylistController.java

+8 −10

Original line number	Diff line number	Diff line
		@@ -21,21 +21,19 @@ import android.annotation.NonNull;
		import java.util.List;

		/**
		* Controller interfaces for playlist management for both {@link MediaSession2} and
		* {@link MediaController2} that related with metadata. This ensures that two classes share the same
		* interface.
		* <p>
		* This class only includes methods that involves {@link MediaItem2}. Because other APIs are
		* considered as the part of {@link MediaPlayerBase} (e.g. set/getPlaylistParams()}. Note that
		* setPlaylist() isn't added on purpose because it's considered as session specific.
		*
		* @hide
		* Controller interface for playlist management.
		* Playlists are composed of one or multiple {@link MediaItem2} instances, which combine metadata
		* and data sources (as {@link DataSourceDesc})
		* Used by {@link MediaSession2} and {@link MediaController2}.
		*/
		// This class only includes methods that contain {@link MediaItem2}.
		// Note that setPlaylist() isn't added on purpose because it's considered session-specific.

		public interface MediaPlaylistController {
		// TODO(jaewan): is Index correct here?
		void addPlaylistItem(int index, @NonNull MediaItem2 item);
		void removePlaylistItem(@NonNull MediaItem2 item);
		MediaItem2 getCurrentPlaylistItem();
		void skipToPlaylistItem(@NonNull MediaItem2 item);
		void replacePlaylistItem(int index, @NonNull MediaItem2 item);
		List<MediaItem2> getPlaylist();
		}

media/java/android/media/MediaSession2.java

+23 −3

File changed.

Preview size limit exceeded, changes collapsed.