android.media
public
class
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
Summary
Constants
Public Constructors
Public Methods
Protected Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
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
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
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
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.
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.
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.
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 |
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 |
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 |
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 |
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 |
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 |
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
|
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
|
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
|
Register a callback to be invoked when an error has happened
during an asynchronous operation.
Parameters
l
| the callback that will be run
|
Register a callback to be invoked when the media file is ready
for playback.
Parameters
l
| the callback that will be run
|
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 |
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().
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.
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.