FileDocCategorySizeDatePackage
MediaPlayer.javaAPI DocAndroid 1.5 API53360Wed May 06 22:42:00 BST 2009android.media

MediaPlayer

public class MediaPlayer extends Object
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 {@link android.widget.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 {@link #reset()} is called, it is in the Idle state; and after {@link #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 {@link #reset()} is called. It is a programming error to invoke methods such as {@link #getCurrentPosition()}, {@link #getDuration()}, {@link #getVideoHeight()}, {@link #getVideoWidth()}, {@link #setAudioStreamType(int)}, {@link #setLooping(boolean)}, {@link #setVolume(float, float)}, {@link #pause()}, {@link #start()}, {@link #stop()}, {@link #seekTo(int)}, {@link #prepare()} or {@link #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 {@link #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 {@link #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 {@link #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 {@link #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, {@link #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 {@link #prepare()}, {@link #prepareAsync()}, or one of the overloaded setDataSource methods in an invalid state.
  • Calling {@link #setDataSource(FileDescriptor)}, or {@link #setDataSource(String)}, or {@link #setDataSource(Context, Uri)}, or {@link #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 {@link #prepare()} (synchronous) which transfers the object to the Prepared state once the method call returns, or a call to {@link #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 {@link #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 {@link #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 {@link #prepare()} or {@link #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, {@link #start()} must be called. After {@link #start()} returns successfully, the MediaPlayer object is in the Started state. {@link #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 {@link #setOnBufferingUpdateListener(OnBufferingUpdateListener)}. This callback allows applications to keep track of the buffering status while streaming audio/video.
    • Calling {@link #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 {@link #pause()}. When the call to {@link #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 {@link #isPlaying()}, and it can be a number of seconds in the case of streamed content.
    • Calling {@link #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 {@link #start()} returns, the paused MediaPlayer object goes back to the Started state.
    • Calling {@link #pause()} has no effect on a MediaPlayer object that is already in the Paused state.
  • Calling {@link #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 {@link #prepare()} or {@link #prepareAsync()} are called to set the MediaPlayer object to the Prepared state again.
    • Calling {@link #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 {@link #seekTo(int)}.
    • Although the asynchronuous {@link #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 {@link #setOnSeekCompleteListener(OnSeekCompleteListener)}.
    • Please note that {@link #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 {@link #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 {@link #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 {@link #setOnCompletionListener(OnCompletionListener)}. The invoke of the callback signals that the object is now in the PlaybackCompleted state.
    • While in the PlaybackCompleted state, calling {@link #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 {@link #release()}, the object is no longer available.

    reset

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

    		 {}

    		 After {@link #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 {@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>} element.

Fields Summary
private static final String
TAG
private int
mNativeContext
private int
mListenerContext
private android.view.Surface
mSurface
private android.view.SurfaceHolder
mSurfaceHolder
private EventHandler
mEventHandler
private PowerManager.WakeLock
mWakeLock
private boolean
mScreenOnWhilePlaying
private boolean
mStayAwake
private static final int
MEDIA_NOP
private static final int
MEDIA_PREPARED
private static final int
MEDIA_PLAYBACK_COMPLETE
private static final int
MEDIA_BUFFERING_UPDATE
private static final int
MEDIA_SEEK_COMPLETE
private static final int
MEDIA_SET_VIDEO_SIZE
private static final int
MEDIA_ERROR
private static final int
MEDIA_INFO
private OnPreparedListener
mOnPreparedListener
private OnCompletionListener
mOnCompletionListener
private OnBufferingUpdateListener
mOnBufferingUpdateListener
private OnSeekCompleteListener
mOnSeekCompleteListener
private OnVideoSizeChangedListener
mOnVideoSizeChangedListener
public static final int
MEDIA_ERROR_UNKNOWN
Unspecified media player error.
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.
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.
private OnErrorListener
mOnErrorListener
public static final int
MEDIA_INFO_UNKNOWN
Unspecified media player info.
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.
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.
public static final int
MEDIA_INFO_NOT_SEEKABLE
The media cannot be seeked (e.g live stream)
private OnInfoListener
mOnInfoListener
Constructors Summary
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 {@link #release()}, to free the resources. If not released, too many MediaPlayer instances may result in an exception.

    
                                                        
      
   
        Looper looper;
        if ((looper = Looper.myLooper()) != null) {
            mEventHandler = new EventHandler(this, looper);
        } else if ((looper = Looper.getMainLooper()) != null) {
            mEventHandler = new EventHandler(this, looper);
        } else {
            mEventHandler = null;
        }

        /* Native setup requires a weak reference to our object.
         * It's easier to create it here than in C++.
         */
        native_setup(new WeakReference<MediaPlayer>(this));
Methods Summary
private native void_pause()

private native void_release()
private native void_reset()
private native void_start()
private native void_stop()
public static android.media.MediaPlayercreate(android.content.Context context, android.net.Uri uri)
Convenience method to create a MediaPlayer for a given Uri.
On success, {@link #prepare()} will already have been called and must not be called again.

When done with the MediaPlayer, you should call {@link #release()},
to free the resources. If not released, too many MediaPlayer instances will
result in an exception.
param
context the Context to use
param
uri the Uri from which to get the datasource
return
a MediaPlayer object, or null if creation failed
        return create (context, uri, null);
    
public static android.media.MediaPlayercreate(android.content.Context context, android.net.Uri uri, android.view.SurfaceHolder holder)
Convenience method to create a MediaPlayer for a given Uri.
On success, {@link #prepare()} will already have been called and must not be called again.

When done with the MediaPlayer, you should call {@link #release()},
to free the resources. If not released, too many MediaPlayer instances will
result in an exception.
param
context the Context to use
param
uri the Uri from which to get the datasource
param
holder the SurfaceHolder to use for displaying the video
return
a MediaPlayer object, or null if creation failed
        
        try {
            MediaPlayer mp = new MediaPlayer();
            mp.setDataSource(context, uri);
            if (holder != null) {
                mp.setDisplay(holder);
            }
            mp.prepare();
            return mp;
        } catch (IOException ex) {
            Log.d(TAG, "create failed:", ex);
            // fall through
        } catch (IllegalArgumentException ex) {
            Log.d(TAG, "create failed:", ex);
            // fall through
        } catch (SecurityException ex) {
            Log.d(TAG, "create failed:", ex);
            // fall through
        }

        return null;
    
public static android.media.MediaPlayercreate(android.content.Context context, int resid)
Convenience method to create a MediaPlayer for a given resource id.
On success, {@link #prepare()} will already have been called and must not be called again.

When done with the MediaPlayer, you should call {@link #release()},
to free the resources. If not released, too many MediaPlayer instances will
result in an exception.
param
context the Context to use
param
resid the raw resource id (R.raw.<something>) for
the resource to use as the datasource
return
a MediaPlayer object, or null if creation failed
        try {
            AssetFileDescriptor afd = context.getResources().openRawResourceFd(resid);
            if (afd == null) return null;

            MediaPlayer mp = new MediaPlayer();
            mp.setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getLength());
            afd.close();
            mp.prepare();
            return mp;
        } catch (IOException ex) {
            Log.d(TAG, "create failed:", ex);
            // fall through
        } catch (IllegalArgumentException ex) {
            Log.d(TAG, "create failed:", ex);
           // fall through
        } catch (SecurityException ex) {
            Log.d(TAG, "create failed:", ex);
            // fall through
        }
        return null;
    
protected voidfinalize()
 native_finalize(); 
public native intgetCurrentPosition()
Gets the current playback position.
return
the current position in milliseconds
public native intgetDuration()
Gets the duration of the file.
return
the duration in milliseconds
public native android.graphics.BitmapgetFrameAt(int msec)
Currently not implemented, returns null.
deprecated
hide
public native intgetVideoHeight()
Returns the height of the video.
return
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 native intgetVideoWidth()
Returns the width of the video.
return
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 native booleanisLooping()
Checks whether the MediaPlayer is looping or non-looping.
return
true if the MediaPlayer is currently looping, false otherwise
public native booleanisPlaying()
Checks whether the MediaPlayer is playing.
return
true if currently playing, false otherwise
private final native voidnative_finalize()
private final native voidnative_setup(java.lang.Object mediaplayer_this)
public voidpause()
Pauses playback. Call start() to resume.
throws
IllegalStateException if the internal player engine has not been
initialized.
        stayAwake(false);
        _pause();
    
private static voidpostEventFromNative(java.lang.Object mediaplayer_ref, int what, int arg1, int arg2, java.lang.Object obj)
Called from native code when an interesting event happens. This method
just uses the EventHandler system to post the event back to the main app thread.
We use a weak reference to the original MediaPlayer object so that the native
code is safe from the object disappearing from underneath it. (This is
the cookie passed to native_setup().)
        MediaPlayer mp = (MediaPlayer)((WeakReference)mediaplayer_ref).get();
        if (mp == null) {
            return;
        }

        if (mp.mEventHandler != null) {
            Message m = mp.mEventHandler.obtainMessage(what, arg1, arg2, obj);
            mp.mEventHandler.sendMessage(m);
        }
    
public native voidprepare()
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
public native voidprepareAsync()
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 voidrelease()
Releases resources associated with this MediaPlayer object.
It is considered good practice to call this method when you're
done using the MediaPlayer.
        stayAwake(false);
        updateSurfaceScreenOn();
        mOnPreparedListener = null;
        mOnBufferingUpdateListener = null;
        mOnCompletionListener = null;
        mOnSeekCompleteListener = null;
        mOnErrorListener = null;
        mOnInfoListener = null;
        mOnVideoSizeChangedListener = null;
        _release();
    
public voidreset()
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().
        stayAwake(false);
        _reset();
        // make sure none of the listeners get called anymore
        mEventHandler.removeCallbacksAndMessages(null);
    
public native voidseekTo(int msec)
Seeks to specified time position.
param
msec the offset in milliseconds from the start to seek to
throws
IllegalStateException if the internal player engine has not been
initialized
public native voidsetAudioStreamType(int streamtype)
Sets the audio stream type for this MediaPlayer. See {@link AudioManager}
for a list of stream types.
param
streamtype the audio stream type
see
android.media.AudioManager
public voidsetDataSource(android.content.Context context, android.net.Uri uri)
Sets the data source as a content Uri.
param
context the Context to use when resolving the Uri
param
uri the Content URI of the data you want to play
throws
IllegalStateException if it is called in an invalid state
        
        String scheme = uri.getScheme();
        if(scheme == null || scheme.equals("file")) {
            setDataSource(uri.getPath());
            return;
        }

        AssetFileDescriptor fd = null;
        try {
            ContentResolver resolver = context.getContentResolver();
            fd = resolver.openAssetFileDescriptor(uri, "r");
            if (fd == null) {
                return;
            }
            // Note: using getDeclaredLength so that our behavior is the same
            // as previous versions when the content provider is returning
            // a full file.
            if (fd.getDeclaredLength() < 0) {
                setDataSource(fd.getFileDescriptor());
            } else {
                setDataSource(fd.getFileDescriptor(), fd.getStartOffset(), fd.getDeclaredLength());
            }
            return;
        } catch (SecurityException ex) {
        } catch (IOException ex) {
        } finally {
            if (fd != null) {
                fd.close();
            }
        }
        setDataSource(uri.toString());
        return;
    
public native voidsetDataSource(java.lang.String path)
Sets the data source (file-path or http/rtsp URL) to use.
param
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
public voidsetDataSource(java.io.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.
param
fd the FileDescriptor for the file you want to play
throws
IllegalStateException if it is called in an invalid state
        // intentionally less than LONG_MAX
        setDataSource(fd, 0, 0x7ffffffffffffffL);
    
public native voidsetDataSource(java.io.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.
param
fd the FileDescriptor for the file you want to play
param
offset the offset into the file where the data to be played starts, in bytes
param
length the length in bytes of the data to be played
throws
IllegalStateException if it is called in an invalid state
public voidsetDisplay(android.view.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.
param
sh the SurfaceHolder to use for video display
        mSurfaceHolder = sh;
        mSurface = sh.getSurface();
        updateSurfaceScreenOn();
    
public native voidsetLooping(boolean looping)
Sets the player to be looping or non-looping.
param
looping whether to loop or not
public voidsetOnBufferingUpdateListener(android.media.MediaPlayer$OnBufferingUpdateListener listener)
Register a callback to be invoked when the status of a network
stream's buffer has changed.
param
listener the callback that will be run.
        mOnBufferingUpdateListener = listener;
    
public voidsetOnCompletionListener(android.media.MediaPlayer$OnCompletionListener listener)
Register a callback to be invoked when the end of a media source
has been reached during playback.
param
listener the callback that will be run
        mOnCompletionListener = listener;
    
public voidsetOnErrorListener(android.media.MediaPlayer$OnErrorListener listener)
Register a callback to be invoked when an error has happened
during an asynchronous operation.
param
listener the callback that will be run

                                    
      
    
                                                                                              
              
    
   
                                 
       
    
        mOnErrorListener = listener;
    
public voidsetOnInfoListener(android.media.MediaPlayer$OnInfoListener listener)
Register a callback to be invoked when an info/warning is available.
param
listener the callback that will be run

                             
      
    
                                                                                                    
              
    

                             
       
    
        mOnInfoListener = listener;
    
public voidsetOnPreparedListener(android.media.MediaPlayer$OnPreparedListener listener)
Register a callback to be invoked when the media source is ready
for playback.
param
listener the callback that will be run
        mOnPreparedListener = listener;
    
public voidsetOnSeekCompleteListener(android.media.MediaPlayer$OnSeekCompleteListener listener)
Register a callback to be invoked when a seek operation has been
completed.
param
listener the callback that will be run
        mOnSeekCompleteListener = listener;
    
public voidsetOnVideoSizeChangedListener(android.media.MediaPlayer$OnVideoSizeChangedListener listener)
Register a callback to be invoked when the video size is
known or updated.
param
listener the callback that will be run
        mOnVideoSizeChangedListener = listener;
    
public voidsetScreenOnWhilePlaying(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 {@link #setWakeMode} where possible, since it doesn't
require that the application have permission for low-level wake lock
access.
param
screenOn Supply true to keep the screen on, false to allow it
to turn off.
        if (mScreenOnWhilePlaying != screenOn) {
            mScreenOnWhilePlaying = screenOn;
            updateSurfaceScreenOn();
        }
    
public native voidsetVolume(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
{@link AudioManager#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.
param
leftVolume left volume scalar
param
rightVolume right volume scalar
public voidsetWakeMode(android.content.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 {@link #setDisplay(SurfaceHolder)} and thus can use the
high-level {@link #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 {@link android.os.PowerManager} wake flags.
Use of this method requires {@link android.Manifest.permission#WAKE_LOCK}
permission.
By default, no attempt is made to keep the device awake during playback.
param
context the Context to use
param
mode the power/wake mode to set
see
android.os.PowerManager
        boolean washeld = false;
        if (mWakeLock != null) {
            if (mWakeLock.isHeld()) {
                washeld = true;
                mWakeLock.release();
            }
            mWakeLock = null;
        }

        PowerManager pm = (PowerManager)context.getSystemService(Context.POWER_SERVICE);
        mWakeLock = pm.newWakeLock(mode|PowerManager.ON_AFTER_RELEASE, MediaPlayer.class.getName());
        mWakeLock.setReferenceCounted(false);
        if (washeld) {
            mWakeLock.acquire();
        }
    
public voidstart()
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
        stayAwake(true);
        _start();
    
private voidstayAwake(boolean awake)
        if (mWakeLock != null) {
            if (awake && !mWakeLock.isHeld()) {
                mWakeLock.acquire();
            } else if (!awake && mWakeLock.isHeld()) {
                mWakeLock.release();
            }
        }
        mStayAwake = awake;
        updateSurfaceScreenOn();
    
public voidstop()
Stops playback after playback has been stopped or paused.
throws
IllegalStateException if the internal player engine has not been
initialized.
        stayAwake(false);
        _stop();
    
private voidupdateSurfaceScreenOn()
        if (mSurfaceHolder != null) {
            mSurfaceHolder.setKeepScreenOn(mScreenOnWhilePlaying && mStayAwake);
        }