public final class MediaPlayer
extends SessionPlayer

   ↳ androidx.media2.common.SessionPlayer
     ↳ androidx.media2.player.MediaPlayer

A media player which plays MediaItems. The details on playback control and player states can be found in the documentation of the base class, SessionPlayer.

Topic covered here:

  1. Audio focus and noisy intent

Audio focus and noisy intent

By default, MediaPlayer handles audio focus and noisy intent with AudioAttributesCompat set to this player. You need to call setAudioAttributes(AudioAttributesCompat) set the audio attribute while in the SessionPlayer.PLAYER_STATE_IDLE.

Here's the table of automatic audio focus behavior with audio attributes.

Audio AttributesAudio Focus Gain TypeMisc
AudioManager.AUDIOFOCUS_GAIN Developers should specific a proper usage instead of AudioAttributesCompat.USAGE_UNKNOWN
null No audio focus handling, and sets the player volume to 0 Only valid if your media contents don't have audio
Any other AudioAttributes No audio focus handling, and sets the player volume to 0 This is to handle error

If an AudioAttributesCompat is not specified by setAudioAttributes(AudioAttributesCompat), getAudioAttributes() will return null and the default audio focus behavior will follow the null case on the table above.

For more information about the audio focus, take a look at Managing audio focus


Nested classes

class MediaPlayer.PlayerCallback

Interface definition for callbacks to be invoked when the player has the corresponding events. 

class MediaPlayer.TrackInfo

Class for the player to return each audio/video/subtitle track's metadata. 



Informs that audio is not playing.


Bad interleaving means that a media has been improperly interleaved or not interleaved at all, e.g has all the video samples first then all the audio ones.


Update status in buffering a media source received through progressive downloading.


A new set of metadata is available.


The media cannot be seeked (e.g live stream)


Informs that video is not playing.


The player just pushed the very first video frame for rendering.


The video is too complex for the decoder: it can't decode frames fast enough.


This constant is deprecated. getSelectedTrack(int) returns null instead of this value.


File or network related operation errors.


Bitstream is not conforming to the related coding standard or file spec.


Some operation takes too long to complete, usually more than 3-5 seconds.


Unspecified player error.


Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature.


This mode is used with seekTo(long, int) to move media position to a frame (not necessarily a key frame) associated with a media item that is located closest to or at the given time.


This mode is used with seekTo(long, int) to move media position to a sync (or key) frame associated with a media item that is located closest to (in time) or at the given time.


This mode is used with seekTo(long, int) to move media position to a sync (or key) frame associated with a media item that is located right after or at the given time.


This mode is used with seekTo(long, int) to move media position to a sync (or key) frame associated with a media item that is located right before or at the given time.

Inherited constants

Public constructors

MediaPlayer(Context context)

Constructor to create a MediaPlayer instance.

Public methods

ListenableFuture<SessionPlayer.PlayerResult> addPlaylistItem(int index, MediaItem item)

Adds the media item to the playlist at the index.

ListenableFuture<SessionPlayer.PlayerResult> attachAuxEffect(int effectId)

Attaches an auxiliary effect to the player.

void close()

Closes the player and relinquish underlying resources.

ListenableFuture<SessionPlayer.PlayerResult> deselectTrack(SessionPlayer.TrackInfo trackInfo)

Deselects the MediaPlayer.TrackInfo for the current media item.

AudioAttributesCompat getAudioAttributes()

Gets the AudioAttributesCompat that media player has.

int getAudioSessionId()

Returns the audio session ID.

long getBufferedPosition()

Gets the position for how much has been buffered, or UNKNOWN_TIME if unknown.

int getBufferingState()

Returns the current buffering state of the player.

MediaItem getCurrentMediaItem()

Gets the current media item, which is currently playing or would be played with later play().

int getCurrentMediaItemIndex()

Gets the index of current media item in playlist.

long getCurrentPosition()

Gets the current playback position.

long getDuration()

Gets the duration of the current media item, or UNKNOWN_TIME if unknown.

float getMaxPlayerVolume()
int getNextMediaItemIndex()

Gets the next item index in the playlist.

PlaybackParams getPlaybackParams()

Gets the playback params, containing the current playback rate.

float getPlaybackSpeed()

Gets the actual playback speed to be used by the player when playing.

int getPlayerState()

Gets the current player state.

float getPlayerVolume()
List<MediaItem> getPlaylist()

Gets the playlist.

MediaMetadata getPlaylistMetadata()

Gets the playlist metadata.

int getPreviousMediaItemIndex()

Gets the previous item index in the playlist.

int getRepeatMode()

Gets the repeat mode.

