Build 1.0_r1(from source)

android.media
Class MediaPlayer

java.lang.Object
  extended by android.media.MediaPlayer

public class MediaPlayer
extends Object

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


Nested Class Summary
static interface MediaPlayer.OnBufferingUpdateListener
          Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network.
static interface MediaPlayer.OnCompletionListener
          Interface definition for a callback to be invoked when playback of a media file has completed.
static 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).
static interface MediaPlayer.OnPreparedListener
          Interface definition for a callback to be invoked when the media file is ready for playback.
static interface MediaPlayer.OnSeekCompleteListener
          Interface definition of a callback to be invoked indicating the completion of a seek operation.
 
Field Summary
static int MEDIA_ERROR_SERVER_DIED
          Media server died.
static int MEDIA_ERROR_UNKNOWN
          Unspecified media player error.
 
Constructor Summary
MediaPlayer()
          Default constructor.
 
Method Summary
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.
static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder)
          Convenience method to create a MediaPlayer for a given Uri.
protected  void finalize()
          Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
 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(Context context, Uri uri)
          Sets the data source as a content Uri.
 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 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.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MEDIA_ERROR_UNKNOWN

public static final int MEDIA_ERROR_UNKNOWN
Unspecified media player error. @see #OnErrorListener

See Also:
Constant Field Values

MEDIA_ERROR_SERVER_DIED

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

See Also:
Constant Field Values
Constructor Detail

MediaPlayer

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.

Method Detail

setDisplay

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

create

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

create

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

create

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

setDataSource

public void setDataSource(Context context,
                          Uri uri)
                   throws IOException,
                          IllegalArgumentException,
                          SecurityException,
                          IllegalStateException
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

setDataSource

public void setDataSource(String path)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException
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

setDataSource

public void setDataSource(FileDescriptor fd)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException
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

setDataSource

public void setDataSource(FileDescriptor fd,
                          long offset,
                          long length)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException
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

prepare

public void prepare()
             throws IOException,
                    IllegalStateException
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

prepareAsync

public void prepareAsync()
                  throws IllegalStateException
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

start

public void start()
           throws IllegalStateException
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

stop

public void stop()
          throws IllegalStateException
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

pause

public void pause()
           throws IllegalStateException
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

setWakeMode

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 Manifest.permission.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:
PowerManager

setScreenOnWhilePlaying

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(android.content.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.

getVideoWidth

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

getVideoHeight

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

isPlaying

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

Returns:
true if currently playing, false otherwise

seekTo

public void seekTo(int msec)
            throws IllegalStateException
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

getCurrentPosition

public int getCurrentPosition()
Gets the current playback position. Call this after setDataSource() method.

Returns:
the current position in milliseconds

getDuration

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

Returns:
the duration in milliseconds

release

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.


reset

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


setAudioStreamType

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:
AudioManager

setLooping

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

setVolume

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

getFrameAt

public Bitmap getFrameAt(int msec)
                  throws IllegalStateException
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

finalize

protected void finalize()
Description copied from class: Object
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.

Overrides:
finalize in class Object

setOnPreparedListener

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

setOnCompletionListener

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

setOnBufferingUpdateListener

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

setOnSeekCompleteListener

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

setOnErrorListener

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

Build 1.0_r1(from source)

Please submit a feedback, bug or feature