public class MediaPlayer extends Object
VideoView
.
Topics covered here are:
For more information about how to use MediaPlayer, read the Media Playback developer guide.
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.
From this state diagram, one can see that a MediaPlayer object has the following states:
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.
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. 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. 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.
setOnErrorListener(android.media.MediaPlayer.OnErrorListener)
.
reset()
can be called to restore the object to its Idle
state.prepare()
,
prepareAsync()
, or one of the overloaded setDataSource
methods in an invalid state. 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.
IllegalArgumentException
and IOException
that may be thrown from the overloaded
setDataSource
methods.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)
.prepare()
or prepareAsync()
is called in
any other state.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.
setOnBufferingUpdateListener(OnBufferingUpdateListener)
.
This callback allows applications to keep track of the buffering status
while streaming audio/video.start()
has not effect
on a MediaPlayer object that is already in the Started state.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.
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.pause()
has no effect on
a MediaPlayer object that is already in the Paused state.stop()
stops playback and causes a
MediaPlayer in the Started, Paused, Prepared
or PlaybackCompleted state to enter the
Stopped state.
prepare()
or prepareAsync()
are called to set
the MediaPlayer object to the Prepared state again.stop()
has no effect on a MediaPlayer
object that is already in the Stopped state.seekTo(int)
.
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)
.seekTo(int)
can also be called in the other states,
such as Prepared, Paused and PlaybackCompleted
state.getCurrentPosition()
, which
is helpful for applications such as a Music player that need to keep
track of the playback progress.setLooping(boolean)
, the MediaPlayer object shall remain in
the Started state.setOnCompletionListener(OnCompletionListener)
.
The invoke of the callback signals that the object is now in the
PlaybackCompleted state.start()
can restart the playback from the
beginning of the audio/video source.Method Name | Valid Sates | Invalid States | Comments |
attachAuxEffect | {Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} | {Idle, Error} | This method must be called after setDataSource. Calling it does not change the object state. |
getAudioSessionId | any | {} | This method can be called in any state and calling it does not change the object state. |
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. |
setAudioSessionId | {Idle} | {Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error} | This method must be called in idle state as the audio session ID must be known before calling setDataSource. Calling it does not change the object state. |
setAudioStreamType | {Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted} | {Error} | Successful invoke of this method does not change the state. In order for the target audio stream type to become effective, this method must be called before prepare() or prepareAsync(). |
setAuxEffectSendLevel | any | {} | Calling this method does not change the object 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. |
setSurface | any | {} | This method can be called in any state and calling it does not change the object state. |
setVideoScalingMode | {Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} | {Idle, Error} | Successful invoke of this method does not change the 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. |
getTrackInfo | {Prepared, Started, Stopped, Paused, PlaybackCompleted} | {Idle, Initialized, Error} | Successful invoke of this method does not change the state. |
addTimedTextSource | {Prepared, Started, Stopped, Paused, PlaybackCompleted} | {Idle, Initialized, Error} | Successful invoke of this method does not change the state. |
selectTrack | {Prepared, Started, Stopped, Paused, PlaybackCompleted} | {Idle, Initialized, Error} | Successful invoke of this method does not change the state. |
deselectTrack | {Prepared, Started, Stopped, Paused, PlaybackCompleted} | {Idle, Initialized, Error} | Successful invoke of this method does not change the state. |
One may need to declare a corresponding WAKE_LOCK permission <uses-permission>
element.
This class requires the android.Manifest.permission#INTERNET
permission
when used with network-based content.
Applications may want to register for informational and error
events in order to be informed of some internal state update and
possible runtime errors during playback or streaming. Registration for
these events is done by properly setting the appropriate listeners (via calls
to
setOnPreparedListener(OnPreparedListener)
setOnPreparedListener,
setOnVideoSizeChangedListener(OnVideoSizeChangedListener)
setOnVideoSizeChangedListener,
setOnSeekCompleteListener(OnSeekCompleteListener)
setOnSeekCompleteListener,
setOnCompletionListener(OnCompletionListener)
setOnCompletionListener,
setOnBufferingUpdateListener(OnBufferingUpdateListener)
setOnBufferingUpdateListener,
setOnInfoListener(OnInfoListener)
setOnInfoListener,
setOnErrorListener(OnErrorListener)
setOnErrorListener, etc).
In order to receive the respective callback
associated with these listeners, applications are required to create
MediaPlayer objects on a thread with its own Looper running (main UI
thread by default has a Looper running).
Modifier and Type | Class and Description |
---|---|
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 source 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.OnInfoListener
Interface definition of a callback to be invoked to communicate some
info and/or warning about the media or its playback.
|
static interface |
MediaPlayer.OnPreparedListener
Interface definition for a callback to be invoked when the media
source is ready for playback.
|
static interface |
MediaPlayer.OnSeekCompleteListener
Interface definition of a callback to be invoked indicating
the completion of a seek operation.
|
static interface |
MediaPlayer.OnTimedTextListener
Interface definition of a callback to be invoked when a
timed text is available for display.
|
static interface |
MediaPlayer.OnVideoSizeChangedListener
Interface definition of a callback to be invoked when the
video size is first known or updated
|
static class |
MediaPlayer.TrackInfo
Class for MediaPlayer to return each audio/video/subtitle track's metadata.
|
Modifier and Type | Field and Description |
---|---|
static boolean |
APPLY_METADATA_FILTER
Constant to enable the metadata filter during retrieval.
|
static boolean |
BYPASS_METADATA_FILTER
Constant to disable the metadata filter during retrieval.
|
static int |
MEDIA_ERROR_IO
File or network related operation errors.
|
static int |
MEDIA_ERROR_MALFORMED
Bitstream is not conforming to the related coding standard or file spec.
|
static 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.
|
static int |
MEDIA_ERROR_SERVER_DIED
Media server died.
|
static int |
MEDIA_ERROR_TIMED_OUT
Some operation takes too long to complete, usually more than 3-5 seconds.
|
static int |
MEDIA_ERROR_UNKNOWN
Unspecified media player error.
|
static int |
MEDIA_ERROR_UNSUPPORTED
Bitstream is conforming to the related coding standard or file spec, but
the media framework does not support the feature.
|
static 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.
|
static int |
MEDIA_INFO_BUFFERING_END
MediaPlayer is resuming playback after filling buffers.
|
static int |
MEDIA_INFO_BUFFERING_START
MediaPlayer is temporarily pausing playback internally in order to
buffer more data.
|
static int |
MEDIA_INFO_METADATA_UPDATE
A new set of metadata is available.
|
static int |
MEDIA_INFO_NOT_SEEKABLE
The media cannot be seeked (e.g live stream)
|
static int |
MEDIA_INFO_STARTED_AS_NEXT
The player was started because it was used as the next player for another
player, which just completed playback.
|
static int |
MEDIA_INFO_TIMED_TEXT_ERROR
Failed to handle timed text track properly.
|
static int |
MEDIA_INFO_UNKNOWN
Unspecified media player info.
|
static int |
MEDIA_INFO_VIDEO_RENDERING_START
The player just pushed the very first video frame for rendering.
|
static int |
MEDIA_INFO_VIDEO_TRACK_LAGGING
The video is too complex for the decoder: it can't decode frames fast
enough.
|
static String |
MEDIA_MIMETYPE_TEXT_SUBRIP
MIME type for SubRip (SRT) container.
|
static boolean |
METADATA_ALL
Constant to retrieve all the metadata.
|
static boolean |
METADATA_UPDATE_ONLY
Constant to retrieve only the new metadata since the last
call.
|
static int |
VIDEO_SCALING_MODE_SCALE_TO_FIT
Specifies a video scaling mode.
|
static int |
VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
Specifies a video scaling mode.
|
Constructor and Description |
---|
MediaPlayer()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
addTimedTextSource(Context context,
Uri uri,
String mimeType)
Adds an external timed text source file (Uri).
|
void |
addTimedTextSource(FileDescriptor fd,
long offset,
long length,
String mimeType)
Adds an external timed text file (FileDescriptor).
|
void |
addTimedTextSource(FileDescriptor fd,
String mimeType)
Adds an external timed text source file (FileDescriptor).
|
void |
addTimedTextSource(String path,
String mimeType)
Adds an external timed text source file.
|
void |
attachAuxEffect(int effectId)
Attaches an auxiliary effect to the player.
|
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.
|
void |
deselectTrack(int index)
Deselect a track.
|
protected void |
finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
|
int |
getAudioSessionId()
Returns the audio session ID.
|
int |
getCurrentPosition()
Gets the current playback position.
|
int |
getDuration()
Gets the duration of the file.
|
Bitmap |
getFrameAt(int msec)
Deprecated.
|
int |
getIntParameter(int key)
Gets the value of the parameter indicated by key.
|
Metadata |
getMetadata(boolean update_only,
boolean apply_filter)
Gets the media metadata.
|
Parcel |
getParcelParameter(int key)
Gets the value of the parameter indicated by key.
|
String |
getStringParameter(int key)
Gets the value of the parameter indicated by key.
|
MediaPlayer.TrackInfo[] |
getTrackInfo()
Returns an array of track information.
|
int |
getVideoHeight()
Returns the height of the video.
|
int |
getVideoWidth()
Returns the width of the video.
|
void |
invoke(Parcel request,
Parcel reply)
Invoke a generic method on the native player using opaque
parcels for the request and reply.
|
boolean |
isLooping()
Checks whether the MediaPlayer is looping or non-looping.
|
boolean |
isPlaying()
Checks whether the MediaPlayer is playing.
|
static int |
native_pullBatteryData(Parcel reply) |
Parcel |
newRequest()
Create a request parcel which can be routed to the native media
player using
invoke(Parcel, Parcel) . |
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 |
selectTrack(int index)
Selects a track.
|
void |
setAudioSessionId(int sessionId)
Sets the audio session ID.
|
void |
setAudioStreamType(int streamtype)
Sets the audio stream type for this MediaPlayer.
|
void |
setAuxEffectSendLevel(float level)
Sets the send level of the player to the attached auxiliary effect
attachAuxEffect(int) . |
void |
setDataSource(Context context,
Uri uri)
Sets the data source as a content Uri.
|
void |
setDataSource(Context context,
Uri uri,
Map<String,String> headers)
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 |
setDataSource(String path,
Map<String,String> headers)
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.
|
int |
setMetadataFilter(Set<Integer> allow,
Set<Integer> block)
Set a filter for the metadata update notification and update
retrieval.
|
void |
setNextMediaPlayer(MediaPlayer next)
Set the MediaPlayer to start when this MediaPlayer finishes playback
(i.e.
|
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 |
setOnTimedTextListener(MediaPlayer.OnTimedTextListener listener)
Register a callback to be invoked when a timed text is available
for display.
|
void |
setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener)
Register a callback to be invoked when the video size is
known or updated.
|
boolean |
setParameter(int key,
int value)
Sets the parameter indicated by key.
|
boolean |
setParameter(int key,
Parcel value)
Sets the parameter indicated by key.
|
boolean |
setParameter(int key,
String value)
Sets the parameter indicated by key.
|
void |
setRetransmitEndpoint(InetSocketAddress endpoint)
Sets the target UDP re-transmit endpoint for the low level player.
|
void |
setScreenOnWhilePlaying(boolean screenOn)
Control whether we should use the attached SurfaceHolder to keep the
screen on while video playback is occurring.
|
void |
setSurface(Surface surface)
Sets the
Surface to be used as the sink for the video portion of
the media. |
void |
setVideoScalingMode(int mode)
Sets video scaling mode.
|
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.
|
public static final boolean METADATA_UPDATE_ONLY
public static final boolean METADATA_ALL
public static final boolean APPLY_METADATA_FILTER
public static final boolean BYPASS_METADATA_FILTER
public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT
VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
,
there is no content cropping with this video scaling mode.public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
public static final String MEDIA_MIMETYPE_TEXT_SUBRIP
public static final int MEDIA_ERROR_UNKNOWN
public static final int MEDIA_ERROR_SERVER_DIED
public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK
public static final int MEDIA_ERROR_IO
public static final int MEDIA_ERROR_MALFORMED
public static final int MEDIA_ERROR_UNSUPPORTED
public static final int MEDIA_ERROR_TIMED_OUT
public static final int MEDIA_INFO_UNKNOWN
public static final int MEDIA_INFO_STARTED_AS_NEXT
public static final int MEDIA_INFO_VIDEO_RENDERING_START
public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING
public static final int MEDIA_INFO_BUFFERING_START
public static final int MEDIA_INFO_BUFFERING_END
public static final int MEDIA_INFO_BAD_INTERLEAVING
public static final int MEDIA_INFO_NOT_SEEKABLE
public static final int MEDIA_INFO_METADATA_UPDATE
public static final int MEDIA_INFO_TIMED_TEXT_ERROR
{@hide}
,
Constant Field Valuespublic MediaPlayer()
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 Parcel newRequest()
invoke(Parcel, Parcel)
. The Parcel
returned has the proper InterfaceToken set. The caller should
not overwrite that token, i.e it can only append data to the
Parcel.public void invoke(Parcel request, Parcel reply)
request
- Parcel with the data for the extension. The
caller must use newRequest()
to get one.reply
- Output parcel with the data returned by the
native player.
public void setDisplay(SurfaceHolder sh)
SurfaceHolder
to use for displaying the video
portion of the media.
Either a surface holder or surface must be set if a display or video sink
is needed. Not calling this method or setSurface(Surface)
when playing back a video will result in only the audio track being played.
A null surface holder or surface will result in only the audio track being
played.sh
- the SurfaceHolder to use for video displaypublic void setSurface(Surface surface)
Surface
to be used as the sink for the video portion of
the media. This is similar to setDisplay(SurfaceHolder)
, but
does not support setScreenOnWhilePlaying(boolean)
. Setting a
Surface will un-set any Surface or SurfaceHolder that was previously set.
A null surface will result in only the audio track being played.
If the Surface sends frames to a SurfaceTexture
, the timestamps
returned from SurfaceTexture.getTimestamp()
will have an
unspecified zero point. These timestamps cannot be directly compared
between different media sources, different instances of the same media
source, or multiple runs of the same program. The timestamp is normally
monotonically increasing and is unaffected by time-of-day adjustments,
but it is reset when the position is set.surface
- The Surface
to be used for the video portion of
the media.public void setVideoScalingMode(int mode)
VIDEO_SCALING_MODE_SCALE_TO_FIT
.
The supported video scaling modes are:
mode
- target video scaling mode. Most be one of the supported
video scaling modes; otherwise, IllegalArgumentException will be thrown.VIDEO_SCALING_MODE_SCALE_TO_FIT
,
VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
public static MediaPlayer create(Context context, Uri uri)
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.
context
- the Context to useuri
- the Uri from which to get the datasourcepublic static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder)
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.
context
- the Context to useuri
- the Uri from which to get the datasourceholder
- the SurfaceHolder to use for displaying the videopublic static MediaPlayer create(Context context, int resid)
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.
context
- the Context to useresid
- the raw resource id (R.raw.<something>) for
the resource to use as the datasourcepublic void setDataSource(Context context, Uri uri) throws IOException, IllegalArgumentException, SecurityException, IllegalStateException
context
- the Context to use when resolving the Uriuri
- the Content URI of the data you want to playIllegalStateException
- if it is called in an invalid stateIOException
IllegalArgumentException
SecurityException
public void setDataSource(Context context, Uri uri, Map<String,String> headers) throws IOException, IllegalArgumentException, SecurityException, IllegalStateException
context
- the Context to use when resolving the Uriuri
- the Content URI of the data you want to playheaders
- the headers to be sent together with the request for the dataIllegalStateException
- if it is called in an invalid stateIOException
IllegalArgumentException
SecurityException
public void setDataSource(String path) throws IOException, IllegalArgumentException, SecurityException, IllegalStateException
path
- the path of the file, or the http/rtsp URL of the stream you want to playIllegalStateException
- if it is called in an invalid state
When path
refers to a local file, the file may actually be opened by a
process other than the calling application. This implies that the pathname
should be an absolute path (as any other process runs with unspecified current working
directory), and that the pathname should reference a world-readable file.
As an alternative, the application could first open the file for reading,
and then use the file descriptor form setDataSource(FileDescriptor)
.
IOException
IllegalArgumentException
SecurityException
public void setDataSource(String path, Map<String,String> headers) throws IOException, IllegalArgumentException, SecurityException, IllegalStateException
path
- the path of the file, or the http/rtsp URL of the stream you want to playheaders
- the headers associated with the http request for the stream you want to playIllegalStateException
- if it is called in an invalid stateIOException
IllegalArgumentException
SecurityException
public void setDataSource(FileDescriptor fd) throws IOException, IllegalArgumentException, IllegalStateException
fd
- the FileDescriptor for the file you want to playIllegalStateException
- if it is called in an invalid stateIOException
IllegalArgumentException
public void setDataSource(FileDescriptor fd, long offset, long length) throws IOException, IllegalArgumentException, IllegalStateException
fd
- the FileDescriptor for the file you want to playoffset
- the offset into the file where the data to be played starts, in byteslength
- the length in bytes of the data to be playedIllegalStateException
- if it is called in an invalid stateIOException
IllegalArgumentException
public void prepare() throws IOException, IllegalStateException
IllegalStateException
- if it is called in an invalid stateIOException
public void prepareAsync() throws IllegalStateException
IllegalStateException
- if it is called in an invalid statepublic void start() throws IllegalStateException
IllegalStateException
- if it is called in an invalid statepublic void stop() throws IllegalStateException
IllegalStateException
- if the internal player engine has not been
initialized.public void pause() throws IllegalStateException
IllegalStateException
- if the internal player engine has not been
initialized.public void setWakeMode(Context context, int mode)
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 android.Manifest.permission#WAKE_LOCK
permission.
By default, no attempt is made to keep the device awake during playback.
context
- the Context to usemode
- the power/wake mode to setPowerManager
public void setScreenOnWhilePlaying(boolean screenOn)
setWakeMode(android.content.Context, int)
where possible, since it doesn't
require that the application have permission for low-level wake lock
access.screenOn
- Supply true to keep the screen on, false to allow it
to turn off.public int getVideoWidth()
setOnVideoSizeChangedListener(OnVideoSizeChangedListener)
to provide a notification when the width is available.public int getVideoHeight()
setOnVideoSizeChangedListener(OnVideoSizeChangedListener)
to provide a notification when the height is available.public boolean isPlaying()
IllegalStateException
- if the internal player engine has not been
initialized or has been released.public void seekTo(int msec) throws IllegalStateException
msec
- the offset in milliseconds from the start to seek toIllegalStateException
- if the internal player engine has not been
initializedpublic int getCurrentPosition()
public int getDuration()
public Metadata getMetadata(boolean update_only, boolean apply_filter)
update_only
- controls whether the full set of available
metadata is returned or just the set that changed since the
last call. See METADATA_UPDATE_ONLY
and METADATA_ALL
.apply_filter
- if true only metadata that matches the
filter is returned. See APPLY_METADATA_FILTER
and BYPASS_METADATA_FILTER
.public int setMetadataFilter(Set<Integer> allow, Set<Integer> block)
allow
- Is the set of metadata the client is interested
in receiving new notifications for.block
- Is the set of metadata the client is not interested
in receiving new notifications for.public void setNextMediaPlayer(MediaPlayer next)
next
- the player to start after this one completes playback.public void release()
public void reset()
public void setAudioStreamType(int streamtype)
AudioManager
for a list of stream types. Must call this method before prepare() or
prepareAsync() in order for the target stream type to become effective
thereafter.streamtype
- the audio stream typeAudioManager
public void setLooping(boolean looping)
looping
- whether to loop or notpublic boolean isLooping()
public void setVolume(float leftVolume, float rightVolume)
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.leftVolume
- left volume scalarrightVolume
- right volume scalarpublic Bitmap getFrameAt(int msec) throws IllegalStateException
IllegalStateException
public void setAudioSessionId(int sessionId) throws IllegalArgumentException, IllegalStateException
sessionId
- the audio session ID.
The audio session ID is a system wide unique identifier for the audio stream played by
this MediaPlayer instance.
The primary use of the audio session ID is to associate audio effects to a particular
instance of MediaPlayer: if an audio session ID is provided when creating an audio effect,
this effect will be applied only to the audio content of media players within the same
audio session and not to the output mix.
When created, a MediaPlayer instance automatically generates its own audio session ID.
However, it is possible to force this player to be part of an already existing audio session
by calling this method.
This method must be called before one of the overloaded setDataSource
methods.IllegalStateException
- if it is called in an invalid stateIllegalArgumentException
public int getAudioSessionId()
setAudioSessionId(int)
Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed.public void attachAuxEffect(int effectId)
setAuxEffectSendLevel(float)
.
After creating an auxiliary effect (e.g.
EnvironmentalReverb
), retrieve its ID with
AudioEffect.getId()
and use it when calling this method
to attach the player to the effect.
To detach the effect from the player, call this method with a null effect id.
This method must be called after one of the overloaded setDataSource
methods.
effectId
- system wide unique id of the effect to attachpublic boolean setParameter(int key, Parcel value)
key
- key indicates the parameter to be set.value
- value of the parameter to be set.public boolean setParameter(int key, String value)
key
- key indicates the parameter to be set.value
- value of the parameter to be set.public boolean setParameter(int key, int value)
key
- key indicates the parameter to be set.value
- value of the parameter to be set.public Parcel getParcelParameter(int key)
key
- key indicates the parameter to get.public String getStringParameter(int key)
key
- key indicates the parameter to get.public int getIntParameter(int key)
key
- key indicates the parameter to get.public void setAuxEffectSendLevel(float level)
attachAuxEffect(int)
. The level value range is 0 to 1.0.
By default the send level is 0, so even if an effect is attached to the player this method must be called for the effect to be applied.
Note that the passed level value is a raw scalar. UI controls should be scaled logarithmically: the gain applied by audio framework ranges from -72dB to 0dB, so an appropriate conversion from linear UI input x to level is: x == 0 -> level = 0 0 < x <= r -> level = 10^(72*(x-R)/20/R)
level
- send level scalarpublic MediaPlayer.TrackInfo[] getTrackInfo() throws IllegalStateException
IllegalStateException
- if it is called in an invalid state.public void addTimedTextSource(String path, String mimeType) throws IOException, IllegalArgumentException, IllegalStateException
getTrackInfo()
to see what
additional tracks become available after this method call.path
- The file path of external timed text source file.mimeType
- The mime type of the file. Must be one of the mime types listed above.IOException
- if the file cannot be accessed or is corrupted.IllegalArgumentException
- if the mimeType is not supported.IllegalStateException
- if called in an invalid state.public void addTimedTextSource(Context context, Uri uri, String mimeType) throws IOException, IllegalArgumentException, IllegalStateException
getTrackInfo()
to see what
additional tracks become available after this method call.context
- the Context to use when resolving the Uriuri
- the Content URI of the data you want to playmimeType
- The mime type of the file. Must be one of the mime types listed above.IOException
- if the file cannot be accessed or is corrupted.IllegalArgumentException
- if the mimeType is not supported.IllegalStateException
- if called in an invalid state.public void addTimedTextSource(FileDescriptor fd, String mimeType) throws IllegalArgumentException, IllegalStateException
getTrackInfo()
to see what additional tracks become available
after this method call.fd
- the FileDescriptor for the file you want to playmimeType
- The mime type of the file. Must be one of the mime types listed above.IllegalArgumentException
- if the mimeType is not supported.IllegalStateException
- if called in an invalid state.public void addTimedTextSource(FileDescriptor fd, long offset, long length, String mimeType) throws IllegalArgumentException, IllegalStateException
getTrackInfo()
to see what additional tracks become available
after this method call.fd
- the FileDescriptor for the file you want to playoffset
- the offset into the file where the data to be played starts, in byteslength
- the length in bytes of the data to be playedmimeType
- The mime type of the file. Must be one of the mime types listed above.IllegalArgumentException
- if the mimeType is not supported.IllegalStateException
- if called in an invalid state.public void selectTrack(int index) throws IllegalStateException
If a MediaPlayer is in invalid state, it throws an IllegalStateException exception. If a MediaPlayer is in Started state, the selected track is presented immediately. If a MediaPlayer is not in Started state, it just marks the track to be played.
In any valid state, if it is called multiple times on the same type of track (ie. Video, Audio, Timed Text), the most recent one will be chosen.
The first audio and video tracks are selected by default if available, even though this method is not called. However, no timed text track will be selected until this function is called.
Currently, only timed text tracks or audio tracks can be selected via this method. In addition, the support for selecting an audio track at runtime is pretty limited in that an audio track can only be selected in the Prepared state.
index
- the index of the track to be selected. The valid range of the index
is 0..total number of track - 1. The total number of tracks as well as the type of
each individual track can be found by calling getTrackInfo()
method.IllegalStateException
- if called in an invalid state.getTrackInfo()
public void deselectTrack(int index) throws IllegalStateException
Currently, the track must be a timed text track and no audio or video tracks can be deselected. If the timed text track identified by index has not been selected before, it throws an exception.
index
- the index of the track to be deselected. The valid range of the index
is 0..total number of tracks - 1. The total number of tracks as well as the type of
each individual track can be found by calling getTrackInfo()
method.IllegalStateException
- if called in an invalid state.getTrackInfo()
public static int native_pullBatteryData(Parcel reply)
reply
- Parcel with audio/video duration info for battery
tracking usagepublic void setRetransmitEndpoint(InetSocketAddress endpoint) throws IllegalStateException, IllegalArgumentException
endpoint
- the address and UDP port of the re-transmission target or
null if no re-transmission is to be performed.IllegalStateException
- if it is called in an invalid stateIllegalArgumentException
- if the retransmit endpoint is supplied,
but invalid.
pending API councilprotected void finalize()
Object
Note that objects that override finalize
are significantly more expensive than
objects that don't. Finalizers may be run a long time after the object is no longer
reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
Note also that finalizers are run on a single VM-wide finalizer thread,
so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
for a class that has a native peer and needs to call a native method to destroy that peer.
Even then, it's better to provide an explicit close
method (and implement
Closeable
), and insist that callers manually dispose of instances. This
works well for something like files, but less well for something like a BigInteger
where typical calling code would have to deal with lots of temporaries. Unfortunately,
code that creates lots of temporaries is the worst kind of code from the point of view of
the single finalizer thread.
If you must use finalizers, consider at least providing your own
ReferenceQueue
and having your own thread process that queue.
Unlike constructors, finalizers are not automatically chained. You are responsible for
calling super.finalize()
yourself.
Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.
public void setOnPreparedListener(MediaPlayer.OnPreparedListener listener)
listener
- the callback that will be runpublic void setOnCompletionListener(MediaPlayer.OnCompletionListener listener)
listener
- the callback that will be runpublic void setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener listener)
listener
- the callback that will be run.public void setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener listener)
listener
- the callback that will be runpublic void setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener)
listener
- the callback that will be runpublic void setOnTimedTextListener(MediaPlayer.OnTimedTextListener listener)
listener
- the callback that will be runpublic void setOnErrorListener(MediaPlayer.OnErrorListener listener)
listener
- the callback that will be runpublic void setOnInfoListener(MediaPlayer.OnInfoListener listener)
listener
- the callback that will be run