MediaPlayer.TrackInfo getSelectedTrack(int trackType)

Returns the selected track for the given track type.

int getShuffleMode()

Gets the shuffle mode.

MediaTimestamp getTimestamp()

Gets current playback position as a MediaTimestamp.

List<MediaPlayer.TrackInfo> getTrackInfo()

This method is deprecated. Use getTracks() instead.

List<SessionPlayer.TrackInfo> getTracks()

Gets the full list of selected and unselected tracks that the media contains.

VideoSize getVideoSize()

Returns the size of the video.

ListenableFuture<SessionPlayer.PlayerResult> movePlaylistItem(int fromIndex, int toIndex)

Moves the media item at fromIdx to toIdx in the playlist.

ListenableFuture<SessionPlayer.PlayerResult> pause()

Pauses playback.

ListenableFuture<SessionPlayer.PlayerResult> play()

Starts or resumes playback.

ListenableFuture<SessionPlayer.PlayerResult> prepare()

Prepares the media items for playback.

void registerPlayerCallback(Executor executor, MediaPlayer.PlayerCallback callback)

Register MediaPlayer.PlayerCallback to listen changes.

ListenableFuture<SessionPlayer.PlayerResult> removePlaylistItem(int index)

Removes the media item from the playlist

On success, a SessionPlayer.PlayerResult would be returned with item removed.

ListenableFuture<SessionPlayer.PlayerResult> replacePlaylistItem(int index, MediaItem item)

Replaces the media item at index in the playlist.

void reset()

Resets MediaPlayer to its uninitialized state if not closed.

ListenableFuture<SessionPlayer.PlayerResult> seekTo(long position, int mode)

Moves the media to specified time position by considering the given mode.

ListenableFuture<SessionPlayer.PlayerResult> seekTo(long position)

Seeks to the specified position.

ListenableFuture<SessionPlayer.PlayerResult> selectTrack(SessionPlayer.TrackInfo trackInfo)

Selects the MediaPlayer.TrackInfo for the current media item.

ListenableFuture<SessionPlayer.PlayerResult> selectTrack(MediaPlayer.TrackInfo trackInfo)

This method is deprecated. Use selectTrack(SessionPlayer.TrackInfo) instead.

ListenableFuture<SessionPlayer.PlayerResult> setAudioAttributes(AudioAttributesCompat attributes)

Sets the AudioAttributesCompat to be used during the playback of the media.

ListenableFuture<SessionPlayer.PlayerResult> setAudioSessionId(int sessionId)

Sets the audio session ID.

ListenableFuture<SessionPlayer.PlayerResult> setAuxEffectSendLevel(float level)

Sets the send level of the player to the attached auxiliary effect.

ListenableFuture<SessionPlayer.PlayerResult> setMediaItem(MediaItem item)

Sets a MediaItem for playback.

ListenableFuture<SessionPlayer.PlayerResult> setPlaybackParams(PlaybackParams params)

Sets playback params using PlaybackParams.

ListenableFuture<SessionPlayer.PlayerResult> setPlaybackSpeed(float playbackSpeed)

Sets the playback speed.

ListenableFuture<SessionPlayer.PlayerResult> setPlayerVolume(float volume)

Sets the volume of the audio of the media to play, expressed as a linear multiplier on the audio samples.

ListenableFuture<SessionPlayer.PlayerResult> setPlaylist(List<MediaItem> list, MediaMetadata metadata)

Sets a list of MediaItem with metadata.

ListenableFuture<SessionPlayer.PlayerResult> setRepeatMode(int repeatMode)

Sets the repeat mode.

ListenableFuture<SessionPlayer.PlayerResult> setShuffleMode(int shuffleMode)

Sets the shuffle mode.

ListenableFuture<SessionPlayer.PlayerResult> setSurface(Surface surface)

Sets the Surface to be used as the sink for the video portion of the media.

ListenableFuture<SessionPlayer.PlayerResult> skipToNextPlaylistItem()

Skips to the next item in the playlist.

ListenableFuture<SessionPlayer.PlayerResult> skipToPlaylistItem(int index)

Skips to the item in the playlist at the index.

ListenableFuture<SessionPlayer.PlayerResult> skipToPreviousPlaylistItem()

Skips to the previous item in the playlist.

void unregisterPlayerCallback(MediaPlayer.PlayerCallback callback)

Unregister the previously registered MediaPlayer.PlayerCallback.

ListenableFuture<SessionPlayer.PlayerResult> updatePlaylistMetadata(MediaMetadata metadata)

Updates the playlist metadata while keeping the playlist as-is.

Inherited methods