MediaPlayer

public class MediaPlayer
extends Object implements AudioRouting, VolumeAutomation

MediaPlayer class can be used to control playback of audio/video files and streams.

MediaPlayer is not thread-safe. Creation of and all access to player instances should be on the same thread. If registering callbacks, the thread must have a Looper.

Topics covered here are:

1. State Diagram
2. Valid and Invalid States
3. Permissions
4. Register informational and error callbacks

State Diagram

Playback control of audio/video files and streams is managed as a state machine. The following diagram shows the life cycle and the states of a MediaPlayer object driven by the supported playback control operations. The ovals represent the states a MediaPlayer object may reside in. The arcs represent the playback control operations that drive the object state transition. There are two types of arcs. The arcs with a single arrow head represent synchronous method calls, while those with a double arrow head represent asynchronous method calls.

From this state diagram, one can see that a MediaPlayer object has the following states:

• When a MediaPlayer object is just created using new or after reset() is called, it is in the Idle state; and after release() is called, it is in the End state. Between these two states is the life cycle of the MediaPlayer object.
  • There is a subtle but important difference between a newly constructed MediaPlayer object and the MediaPlayer object after reset() is called. It is a programming error to invoke methods such as getCurrentPosition(), getDuration(), getVideoHeight(), getVideoWidth(), setAudioAttributes(AudioAttributes), setLooping(boolean), setVolume(float, float), pause(), start(), stop(), seekTo(long, int), prepare() or prepareAsync() in the Idle state for both cases. If any of these methods is called right after a MediaPlayer object is constructed, the user supplied callback method OnErrorListener.onError() won't be called by the internal player engine and the object state remains unchanged; but if these methods are called right after reset(), the user supplied callback method OnErrorListener.onError() will be invoked by the internal player engine and the object will be transfered to the Error state.
  • You must keep a reference to a MediaPlayer instance to prevent it from being garbage collected. If a MediaPlayer instance is garbage collected, release() will be called, causing any ongoing playback to stop.
  • You must call release() once you have finished using an instance to release acquired resources, such as memory and codecs. Once you have called release(), you must no longer interact with the released instance.
  • MediaPlayer objects created using new is in the Idle state, while those created with one of the overloaded convenient create methods are NOT in the Idle state. In fact, the objects are in the Prepared state if the creation using create method is successful.
• In general, some playback control operation may fail due to various reasons, such as unsupported audio/video format, poorly interleaved audio/video, resolution too high, streaming timeout, and the like. Thus, error reporting and recovery is an important concern under these circumstances. Sometimes, due to programming errors, invoking a playback control operation in an invalid state may also occur. Under all these error conditions, the internal player engine invokes a user supplied OnErrorListener.onError() method if an OnErrorListener has been registered beforehand via setOnErrorListener(android.media.MediaPlayer.OnErrorListener).
  • It is important to note that once an error occurs, the MediaPlayer object enters the Error state (except as noted above), even if an error listener has not been registered by the application.
  • In order to reuse a MediaPlayer object that is in the Error state and recover from the error, reset() can be called to restore the object to its Idle state.
  • It is good programming practice to have your application register a OnErrorListener to look out for error notifications from the internal player engine.
  • IllegalStateException is thrown to prevent programming errors such as calling prepare(), prepareAsync(), or one of the overloaded setDataSource methods in an invalid state.
• Calling setDataSource(FileDescriptor), or setDataSource(String), or setDataSource(Context,Uri), or setDataSource(FileDescriptor,long,long), or setDataSource(MediaDataSource) transfers a MediaPlayer object in the Idle state to the Initialized state.
  • An IllegalStateException is thrown if setDataSource() is called in any other state.
  • It is good programming practice to always look out for IllegalArgumentException and IOException that may be thrown from the overloaded setDataSource methods.
• A MediaPlayer object must first enter the Prepared state before playback can be started.
  • There are two ways (synchronous vs. asynchronous) that the Prepared state can be reached: either a call to prepare() (synchronous) which transfers the object to the Prepared state once the method call returns, or a call to prepareAsync() (asynchronous) which first transfers the object to the Preparing state after the call returns (which occurs almost right away) while the internal player engine continues working on the rest of preparation work until the preparation work completes. When the preparation completes or when prepare() call returns, the internal player engine then calls a user supplied callback method, onPrepared() of the OnPreparedListener interface, if an OnPreparedListener is registered beforehand via setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener).
  • It is important to note that the Preparing state is a transient state, and the behavior of calling any method with side effect while a MediaPlayer object is in the Preparing state is undefined.
  • An IllegalStateException is thrown if prepare() or prepareAsync() is called in any other state.
  • While in the Prepared state, properties such as audio/sound volume, screenOnWhilePlaying, looping can be adjusted by invoking the corresponding set methods.
• To start the playback, start() must be called. After start() returns successfully, the MediaPlayer object is in the Started state. isPlaying() can be called to test whether the MediaPlayer object is in the Started state.
  • While in the Started state, the internal player engine calls a user supplied OnBufferingUpdateListener.onBufferingUpdate() callback method if a OnBufferingUpdateListener has been registered beforehand via setOnBufferingUpdateListener(OnBufferingUpdateListener). This callback allows applications to keep track of the buffering status while streaming audio/video.
  • Calling start() has no effect on a MediaPlayer object that is already in the Started state.
• Playback can be paused and stopped, and the current playback position can be adjusted. Playback can be paused via pause(). When the call to pause() returns, the MediaPlayer object enters the Paused state. Note that the transition from the Started state to the Paused state and vice versa happens asynchronously in the player engine. It may take some time before the state is updated in calls to isPlaying(), and it can be a number of seconds in the case of streamed content.
  • Calling start() to resume playback for a paused MediaPlayer object, and the resumed playback position is the same as where it was paused. When the call to start() returns, the paused MediaPlayer object goes back to the Started state.
  • Calling pause() has no effect on a MediaPlayer object that is already in the Paused state.
• Calling stop() stops playback and causes a MediaPlayer in the Started, Paused, Prepared or PlaybackCompleted state to enter the Stopped state.
  • Once in the Stopped state, playback cannot be started until prepare() or prepareAsync() are called to set the MediaPlayer object to the Prepared state again.
  • Calling stop() has no effect on a MediaPlayer object that is already in the Stopped state.
• The playback position can be adjusted with a call to seekTo(long, int).
  • Although the asynchronuous seekTo(long, int) call returns right away, the actual seek operation may take a while to finish, especially for audio/video being streamed. When the actual seek operation completes, the internal player engine calls a user supplied OnSeekComplete.onSeekComplete() if an OnSeekCompleteListener has been registered beforehand via setOnSeekCompleteListener(OnSeekCompleteListener).
  • Please note that seekTo(long, int) can also be called in the other states, such as Prepared, Paused and PlaybackCompleted state. When seekTo(long, int) is called in those states, one video frame will be displayed if the stream has video and the requested position is valid.
  • Furthermore, the actual current playback position can be retrieved with a call to getCurrentPosition(), which is helpful for applications such as a Music player that need to keep track of the playback progress.
