Android
android.media
public class

android.media.MediaPlayer

java.lang.Object
android.media.MediaPlayer

Used to play audio and video files and streams. See the Android Media APIs page for help using using MediaPlayer.

Nested Classes
MediaPlayer.OnBufferingUpdateListener Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network. 
MediaPlayer.OnCompletionListener Interface definition for a callback to be invoked when playback of a media file has completed. 
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). 
MediaPlayer.OnPreparedListener Interface definition for a callback to be invoked when the media file is ready for playback. 
MediaPlayer.OnSeekCompleteListener Interface definition of a callback to be invoked indicating the completion of a seek operation. 

Summary

Constants

      Value  
int  MEDIA_ERROR_SERVER_DIED  Media server died.  100  0x00000064 
int  MEDIA_ERROR_UNKNOWN  Unspecified media player error.  0x00000001 

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.
          Bitmap  getFrameAt(int msec)
Returns a Bitmap containing the video frame at the specified time.
          int  getVideoHeight()
Returns the height of the video.
          int  getVideoWidth()
Returns the width of the video.
          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 l)
Register a callback to be invoked when the status of a network stream's buffer has changed.
          void  setOnCompletionListener(MediaPlayer.OnCompletionListener l)
Register a callback to be invoked when the end of a media file has been reached during playback.
          void  setOnErrorListener(MediaPlayer.OnErrorListener l)
Register a callback to be invoked when an error has happened during an asynchronous operation.
          void  setOnPreparedListener(MediaPlayer.OnPreparedListener l)
Register a callback to be invoked when the media file is ready for playback.
          void  setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener l)
Register a callback to be invoked when a seek operation has been completed.
          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()
Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
Methods inherited from class java.lang.Object

Details

Constants

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

public static final int MEDIA_ERROR_UNKNOWN

Unspecified media player error. @see #OnErrorListener
Constant Value: 1 (0x00000001)

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. Call this after setDataSource() method.

Returns

  • the current position in milliseconds

public int getDuration()

Gets the duration of the file. Call this after setDataSource() method.

Returns

  • the duration in milliseconds

public Bitmap getFrameAt(int msec)

Returns a Bitmap containing the video frame at the specified time. Call this after setDataSource() or stop().

Parameters

msec the time at which to capture the video frame, in milliseconds

Returns

  • a Bitmap containing the video frame at the specified time

Throws

IllegalStateException if it is called in an order other than the one specified above

public int getVideoHeight()

Returns the height of the video. Call this after setDataSource() method.

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. Call this after setDataSource() method.

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

Checks whether the MediaPlayer is playing. Call this after setDataSource() method.

Returns

  • true if currently playing, false otherwise

public void pause()

Pauses playback. Call start() to resume. Call this after start() and before any other method that might throw IllegalStateException in this class.

Throws

IllegalStateException if it is called in an order other than the one specified above

public void prepare()

Prepares the player for playback, synchronously. Call this after setDataSource() or stop(), and before any other method that might throw IllegalStateException in this class. 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 order other than the one specified above
IOException

public void prepareAsync()

Prepares the player for playback, asynchronously. Call this after setDataSource() or stop(), and before any other method that might throw IllegalStateException in this class. 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 order other than the one specified above

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. Call this after start(), pause(), or prepare(), or after receiving onPrepared or onCompletion event notification from OnPreparedListener or OnCompletionListener interface.

Parameters

msec the offset in milliseconds from the start to seek to

Throws

IllegalStateException if it is called in an order other than the one specified above

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. Call this after reset(), or before any other method (including setDataSource()) that might throw IllegalStateException in this class.

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 order other than the one specified above
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. Call this after reset(), or before any other method (including setDataSource()) that might throw IllegalStateException in this class.

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 order other than the one specified above
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. Call this after reset(), or before any other method (including setDataSource()) that might throw IllegalStateException in this class.

Parameters

fd the FileDescriptor for the file you want to play

Throws

IllegalStateException if it is called in an order other than the one specified above
IOException
IllegalArgumentException

public void setDataSource(Context context, Uri uri)

Sets the data source as a content Uri. Call this after reset(), or before any other method (including setDataSource()) that might throw IllegalStateException in this class.

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 order other than the one specified above
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. Call this after setDataSource method.

Parameters

looping whether to loop or not

public void setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener l)

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

Parameters

l the callback that will be run

public void setOnCompletionListener(MediaPlayer.OnCompletionListener l)

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

Parameters

l the callback that will be run

public void setOnErrorListener(MediaPlayer.OnErrorListener l)

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

Parameters

l the callback that will be run

public void setOnPreparedListener(MediaPlayer.OnPreparedListener l)

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

Parameters

l the callback that will be run

public void setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener l)

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

Parameters

l 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. Call after setDataSource method. 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 AudioManager::setStreamVolume API 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. Call this after receiving onCompletion or onPrepared event notification from OnCompletionListener or OnPreparedListener interface, or called after prepare() or pause().

Throws

IllegalStateException if it is called in an order other than the one specified above

public void stop()

Stops playback after playback has been stopped or paused. Call this after start() or pause(), or after receiving the onPrepared event notification from OnPreparedListener interface.

Throws

IllegalStateException if it is called in an order other than the one specified above

Protected Methods

protected void finalize()

Called by the virtual machine when there are no longer any (non-weak) references to the receiver. Subclasses can use this facility to guarantee that any associated resources are cleaned up before the receiver is garbage collected. Uncaught exceptions which are thrown during the running of the method cause it to terminate immediately, but are otherwise ignored.

Note: The virtual machine assumes that the implementation in class Object is empty.

Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48