public class

MediaPlayer

extends Object
java.lang.Object
   ↳ android.media.MediaPlayer

Class Overview

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. Please see Audio and Video for additional help using MediaPlayer.

Topics covered here are:

  1. State Diagram
  2. Valid and Invalid States
  3. Permissions

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.
    • IlleglStateException 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) 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

    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}

    		 {Idle, Initialized, Prepared, Stopped, PlaybackCompleted, 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.

    setAudioStreamType

    		{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}

    		 {Error}

    		 Successful invoke of this method does not change the 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.

    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.

    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.

    Permissions

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

Summary

Nested Classes
public class MediaPlayer.OnBufferingUpdateListener Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network. 
public class MediaPlayer.OnCompletionListener Interface definition for a callback to be invoked when playback of a media source has completed. 
public class 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). 
public class MediaPlayer.OnInfoListener Interface definition of a callback to be invoked to communicate some info and/or warning about the media or its playback. 
public class MediaPlayer.OnPreparedListener Interface definition for a callback to be invoked when the media source is ready for playback. 
public class MediaPlayer.OnSeekCompleteListener Interface definition of a callback to be invoked indicating the completion of a seek operation. 
public class MediaPlayer.OnVideoSizeChangedListener Interface definition of a callback to be invoked when the video size is first known or updated  
Constants
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_UNKNOWN Unspecified media player error.
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_NOT_SEEKABLE The media cannot be seeked (e.g live stream)
int MEDIA_INFO_UNKNOWN Unspecified media player info.
int MEDIA_INFO_VIDEO_TRACK_LAGGING The video is too complex for the decoder: it can't decode frames fast enough.
Public Constructors
MediaPlayer()
Default constructor.
Public Methods
static MediaPlayer create(Context context, Uri uri)
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, SurfaceHolder holder)
Convenience method to create a MediaPlayer for a given Uri.
int getCurrentPosition()
Gets the current playback position.
int getDuration()
Gets the duration of the file.
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 setAudioStreamType(int streamtype)
Sets the audio stream type for this MediaPlayer.
void setDataSource(String path)
Sets the data source (file-path or http/rtsp URL) to use.
void setDataSource(FileDescriptor fd, long offset, long length)
Sets the data source (FileDescriptor) to use.
void setDataSource(FileDescriptor fd)
Sets the data source (FileDescriptor) 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 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 setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener)
Register a callback to be invoked when the video size is known or updated.
void setScreenOnWhilePlaying(boolean screenOn)
Control whether we should use the attached SurfaceHolder to keep the screen on while video playback is occurring.
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()
Is called before the object's memory is being reclaimed by the VM.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

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
Constant Value: 200 (0x000000c8)

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
Constant Value: 100 (0x00000064)

public static final int MEDIA_ERROR_UNKNOWN

Unspecified media player error.

See Also
Constant Value: 1 (0x00000001)

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
Constant Value: 800 (0x00000320)

public static final int MEDIA_INFO_NOT_SEEKABLE

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

See Also
Constant Value: 801 (0x00000321)

public static final int MEDIA_INFO_UNKNOWN

Unspecified media player info.

See Also
Constant Value: 1 (0x00000001)

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
Constant Value: 700 (0x000002bc)

Public Constructors

public 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

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.

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.

Parameters
context the Context to use
uri the Uri from which to get the datasource
Returns
  • a MediaPlayer object, or null if creation failed

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.

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.

Parameters
context the Context to use
resid the raw resource id (R.raw.<something>) for the resource to use as the datasource
Returns
  • a MediaPlayer object, or null if creation failed

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.

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.

Parameters
context the Context to use
uri the Uri from which to get the datasource
holder the SurfaceHolder to use for displaying the video
Returns
  • a MediaPlayer object, or null if creation failed

public int getCurrentPosition ()

Gets the current playback position.

Returns
  • the current position in milliseconds

public int getDuration ()

Gets the duration of the file.

Returns
  • the duration in milliseconds

public int getVideoHeight ()

Returns the height of the video.

Returns
  • the height of the video, or 0 if there is no video, no display surface was set, or prepare()/prepareAsync() have not completed yet

public int getVideoWidth ()

Returns the width of the video.

Returns
  • the width of the video, or 0 if there is no video, no display surface was set, or prepare()/prepareAsync() have not completed yet

public boolean isLooping ()

Checks whether the MediaPlayer is looping or non-looping.

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

public boolean isPlaying ()

Checks whether the MediaPlayer is playing.

Returns
  • true if currently playing, false otherwise

public void pause ()

Pauses playback. Call start() to resume.

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

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

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

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

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

public void seekTo (int msec)

Seeks to specified time position.

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

public void setAudioStreamType (int streamtype)

Sets the audio stream type for this MediaPlayer. See AudioManager for a list of stream types.

Parameters
streamtype the audio stream type
See Also

public void setDataSource (String path)

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

Parameters
path 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
IOException
IllegalArgumentException

public void setDataSource (FileDescriptor fd, long offset, long length)

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 the FileDescriptor for the file you want to play
offset the offset into the file where the data to be played starts, in bytes
length the length in bytes of the data to be played
Throws
IllegalStateException if it is called in an invalid state
IOException
IllegalArgumentException

public 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 the FileDescriptor for the file you want to play
Throws
IllegalStateException if it is called in an invalid state
IOException
IllegalArgumentException

public void setDataSource (Context context, Uri uri)

Sets the data source as a content Uri.

Parameters
context the Context to use when resolving the 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

public void setDisplay (SurfaceHolder sh)

Sets the SurfaceHolder to use for displaying the video portion of the media. This call is optional. Not calling it when playing back a video will result in only the audio track being played.

Parameters
sh the SurfaceHolder to use for video display

public void setLooping (boolean looping)

Sets the player to be looping or non-looping.

Parameters
looping whether to loop or not

public void setOnBufferingUpdateListener (MediaPlayer.OnBufferingUpdateListener listener)

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

Parameters
listener the callback that will be run.

public 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 the callback that will be run

public void setOnErrorListener (MediaPlayer.OnErrorListener listener)

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

Parameters
listener the callback that will be run

public void setOnInfoListener (MediaPlayer.OnInfoListener listener)

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

Parameters
listener the callback that will be run

public void setOnPreparedListener (MediaPlayer.OnPreparedListener listener)

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

Parameters
listener the callback that will be run

public void setOnSeekCompleteListener (MediaPlayer.OnSeekCompleteListener listener)

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

Parameters
listener the callback that will be run

public void setOnVideoSizeChangedListener (MediaPlayer.OnVideoSizeChangedListener listener)

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

Parameters
listener the callback that will be run

public 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 Supply true to keep the screen on, false to allow it to turn off.

public 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. UI controls should be scaled logarithmically.

Parameters
leftVolume left volume scalar
rightVolume right volume scalar

public 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 the Context to use
mode the power/wake mode to set
See Also

public 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

public void stop ()

Stops playback after playback has been stopped or paused.

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

Protected Methods

protected void finalize ()

Is called before the object's memory is being reclaimed by the VM. This can only happen once the VM has detected, during a run of the garbage collector, that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.