• When the playback reaches the end of stream, the playback completes.
  • If the looping mode was being set to true with setLooping(boolean), the MediaPlayer object shall remain in the Started state.
  • If the looping mode was set to false , the player engine calls a user supplied callback method, OnCompletion.onCompletion(), if a OnCompletionListener is registered beforehand via setOnCompletionListener(OnCompletionListener). The invoke of the callback signals that the object is now in the PlaybackCompleted state.
  • While in the PlaybackCompleted state, calling start() can restart the playback from the beginning of the audio/video source.

  Valid and invalid states

  Method Name	Valid States	Invalid States	Comments
  attachAuxEffect	{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Idle, Error}	This method must be called after setDataSource. Calling it does not change the object state.
  getAudioSessionId	any	{}	This method can be called in any state and calling it does not change the object state.
  getCurrentPosition	{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  getDuration	{Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Idle, Initialized, Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  getVideoHeight	{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  getVideoWidth	{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  isPlaying	{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  pause	{Started, Paused, PlaybackCompleted}	{Idle, Initialized, Prepared, Stopped, Error}	Successful invoke of this method in a valid state transfers the object to the Paused state. Calling this method in an invalid state transfers the object to the Error state.
  prepare	{Initialized, Stopped}	{Idle, Prepared, Started, Paused, PlaybackCompleted, Error}	Successful invoke of this method in a valid state transfers the object to the Prepared state. Calling this method in an invalid state throws an IllegalStateException.
  prepareAsync	{Initialized, Stopped}	{Idle, Prepared, Started, Paused, PlaybackCompleted, Error}	Successful invoke of this method in a valid state transfers the object to the Preparing state. Calling this method in an invalid state throws an IllegalStateException.
  release	any	{}	After release(), you must not interact with the object.
  reset	{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}	{}	After reset(), the object is like being just created.
  seekTo	{Prepared, Started, Paused, PlaybackCompleted}	{Idle, Initialized, Stopped, Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  setAudioAttributes	{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}	{Error}	Successful invoke of this method does not change the state. In order for the target audio attributes type to become effective, this method must be called before prepare() or prepareAsync().
  setAudioSessionId	{Idle}	{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}	This method must be called in idle state as the audio session ID must be known before calling setDataSource. Calling it does not change the object state.
  setAudioStreamType (deprecated)	{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}	{Error}	Successful invoke of this method does not change the state. In order for the target audio stream type to become effective, this method must be called before prepare() or prepareAsync().
  setAuxEffectSendLevel	any	{}	Calling this method does not change the object state.
  setDataSource	{Idle}	{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}	Successful invoke of this method in a valid state transfers the object to the Initialized state. Calling this method in an invalid state throws an IllegalStateException.
  setDisplay	any	{}	This method can be called in any state and calling it does not change the object state.
  setSurface	any	{}	This method can be called in any state and calling it does not change the object state.
  setVideoScalingMode	{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}	{Idle, Error}	Successful invoke of this method does not change the state.
  setLooping	{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}	{Error}	Successful invoke of this method in a valid state does not change the state. Calling this method in an invalid state transfers the object to the Error state.
  isLooping	any	{}	This method can be called in any state and calling it does not change the object state.
  setOnBufferingUpdateListener	any	{}	This method can be called in any state and calling it does not change the object state.
  setOnCompletionListener	any	{}	This method can be called in any state and calling it does not change the object state.
  setOnErrorListener	any	{}	This method can be called in any state and calling it does not change the object state.
  setOnPreparedListener	any	{}	This method can be called in any state and calling it does not change the object state.
  setOnSeekCompleteListener	any	{}	This method can be called in any state and calling it does not change the object state.
  setPlaybackParams	{Initialized, Prepared, Started, Paused, PlaybackCompleted, Error}	{Idle, Stopped}	This method will change state in some cases, depending on when it's called.
  setScreenOnWhilePlaying	any	{}	This method can be called in any state and calling it does not change the object state.
  setVolume	{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}	{Error}	Successful invoke of this method does not change the state.
  setWakeMode	any	{}	This method can be called in any state and calling it does not change the object state.
  start	{Prepared, Started, Paused, PlaybackCompleted}	{Idle, Initialized, Stopped, Error}	Successful invoke of this method in a valid state transfers the object to the Started state. Calling this method in an invalid state transfers the object to the Error state.
  stop	{Prepared, Started, Stopped, Paused, PlaybackCompleted}	{Idle, Initialized, Error}	Successful invoke of this method in a valid state transfers the object to the Stopped state. Calling this method in an invalid state transfers the object to the Error state.
  getTrackInfo	{Prepared, Started, Stopped, Paused, PlaybackCompleted}	{Idle, Initialized, Error}	Successful invoke of this method does not change the state.
  addTimedTextSource	{Prepared, Started, Stopped, Paused, PlaybackCompleted}	{Idle, Initialized, Error}	Successful invoke of this method does not change the state.
  selectTrack	{Prepared, Started, Stopped, Paused, PlaybackCompleted}	{Idle, Initialized, Error}	Successful invoke of this method does not change the state.
  deselectTrack	{Prepared, Started, Stopped, Paused, PlaybackCompleted}	{Idle, Initialized, Error}	Successful invoke of this method does not change the state.

  Permissions

  One may need to declare a corresponding WAKE_LOCK permission <uses-permission> element.

  This class requires the Manifest.permission.INTERNET permission when used with network-based content.

  Callbacks

  Applications may want to register for informational and error events in order to be informed of some internal state update and possible runtime errors during playback or streaming. Registration for these events is done by properly setting the appropriate listeners (via calls to setOnPreparedListener, setOnVideoSizeChangedListener, setOnSeekCompleteListener, setOnCompletionListener, setOnBufferingUpdateListener, setOnInfoListener, setOnErrorListener, etc). In order to receive the respective callback associated with these listeners, applications are required to create MediaPlayer objects on a thread with its own Looper running (main UI thread by default has a Looper running).

  Summary

  Nested classes
  class	MediaPlayer.DrmInfo Encapsulates the DRM properties of the source.
  class	MediaPlayer.MetricsConstants
  class	MediaPlayer.NoDrmSchemeException Thrown when a DRM method is called before preparing a DRM scheme through prepareDrm().
  interface	MediaPlayer.OnBufferingUpdateListener Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network.
  interface	MediaPlayer.OnCompletionListener Interface definition for a callback to be invoked when playback of a media source has completed.
  interface	MediaPlayer.OnDrmConfigHelper Interface definition of a callback to be invoked when the app can do DRM configuration (get/set properties) before the session is opened.
  interface	MediaPlayer.OnDrmInfoListener Interface definition of a callback to be invoked when the DRM info becomes available
  interface	MediaPlayer.OnDrmPreparedListener Interface definition of a callback to notify the app when the DRM is ready for key request/response
  interface	MediaPlayer.OnErrorListener Interface definition of a callback to be invoked when there has been an error during an asynchronous operation (other errors will throw exceptions at method call time).
  interface	MediaPlayer.OnInfoListener Interface definition of a callback to be invoked to communicate some info and/or warning about the media or its playback.
  interface	MediaPlayer.OnMediaTimeDiscontinuityListener Interface definition of a callback to be invoked when discontinuity in the normal progression of the media time is detected.
  interface	MediaPlayer.OnPreparedListener Interface definition for a callback to be invoked when the media source is ready for playback.
  interface	MediaPlayer.OnSeekCompleteListener Interface definition of a callback to be invoked indicating the completion of a seek operation.
  interface	MediaPlayer.OnSubtitleDataListener Interface definition of a callback to be invoked when a player subtitle track has new subtitle data available.
  interface	MediaPlayer.OnTimedMetaDataAvailableListener Interface definition of a callback to be invoked when a track has timed metadata available.
  interface	MediaPlayer.OnTimedTextListener Interface definition of a callback to be invoked when a timed text is available for display.
  interface	MediaPlayer.OnVideoSizeChangedListener Interface definition of a callback to be invoked when the video size is first known or updated
  class	MediaPlayer.ProvisioningNetworkErrorException Thrown when the device requires DRM provisioning but the provisioning attempt has failed due to a network error (Internet reachability, timeout, etc.).
  class	MediaPlayer.ProvisioningServerErrorException Thrown when the device requires DRM provisioning but the provisioning attempt has failed due to the provisioning server denying the request.
  class	MediaPlayer.TrackInfo Class for MediaPlayer to return each audio/video/subtitle track's metadata.

  Constants
  int	MEDIA_ERROR_IO File or network related operation errors.
  int	MEDIA_ERROR_MALFORMED Bitstream is not conforming to the related coding standard or file spec.
  int	MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK 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.
  int	MEDIA_ERROR_SERVER_DIED Media server died.
  int	MEDIA_ERROR_TIMED_OUT Some operation takes too long to complete, usually more than 3-5 seconds.
  int	MEDIA_ERROR_UNKNOWN Unspecified media player error.
  int	MEDIA_ERROR_UNSUPPORTED Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature.
  int	MEDIA_INFO_AUDIO_NOT_PLAYING Informs that audio is not playing.
  int	MEDIA_INFO_BAD_INTERLEAVING 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.
  int	MEDIA_INFO_BUFFERING_END MediaPlayer is resuming playback after filling buffers.
  int	MEDIA_INFO_BUFFERING_START MediaPlayer is temporarily pausing playback internally in order to buffer more data.
  int	MEDIA_INFO_METADATA_UPDATE A new set of metadata is available.
  int	MEDIA_INFO_NOT_SEEKABLE The media cannot be seeked (e.g live stream)
  int	MEDIA_INFO_STARTED_AS_NEXT The player was started because it was used as the next player for another player, which just completed playback.
  int	MEDIA_INFO_SUBTITLE_TIMED_OUT Reading the subtitle track takes too long.
  int	MEDIA_INFO_UNKNOWN Unspecified media player info.
  int	MEDIA_INFO_UNSUPPORTED_SUBTITLE Subtitle track was not supported by the media framework.
  int	MEDIA_INFO_VIDEO_NOT_PLAYING Informs that video is not playing.
  int	MEDIA_INFO_VIDEO_RENDERING_START The player just pushed the very first video frame for rendering.
  int	MEDIA_INFO_VIDEO_TRACK_LAGGING The video is too complex for the decoder: it can't decode frames fast enough.
  String	MEDIA_MIMETYPE_TEXT_SUBRIP This constant was deprecated in API level 28. use MediaFormat.MIMETYPE_TEXT_SUBRIP
  int	PREPARE_DRM_STATUS_PREPARATION_ERROR The DRM preparation has failed .
  int	PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR The device required DRM provisioning but couldn't reach the provisioning server.
  int	PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR The device required DRM provisioning but the provisioning server denied the request.
  int	PREPARE_DRM_STATUS_SUCCESS The status codes for OnDrmPreparedListener.onDrmPrepared listener.
  int	SEEK_CLOSEST This mode is used with seekTo(long, int) to move media position to a frame (not necessarily a key frame) associated with a data source that is located closest to or at the given time.
  int	SEEK_CLOSEST_SYNC This mode is used with seekTo(long, int) to move media position to a sync (or key) frame associated with a data source that is located closest to (in time) or at the given time.
  int	SEEK_NEXT_SYNC This mode is used with seekTo(long, int) to move media position to a sync (or key) frame associated with a data source that is located right after or at the given time.
  int	SEEK_PREVIOUS_SYNC This mode is used with seekTo(long, int) to move media position to a sync (or key) frame associated with a data source that is located right before or at the given time.
  int	VIDEO_SCALING_MODE_SCALE_TO_FIT Specifies a video scaling mode.
  int	VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING Specifies a video scaling mode.

  Public constructors
  MediaPlayer() Default constructor.
  MediaPlayer(Context context) Default constructor with context.

  Public methods
  void	addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener, Handler handler) Adds an AudioRouting.OnRoutingChangedListener to receive notifications of routing changes on this MediaPlayer.
  void	addTimedTextSource(FileDescriptor fd, String mimeType) Adds an external timed text source file (FileDescriptor).
  void	addTimedTextSource(String path, String mimeType) Adds an external timed text source file.
  void	addTimedTextSource(FileDescriptor fd, long offset, long length, String mime) Adds an external timed text file (FileDescriptor).
  void	addTimedTextSource(Context context, Uri uri, String mimeType) Adds an external timed text source file (Uri).
  void	attachAuxEffect(int effectId) Attaches an auxiliary effect to the player.
  void	clearOnMediaTimeDiscontinuityListener() Clears the listener previously set with setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener) or setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener,Handler)
  void	clearOnSubtitleDataListener() Clears the listener previously set with setOnSubtitleDataListener(OnSubtitleDataListener) or setOnSubtitleDataListener(OnSubtitleDataListener,Handler).
  static MediaPlayer	create(Context context, Uri uri, SurfaceHolder holder, AudioAttributes audioAttributes, int audioSessionId) Same factory method as create(Context,Uri,SurfaceHolder) but that lets you specify the audio attributes and session ID to be used by the new MediaPlayer instance.
  static MediaPlayer	create(Context context, int resid, AudioAttributes audioAttributes, int audioSessionId) Same factory method as create(Context,int) but that lets you specify the audio attributes and session ID to be used by the new MediaPlayer instance.
  static MediaPlayer	create(Context context, Uri uri, SurfaceHolder holder) Convenience method to create a MediaPlayer for a given Uri.
  static MediaPlayer	create(Context context, int resid) Convenience method to create a MediaPlayer for a given resource id.
  static MediaPlayer	create(Context context, Uri uri) Convenience method to create a MediaPlayer for a given Uri.
  VolumeShaper	createVolumeShaper(VolumeShaper.Configuration configuration) Returns a VolumeShaper object that can be used modify the volume envelope of the player or track.
  void	deselectTrack(int index) Deselect a track.
  int	getAudioSessionId() Returns the audio session ID.
  int	getCurrentPosition() Gets the current playback position.
  MediaPlayer.DrmInfo	getDrmInfo() Retrieves the DRM Info associated with the current source
  String	getDrmPropertyString(String propertyName) Read a DRM engine plugin String property value, given the property name string.
  int	getDuration() Gets the duration of the file.
  MediaDrm.KeyRequest	getKeyRequest(byte[] keySetId, byte[] initData, String mimeType, int keyType, Map<String, String> optionalParameters) A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.
  PersistableBundle	getMetrics() Return Metrics data about the current player.
  PlaybackParams	getPlaybackParams() Gets the playback params, containing the current playback rate.
  AudioDeviceInfo	getPreferredDevice() Returns the selected output specified by setPreferredDevice(AudioDeviceInfo).
  AudioDeviceInfo	getRoutedDevice() Returns an AudioDeviceInfo identifying the current routing of this MediaPlayer Note: The query is only valid if the MediaPlayer is currently playing.
  List<AudioDeviceInfo>	getRoutedDevices() Returns a List of AudioDeviceInfo identifying the current routing of this MediaPlayer.
  int	getSelectedTrack(int trackType) Returns the index of the audio, video, or subtitle track currently selected for playback, The return value is an index into the array returned by getTrackInfo(), and can be used in calls to selectTrack(int) or deselectTrack(int).
  SyncParams	getSyncParams() Gets the A/V sync mode.
  MediaTimestamp	getTimestamp() Get current playback position as a MediaTimestamp.
  TrackInfo[]	getTrackInfo() Returns an array of track information.
  int	getVideoHeight() Returns the height of the video.
  int	getVideoWidth() Returns the width of the video.
  boolean	isLooping() Checks whether the MediaPlayer is looping or non-looping.
  boolean	isPlaying() Checks whether the MediaPlayer is playing.
  void	pause() Pauses playback.
  void	prepare() Prepares the player for playback, synchronously.
  void	prepareAsync() Prepares the player for playback, asynchronously.
  void	prepareDrm(UUID uuid) Prepares the DRM for the current source If OnDrmConfigHelper is registered, it will be called during preparation to allow configuration of the DRM properties before opening the DRM session.
  byte[]	provideKeyResponse(byte[] keySetId, byte[] response) A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse.
  void	release() Releases resources associated with this MediaPlayer object.
  void	releaseDrm() Releases the DRM session The player has to have an active DRM session and be in stopped, or prepared state before this call is made.
  void	removeOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener) Removes an AudioRouting.OnRoutingChangedListener which has been previously added to receive rerouting notifications.
  void	reset() Resets the MediaPlayer to its uninitialized state.
  void	restoreKeys(byte[] keySetId) Restore persisted offline keys into a new session.
  void	seekTo(int msec) Seeks to specified time position.
  void	seekTo(long msec, int mode) Moves the media to specified time position by considering the given mode.
  void	selectTrack(int index) Selects a track.
  void	setAudioAttributes(AudioAttributes attributes) Sets the audio attributes for this MediaPlayer.
  void	setAudioSessionId(int sessionId) Sets the audio session ID.
  void	setAudioStreamType(int streamtype) This method was deprecated in API level 26. use setAudioAttributes(AudioAttributes)
  void	setAuxEffectSendLevel(float level) Sets the send level of the player to the attached auxiliary effect.
  void	setDataSource(AssetFileDescriptor afd) Sets the data source (AssetFileDescriptor) to use.
  void	setDataSource(FileDescriptor fd) Sets the data source (FileDescriptor) to use.
  void	setDataSource(FileDescriptor fd, long offset, long length) Sets the data source (FileDescriptor) to use.
  void	setDataSource(String path) Sets the data source (file-path or http/rtsp URL) to use.
  void	setDataSource(MediaDataSource dataSource) Sets the data source (MediaDataSource) to use.
  void	setDataSource(Context context, Uri uri, Map<String, String> headers, List<HttpCookie> cookies) Sets the data source as a content Uri.
  void	setDataSource(Context context, Uri uri, Map<String, String> headers) Sets the data source as a content Uri.
  void	setDataSource(Context context, Uri uri) Sets the data source as a content Uri.
  void	setDisplay(SurfaceHolder sh) Sets the SurfaceHolder to use for displaying the video portion of the media.
  void	setDrmPropertyString(String propertyName, String value) Set a DRM engine plugin String property value.
  void	setLooping(boolean looping) Sets the player to be looping or non-looping.
  void	setNextMediaPlayer(MediaPlayer next) Set the MediaPlayer to start when this MediaPlayer finishes playback (i.e.
  void	setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener listener) Register a callback to be invoked when the status of a network stream's buffer has changed.
  void	setOnCompletionListener(MediaPlayer.OnCompletionListener listener) Register a callback to be invoked when the end of a media source has been reached during playback.
  void	setOnDrmConfigHelper(MediaPlayer.OnDrmConfigHelper listener) Register a callback to be invoked for configuration of the DRM object before the session is created.
  void	setOnDrmInfoListener(MediaPlayer.OnDrmInfoListener listener) Register a callback to be invoked when the DRM info is known.
  void	setOnDrmInfoListener(MediaPlayer.OnDrmInfoListener listener, Handler handler) Register a callback to be invoked when the DRM info is known.
  void	setOnDrmPreparedListener(MediaPlayer.OnDrmPreparedListener listener, Handler handler) Register a callback to be invoked when the DRM object is prepared.
  void	setOnDrmPreparedListener(MediaPlayer.OnDrmPreparedListener listener) Register a callback to be invoked when the DRM object is prepared.
  void	setOnErrorListener(MediaPlayer.OnErrorListener listener) Register a callback to be invoked when an error has happened during an asynchronous operation.
  void	setOnInfoListener(MediaPlayer.OnInfoListener listener) Register a callback to be invoked when an info/warning is available.
  void	setOnMediaTimeDiscontinuityListener(MediaPlayer.OnMediaTimeDiscontinuityListener listener, Handler handler) Sets the listener to be invoked when a media time discontinuity is encountered.
  void	setOnMediaTimeDiscontinuityListener(MediaPlayer.OnMediaTimeDiscontinuityListener listener) Sets the listener to be invoked when a media time discontinuity is encountered.
  void	setOnPreparedListener(MediaPlayer.OnPreparedListener listener) Register a callback to be invoked when the media source is ready for playback.
  void	setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener listener) Register a callback to be invoked when a seek operation has been completed.
  void	setOnSubtitleDataListener(MediaPlayer.OnSubtitleDataListener listener) Sets the listener to be invoked when a subtitle track has new data available.
  void	setOnSubtitleDataListener(MediaPlayer.OnSubtitleDataListener listener, Handler handler) Sets the listener to be invoked when a subtitle track has new data available.
  void	setOnTimedMetaDataAvailableListener(MediaPlayer.OnTimedMetaDataAvailableListener listener) Register a callback to be invoked when a selected track has timed metadata available.
  void	setOnTimedTextListener(MediaPlayer.OnTimedTextListener listener) Register a callback to be invoked when a timed text is available for display.
  void	setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener) Register a callback to be invoked when the video size is known or updated.
  void	setPlaybackParams(PlaybackParams params) Sets playback rate using PlaybackParams.
  boolean	setPreferredDevice(AudioDeviceInfo deviceInfo) Specifies an audio device (via an AudioDeviceInfo object) to route the output from this MediaPlayer.
  void	setScreenOnWhilePlaying(boolean screenOn) Control whether we should use the attached SurfaceHolder to keep the screen on while video playback is occurring.
  void	setSurface(Surface surface) Sets the Surface to be used as the sink for the video portion of the media.
  void	setSyncParams(SyncParams params) Sets A/V sync mode.
  void	setVideoScalingMode(int mode) Sets video scaling mode.
  void	setVolume(float leftVolume, float rightVolume) Sets the volume on this player.
  void	setWakeMode(Context context, int mode) Set the low-level power management behavior for this MediaPlayer.
  void	start() Starts or resumes playback.
  void	stop() Stops playback after playback has been started or paused.

  Protected methods
  void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

  Inherited methods
  From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  From interface android.media.AudioRouting abstract void addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener, Handler handler) Adds an AudioRouting.OnRoutingChangedListener to receive notifications of routing changes on this AudioTrack/AudioRecord. abstract AudioDeviceInfo getPreferredDevice() Returns the selected output/input specified by setPreferredDevice(AudioDeviceInfo). abstract AudioDeviceInfo getRoutedDevice() Returns an AudioDeviceInfo identifying the current routing of this AudioTrack/AudioRecord. default List<AudioDeviceInfo> getRoutedDevices() Returns a List of AudioDeviceInfo identifying the current routing of this AudioTrack/AudioRecord. abstract void removeOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener) Removes an AudioRouting.OnRoutingChangedListener which has been previously added to receive rerouting notifications. abstract boolean setPreferredDevice(AudioDeviceInfo deviceInfo) Specifies an audio device (via an AudioDeviceInfo object) to route the output/input to/from.
  From interface android.media.VolumeAutomation abstract VolumeShaper createVolumeShaper(VolumeShaper.Configuration configuration) Returns a VolumeShaper object that can be used modify the volume envelope of the player or track.

  Constants

  MEDIA_ERROR_IO

  Added in API level 17

  public static final int MEDIA_ERROR_IO

  File or network related operation errors.

  Constant Value: -1004 (0xfffffc14)

  MEDIA_ERROR_MALFORMED

  Added in API level 17

  public static final int MEDIA_ERROR_MALFORMED

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

  Constant Value: -1007 (0xfffffc11)

  MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

  Added in API level 3

  public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

  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.

  See also:

  • MediaPlayer.OnErrorListener

  Constant Value: 200 (0x000000c8)

  MEDIA_ERROR_SERVER_DIED

  Added in API level 1

  public static final int MEDIA_ERROR_SERVER_DIED

  Media server died. In this case, the application must release the MediaPlayer object and instantiate a new one.

  See also:

  • MediaPlayer.OnErrorListener

  Constant Value: 100 (0x00000064)

  MEDIA_ERROR_TIMED_OUT

  Added in API level 17

  public static final int MEDIA_ERROR_TIMED_OUT

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

  Constant Value: -110 (0xffffff92)

  MEDIA_ERROR_UNKNOWN

  Added in API level 1

  public static final int MEDIA_ERROR_UNKNOWN

  Unspecified media player error.

  See also:

  • MediaPlayer.OnErrorListener

  Constant Value: 1 (0x00000001)

  MEDIA_ERROR_UNSUPPORTED

  Added in API level 17

  public static final int MEDIA_ERROR_UNSUPPORTED

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

  Constant Value: -1010 (0xfffffc0e)

  MEDIA_INFO_AUDIO_NOT_PLAYING

  Added in API level 26

  public static final int MEDIA_INFO_AUDIO_NOT_PLAYING

  Informs that audio is not playing. Note that playback of the video is not interrupted.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 804 (0x00000324)

  MEDIA_INFO_BAD_INTERLEAVING

  Added in API level 3

  public static final int MEDIA_INFO_BAD_INTERLEAVING

  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. Video is playing but a lot of disk seeks may be happening.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 800 (0x00000320)

  MEDIA_INFO_BUFFERING_END

  Added in API level 9

  public static final int MEDIA_INFO_BUFFERING_END

  MediaPlayer is resuming playback after filling buffers.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 702 (0x000002be)

  MEDIA_INFO_BUFFERING_START

  Added in API level 9

  public static final int MEDIA_INFO_BUFFERING_START

  MediaPlayer is temporarily pausing playback internally in order to buffer more data.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 701 (0x000002bd)

  MEDIA_INFO_METADATA_UPDATE

  Added in API level 5

  public static final int MEDIA_INFO_METADATA_UPDATE

  A new set of metadata is available.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 802 (0x00000322)

  MEDIA_INFO_NOT_SEEKABLE

  Added in API level 3

  public static final int MEDIA_INFO_NOT_SEEKABLE

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

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 801 (0x00000321)

  MEDIA_INFO_STARTED_AS_NEXT

  Added in API level 28

  public static final int MEDIA_INFO_STARTED_AS_NEXT

  The player was started because it was used as the next player for another player, which just completed playback.

  See also:

  • android.media.MediaPlayer.setNextMediaPlayer(MediaPlayer)
  • MediaPlayer.OnInfoListener

  Constant Value: 2 (0x00000002)

  MEDIA_INFO_SUBTITLE_TIMED_OUT

  Added in API level 19

  public static final int MEDIA_INFO_SUBTITLE_TIMED_OUT

  Reading the subtitle track takes too long.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 902 (0x00000386)

  MEDIA_INFO_UNKNOWN

  Added in API level 3

  public static final int MEDIA_INFO_UNKNOWN

  Unspecified media player info.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 1 (0x00000001)

  MEDIA_INFO_UNSUPPORTED_SUBTITLE

  Added in API level 19

  public static final int MEDIA_INFO_UNSUPPORTED_SUBTITLE

  Subtitle track was not supported by the media framework.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 901 (0x00000385)

  MEDIA_INFO_VIDEO_NOT_PLAYING

  Added in API level 26

  public static final int MEDIA_INFO_VIDEO_NOT_PLAYING

  Informs that video is not playing. Note that playback of the audio is not interrupted.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 805 (0x00000325)

  MEDIA_INFO_VIDEO_RENDERING_START

  Added in API level 17

  public static final int MEDIA_INFO_VIDEO_RENDERING_START

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

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 3 (0x00000003)

  MEDIA_INFO_VIDEO_TRACK_LAGGING

  Added in API level 3

  public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING

  The video is too complex for the decoder: it can't decode frames fast enough. Possibly only the audio plays fine at this stage.

  See also:

  • MediaPlayer.OnInfoListener

  Constant Value: 700 (0x000002bc)

  MEDIA_MIMETYPE_TEXT_SUBRIP

  Added in API level 16
  Deprecated in API level 28

  public static final String MEDIA_MIMETYPE_TEXT_SUBRIP

  This constant was deprecated in API level 28.
  use MediaFormat.MIMETYPE_TEXT_SUBRIP

  MIME type for SubRip (SRT) container. Used in addTimedTextSource APIs.

  Constant Value: "application/x-subrip"

  PREPARE_DRM_STATUS_PREPARATION_ERROR

  Added in API level 26

  public static final int PREPARE_DRM_STATUS_PREPARATION_ERROR

  The DRM preparation has failed .

  Constant Value: 3 (0x00000003)

  PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR

  Added in API level 26

  public static final int PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR

  The device required DRM provisioning but couldn't reach the provisioning server.

  Constant Value: 1 (0x00000001)

  PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR

  Added in API level 26

  public static final int PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR

  The device required DRM provisioning but the provisioning server denied the request.

  Constant Value: 2 (0x00000002)

  PREPARE_DRM_STATUS_SUCCESS

  Added in API level 26

  public static final int PREPARE_DRM_STATUS_SUCCESS

  The status codes for OnDrmPreparedListener.onDrmPrepared listener.

  DRM preparation has succeeded.

  Constant Value: 0 (0x00000000)

  SEEK_CLOSEST

  Added in API level 26

  public static final int SEEK_CLOSEST

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

  See also:

  • seekTo(long, int)

  Constant Value: 3 (0x00000003)

  SEEK_CLOSEST_SYNC

  Added in API level 26

  public static final int SEEK_CLOSEST_SYNC

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

  See also:

  • seekTo(long, int)

  Constant Value: 2 (0x00000002)

  SEEK_NEXT_SYNC

  Added in API level 26

  public static final int SEEK_NEXT_SYNC

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

  See also:

  • seekTo(long, int)

  Constant Value: 1 (0x00000001)

  SEEK_PREVIOUS_SYNC

  Added in API level 26

  public static final int SEEK_PREVIOUS_SYNC

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

  See also:

  • seekTo(long, int)

  Constant Value: 0 (0x00000000)

  VIDEO_SCALING_MODE_SCALE_TO_FIT

  Added in API level 16

  public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT

  Specifies a video scaling mode. The content is stretched to the surface rendering area. When the surface has the same aspect ratio as the content, the aspect ratio of the content is maintained; otherwise, the aspect ratio of the content is not maintained when video is being rendered. Unlike VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING, there is no content cropping with this video scaling mode.

  Constant Value: 1 (0x00000001)

  VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING

  Added in API level 16

  public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING

  Specifies a video scaling mode. The content is scaled, maintaining its aspect ratio. The whole surface area is always used. When the aspect ratio of the content is the same as the surface, no content is cropped; otherwise, content is cropped to fit the surface.

  Constant Value: 2 (0x00000002)

  Public constructors

  MediaPlayer

  Added in API level 1

  public MediaPlayer ()

  Default constructor.

  Consider using one of the create() methods for synchronously instantiating a MediaPlayer from a Uri or resource.

  You must call release() when you are finished using the instantiated instance. Doing so frees any resources you have previously acquired.

  MediaPlayer

  Added in API level 34

  public MediaPlayer (Context context)

  Default constructor with context.

  Consider using one of the create() methods for synchronously instantiating a MediaPlayer from a Uri or resource.

  Parameters
  context	Context: non-null context. This context will be used to pull information, such as AttributionSource and device specific session ids, which will be associated with the MediaPlayer. However, the context itself will not be retained by the MediaPlayer.

  Public methods

  addOnRoutingChangedListener

  Added in API level 28

  public void addOnRoutingChangedListener (AudioRouting.OnRoutingChangedListener listener, 
                  Handler handler)

  Adds an AudioRouting.OnRoutingChangedListener to receive notifications of routing changes on this MediaPlayer.

  Parameters
  listener	AudioRouting.OnRoutingChangedListener: The AudioRouting.OnRoutingChangedListener interface to receive notifications of rerouting events.
  handler	Handler: Specifies the Handler object for the thread on which to execute the callback. If null, the handler on the main looper will be used.

  addTimedTextSource

  Added in API level 16

  public void addTimedTextSource (FileDescriptor fd, 
                  String mimeType)

  Adds an external timed text source file (FileDescriptor). It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns. Currently supported format is SubRip. Note that a single external timed text source may contain multiple tracks in it. One can find the total number of available tracks using getTrackInfo() to see what additional tracks become available after this method call.

  Parameters
  fd	FileDescriptor: the FileDescriptor for the file you want to play
  mimeType	String: The mime type of the file. Must be one of the mime types listed above.

  Throws
  IllegalArgumentException	if the mimeType is not supported.
  IllegalStateException	if called in an invalid state.

  addTimedTextSource

  Added in API level 16

  public void addTimedTextSource (String path, 
                  String mimeType)

  Adds an external timed text source file. Currently supported format is SubRip with the file extension .srt, case insensitive. Note that a single external timed text source may contain multiple tracks in it. One can find the total number of available tracks using getTrackInfo() to see what additional tracks become available after this method call.

  Parameters
  path	String: The file path of external timed text source file.
  mimeType	String: The mime type of the file. Must be one of the mime types listed above.

  Throws
  IOException	if the file cannot be accessed or is corrupted.
  IllegalArgumentException	if the mimeType is not supported.
  IllegalStateException	if called in an invalid state.

  addTimedTextSource

  Added in API level 16

  public void addTimedTextSource (FileDescriptor fd, 
                  long offset, 
                  long length, 
                  String mime)

  Adds an external timed text file (FileDescriptor). It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns. Currently supported format is SubRip. Note that a single external timed text source may contain multiple tracks in it. One can find the total number of available tracks using getTrackInfo() to see what additional tracks become available after this method call.

  Parameters
  fd	FileDescriptor: the FileDescriptor for the file you want to play
  offset	long: the offset into the file where the data to be played starts, in bytes
  length	long: the length in bytes of the data to be played
  mime	String: The mime type of the file. Must be one of the mime types listed above.

  Throws
  IllegalArgumentException	if the mimeType is not supported.
  IllegalStateException	if called in an invalid state.

  addTimedTextSource

  Added in API level 16

  public void addTimedTextSource (Context context, 
                  Uri uri, 
                  String mimeType)

  Adds an external timed text source file (Uri). Currently supported format is SubRip with the file extension .srt, case insensitive. Note that a single external timed text source may contain multiple tracks in it. One can find the total number of available tracks using getTrackInfo() to see what additional tracks become available after this method call.

  Parameters
  context	Context: the Context to use when resolving the Uri
  uri	Uri: the Content URI of the data you want to play
  mimeType	String: The mime type of the file. Must be one of the mime types listed above.

  Throws
  IOException	if the file cannot be accessed or is corrupted.
  IllegalArgumentException	if the mimeType is not supported.
  IllegalStateException	if called in an invalid state.

  attachAuxEffect

  Added in API level 9

  public void attachAuxEffect (int effectId)

  Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation effect which can be applied on any sound source that directs a certain amount of its energy to this effect. This amount is defined by setAuxEffectSendLevel(). See setAuxEffectSendLevel(float).

  After creating an auxiliary effect (e.g. EnvironmentalReverb), retrieve its ID with AudioEffect.getId() and use it when calling this method to attach the player to the effect.

  To detach the effect from the player, call this method with a null effect id.

  This method must be called after one of the overloaded setDataSource methods.

  Parameters
  effectId	int: system wide unique id of the effect to attach

  clearOnMediaTimeDiscontinuityListener

  Added in API level 28

  public void clearOnMediaTimeDiscontinuityListener ()

  Clears the listener previously set with setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener) or setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener,Handler)

  clearOnSubtitleDataListener

  Added in API level 28

  public void clearOnSubtitleDataListener ()

  Clears the listener previously set with setOnSubtitleDataListener(OnSubtitleDataListener) or setOnSubtitleDataListener(OnSubtitleDataListener,Handler).

  create

  Added in API level 21

  public static MediaPlayer create (Context context, 
                  Uri uri, 
                  SurfaceHolder holder, 
                  AudioAttributes audioAttributes, 
                  int audioSessionId)

  Same factory method as create(Context,Uri,SurfaceHolder) but that lets you specify the audio attributes and session ID to be used by the new MediaPlayer instance.

  Parameters
  context	Context: the Context to use
  uri	Uri: the Uri from which to get the datasource
  holder	SurfaceHolder: the SurfaceHolder to use for displaying the video, may be null.
  audioAttributes	AudioAttributes: the AudioAttributes to be used by the media player.
  audioSessionId	int: the audio session ID to be used by the media player, see AudioManager.generateAudioSessionId() to obtain a new session.

  Returns
  MediaPlayer	a MediaPlayer object, or null if creation failed

  create

  Added in API level 21

  public static MediaPlayer create (Context context, 
                  int resid, 
                  AudioAttributes audioAttributes, 
                  int audioSessionId)

  Same factory method as create(Context,int) but that lets you specify the audio attributes and session ID to be used by the new MediaPlayer instance.

  Parameters
  context	Context: the Context to use
  resid	int: the raw resource id (R.raw.<something>) for the resource to use as the datasource
  audioAttributes	AudioAttributes: the AudioAttributes to be used by the media player.
  audioSessionId	int: the audio session ID to be used by the media player, see AudioManager.generateAudioSessionId() to obtain a new session.

  Returns
  MediaPlayer	a MediaPlayer object, or null if creation failed

  create

  Added in API level 1

  public static MediaPlayer create (Context context, 
                  Uri uri, 
                  SurfaceHolder holder)

  Convenience method to create a MediaPlayer for a given Uri. On success, prepare() will already have been called and must not be called again.

  You must call release() when you are finished using the created instance. Doing so frees any resources you have previously acquired.

  Note that since prepare() is called automatically in this method, you cannot change the audio session ID (see setAudioSessionId(int)) or audio attributes (see setAudioAttributes(AudioAttributes) of the new MediaPlayer.

  Parameters
  context	Context: the Context to use
  uri	Uri: the Uri from which to get the datasource
  holder	SurfaceHolder: the SurfaceHolder to use for displaying the video

  Returns
  MediaPlayer	a MediaPlayer object, or null if creation failed

  create

  Added in API level 1

  public static MediaPlayer create (Context context, 
                  int resid)

  Convenience method to create a MediaPlayer for a given resource id. On success, prepare() will already have been called and must not be called again.

  You must call release() when you are finished using the created instance. Doing so frees any resources you have previously acquired.

  Note that since prepare() is called automatically in this method, you cannot change the audio session ID (see setAudioSessionId(int)) or audio attributes (see setAudioAttributes(AudioAttributes) of the new MediaPlayer.

  Parameters
  context	Context: the Context to use
  resid	int: the raw resource id (R.raw.<something>) for the resource to use as the datasource

  Returns
  MediaPlayer	a MediaPlayer object, or null if creation failed

  create

  Added in API level 1

  public static MediaPlayer create (Context context, 
                  Uri uri)

  Convenience method to create a MediaPlayer for a given Uri. On success, prepare() will already have been called and must not be called again.

  You must call release() when you are finished using the created instance. Doing so frees any resources you have previously acquired.

  Note that since prepare() is called automatically in this method, you cannot change the audio session ID (see setAudioSessionId(int)) or audio attributes (see setAudioAttributes(AudioAttributes) of the new MediaPlayer.

  Parameters
  context	Context: the Context to use
  uri	Uri: the Uri from which to get the datasource

  Returns
  MediaPlayer	a MediaPlayer object, or null if creation failed

  createVolumeShaper

  Added in API level 26

  public VolumeShaper createVolumeShaper (VolumeShaper.Configuration configuration)

  Returns a VolumeShaper object that can be used modify the volume envelope of the player or track.

  Parameters
  configuration	VolumeShaper.Configuration: This value cannot be null.

  Returns
  VolumeShaper	This value cannot be null.

  deselectTrack

  Added in API level 16

  public void deselectTrack (int index)

  Deselect a track.

  Currently, the track must be a timed text track and no audio or video tracks can be deselected. If the timed text track identified by index has not been selected before, it throws an exception.

  Parameters
  index	int: the index of the track to be deselected. The valid range of the index is 0..total number of tracks - 1. The total number of tracks as well as the type of each individual track can be found by calling getTrackInfo() method.

  Throws
  IllegalStateException	if called in an invalid state.

  See also:

  • getTrackInfo()

  getAudioSessionId

  Added in API level 9

  public int getAudioSessionId ()

  Returns the audio session ID.

  Returns
  int	the audio session ID. Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed.

  See also:

  • setAudioSessionId(int)

  getCurrentPosition

  Added in API level 1

  public int getCurrentPosition ()

  Gets the current playback position.

  Returns
  int	the current position in milliseconds

  getDrmInfo

  Added in API level 26

  public MediaPlayer.DrmInfo getDrmInfo ()

  Retrieves the DRM Info associated with the current source

  Returns
  MediaPlayer.DrmInfo

  Throws
  IllegalStateException	if called before prepare()

  getDrmPropertyString

  Added in API level 26

  public String getDrmPropertyString (String propertyName)

  Read a DRM engine plugin String property value, given the property name string.

  Parameters
  propertyName	String: the property name Standard fields names are: MediaDrm.PROPERTY_VENDOR, MediaDrm.PROPERTY_VERSION, MediaDrm.PROPERTY_DESCRIPTION, MediaDrm.PROPERTY_ALGORITHMS This value cannot be null. Value is one of the following: MediaDrm.PROPERTY_VENDOR MediaDrm.PROPERTY_VERSION MediaDrm.PROPERTY_DESCRIPTION MediaDrm.PROPERTY_ALGORITHMS

  Returns
  String	This value cannot be null.

  Throws
  MediaPlayer.NoDrmSchemeException

  getDuration

  Added in API level 1

  public int getDuration ()

  Gets the duration of the file.

  Returns
  int	the duration in milliseconds, if no duration is available (for example, if streaming live content), -1 is returned.

  getKeyRequest

  Added in API level 26

  public MediaDrm.KeyRequest getKeyRequest (byte[] keySetId, 
                  byte[] initData, 
                  String mimeType, 
                  int keyType, 
                  Map<String, String> optionalParameters)

  A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.

  getKeyRequest() is used to obtain an opaque key request byte array that is delivered to the license server. The opaque key request byte array is returned in KeyRequest.data. The recommended URL to deliver the key request to is returned in KeyRequest.defaultUrl.

  After the app has received the key request response from the server, it should deliver to the response to the DRM engine plugin using the method provideKeyResponse(byte, byte).

  Parameters
  keySetId	byte: is the key-set identifier of the offline keys being released when keyType is MediaDrm.KEY_TYPE_RELEASE. It should be set to null for other key requests, when keyType is MediaDrm.KEY_TYPE_STREAMING or MediaDrm.KEY_TYPE_OFFLINE.
  initData	byte: is the container-specific initialization data when the keyType is MediaDrm.KEY_TYPE_STREAMING or MediaDrm.KEY_TYPE_OFFLINE. Its meaning is interpreted based on the mime type provided in the mimeType parameter. It could contain, for example, the content ID, key ID or other data obtained from the content metadata that is required in generating the key request. When the keyType is MediaDrm.KEY_TYPE_RELEASE, it should be set to null.
  mimeType	String: identifies the mime type of the content. This value may be null.
  keyType	int: specifies the type of the request. The request may be to acquire keys for streaming, MediaDrm.KEY_TYPE_STREAMING, or for offline content MediaDrm.KEY_TYPE_OFFLINE, or to release previously acquired keys (MediaDrm.KEY_TYPE_RELEASE), which are identified by a keySetId. Value is one of the following: MediaDrm.KEY_TYPE_STREAMING MediaDrm.KEY_TYPE_OFFLINE MediaDrm.KEY_TYPE_RELEASE
  optionalParameters	Map: are included in the key request message to allow a client application to provide additional message parameters to the server. This may be null if no additional parameters are to be sent.

  Returns
  MediaDrm.KeyRequest	This value cannot be null.

  Throws
  MediaPlayer.NoDrmSchemeException	if there is no active DRM session

  getMetrics

  Added in API level 26

  public PersistableBundle getMetrics ()

  Return Metrics data about the current player.

  Returns
  PersistableBundle	a PersistableBundle containing the set of attributes and values available for the media being handled by this instance of MediaPlayer The attributes are descibed in MetricsConstants. Additional vendor-specific fields may also be present in the return value.

  getPlaybackParams

  Added in API level 23

  public PlaybackParams getPlaybackParams ()

  Gets the playback params, containing the current playback rate.

  Returns
  PlaybackParams	the playback params. This value cannot be null.

  Throws
  IllegalStateException	if the internal player engine has not been initialized.

  getPreferredDevice

  Added in API level 28

  public AudioDeviceInfo getPreferredDevice ()

  Returns the selected output specified by setPreferredDevice(AudioDeviceInfo). Note that this is not guaranteed to correspond to the actual device being used for playback.

  Returns
  AudioDeviceInfo

  getRoutedDevice

  Added in API level 28

  public AudioDeviceInfo getRoutedDevice ()

  Returns an AudioDeviceInfo identifying the current routing of this MediaPlayer Note: The query is only valid if the MediaPlayer is currently playing. If the player is not playing, the returned device can be null or correspond to previously selected device when the player was last active. Audio may play on multiple devices simultaneously (e.g. an alarm playing on headphones and speaker on a phone), so prefer using getRoutedDevices().

  Returns
  AudioDeviceInfo

  getRoutedDevices

  Added in API level 36

  public List<AudioDeviceInfo> getRoutedDevices ()

  Returns a List of AudioDeviceInfo identifying the current routing of this MediaPlayer. Note: The query is only valid if the MediaPlayer is currently playing. If the player is not playing, the returned devices can be empty or correspond to previously selected devices when the player was last active.

  Returns
  List<AudioDeviceInfo>	This value cannot be null.

  getSelectedTrack

  Added in API level 21

  public int getSelectedTrack (int trackType)

  Returns the index of the audio, video, or subtitle track currently selected for playback, The return value is an index into the array returned by getTrackInfo(), and can be used in calls to selectTrack(int) or deselectTrack(int).

  Parameters
  trackType	int: should be one of TrackInfo.MEDIA_TRACK_TYPE_VIDEO, TrackInfo.MEDIA_TRACK_TYPE_AUDIO, or TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE

  Returns
  int	index of the audio, video, or subtitle track currently selected for playback; a negative integer is returned when there is no selected track for trackType or when trackType is not one of audio, video, or subtitle.

  Throws
  IllegalStateException	if called after release()

  See also:

  • getTrackInfo()
  • selectTrack(int)
  • deselectTrack(int)

  getSyncParams

  Added in API level 23

  public SyncParams getSyncParams ()

  Gets the A/V sync mode.

  Returns
  SyncParams	the A/V sync params. This value cannot be null.

  Throws
  IllegalStateException	if the internal player engine has not been initialized.

  getTimestamp

  Added in API level 23

  public MediaTimestamp getTimestamp ()

  Get current playback position as a MediaTimestamp.

  The MediaTimestamp represents how the media time correlates to the system time in a linear fashion using an anchor and a clock rate. During regular playback, the media time moves fairly constantly (though the anchor frame may be rebased to a current system time, the linear correlation stays steady). Therefore, this method does not need to be called often.

  To help users get current playback position, this method always anchors the timestamp to the current system time, so MediaTimestamp.getAnchorMediaTimeUs can be used as current playback position.

  Returns
  MediaTimestamp	a MediaTimestamp object if a timestamp is available, or null if no timestamp is available, e.g. because the media player has not been initialized.

  See also:

  • MediaTimestamp

  getTrackInfo

  Added in API level 16

  public TrackInfo[] getTrackInfo ()

  Returns an array of track information.

  Returns
  TrackInfo[]	Array of track info. The total number of tracks is the array length. Must be called again if an external timed text source has been added after any of the addTimedTextSource methods are called.

  Throws
  IllegalStateException	if it is called in an invalid state.

  getVideoHeight

  Added in API level 1

  public int getVideoHeight ()

  Returns the height of the video.

  Returns
  int	the height of the video, or 0 if there is no video, no display surface was set, or the height has not been determined yet. The OnVideoSizeChangedListener can be registered via setOnVideoSizeChangedListener(OnVideoSizeChangedListener) to provide a notification when the height is available.

  getVideoWidth

  Added in API level 1

  public int getVideoWidth ()

  Returns the width of the video.

  Returns
  int	the width of the video, or 0 if there is no video, no display surface was set, or the width has not been determined yet. The OnVideoSizeChangedListener can be registered via setOnVideoSizeChangedListener(OnVideoSizeChangedListener) to provide a notification when the width is available.

  isLooping

  Added in API level 3

  public boolean isLooping ()

  Checks whether the MediaPlayer is looping or non-looping.

  Returns
  boolean	true if the MediaPlayer is currently looping, false otherwise

  isPlaying

  Added in API level 1

  public boolean isPlaying ()

  Checks whether the MediaPlayer is playing.

  Returns
  boolean	true if currently playing, false otherwise

  Throws
  IllegalStateException	if the internal player engine has not been initialized or has been released.

  pause

  Added in API level 1

  public void pause ()

  Pauses playback. Call start() to resume.

  Throws
  IllegalStateException	if the internal player engine has not been initialized.

  prepare

  Added in API level 1

  public void prepare ()

  Prepares the player for playback, synchronously. After setting the datasource and the display surface, you need to either call prepare() or prepareAsync(). For files, it is OK to call prepare(), which blocks until MediaPlayer is ready for playback.

  Throws
  IllegalStateException	if it is called in an invalid state
  IOException

  prepareAsync

  Added in API level 1

  public void prepareAsync ()

  Prepares the player for playback, asynchronously. After setting the datasource and the display surface, you need to either call prepare() or prepareAsync(). For streams, you should call prepareAsync(), which returns immediately, rather than blocking until enough data has been buffered.

  Throws
  IllegalStateException	if it is called in an invalid state

  prepareDrm

  Added in API level 26

  public void prepareDrm (UUID uuid)

  Prepares the DRM for the current source

  If OnDrmConfigHelper is registered, it will be called during preparation to allow configuration of the DRM properties before opening the DRM session. Note that the callback is called synchronously in the thread that called prepareDrm. It should be used only for a series of getDrmPropertyString and setDrmPropertyString calls and refrain from any lengthy operation.

  If the device has not been provisioned before, this call also provisions the device which involves accessing the provisioning server and can take a variable time to complete depending on the network connectivity. If OnDrmPreparedListener is registered, prepareDrm() runs in non-blocking mode by launching the provisioning in the background and returning. The listener will be called when provisioning and preparation has finished. If a OnDrmPreparedListener is not registered, prepareDrm() waits till provisioning and preparation has finished, i.e., runs in blocking mode.

  If OnDrmPreparedListener is registered, it is called to indicate the DRM session being ready. The application should not make any assumption about its call sequence (e.g., before or after prepareDrm returns), or the thread context that will execute the listener (unless the listener is registered with a handler thread).

  Parameters
  uuid	UUID: The UUID of the crypto scheme. If not known beforehand, it can be retrieved from the source through getDrmInfo or registering a onDrmInfoListener. This value cannot be null.

  Throws
  MediaPlayer.ProvisioningNetworkErrorException	if provisioning is required but failed due to a network error
  MediaPlayer.ProvisioningServerErrorException	if provisioning is required but failed due to the request denied by the provisioning server
  ResourceBusyException	if required DRM resources are in use
  UnsupportedSchemeException	if the crypto scheme is not supported
  IllegalStateException	if called before prepare(), or the DRM was prepared already

  provideKeyResponse

  Added in API level 26

  public byte[] provideKeyResponse (byte[] keySetId, 
                  byte[] response)

  A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse. When the response is for an offline key request, a key-set identifier is returned that can be used to later restore the keys to a new session with the method restoreKeys(byte). When the response is for a streaming or release request, null is returned.

  Parameters
  keySetId	byte: When the response is for a release request, keySetId identifies the saved key associated with the release request (i.e., the same keySetId passed to the earlier getKeyRequest(byte, byte, String, int, Map) call. It MUST be null when the response is for either streaming or offline key requests.
  response	byte: the byte array response from the server. This value cannot be null.

  Returns
  byte[]

  Throws
  DeniedByServerException	if the response indicates that the server rejected the request
  MediaPlayer.NoDrmSchemeException	if there is no active DRM session

  release

  Added in API level 1

  public void release ()

  Releases resources associated with this MediaPlayer object.

  You must call this method once the instance is no longer required.

  releaseDrm

  Added in API level 26

  public void releaseDrm ()

  Releases the DRM session

  The player has to have an active DRM session and be in stopped, or prepared state before this call is made. A reset() call will release the DRM session implicitly.

  Throws
  MediaPlayer.NoDrmSchemeException	if there is no active DRM session to release

  removeOnRoutingChangedListener

  Added in API level 28

  public void removeOnRoutingChangedListener (AudioRouting.OnRoutingChangedListener listener)

  Removes an AudioRouting.OnRoutingChangedListener which has been previously added to receive rerouting notifications.

  Parameters
  listener	AudioRouting.OnRoutingChangedListener: The previously added AudioRouting.OnRoutingChangedListener interface to remove.

  reset

  Added in API level 1

  public void reset ()

  Resets the MediaPlayer to its uninitialized state. After calling this method, you will have to initialize it again by setting the data source and calling prepare().

  restoreKeys

  Added in API level 26

  public void restoreKeys (byte[] keySetId)

  Restore persisted offline keys into a new session. keySetId identifies the keys to load, obtained from a prior call to provideKeyResponse(byte, byte).

  Parameters
  keySetId	byte: identifies the saved key set to restore. This value cannot be null.

  Throws
  MediaPlayer.NoDrmSchemeException

  seekTo

  Added in API level 1

  public void seekTo (int msec)

  Seeks to specified time position. Same as seekTo(long, int) with mode = SEEK_PREVIOUS_SYNC.

  Parameters
  msec	int: the offset in milliseconds from the start to seek to

  Throws
  IllegalStateException	if the internal player engine has not been initialized

  seekTo

  Added in API level 26

  public void seekTo (long msec, 
                  int mode)

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

  When seekTo is finished, the user will be notified via OnSeekComplete supplied by the user. There is at most one active seekTo processed at any time. If there is a to-be-completed seekTo, new seekTo requests will be queued in such a way that only the last request is kept. When current seekTo is completed, the queued request will be processed if that request is different from just-finished seekTo operation, i.e., the requested position or mode is different.

  Parameters
  msec	long: the offset in milliseconds from the start to seek to. When seeking to the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be rendered. If msec is negative, time position zero will be used. If msec is larger than duration, duration will be used.
  mode	int: the mode indicating where exactly to seek to. Use SEEK_PREVIOUS_SYNC if one wants to seek to a sync frame that has a timestamp earlier than or the same as msec. Use SEEK_NEXT_SYNC if one wants to seek to a sync frame that has a timestamp later than or the same as msec. Use SEEK_CLOSEST_SYNC if one wants to seek to a sync frame that has a timestamp closest to or the same as msec. Use SEEK_CLOSEST if one wants to seek to a frame that may or may not be a sync frame but is closest to or the same as msec. SEEK_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at msec. Value is one of the following: SEEK_PREVIOUS_SYNC SEEK_NEXT_SYNC SEEK_CLOSEST_SYNC SEEK_CLOSEST

  Throws
  IllegalArgumentException	if the mode is invalid.
  IllegalStateException	if the internal player engine has not been initialized

  selectTrack

  Added in API level 16

  public void selectTrack (int index)

  Selects a track.

  If a MediaPlayer is in invalid state, it throws an IllegalStateException exception. If a MediaPlayer is in Started state, the selected track is presented immediately. If a MediaPlayer is not in Started state, it just marks the track to be played.

  In any valid state, if it is called multiple times on the same type of track (ie. Video, Audio, Timed Text), the most recent one will be chosen.

  The first audio and video tracks are selected by default if a