Skip to content

Most visited

Recently visited

navigation

MediaPlayer

public class MediaPlayer
extends Object

java.lang.Object
   ↳ android.media.MediaPlayer


MediaPlayer class can be used to control playback of audio/video files and streams. An example on how to use the methods in this class can be found in VideoView.

Topics covered here are:

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

Developer Guides

For more information about how to use MediaPlayer, read the Media Playback developer guide.

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.

MediaPlayer State diagram

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(), setAudioStreamType(int), setLooping(boolean), setVolume(float, float), pause(), start(), stop(), seekTo(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.
    • It is also recommended that once a MediaPlayer object is no longer being used, call release() immediately so that resources used by the internal player engine associated with the MediaPlayer object can be released immediately. Resource may include singleton resources such as hardware acceleration components and failure to call release() may cause subsequent instances of MediaPlayer objects to fallback to software implementations or fail altogether. Once the MediaPlayer object is in the End state, it can no longer be used and there is no way to bring it back to any other state.
    • Furthermore, the 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 way) 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 not 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(int).
    • Although the asynchronuous seekTo(int) call returns right way, 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(int) can also be called in the other states, such as Prepared, Paused and PlaybackCompleted state.
    • 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 truewith 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 Sates

    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(), the object is no longer available.

    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

    {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 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(OnPreparedListener)setOnPreparedListener, setOnVideoSizeChangedListener(OnVideoSizeChangedListener)setOnVideoSizeChangedListener, setOnSeekCompleteListener(OnSeekCompleteListener)setOnSeekCompleteListener, setOnCompletionListener(OnCompletionListener)setOnCompletionListener, setOnBufferingUpdateListener(OnBufferingUpdateListener)setOnBufferingUpdateListener, setOnInfoListener(OnInfoListener)setOnInfoListener, setOnErrorListener(OnErrorListener)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

    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.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.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.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.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_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_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_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

    MIME type for SubRip (SRT) container.

    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.

    Fields

    protected AudioAttributes mAttributes

    protected float mAuxEffectSendLevel

    protected float mLeftVolume

    protected float mRightVolume

    Public constructors

    MediaPlayer()

    Default constructor.

    Public methods

    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.

    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.

    void deselectTrack(int index)

    Deselect a track.

    int getAudioSessionId()

    Returns the audio session ID.

    int getCurrentPosition()

    Gets the current playback position.

    int getDuration()

    Gets the duration of the file.

    PlaybackParams getPlaybackParams()

    Gets the playback params, containing the current playback rate.

    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 release()

    Releases resources associated with this MediaPlayer object.

    void reset()

    Resets the MediaPlayer to its uninitialized state.

    void seekTo(int msec)

    Seeks to specified time position.

    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)

    Sets the audio stream type for this MediaPlayer.

    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(Context context, Uri uri, Map<StringString> headers)

    Sets the data source as a content Uri.

    void setDataSource(MediaDataSource dataSource)

    Sets the data source (MediaDataSource) to use.

    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 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 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 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 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.

    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 stopped 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

    Constants

    MEDIA_ERROR_IO

    Added in API level 17
    int MEDIA_ERROR_IO

    File or network related operation errors.

    Constant Value: -1004 (0xfffffc14)

    MEDIA_ERROR_MALFORMED

    Added in API level 17
    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
    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.

    Constant Value: 200 (0x000000c8)

    MEDIA_ERROR_SERVER_DIED

    Added in API level 1
    int MEDIA_ERROR_SERVER_DIED

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

    Constant Value: 100 (0x00000064)

    MEDIA_ERROR_TIMED_OUT

    Added in API level 17
    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
    int MEDIA_ERROR_UNKNOWN

    Unspecified media player error.

    Constant Value: 1 (0x00000001)

    MEDIA_ERROR_UNSUPPORTED

    Added in API level 17
    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_BAD_INTERLEAVING

    Added in API level 3
    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.

    Constant Value: 800 (0x00000320)

    MEDIA_INFO_BUFFERING_END

    Added in API level 9
    int MEDIA_INFO_BUFFERING_END

    MediaPlayer is resuming playback after filling buffers.

    Constant Value: 702 (0x000002be)

    MEDIA_INFO_BUFFERING_START

    Added in API level 9
    int MEDIA_INFO_BUFFERING_START

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

    Constant Value: 701 (0x000002bd)

    MEDIA_INFO_METADATA_UPDATE

    Added in API level 5
    int MEDIA_INFO_METADATA_UPDATE

    A new set of metadata is available.

    Constant Value: 802 (0x00000322)

    MEDIA_INFO_NOT_SEEKABLE

    Added in API level 3
    int MEDIA_INFO_NOT_SEEKABLE

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

    Constant Value: 801 (0x00000321)

    MEDIA_INFO_SUBTITLE_TIMED_OUT

    Added in API level 19
    int MEDIA_INFO_SUBTITLE_TIMED_OUT

    Reading the subtitle track takes too long.

    Constant Value: 902 (0x00000386)

    MEDIA_INFO_UNKNOWN

    Added in API level 3
    int MEDIA_INFO_UNKNOWN

    Unspecified media player info.

    Constant Value: 1 (0x00000001)

    MEDIA_INFO_UNSUPPORTED_SUBTITLE

    Added in API level 19
    int MEDIA_INFO_UNSUPPORTED_SUBTITLE

    Subtitle track was not supported by the media framework.

    Constant Value: 901 (0x00000385)

    MEDIA_INFO_VIDEO_RENDERING_START

    Added in API level 17
    int MEDIA_INFO_VIDEO_RENDERING_START

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

    Constant Value: 3 (0x00000003)

    MEDIA_INFO_VIDEO_TRACK_LAGGING

    Added in API level 3
    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.

    Constant Value: 700 (0x000002bc)

    MEDIA_MIMETYPE_TEXT_SUBRIP

    Added in API level 16
    String MEDIA_MIMETYPE_TEXT_SUBRIP

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

    Constant Value: "application/x-subrip"

    VIDEO_SCALING_MODE_SCALE_TO_FIT

    Added in API level 16
    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
    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)

    Fields

    mAttributes

    AudioAttributes mAttributes

    mAuxEffectSendLevel

    float mAuxEffectSendLevel

    mLeftVolume

    float mLeftVolume

    mRightVolume

    float mRightVolume

    Public constructors

    MediaPlayer

    Added in API level 1
    MediaPlayer ()

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

    When done with the MediaPlayer, you should call release(), to free the resources. If not released, too many MediaPlayer instances may result in an exception.

    Public methods

    addTimedTextSource

    Added in API level 16
    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
    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
    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
    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
    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 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

    create

    Added in API level 21
    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 generateAudioSessionId() to obtain a new session.
    Returns
    MediaPlayer a MediaPlayer object, or null if creation failed

    create

    Added in API level 21
    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 generateAudioSessionId() to obtain a new session.
    Returns
    MediaPlayer a MediaPlayer object, or null if creation failed

    create

    Added in API level 1
    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.

    When done with the MediaPlayer, you should call release(), to free the resources. If not released, too many MediaPlayer instances will result in an exception.

    Note that since prepare() is called automatically in this method, you cannot change the audio stream type (see setAudioStreamType(int)), 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
    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.

    When done with the MediaPlayer, you should call release(), to free the resources. If not released, too many MediaPlayer instances will result in an exception.

    Note that since prepare() is called automatically in this method, you cannot change the audio stream type (see setAudioStreamType(int)), 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
    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.

    When done with the MediaPlayer, you should call release(), to free the resources. If not released, too many MediaPlayer instances will result in an exception.

    Note that since prepare() is called automatically in this method, you cannot change the audio stream type (see setAudioStreamType(int)), 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

    deselectTrack

    Added in API level 16
    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:

    getAudioSessionId

    Added in API level 9
    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.

    getCurrentPosition

    Added in API level 1
    int getCurrentPosition ()

    Gets the current playback position.

    Returns
    int the current position in milliseconds

    getDuration

    Added in API level 1
    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.

    getPlaybackParams

    Added in API level 23
    PlaybackParams getPlaybackParams ()

    Gets the playback params, containing the current playback rate.

    Returns
    PlaybackParams the playback params.
    Throws
    IllegalStateException if the internal player engine has not been initialized.

    getSelectedTrack

    Added in API level 21
    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 MEDIA_TRACK_TYPE_VIDEO, MEDIA_TRACK_TYPE_AUDIO, or 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()

    getSyncParams

    Added in API level 23
    SyncParams getSyncParams ()

    Gets the A/V sync mode.

    Returns
    SyncParams the A/V sync params
    Throws
    IllegalStateException if the internal player engine has not been initialized.

    getTimestamp

    Added in API level 23
    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 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:

    getTrackInfo

    Added in API level 16
    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
    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
    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
    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
    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
    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
    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
    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

    release

    Added in API level 1
    void release ()

    Releases resources associated with this MediaPlayer object. It is considered good practice to call this method when you're done using the MediaPlayer. In particular, whenever an Activity of an application is paused (its onPause() method is called), or stopped (its onStop() method is called), this method should be invoked to release the MediaPlayer object, unless the application has a special need to keep the object around. In addition to unnecessary resources (such as memory and instances of codecs) being held, failure to call this method immediately if a MediaPlayer object is no longer needed may also lead to continuous battery consumption for mobile devices, and playback failure for other applications if no multiple instances of the same codec are supported on a device. Even if multiple instances of the same codec are supported, some performance degradation may be expected when unnecessary multiple instances are used at the same time.

    reset

    Added in API level 1
    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().

    seekTo

    Added in API level 1
    void seekTo (int msec)

    Seeks to specified time position.

    Parameters
    msec int: the offset in milliseconds from the start to seek to
    Throws
    IllegalStateException if the internal player engine has not been initialized

    selectTrack

    Added in API level 16
    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 available, even though this method is not called. However, no timed text track will be selected until this function is called.

    Currently, only timed text tracks or audio tracks can be selected via this method. In addition, the support for selecting an audio track at runtime is pretty limited in that an audio track can only be selected in the Prepared state.

    Parameters
    index int: the index of the track to be selected. The valid range of the index is 0..total number of track - 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:

    setAudioAttributes

    Added in API level 21
    void setAudioAttributes (AudioAttributes attributes)

    Sets the audio attributes for this MediaPlayer. See AudioAttributes for how to build and configure an instance of this class. You must call this method before prepare() or prepareAsync() in order for the audio attributes to become effective thereafter.

    Parameters
    attributes AudioAttributes: a non-null set of audio attributes
    Throws
    IllegalArgumentException

    setAudioSessionId

    Added in API level 9
    void setAudioSessionId (int sessionId)

    Sets the audio session ID.

    Parameters
    sessionId int: the audio session ID. The audio session ID is a system wide unique identifier for the audio stream played by this MediaPlayer instance. The primary use of the audio session ID is to associate audio effects to a particular instance of MediaPlayer: if an audio session ID is provided when creating an audio effect, this effect will be applied only to the audio content of media players within the same audio session and not to the output mix. When created, a MediaPlayer instance automatically generates its own audio session ID. However, it is possible to force this player to be part of an already existing audio session by calling this method. This method must be called before one of the overloaded setDataSource methods.
    Throws
    IllegalStateException if it is called in an invalid state
    IllegalArgumentException

    setAudioStreamType

    Added in API level 1
    void setAudioStreamType (int streamtype)

    Sets the audio stream type for this MediaPlayer. See AudioManager for a list of stream types. Must call this method before prepare() or prepareAsync() in order for the target stream type to become effective thereafter.

    Parameters
    streamtype int: the audio stream type

    See also:

    setAuxEffectSendLevel

    Added in API level 9
    void setAuxEffectSendLevel (float level)

    Sets the send level of the player to the attached auxiliary effect. See attachAuxEffect(int). The level value range is 0 to 1.0.

    By default the send level is 0, so even if an effect is attached to the player this method must be called for the effect to be applied.

    Note that the passed level value is a raw scalar. UI controls should be scaled logarithmically: the gain applied by audio framework ranges from -72dB to 0dB, so an appropriate conversion from linear UI input x to level is: x == 0 -> level = 0 0 < x <= R -> level = 10^(72*(x-R)/20/R)

    Parameters
    level float: send level scalar

    setDataSource

    Added in API level 24
    void setDataSource (AssetFileDescriptor afd)

    Sets the data source (AssetFileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns.

    Parameters
    afd AssetFileDescriptor: the AssetFileDescriptor for the file you want to play
    Throws
    IllegalStateException if it is called in an invalid state
    IllegalArgumentException if afd is not a valid AssetFileDescriptor
    IOException if afd can not be read

    setDataSource

    Added in API level 1
    void setDataSource (FileDescriptor fd)

    Sets the data source (FileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns.

    Parameters
    fd FileDescriptor: the FileDescriptor for the file you want to play
    Throws
    IllegalStateException if it is called in an invalid state
    IllegalArgumentException if fd is not a valid FileDescriptor
    IOException if fd can not be read

    setDataSource

    Added in API level 1
    void setDataSource (FileDescriptor fd, 
                    long offset, 
                    long length)

    Sets the data source (FileDescriptor) to use. The FileDescriptor must be seekable (N.B. a LocalSocket is not seekable). It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns.

    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
    Throws
    IllegalStateException if it is called in an invalid state
    IllegalArgumentException if fd is not a valid FileDescriptor
    IOException if fd can not be read

    setDataSource

    Added in API level 1
    void setDataSource (String path)

    Sets the data source (file-path or http/rtsp URL) to use.

    Parameters
    path String: the path of the file, or the http/rtsp URL of the stream you want to play
    Throws
    IllegalStateException if it is called in an invalid state

    When path refers to a local file, the file may actually be opened by a process other than the calling application. This implies that the pathname should be an absolute path (as any other process runs with unspecified current working directory), and that the pathname should reference a world-readable file. As an alternative, the application could first open the file for reading, and then use the file descriptor form setDataSource(FileDescriptor).

    IOException
    IllegalArgumentException
    SecurityException

    setDataSource

    Added in API level 14
    void setDataSource (Context context, 
                    Uri uri, 
                    Map<StringString> headers)

    Sets the data source as a content Uri.

    Parameters
    context Context: the Context to use when resolving the Uri
    uri Uri: the Content URI of the data you want to play
    headers Map: the headers to be sent together with the request for the data Note that the cross domain redirection is allowed by default, but that can be changed with key/value pairs through the headers parameter with "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value to disallow or allow cross domain redirection.
    Throws
    IllegalStateException if it is called in an invalid state
    IOException
    IllegalArgumentException
    SecurityException

    setDataSource

    Added in API level 23
    void setDataSource (MediaDataSource dataSource)

    Sets the data source (MediaDataSource) to use.

    Parameters
    dataSource MediaDataSource: the MediaDataSource for the media you want to play
    Throws
    IllegalStateException if it is called in an invalid state
    IllegalArgumentException if dataSource is not a valid MediaDataSource

    setDataSource

    Added in API level 1
    void setDataSource (Context context, 
                    Uri uri)

    Sets the data source as a content Uri.

    Parameters
    context Context: the Context to use when resolving the Uri
    uri Uri: the Content URI of the data you want to play
    Throws
    IllegalStateException if it is called in an invalid state
    IOException
    IllegalArgumentException
    SecurityException

    setDisplay

    Added in API level 1
    void setDisplay (SurfaceHolder sh)

    Sets the SurfaceHolder to use for displaying the video portion of the media. Either a surface holder or surface must be set if a display or video sink is needed. Not calling this method or setSurface(Surface) when playing back a video will result in only the audio track being played. A null surface holder or surface will result in only the audio track being played.

    Parameters
    sh SurfaceHolder: the SurfaceHolder to use for video display
    Throws
    IllegalStateException if the internal player engine has not been initialized or has been released.

    setLooping

    Added in API level 1
    void setLooping (boolean looping)

    Sets the player to be looping or non-looping.

    Parameters
    looping boolean: whether to loop or not

    setNextMediaPlayer

    Added in API level 16
    void setNextMediaPlayer (MediaPlayer next)

    Set the MediaPlayer to start when this MediaPlayer finishes playback (i.e. reaches the end of the stream). The media framework will attempt to transition from this player to the next as seamlessly as possible. The next player can be set at any time before completion. The next player must be prepared by the app, and the application should not call start() on it. The next MediaPlayer must be different from 'this'. An exception will be thrown if next == this. The application may call setNextMediaPlayer(null) to indicate no next player should be started at the end of playback. If the current player is looping, it will keep looping and the next player will not be started.

    Parameters
    next MediaPlayer: the player to start after this one completes playback.

    setOnBufferingUpdateListener

    Added in API level 1
    void setOnBufferingUpdateListener (MediaPlayer.OnBufferingUpdateListener listener)

    Register a callback to be invoked when the status of a network stream's buffer has changed.

    Parameters
    listener MediaPlayer.OnBufferingUpdateListener: the callback that will be run.

    setOnCompletionListener

    Added in API level 1
    void setOnCompletionListener (MediaPlayer.OnCompletionListener listener)

    Register a callback to be invoked when the end of a media source has been reached during playback.

    Parameters
    listener MediaPlayer.OnCompletionListener: the callback that will be run

    setOnErrorListener

    Added in API level 1
    void setOnErrorListener (MediaPlayer.OnErrorListener listener)

    Register a callback to be invoked when an error has happened during an asynchronous operation.

    Parameters
    listener MediaPlayer.OnErrorListener: the callback that will be run

    setOnInfoListener

    Added in API level 3
    void setOnInfoListener (MediaPlayer.OnInfoListener listener)

    Register a callback to be invoked when an info/warning is available.

    Parameters
    listener MediaPlayer.OnInfoListener: the callback that will be run

    setOnPreparedListener

    Added in API level 1
    void setOnPreparedListener (MediaPlayer.OnPreparedListener listener)

    Register a callback to be invoked when the media source is ready for playback.

    Parameters
    listener MediaPlayer.OnPreparedListener: the callback that will be run

    setOnSeekCompleteListener

    Added in API level 1
    void setOnSeekCompleteListener (MediaPlayer.OnSeekCompleteListener listener)

    Register a callback to be invoked when a seek operation has been completed.

    Parameters
    listener MediaPlayer.OnSeekCompleteListener: the callback that will be run

    setOnTimedMetaDataAvailableListener

    Added in API level 23
    void setOnTimedMetaDataAvailableListener (MediaPlayer.OnTimedMetaDataAvailableListener listener)

    Register a callback to be invoked when a selected track has timed metadata available.

    Currently only HTTP live streaming data URI's embedded with timed ID3 tags generates TimedMetaData.

    Parameters
    listener MediaPlayer.OnTimedMetaDataAvailableListener: the callback that will be run

    setOnTimedTextListener

    Added in API level 16
    void setOnTimedTextListener (MediaPlayer.OnTimedTextListener listener)

    Register a callback to be invoked when a timed text is available for display.

    Parameters
    listener MediaPlayer.OnTimedTextListener: the callback that will be run

    setOnVideoSizeChangedListener

    Added in API level 3
    void setOnVideoSizeChangedListener (MediaPlayer.OnVideoSizeChangedListener listener)

    Register a callback to be invoked when the video size is known or updated.

    Parameters
    listener MediaPlayer.OnVideoSizeChangedListener: the callback that will be run

    setPlaybackParams

    Added in API level 23
    void setPlaybackParams (PlaybackParams params)

    Sets playback rate using PlaybackParams. The object sets its internal PlaybackParams to the input, except that the object remembers previous speed when input speed is zero. This allows the object to resume at previous speed when start() is called. Calling it before the object is prepared does not change the object state. After the object is prepared, calling it with zero speed is equivalent to calling pause(). After the object is prepared, calling it with non-zero speed is equivalent to calling start().

    Parameters
    params PlaybackParams: the playback params.
    Throws
    IllegalStateException if the internal player engine has not been initialized or has been released.
    IllegalArgumentException if params is not supported.

    setScreenOnWhilePlaying

    Added in API level 1
    void setScreenOnWhilePlaying (boolean screenOn)

    Control whether we should use the attached SurfaceHolder to keep the screen on while video playback is occurring. This is the preferred method over setWakeMode(Context, int) where possible, since it doesn't require that the application have permission for low-level wake lock access.

    Parameters
    screenOn boolean: Supply true to keep the screen on, false to allow it to turn off.

    setSurface

    Added in API level 14
    void setSurface (Surface surface)

    Sets the Surface to be used as the sink for the video portion of the media. This is similar to setDisplay(SurfaceHolder), but does not support setScreenOnWhilePlaying(boolean). Setting a Surface will un-set any Surface or SurfaceHolder that was previously set. A null surface will result in only the audio track being played. If the Surface sends frames to a SurfaceTexture, the timestamps returned from getTimestamp() will have an unspecified zero point. These timestamps cannot be directly compared between different media sources, different instances of the same media source, or multiple runs of the same program. The timestamp is normally monotonically increasing and is unaffected by time-of-day adjustments, but it is reset when the position is set.

    Parameters
    surface Surface: The Surface to be used for the video portion of the media.
    Throws
    IllegalStateException if the internal player engine has not been initialized or has been released.

    setSyncParams

    Added in API level 23
    void setSyncParams (SyncParams params)

    Sets A/V sync mode.

    Parameters
    params SyncParams: the A/V sync params to apply
    Throws
    IllegalStateException if the internal player engine has not been initialized.
    IllegalArgumentException if params are not supported.

    setVideoScalingMode

    Added in API level 16
    void setVideoScalingMode (int mode)

    Sets video scaling mode. To make the target video scaling mode effective during playback, this method must be called after data source is set. If not called, the default video scaling mode is VIDEO_SCALING_MODE_SCALE_TO_FIT.

    The supported video scaling modes are:

    Parameters
    mode int: target video scaling mode. Must be one of the supported video scaling modes; otherwise, IllegalArgumentException will be thrown.

    setVolume

    Added in API level 1
    void setVolume (float leftVolume, 
                    float rightVolume)

    Sets the volume on this player. This API is recommended for balancing the output of audio streams within an application. Unless you are writing an application to control user settings, this API should be used in preference to setStreamVolume(int, int, int) which sets the volume of ALL streams of a particular type. Note that the passed volume values are raw scalars in range 0.0 to 1.0. UI controls should be scaled logarithmically.

    Parameters
    leftVolume float: left volume scalar
    rightVolume float: right volume scalar

    setWakeMode

    Added in API level 1
    void setWakeMode (Context context, 
                    int mode)

    Set the low-level power management behavior for this MediaPlayer. This can be used when the MediaPlayer is not playing through a SurfaceHolder set with setDisplay(SurfaceHolder) and thus can use the high-level setScreenOnWhilePlaying(boolean) feature.

    This function has the MediaPlayer access the low-level power manager service to control the device's power usage while playing is occurring. The parameter is a combination of PowerManager wake flags. Use of this method requires WAKE_LOCK permission. By default, no attempt is made to keep the device awake during playback.

    Parameters
    context Context: the Context to use
    mode int: the power/wake mode to set

    See also:

    start

    Added in API level 1
    void start ()

    Starts or resumes playback. If playback had previously been paused, playback will continue from where it was paused. If playback had been stopped, or never started before, playback will start at the beginning.

    Throws
    IllegalStateException if it is called in an invalid state

    stop

    Added in API level 1
    void stop ()

    Stops playback after playback has been stopped or paused.

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

    Protected methods

    finalize

    Added in API level 1
    void finalize ()

    Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

    The general contract of finalize is that it is invoked if and when the JavaTM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

    The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

    The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

    After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

    The finalize method is never invoked more than once by a Java virtual machine for any given object.

    Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.