# Print output for @column tags ?>
public
class
MediaPlayer
extends Object
implements
VolumeAutomation,
AudioRouting
java.lang.Object | |
↳ | android.media.MediaPlayer |
MediaPlayer class can be used to control playback
of audio/video files and streams. An example on how to use the methods in
this class can be found in VideoView
.
MediaPlayer is not thread-safe. Creation of and all access to player instances should be on the same thread. If registering callbacks, the thread must have a Looper.
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()
, setAudioAttributes(android.media.AudioAttributes)
,
setLooping(boolean)
,
setVolume(float, float)
, pause()
, start()
,
stop()
, seekTo(long, 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(java.io.FileDescriptor)
, or
setDataSource(java.lang.String)
, or
setDataSource(android.content.Context, android.net.Uri)
, or
setDataSource(java.io.FileDescriptor, long, long)
, or
setDataSource(android.media.MediaDataSource)
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 away) 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(android.media.MediaPlayer.OnBufferingUpdateListener)
.
This callback allows applications to keep track of the buffering status
while streaming audio/video.start()
has no 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(long, int)
.
seekTo(long, int)
call returns right away, 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(android.media.MediaPlayer.OnSeekCompleteListener)
.seekTo(long, int)
can also be called in the other states,
such as Prepared, Paused and PlaybackCompleted
state. When seekTo(long, int)
is called in those states,
one video frame will be displayed if the stream has video and the requested
position is valid.
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(android.media.MediaPlayer.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 States | 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, PlaybackCompleted} | {Idle, Initialized, Prepared, Stopped, 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. |
setAudioAttributes | {Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted} | {Error} | Successful invoke of this method does not change the state. In order for the target audio attributes type to become effective, this method must be called before prepare() or prepareAsync(). |
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 (deprecated) | {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. |
setPlaybackParams | {Initialized, Prepared, Started, Paused, PlaybackCompleted, Error} | {Idle, Stopped} | This method will change state in some cases, depending on when it's called. |
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 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
,
setOnVideoSizeChangedListener
,
setOnSeekCompleteListener
,
setOnCompletionListener
,
setOnBufferingUpdateListener
,
setOnInfoListener
,
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).
Nested classes | |
---|---|
class |
MediaPlayer.DrmInfo
Encapsulates the DRM properties of the source. |
class |
MediaPlayer.MetricsConstants
|
class |
MediaPlayer.NoDrmSchemeException
Thrown when a DRM method is called before preparing a DRM scheme through prepareDrm(). |
interface |
MediaPlayer.OnBufferingUpdateListener
Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network. |
interface |
MediaPlayer.OnCompletionListener
Interface definition for a callback to be invoked when playback of a media source has completed. |
interface |
MediaPlayer.OnDrmConfigHelper
Interface definition of a callback to be invoked when the app can do DRM configuration (get/set properties) before the session is opened. |
interface |
MediaPlayer.OnDrmInfoListener
Interface definition of a callback to be invoked when the DRM info becomes available |
interface |
MediaPlayer.OnDrmPreparedListener
Interface definition of a callback to notify the app when the DRM is ready for key request/response |
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). |
interface |
MediaPlayer.OnInfoListener
Interface definition of a callback to be invoked to communicate some info and/or warning about the media or its playback. |
interface |
MediaPlayer.OnMediaTimeDiscontinuityListener
Interface definition of a callback to be invoked when discontinuity in the normal progression of the media time is detected. |
interface |
MediaPlayer.OnPreparedListener
Interface definition for a callback to be invoked when the media source is ready for playback. |
interface |
MediaPlayer.OnSeekCompleteListener
Interface definition of a callback to be invoked indicating the completion of a seek operation. |
interface |
MediaPlayer.OnSubtitleDataListener
Interface definition of a callback to be invoked when a player subtitle track has new subtitle data available. |
interface |
MediaPlayer.OnTimedMetaDataAvailableListener
Interface definition of a callback to be invoked when a track has timed metadata available. |
interface |
MediaPlayer.OnTimedTextListener
Interface definition of a callback to be invoked when a timed text is available for display. |
interface |
MediaPlayer.OnVideoSizeChangedListener
Interface definition of a callback to be invoked when the video size is first known or updated |
class |
MediaPlayer.ProvisioningNetworkErrorException
Thrown when the device requires DRM provisioning but the provisioning attempt has failed due to a network error (Internet reachability, timeout, etc.). |
class |
MediaPlayer.ProvisioningServerErrorException
Thrown when the device requires DRM provisioning but the provisioning attempt has failed due to the provisioning server denying the request. |
class |
MediaPlayer.TrackInfo
Class for MediaPlayer to return each audio/video/subtitle track's metadata. |
Constants | |
---|---|
int |
MEDIA_ERROR_IO
File or network related operation errors. |
int |
MEDIA_ERROR_MALFORMED
Bitstream is not conforming to the related coding standard or file spec. |
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. |
int |
MEDIA_ERROR_SERVER_DIED
Media server died. |
int |
MEDIA_ERROR_TIMED_OUT
Some operation takes too long to complete, usually more than 3-5 seconds. |
int |
MEDIA_ERROR_UNKNOWN
Unspecified media player error. |
int |
MEDIA_ERROR_UNSUPPORTED
Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature. |
int |
MEDIA_INFO_AUDIO_NOT_PLAYING
Informs that audio is not playing. |
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. |
int |
MEDIA_INFO_BUFFERING_END
MediaPlayer is resuming playback after filling buffers. |
int |
MEDIA_INFO_BUFFERING_START
MediaPlayer is temporarily pausing playback internally in order to buffer more data. |
int |
MEDIA_INFO_METADATA_UPDATE
A new set of metadata is available. |
int |
MEDIA_INFO_NOT_SEEKABLE
The media cannot be seeked (e.g live stream) |
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. |
int |
MEDIA_INFO_SUBTITLE_TIMED_OUT
Reading the subtitle track takes too long. |
int |
MEDIA_INFO_UNKNOWN
Unspecified media player info. |
int |
MEDIA_INFO_UNSUPPORTED_SUBTITLE
Subtitle track was not supported by the media framework. |
int |
MEDIA_INFO_VIDEO_NOT_PLAYING
Informs that video is not playing. |
int |
MEDIA_INFO_VIDEO_RENDERING_START
The player just pushed the very first video frame for rendering. |
int |
MEDIA_INFO_VIDEO_TRACK_LAGGING
The video is too complex for the decoder: it can't decode frames fast enough. |
String |
MEDIA_MIMETYPE_TEXT_SUBRIP
This constant is deprecated.
use |
int |
PREPARE_DRM_STATUS_PREPARATION_ERROR
The DRM preparation has failed . |
int |
PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR
The device required DRM provisioning but couldn't reach the provisioning server. |
int |
PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR
The device required DRM provisioning but the provisioning server denied the request. |
int |
PREPARE_DRM_STATUS_SUCCESS
The status codes for |
int |
SEEK_CLOSEST
This mode is used with |
int |
SEEK_CLOSEST_SYNC
This mode is used with |
int |
SEEK_NEXT_SYNC
This mode is used with |
int |
SEEK_PREVIOUS_SYNC
This mode is used with |
int |
VIDEO_SCALING_MODE_SCALE_TO_FIT
Specifies a video scaling mode. |
int |
VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
Specifies a video scaling mode. |
Public constructors | |
---|---|
MediaPlayer()
Default constructor. |
Public methods | |
---|---|
void
|
addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener, Handler handler)
Adds an |
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
|
addTimedTextSource(FileDescriptor fd, long offset, long length, String mime)
Adds an external timed text file (FileDescriptor). |
void
|
addTimedTextSource(Context context, Uri uri, String mimeType)
Adds an external timed text source file (Uri). |
void
|
attachAuxEffect(int effectId)
Attaches an auxiliary effect to the player. |
void
|
clearOnMediaTimeDiscontinuityListener()
Clears the listener previously set with
|
void
|
clearOnSubtitleDataListener()
Clears the listener previously set with
|
static
MediaPlayer
|
create(Context context, Uri uri, SurfaceHolder holder, AudioAttributes audioAttributes, int audioSessionId)
Same factory method as |
static
MediaPlayer
|
create(Context context, int resid, AudioAttributes audioAttributes, int audioSessionId)
Same factory method as |
static
MediaPlayer
|
create(Context context, Uri uri, SurfaceHolder holder)
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)
Convenience method to create a MediaPlayer for a given Uri. |
VolumeShaper
|
createVolumeShaper(VolumeShaper.Configuration configuration)
Returns a |
void
|
deselectTrack(int index)
Deselect a track. |
int
|
getAudioSessionId()
Returns the audio session ID. |
int
|
getCurrentPosition()
Gets the current playback position. |
MediaPlayer.DrmInfo
|
getDrmInfo()
Retrieves the DRM Info associated with the current source |
String
|
getDrmPropertyString(String propertyName)
Read a DRM engine plugin String property value, given the property name string. |
int
|
getDuration()
Gets the duration of the file. |
MediaDrm.KeyRequest
|
getKeyRequest(byte[] keySetId, byte[] initData, String mimeType, int keyType, Map<String, String> optionalParameters)
A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content. |
PersistableBundle
|
getMetrics()
Return Metrics data about the current player. |
PlaybackParams
|
getPlaybackParams()
Gets the playback params, containing the current playback rate. |
AudioDeviceInfo
|
getPreferredDevice()
Returns the selected output specified by |
AudioDeviceInfo
|
getRoutedDevice()
Returns an |
int
|
getSelectedTrack(int trackType)
Returns the index of the audio, video, or subtitle track currently selected for playback,
The return value is an index into the array returned by |
SyncParams
|
getSyncParams()
Gets the A/V sync mode. |
MediaTimestamp
|
getTimestamp()
Get current playback position as a |
TrackInfo[]
|
getTrackInfo()
Returns an array of track information. |
int
|
getVideoHeight()
Returns the height of the video. |
int
|
getVideoWidth()
Returns the width of the video. |
boolean
|
isLooping()
Checks whether the MediaPlayer is looping or non-looping. |
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
|
prepareDrm(UUID uuid)
Prepares the DRM for the current source
If |
byte[]
|
provideKeyResponse(byte[] keySetId, byte[] response)
A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse. |
void
|
release()
Releases resources associated with this MediaPlayer object. |
void
|
releaseDrm()
Releases the DRM session The player has to have an active DRM session and be in stopped, or prepared state before this call is made. |
void
|
removeOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener)
Removes an |
void
|
reset()
Resets the MediaPlayer to its uninitialized state. |
void
|
restoreKeys(byte[] keySetId)
Restore persisted offline keys into a new session. |
void
|
seekTo(int msec)
Seeks to specified time position. |
void
|
seekTo(long msec, int mode)
Moves the media to specified time position by considering the given mode. |
void
|
selectTrack(int index)
Selects a track. |
void
|
setAudioAttributes(AudioAttributes attributes)
Sets the audio attributes for this MediaPlayer. |
void
|
setAudioSessionId(int sessionId)
Sets the audio session ID. |
void
|
setAudioStreamType(int streamtype)
This method is deprecated.
use |
void
|
setAuxEffectSendLevel(float level)
Sets the send level of the player to the attached auxiliary effect. |
void
|
setDataSource(AssetFileDescriptor afd)
Sets the data source (AssetFileDescriptor) to use. |
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(Context context, Uri uri, Map<String, String> headers, List<HttpCookie> cookies)
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(MediaDataSource dataSource)
Sets the data source (MediaDataSource) to use. |
void
|
setDataSource(Context context, Uri uri)
Sets the data source as a content Uri. |
void
|
setDisplay(SurfaceHolder sh)
Sets the |
void
|
setDrmPropertyString(String propertyName, String value)
Set a DRM engine plugin String property value. |
void
|
setLooping(boolean looping)
Sets the player to be looping or non-looping. |
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
|
setOnDrmConfigHelper(MediaPlayer.OnDrmConfigHelper listener)
Register a callback to be invoked for configuration of the DRM object before the session is created. |
void
|
setOnDrmInfoListener(MediaPlayer.OnDrmInfoListener listener)
Register a callback to be invoked when the DRM info is known. |
void
|
setOnDrmInfoListener(MediaPlayer.OnDrmInfoListener listener, Handler handler)
Register a callback to be invoked when the DRM info is known. |
void
|
setOnDrmPreparedListener(MediaPlayer.OnDrmPreparedListener listener, Handler handler)
Register a callback to be invoked when the DRM object is prepared. |
void
|
setOnDrmPreparedListener(MediaPlayer.OnDrmPreparedListener listener)
Register a callback to be invoked when the DRM object is prepared. |
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
|
setOnMediaTimeDiscontinuityListener(MediaPlayer.OnMediaTimeDiscontinuityListener listener, Handler handler)
Sets the listener to be invoked when a media time discontinuity is encountered. |
void
|
setOnMediaTimeDiscontinuityListener(MediaPlayer.OnMediaTimeDiscontinuityListener listener)
Sets the listener to be invoked when a media time discontinuity is encountered. |
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
|
setOnSubtitleDataListener(MediaPlayer.OnSubtitleDataListener listener)
Sets the listener to be invoked when a subtitle track has new data available. |
void
|
setOnSubtitleDataListener(MediaPlayer.OnSubtitleDataListener listener, Handler handler)
Sets the listener to be invoked when a subtitle track has new data available. |
void
|
setOnTimedMetaDataAvailableListener(MediaPlayer.OnTimedMetaDataAvailableListener listener)
Register a callback to be invoked when a selected track has timed metadata available. |
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. |
void
|
setPlaybackParams(PlaybackParams params)
Sets playback rate using |
boolean
|
setPreferredDevice(AudioDeviceInfo deviceInfo)
Specifies an audio device (via an |
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 |
void
|
setSyncParams(SyncParams params)
Sets A/V sync mode. |
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 started or paused. |
Protected methods | |
---|---|
void
|
finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
Inherited methods | |
---|---|
public static final int MEDIA_ERROR_IO
File or network related operation errors.
Constant Value: -1004 (0xfffffc14)
public static final int MEDIA_ERROR_MALFORMED
Bitstream is not conforming to the related coding standard or file spec.
Constant Value: -1007 (0xfffffc11)
public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK
The video is streamed and its container is not valid for progressive playback i.e the video's index (e.g moov atom) is not at the start of the file.
See also:
Constant Value: 200 (0x000000c8)
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 also:
Constant Value: 100 (0x00000064)
public static final int MEDIA_ERROR_TIMED_OUT
Some operation takes too long to complete, usually more than 3-5 seconds.
Constant Value: -110 (0xffffff92)
public static final int MEDIA_ERROR_UNKNOWN
Unspecified media player error.
See also:
Constant Value: 1 (0x00000001)
public static final int MEDIA_ERROR_UNSUPPORTED
Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature.
Constant Value: -1010 (0xfffffc0e)
public static final int MEDIA_INFO_AUDIO_NOT_PLAYING
Informs that audio is not playing. Note that playback of the video is not interrupted.
See also:
Constant Value: 804 (0x00000324)
public static final int MEDIA_INFO_BAD_INTERLEAVING
Bad interleaving means that a media has been improperly interleaved or not interleaved at all, e.g has all the video samples first then all the audio ones. Video is playing but a lot of disk seeks may be happening.
See also:
Constant Value: 800 (0x00000320)
public static final int MEDIA_INFO_BUFFERING_END
MediaPlayer is resuming playback after filling buffers.
See also:
Constant Value: 702 (0x000002be)
public static final int MEDIA_INFO_BUFFERING_START
MediaPlayer is temporarily pausing playback internally in order to buffer more data.
See also:
Constant Value: 701 (0x000002bd)
public static final int MEDIA_INFO_METADATA_UPDATE
A new set of metadata is available.
See also:
Constant Value: 802 (0x00000322)
public static final int MEDIA_INFO_NOT_SEEKABLE
The media cannot be seeked (e.g live stream)
See also:
Constant Value: 801 (0x00000321)
public static final 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.
Constant Value: 2 (0x00000002)
public static final int MEDIA_INFO_SUBTITLE_TIMED_OUT
Reading the subtitle track takes too long.
See also:
Constant Value: 902 (0x00000386)
public static final int MEDIA_INFO_UNKNOWN
Unspecified media player info.
See also:
Constant Value: 1 (0x00000001)
public static final int MEDIA_INFO_UNSUPPORTED_SUBTITLE
Subtitle track was not supported by the media framework.
See also:
Constant Value: 901 (0x00000385)
public static final int MEDIA_INFO_VIDEO_NOT_PLAYING
Informs that video is not playing. Note that playback of the audio is not interrupted.
See also:
Constant Value: 805 (0x00000325)
public static final int MEDIA_INFO_VIDEO_RENDERING_START
The player just pushed the very first video frame for rendering.
See also:
Constant Value: 3 (0x00000003)
public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING
The video is too complex for the decoder: it can't decode frames fast enough. Possibly only the audio plays fine at this stage.
See also:
Constant Value: 700 (0x000002bc)
public static final String MEDIA_MIMETYPE_TEXT_SUBRIP
This constant is deprecated.
use MediaFormat#MIMETYPE_TEXT_SUBRIP
MIME type for SubRip (SRT) container. Used in addTimedTextSource APIs.
Constant Value: "application/x-subrip"
public static final int PREPARE_DRM_STATUS_PREPARATION_ERROR
The DRM preparation has failed .
Constant Value: 3 (0x00000003)
public static final int PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR
The device required DRM provisioning but couldn't reach the provisioning server.
Constant Value: 1 (0x00000001)
public static final int PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR
The device required DRM provisioning but the provisioning server denied the request.
Constant Value: 2 (0x00000002)
public static final int PREPARE_DRM_STATUS_SUCCESS
The status codes for OnDrmPreparedListener#onDrmPrepared
listener.
DRM preparation has succeeded.
Constant Value: 0 (0x00000000)
public static final int SEEK_CLOSEST
This mode is used with seekTo(long, int)
to move media position to
a frame (not necessarily a key frame) associated with a data source that
is located closest to or at the given time.
See also:
Constant Value: 3 (0x00000003)
public static final int SEEK_CLOSEST_SYNC
This mode is used with seekTo(long, int)
to move media position to
a sync (or key) frame associated with a data source that is located
closest to (in time) or at the given time.
See also:
Constant Value: 2 (0x00000002)
public static final int SEEK_NEXT_SYNC
This mode is used with seekTo(long, int)
to move media position to
a sync (or key) frame associated with a data source that is located
right after or at the given time.
See also:
Constant Value: 1 (0x00000001)
public static final int SEEK_PREVIOUS_SYNC
This mode is used with seekTo(long, int)
to move media position to
a sync (or key) frame associated with a data source that is located
right before or at the given time.
See also:
Constant Value: 0 (0x00000000)
public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT
Specifies a video scaling mode. The content is stretched to the
surface rendering area. When the surface has the same aspect ratio
as the content, the aspect ratio of the content is maintained;
otherwise, the aspect ratio of the content is not maintained when video
is being rendered. Unlike VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
,
there is no content cropping with this video scaling mode.
Constant Value: 1 (0x00000001)
public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
Specifies a video scaling mode. The content is scaled, maintaining its aspect ratio. The whole surface area is always used. When the aspect ratio of the content is the same as the surface, no content is cropped; otherwise, content is cropped to fit the surface.
Constant Value: 2 (0x00000002)
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 void addOnRoutingChangedListener (AudioRouting.OnRoutingChangedListener listener, Handler handler)
Adds an AudioRouting.OnRoutingChangedListener
to receive notifications of routing
changes on this MediaPlayer.
Parameters | |
---|---|
listener |
AudioRouting.OnRoutingChangedListener : The AudioRouting.OnRoutingChangedListener interface to receive
notifications of rerouting events. |
handler |
Handler : Specifies the Handler object for the thread on which to execute
the callback. If null , the handler on the main looper will be used. |
public void addTimedTextSource (FileDescriptor fd, String mimeType)
Adds an external timed text source file (FileDescriptor).
It is the caller's responsibility to close the file descriptor.
It is safe to do so as soon as this call returns.
Currently supported format is SubRip. Note that a single external timed text source may
contain multiple tracks in it. One can find the total number of available tracks
using getTrackInfo()
to see what additional tracks become available
after this method call.
Parameters | |
---|---|
fd |
FileDescriptor : the FileDescriptor for the file you want to play |
mimeType |
String : The mime type of the file. Must be one of the mime types listed above. |
Throws | |
---|---|
IllegalArgumentException |
if the mimeType is not supported. |
IllegalStateException |
if called in an invalid state. |
public void addTimedTextSource (String path, String mimeType)
Adds an external timed text source file.
Currently supported format is SubRip with the file extension .srt, case insensitive.
Note that a single external timed text source may contain multiple tracks in it.
One can find the total number of available tracks using getTrackInfo()
to see what
additional tracks become available after this method call.
Parameters | |
---|---|
path |
String : The file path of external timed text source file. |
mimeType |
String : The mime type of the file. Must be one of the mime types listed above. |
Throws | |
---|---|
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, long offset, long length, String mime)
Adds an external timed text file (FileDescriptor).
It is the caller's responsibility to close the file descriptor.
It is safe to do so as soon as this call returns.
Currently supported format is SubRip. Note that a single external timed text source may
contain multiple tracks in it. One can find the total number of available tracks
using getTrackInfo()
to see what additional tracks become available
after this method call.
Parameters | |
---|---|
fd |
FileDescriptor : the FileDescriptor for the file you want to play |
offset |
long : the offset into the file where the data to be played starts, in bytes |
length |
long : the length in bytes of the data to be played |
mime |
String : The mime type of the file. Must be one of the mime types listed above. |
Throws | |
---|---|
IllegalArgumentException |
if the mimeType is not supported. |
IllegalStateException |
if called in an invalid state. |
public void addTimedTextSource (Context context, Uri uri, String mimeType)
Adds an external timed text source file (Uri).
Currently supported format is SubRip with the file extension .srt, case insensitive.
Note that a single external timed text source may contain multiple tracks in it.
One can find the total number of available tracks using getTrackInfo()
to see what
additional tracks become available after this method call.
Parameters | |
---|---|
context |
Context : the Context to use when resolving the Uri |
uri |
Uri : the Content URI of the data you want to play |
mimeType |
String : The mime type of the file. Must be one of the mime types listed above. |
Throws | |
---|---|
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 attachAuxEffect (int effectId)
Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation
effect which can be applied on any sound source that directs a certain amount of its
energy to this effect. This amount is defined by setAuxEffectSendLevel().
See 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.
Parameters | |
---|---|
effectId |
int : system wide unique id of the effect to attach |
public void clearOnMediaTimeDiscontinuityListener ()
Clears the listener previously set with
setOnMediaTimeDiscontinuityListener(android.media.MediaPlayer.OnMediaTimeDiscontinuityListener)
or setOnMediaTimeDiscontinuityListener(android.media.MediaPlayer.OnMediaTimeDiscontinuityListener, android.os.Handler)
public void clearOnSubtitleDataListener ()
Clears the listener previously set with
setOnSubtitleDataListener(android.media.MediaPlayer.OnSubtitleDataListener)
or
setOnSubtitleDataListener(android.media.MediaPlayer.OnSubtitleDataListener, android.os.Handler)
.
public static MediaPlayer create (Context context, Uri uri, SurfaceHolder holder, AudioAttributes audioAttributes, int audioSessionId)
Same factory method as create(android.content.Context, android.net.Uri, android.view.SurfaceHolder)
but that lets you specify
the audio attributes and session ID to be used by the new MediaPlayer instance.
Parameters | |
---|---|
context |
Context : the Context to use |
uri |
Uri : the Uri from which to get the datasource |
holder |
SurfaceHolder : the SurfaceHolder to use for displaying the video, may be null. |
audioAttributes |
AudioAttributes : the AudioAttributes to be used by the media player. |
audioSessionId |
int : the audio session ID to be used by the media player,
see AudioManager#generateAudioSessionId() to obtain a new session. |
Returns | |
---|---|
MediaPlayer |
a MediaPlayer object, or null if creation failed |
public static MediaPlayer create (Context context, int resid, AudioAttributes audioAttributes, int audioSessionId)
Same factory method as create(android.content.Context, int)
but that lets you specify the audio
attributes and session ID to be used by the new MediaPlayer instance.
Parameters | |
---|---|
context |
Context : the Context to use |
resid |
int : the raw resource id (R.raw.<something>) for
the resource to use as the datasource |
audioAttributes |
AudioAttributes : the AudioAttributes to be used by the media player. |
audioSessionId |
int : the audio session ID to be used by the media player,
see AudioManager#generateAudioSessionId() to obtain a new session. |
Returns | |
---|---|
MediaPlayer |
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.
Note that since prepare()
is called automatically in this method,
you cannot change the audio
session ID (see setAudioSessionId(int)
) or audio attributes
(see setAudioAttributes(android.media.AudioAttributes)
of the new MediaPlayer.
Parameters | |
---|---|
context |
Context : the Context to use |
uri |
Uri : the Uri from which to get the datasource |
holder |
SurfaceHolder : the SurfaceHolder to use for displaying the video |
Returns | |
---|---|
MediaPlayer |
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.
Note that since prepare()
is called automatically in this method,
you cannot change the audio
session ID (see setAudioSessionId(int)
) or audio attributes
(see setAudioAttributes(android.media.AudioAttributes)
of the new MediaPlayer.
Parameters | |
---|---|
context |
Context : the Context to use |
resid |
int : the raw resource id (R.raw.<something>) for
the resource to use as the datasource |
Returns | |
---|---|
MediaPlayer |
a MediaPlayer object, or null if creation failed |
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.
Note that since prepare()
is called automatically in this method,
you cannot change the audio
session ID (see setAudioSessionId(int)
) or audio attributes
(see setAudioAttributes(android.media.AudioAttributes)
of the new MediaPlayer.
Parameters | |
---|---|
context |
Context : the Context to use |
uri |
Uri : the Uri from which to get the datasource |
Returns | |
---|---|
MediaPlayer |
a MediaPlayer object, or null if creation failed |
public VolumeShaper createVolumeShaper (VolumeShaper.Configuration configuration)
Returns a VolumeShaper
object that can be used modify the volume envelope
of the player or track.
Parameters | |
---|---|
configuration |
VolumeShaper.Configuration : This value cannot be null . |
Returns | |
---|---|
VolumeShaper |
This value cannot be null . |
public void deselectTrack (int index)
Deselect a track.
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.
Parameters | |
---|---|
index |
int : 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. |
Throws | |
---|---|
IllegalStateException |
if called in an invalid state. |
See also:
public int getAudioSessionId ()
Returns the audio session ID.
Returns | |
---|---|
int |
the audio session ID. Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed. |
public int getCurrentPosition ()
Gets the current playback position.
Returns | |
---|---|
int |
the current position in milliseconds |
public MediaPlayer.DrmInfo getDrmInfo ()
Retrieves the DRM Info associated with the current source
Returns | |
---|---|
MediaPlayer.DrmInfo |
Throws | |
---|---|
IllegalStateException |
if called before prepare() |
public String getDrmPropertyString (String propertyName)
Read a DRM engine plugin String property value, given the property name string.
Parameters | |
---|---|
propertyName |
String : the property name
Standard fields names are:
MediaDrm#PROPERTY_VENDOR , MediaDrm#PROPERTY_VERSION ,
MediaDrm#PROPERTY_DESCRIPTION , MediaDrm#PROPERTY_ALGORITHMS
This value cannot be null .
Value is MediaDrm.PROPERTY_VENDOR , MediaDrm.PROPERTY_VERSION , MediaDrm.PROPERTY_DESCRIPTION , or MediaDrm.PROPERTY_ALGORITHMS |
Returns | |
---|---|
String |
This value cannot be null . |
Throws | |
---|---|
MediaPlayer.NoDrmSchemeException |
public int getDuration ()
Gets the duration of the file.
Returns | |
---|---|
int |
the duration in milliseconds, if no duration is available (for example, if streaming live content), -1 is returned. |
public MediaDrm.KeyRequest getKeyRequest (byte[] keySetId, byte[] initData, String mimeType, int keyType, Map<String, String> optionalParameters)
A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.
getKeyRequest() is used to obtain an opaque key request byte array that is delivered to the license server. The opaque key request byte array is returned in KeyRequest.data. The recommended URL to deliver the key request to is returned in KeyRequest.defaultUrl.
After the app has received the key request response from the server,
it should deliver to the response to the DRM engine plugin using the method
provideKeyResponse(byte[], byte[])
.
Parameters | |
---|---|
keySetId |
byte : is the key-set identifier of the offline keys being released when keyType is
MediaDrm#KEY_TYPE_RELEASE . It should be set to null for other key requests, when
keyType is MediaDrm#KEY_TYPE_STREAMING or MediaDrm#KEY_TYPE_OFFLINE .
This value may be null . |
initData |
byte : is the container-specific initialization data when the keyType is
MediaDrm#KEY_TYPE_STREAMING or MediaDrm#KEY_TYPE_OFFLINE . Its meaning is
interpreted based on the mime type provided in the mimeType parameter. It could
contain, for example, the content ID, key ID or other data obtained from the content
metadata that is required in generating the key request.
When the keyType is MediaDrm#KEY_TYPE_RELEASE , it should be set to null.
This value may be null . |
mimeType |
String : identifies the mime type of the content
This value may be null . |
keyType |
int : specifies the type of the request. The request may be to acquire
keys for streaming, MediaDrm#KEY_TYPE_STREAMING , or for offline content
MediaDrm#KEY_TYPE_OFFLINE , or to release previously acquired
keys (MediaDrm#KEY_TYPE_RELEASE ), which are identified by a keySetId.
Value is MediaDrm.KEY_TYPE_STREAMING , MediaDrm.KEY_TYPE_OFFLINE , or MediaDrm.KEY_TYPE_RELEASE |
optionalParameters |
Map : are included in the key request message to
allow a client application to provide additional message parameters to the server.
This may be null if no additional parameters are to be sent.
This value may be null . |
Returns | |
---|---|
MediaDrm.KeyRequest |
Throws | |
---|---|
MediaPlayer.NoDrmSchemeException |
if there is no active DRM session |
public PersistableBundle getMetrics ()
Return Metrics data about the current player.
Returns | |
---|---|
PersistableBundle |
a PersistableBundle containing the set of attributes and values
available for the media being handled by this instance of MediaPlayer
The attributes are descibed in MetricsConstants .
Additional vendor-specific fields may also be present in
the return value. |
public PlaybackParams getPlaybackParams ()
Gets the playback params, containing the current playback rate.
Returns | |
---|---|
PlaybackParams |
the playback params.
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized. |
public AudioDeviceInfo getPreferredDevice ()
Returns the selected output specified by setPreferredDevice(AudioDeviceInfo)
. Note that this
is not guaranteed to correspond to the actual device being used for playback.
Returns | |
---|---|
AudioDeviceInfo |
public AudioDeviceInfo getRoutedDevice ()
Returns an AudioDeviceInfo
identifying the current routing of this MediaPlayer
Note: The query is only valid if the MediaPlayer is currently playing.
If the player is not playing, the returned device can be null or correspond to previously
selected device when the player was last active.
Returns | |
---|---|
AudioDeviceInfo |
public int getSelectedTrack (int trackType)
Returns the index of the audio, video, or subtitle track currently selected for playback,
The return value is an index into the array returned by getTrackInfo()
, and can
be used in calls to selectTrack(int)
or deselectTrack(int)
.
Parameters | |
---|---|
trackType |
int : should be one of TrackInfo#MEDIA_TRACK_TYPE_VIDEO ,
TrackInfo#MEDIA_TRACK_TYPE_AUDIO , or
TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE |
Returns | |
---|---|
int |
index of the audio, video, or subtitle track currently selected for playback;
a negative integer is returned when there is no selected track for trackType or
when trackType is not one of audio, video, or subtitle. |
Throws | |
---|---|
IllegalStateException |
if called after release() |
public SyncParams getSyncParams ()
Gets the A/V sync mode.
Returns | |
---|---|
SyncParams |
the A/V sync params
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized. |
public MediaTimestamp getTimestamp ()
Get current playback position as a MediaTimestamp
.
The MediaTimestamp represents how the media time correlates to the system time in a linear fashion using an anchor and a clock rate. During regular playback, the media time moves fairly constantly (though the anchor frame may be rebased to a current system time, the linear correlation stays steady). Therefore, this method does not need to be called often.
To help users get current playback position, this method always anchors the timestamp
to the current System#nanoTime
, so
MediaTimestamp#getAnchorMediaTimeUs
can be used as current playback position.
Returns | |
---|---|
MediaTimestamp |
a MediaTimestamp object if a timestamp is available, or null if no timestamp
is available, e.g. because the media player has not been initialized. |
See also:
public TrackInfo[] getTrackInfo ()
Returns an array of track information.
Returns | |
---|---|
TrackInfo[] |
Array of track info. The total number of tracks is the array length. Must be called again if an external timed text source has been added after any of the addTimedTextSource methods are called. |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state. |
public int getVideoHeight ()
Returns the height of the video.
Returns | |
---|---|
int |
the height of the video, or 0 if there is no video,
no display surface was set, or the height has not been determined
yet. The OnVideoSizeChangedListener can be registered via
setOnVideoSizeChangedListener(android.media.MediaPlayer.OnVideoSizeChangedListener)
to provide a notification when the height is available. |
public int getVideoWidth ()
Returns the width of the video.
Returns | |
---|---|
int |
the width of the video, or 0 if there is no video,
no display surface was set, or the width has not been determined
yet. The OnVideoSizeChangedListener can be registered via
setOnVideoSizeChangedListener(android.media.MediaPlayer.OnVideoSizeChangedListener)
to provide a notification when the width is available. |
public boolean isLooping ()
Checks whether the MediaPlayer is looping or non-looping.
Returns | |
---|---|
boolean |
true if the MediaPlayer is currently looping, false otherwise |
public boolean isPlaying ()
Checks whether the MediaPlayer is playing.
Returns | |
---|---|
boolean |
true if currently playing, false otherwise |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized or has been released. |
public void pause ()
Pauses playback. Call start() to resume.
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized. |
public void prepare ()
Prepares the player for playback, synchronously. After setting the datasource and the display surface, you need to either call prepare() or prepareAsync(). For files, it is OK to call prepare(), which blocks until MediaPlayer is ready for playback.
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IOException |
public void prepareAsync ()
Prepares the player for playback, asynchronously. After setting the datasource and the display surface, you need to either call prepare() or prepareAsync(). For streams, you should call prepareAsync(), which returns immediately, rather than blocking until enough data has been buffered.
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
public void prepareDrm (UUID uuid)
Prepares the DRM for the current source
If OnDrmConfigHelper
is registered, it will be called during
preparation to allow configuration of the DRM properties before opening the
DRM session. Note that the callback is called synchronously in the thread that called
prepareDrm
. It should be used only for a series of getDrmPropertyString
and setDrmPropertyString
calls and refrain from any lengthy operation.
If the device has not been provisioned before, this call also provisions the device
which involves accessing the provisioning server and can take a variable time to
complete depending on the network connectivity.
If OnDrmPreparedListener
is registered, prepareDrm() runs in non-blocking
mode by launching the provisioning in the background and returning. The listener
will be called when provisioning and preparation has finished. If a
OnDrmPreparedListener
is not registered, prepareDrm() waits till provisioning
and preparation has finished, i.e., runs in blocking mode.
If OnDrmPreparedListener
is registered, it is called to indicate the DRM
session being ready. The application should not make any assumption about its call
sequence (e.g., before or after prepareDrm returns), or the thread context that will
execute the listener (unless the listener is registered with a handler thread).
Parameters | |
---|---|
uuid |
UUID : The UUID of the crypto scheme. If not known beforehand, it can be retrieved
from the source through getDrmInfo or registering a onDrmInfoListener .
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if called before prepare(), or the DRM was prepared already |
UnsupportedSchemeException |
if the crypto scheme is not supported |
ResourceBusyException |
if required DRM resources are in use |
MediaPlayer.ProvisioningNetworkErrorException |
if provisioning is required but failed due to a network error |
MediaPlayer.ProvisioningServerErrorException |
if provisioning is required but failed due to the request denied by the provisioning server |
public byte[] provideKeyResponse (byte[] keySetId, byte[] response)
A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse. When the response is for an offline key request, a key-set identifier is returned that can be used to later restore the keys to a new session with the method {@ link # restoreKeys}. When the response is for a streaming or release request, null is returned.
Parameters | |
---|---|
keySetId |
byte : When the response is for a release request, keySetId identifies
the saved key associated with the release request (i.e., the same keySetId
passed to the earlier {@ link # getKeyRequest} call. It MUST be null when the
response is for either streaming or offline key requests. |
response |
byte : the byte array response from the server |
Returns | |
---|---|
byte[] |
Throws | |
---|---|
MediaPlayer.NoDrmSchemeException |
if there is no active DRM session |
DeniedByServerException |
if the response indicates that the server rejected the request |
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. In particular, whenever an Activity of an application is paused (its onPause() method is called), or stopped (its onStop() method is called), this method should be invoked to release the MediaPlayer object, unless the application has a special need to keep the object around. In addition to unnecessary resources (such as memory and instances of codecs) being held, failure to call this method immediately if a MediaPlayer object is no longer needed may also lead to continuous battery consumption for mobile devices, and playback failure for other applications if no multiple instances of the same codec are supported on a device. Even if multiple instances of the same codec are supported, some performance degradation may be expected when unnecessary multiple instances are used at the same time.
public void releaseDrm ()
Releases the DRM session
The player has to have an active DRM session and be in stopped, or prepared
state before this call is made.
A reset()
call will release the DRM session implicitly.
Throws | |
---|---|
MediaPlayer.NoDrmSchemeException |
if there is no active DRM session to release |
public void removeOnRoutingChangedListener (AudioRouting.OnRoutingChangedListener listener)
Removes an AudioRouting.OnRoutingChangedListener
which has been previously added
to receive rerouting notifications.
Parameters | |
---|---|
listener |
AudioRouting.OnRoutingChangedListener : The previously added AudioRouting.OnRoutingChangedListener interface
to remove. |
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 restoreKeys (byte[] keySetId)
Restore persisted offline keys into a new session. keySetId identifies the
keys to load, obtained from a prior call to provideKeyResponse(byte[], byte[])
.
Parameters | |
---|---|
keySetId |
byte : identifies the saved key set to restore
This value cannot be null . |
Throws | |
---|---|
MediaPlayer.NoDrmSchemeException |
public void seekTo (int msec)
Seeks to specified time position.
Same as seekTo(long, int)
with mode = SEEK_PREVIOUS_SYNC
.
Parameters | |
---|---|
msec |
int : the offset in milliseconds from the start to seek to |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized |
public void seekTo (long msec, int mode)
Moves the media to specified time position by considering the given mode.
When seekTo is finished, the user will be notified via OnSeekComplete supplied by the user. There is at most one active seekTo processed at any time. If there is a to-be-completed seekTo, new seekTo requests will be queued in such a way that only the last request is kept. When current seekTo is completed, the queued request will be processed if that request is different from just-finished seekTo operation, i.e., the requested position or mode is different.
Parameters | |
---|---|
msec |
long : the offset in milliseconds from the start to seek to.
When seeking to the given time position, there is no guarantee that the data source
has a frame located at the position. When this happens, a frame nearby will be rendered.
If msec is negative, time position zero will be used.
If msec is larger than duration, duration will be used. |
mode |
int : the mode indicating where exactly to seek to.
Use SEEK_PREVIOUS_SYNC if one wants to seek to a sync frame
that has a timestamp earlier than or the same as msec. Use
SEEK_NEXT_SYNC if one wants to seek to a sync frame
that has a timestamp later than or the same as msec. Use
SEEK_CLOSEST_SYNC if one wants to seek to a sync frame
that has a timestamp closest to or the same as msec. Use
SEEK_CLOSEST if one wants to seek to a frame that may
or may not be a sync frame but is closest to or the same as msec.
SEEK_CLOSEST often has larger performance overhead compared
to the other options if there is no sync frame located at msec.
Value is SEEK_PREVIOUS_SYNC , SEEK_NEXT_SYNC , SEEK_CLOSEST_SYNC , or SEEK_CLOSEST |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized |
IllegalArgumentException |
if the mode is invalid. |
public void selectTrack (int index)
Selects a track.
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, subtitle 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.
Parameters | |
---|---|
index |
int : 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. |
Throws | |
---|---|
IllegalStateException |
if called in an invalid state. |
See also:
public void setAudioAttributes (AudioAttributes attributes)
Sets the audio attributes for this MediaPlayer.
See AudioAttributes
for how to build and configure an instance of this class.
You must call this method before prepare()
or prepareAsync()
in order
for the audio attributes to become effective thereafter.
Parameters | |
---|---|
attributes |
AudioAttributes : a non-null set of audio attributes |
Throws | |
---|---|
IllegalArgumentException |
public void setAudioSessionId (int sessionId)
Sets the audio session ID.
Parameters | |
---|---|
sessionId |
int : 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. |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IllegalArgumentException |
public void setAudioStreamType (int streamtype)
This method is deprecated.
use setAudioAttributes(android.media.AudioAttributes)
Sets the audio stream type for this MediaPlayer. See 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.
Parameters | |
---|---|
streamtype |
int : the audio stream type |
See also:
public void setAuxEffectSendLevel (float level)
Sets the send level of the player to the attached auxiliary effect.
See 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)
Parameters | |
---|---|
level |
float : send level scalar |
public void setDataSource (AssetFileDescriptor afd)
Sets the data source (AssetFileDescriptor) 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.
Parameters | |
---|---|
afd |
AssetFileDescriptor : the AssetFileDescriptor for the file you want to play
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IllegalArgumentException |
if afd is not a valid AssetFileDescriptor |
IOException |
if afd can not be read |
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.
Parameters | |
---|---|
fd |
FileDescriptor : the FileDescriptor for the file you want to play |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IllegalArgumentException |
if fd is not a valid FileDescriptor |
IOException |
if fd can not be read |
public void setDataSource (FileDescriptor fd, long offset, long length)
Sets the data source (FileDescriptor) to use. The FileDescriptor must be seekable (N.B. a LocalSocket is not seekable). It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns.
Parameters | |
---|---|
fd |
FileDescriptor : the FileDescriptor for the file you want to play |
offset |
long : the offset into the file where the data to be played starts, in bytes |
length |
long : the length in bytes of the data to be played |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IllegalArgumentException |
if fd is not a valid FileDescriptor |
IOException |
if fd can not be read |
public void setDataSource (String path)
Sets the data source (file-path or http/rtsp URL) to use.
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(java.io.FileDescriptor)
.
Parameters | |
---|---|
path |
String : the path of the file, or the http/rtsp URL of the stream you want to play |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IOException |
|
IllegalArgumentException |
|
SecurityException |
public void setDataSource (Context context, Uri uri, Map<String, String> headers, List<HttpCookie> cookies)
Sets the data source as a content Uri. To provide cookies for the subsequent HTTP requests, you can install your own default cookie handler and use other variants of setDataSource APIs instead. Alternatively, you can use this API to pass the cookies as a list of HttpCookie. If the app has not installed a CookieHandler already, this API creates a CookieManager and populates its CookieStore with the provided cookies. If the app has installed its own handler already, this API requires the handler to be of CookieManager type such that the API can update the manager’s CookieStore.
Note that the cross domain redirection is allowed by default, but that can be changed with key/value pairs through the headers parameter with "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value to disallow or allow cross domain redirection.
Parameters | |
---|---|
context |
Context : the Context to use when resolving the Uri
This value cannot be null . |
uri |
Uri : the Content URI of the data you want to play
This value cannot be null . |
headers |
Map : the headers to be sent together with the request for the data
The headers must not include cookies. Instead, use the cookies param.
This value may be null . |
cookies |
List : the cookies to be sent together with the request
This value may be null . |
Throws | |
---|---|
IllegalArgumentException |
if cookies are provided and the installed handler is not a CookieManager |
IllegalStateException |
if it is called in an invalid state |
NullPointerException |
if context or uri is null |
IOException |
if uri has a file scheme and an I/O error occurs |
public void setDataSource (Context context, Uri uri, Map<String, String> headers)
Sets the data source as a content Uri.
Note that the cross domain redirection is allowed by default, but that can be changed with key/value pairs through the headers parameter with "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value to disallow or allow cross domain redirection.
Parameters | |
---|---|
context |
Context : the Context to use when resolving the Uri
This value cannot be null . |
uri |
Uri : the Content URI of the data you want to play
This value cannot be null . |
headers |
Map : the headers to be sent together with the request for the data
This value may be null . |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IOException |
|
IllegalArgumentException |
|
SecurityException |
public void setDataSource (MediaDataSource dataSource)
Sets the data source (MediaDataSource) to use.
Parameters | |
---|---|
dataSource |
MediaDataSource : the MediaDataSource for the media you want to play |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IllegalArgumentException |
if dataSource is not a valid MediaDataSource |
public void setDataSource (Context context, Uri uri)
Sets the data source as a content Uri.
Parameters | |
---|---|
context |
Context : the Context to use when resolving the Uri
This value cannot be null . |
uri |
Uri : the Content URI of the data you want to play
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
IOException |
|
IllegalArgumentException |
|
SecurityException |
public void setDisplay (SurfaceHolder sh)
Sets the 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(android.view.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.
Parameters | |
---|---|
sh |
SurfaceHolder : the SurfaceHolder to use for video display |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized or has been released. |
public void setDrmPropertyString (String propertyName, String value)
Set a DRM engine plugin String property value.
Parameters | |
---|---|
propertyName |
String : the property name
This value cannot be null .
Value is MediaDrm.PROPERTY_VENDOR , MediaDrm.PROPERTY_VERSION , MediaDrm.PROPERTY_DESCRIPTION , or MediaDrm.PROPERTY_ALGORITHMS |
value |
String : the property value
Standard fields names are:
MediaDrm#PROPERTY_VENDOR , MediaDrm#PROPERTY_VERSION ,
MediaDrm#PROPERTY_DESCRIPTION , MediaDrm#PROPERTY_ALGORITHMS
This value cannot be null . |
Throws | |
---|---|
MediaPlayer.NoDrmSchemeException |
public void setLooping (boolean looping)
Sets the player to be looping or non-looping.
Parameters | |
---|---|
looping |
boolean : whether to loop or not |
public void setNextMediaPlayer (MediaPlayer next)
Set the MediaPlayer to start when this MediaPlayer finishes playback (i.e. reaches the end of the stream). The media framework will attempt to transition from this player to the next as seamlessly as possible. The next player can be set at any time before completion, but shall be after setDataSource has been called successfully. The next player must be prepared by the app, and the application should not call start() on it. The next MediaPlayer must be different from 'this'. An exception will be thrown if next == this. The application may call setNextMediaPlayer(null) to indicate no next player should be started at the end of playback. If the current player is looping, it will keep looping and the next player will not be started.
Parameters | |
---|---|
next |
MediaPlayer : the player to start after this one completes playback. |
public void setOnBufferingUpdateListener (MediaPlayer.OnBufferingUpdateListener listener)
Register a callback to be invoked when the status of a network stream's buffer has changed.
Parameters | |
---|---|
listener |
MediaPlayer.OnBufferingUpdateListener : the callback that will be run. |
public void setOnCompletionListener (MediaPlayer.OnCompletionListener listener)
Register a callback to be invoked when the end of a media source has been reached during playback.
Parameters | |
---|---|
listener |
MediaPlayer.OnCompletionListener : the callback that will be run |
public void setOnDrmConfigHelper (MediaPlayer.OnDrmConfigHelper listener)
Register a callback to be invoked for configuration of the DRM object before
the session is created.
The callback will be invoked synchronously during the execution
of prepareDrm(java.util.UUID)
.
Parameters | |
---|---|
listener |
MediaPlayer.OnDrmConfigHelper : the callback that will be run |
public void setOnDrmInfoListener (MediaPlayer.OnDrmInfoListener listener)
Register a callback to be invoked when the DRM info is known.
Parameters | |
---|---|
listener |
MediaPlayer.OnDrmInfoListener : the callback that will be run |
public void setOnDrmInfoListener (MediaPlayer.OnDrmInfoListener listener, Handler handler)
Register a callback to be invoked when the DRM info is known.
Parameters | |
---|---|
listener |
MediaPlayer.OnDrmInfoListener : the callback that will be run |
handler |
Handler |
public void setOnDrmPreparedListener (MediaPlayer.OnDrmPreparedListener listener, Handler handler)
Register a callback to be invoked when the DRM object is prepared.
Parameters | |
---|---|
listener |
MediaPlayer.OnDrmPreparedListener : the callback that will be run |
handler |
Handler : the Handler that will receive the callback |
public void setOnDrmPreparedListener (MediaPlayer.OnDrmPreparedListener listener)
Register a callback to be invoked when the DRM object is prepared.
Parameters | |
---|---|
listener |
MediaPlayer.OnDrmPreparedListener : the callback that will be run |
public void setOnErrorListener (MediaPlayer.OnErrorListener listener)
Register a callback to be invoked when an error has happened during an asynchronous operation.
Parameters | |
---|---|
listener |
MediaPlayer.OnErrorListener : the callback that will be run |
public void setOnInfoListener (MediaPlayer.OnInfoListener listener)
Register a callback to be invoked when an info/warning is available.
Parameters | |
---|---|
listener |
MediaPlayer.OnInfoListener : the callback that will be run |
public void setOnMediaTimeDiscontinuityListener (MediaPlayer.OnMediaTimeDiscontinuityListener listener, Handler handler)
Sets the listener to be invoked when a media time discontinuity is encountered.
Parameters | |
---|---|
listener |
MediaPlayer.OnMediaTimeDiscontinuityListener : the listener called after a discontinuity
This value cannot be null . |
handler |
Handler : the Handler that receives the listener events
This value cannot be null . |
public void setOnMediaTimeDiscontinuityListener (MediaPlayer.OnMediaTimeDiscontinuityListener listener)
Sets the listener to be invoked when a media time discontinuity is encountered. The listener will be called on the same thread as the one in which the MediaPlayer was created.
Parameters | |
---|---|
listener |
MediaPlayer.OnMediaTimeDiscontinuityListener : the listener called after a discontinuity
This value cannot be null . |
public void setOnPreparedListener (MediaPlayer.OnPreparedListener listener)
Register a callback to be invoked when the media source is ready for playback.
Parameters | |
---|---|
listener |
MediaPlayer.OnPreparedListener : the callback that will be run |
public void setOnSeekCompleteListener (MediaPlayer.OnSeekCompleteListener listener)
Register a callback to be invoked when a seek operation has been completed.
Parameters | |
---|---|
listener |
MediaPlayer.OnSeekCompleteListener : the callback that will be run |
public void setOnSubtitleDataListener (MediaPlayer.OnSubtitleDataListener listener)
Sets the listener to be invoked when a subtitle track has new data available.
The subtitle data comes from a subtitle track previously selected with
selectTrack(int)
. Use getTrackInfo()
to determine which tracks are
subtitles (of type TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE
), Subtitle track encodings
can be determined by TrackInfo#getFormat()
).
See SubtitleData
for an example of querying subtitle encoding.
The listener will be called on the same thread as the one in which the MediaPlayer was
created.
Parameters | |
---|---|
listener |
MediaPlayer.OnSubtitleDataListener : the listener called when new data is available
This value cannot be null . |
public void setOnSubtitleDataListener (MediaPlayer.OnSubtitleDataListener listener, Handler handler)
Sets the listener to be invoked when a subtitle track has new data available.
The subtitle data comes from a subtitle track previously selected with
selectTrack(int)
. Use getTrackInfo()
to determine which tracks are
subtitles (of type TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE
), Subtitle track encodings
can be determined by TrackInfo#getFormat()
).
See SubtitleData
for an example of querying subtitle encoding.
Parameters | |
---|---|
listener |
MediaPlayer.OnSubtitleDataListener : the listener called when new data is available
This value cannot be null . |
handler |
Handler : the Handler that receives the listener events
This value cannot be null . |
public void setOnTimedMetaDataAvailableListener (MediaPlayer.OnTimedMetaDataAvailableListener listener)
Register a callback to be invoked when a selected track has timed metadata available.
Currently only HTTP live streaming data URI's embedded with timed ID3 tags generates
TimedMetaData
.
Parameters | |
---|---|
listener |
MediaPlayer.OnTimedMetaDataAvailableListener : the callback that will be run |
public void setOnTimedTextListener (MediaPlayer.OnTimedTextListener listener)
Register a callback to be invoked when a timed text is available for display.
Parameters | |
---|---|
listener |
MediaPlayer.OnTimedTextListener : the callback that will be run |
public void setOnVideoSizeChangedListener (MediaPlayer.OnVideoSizeChangedListener listener)
Register a callback to be invoked when the video size is known or updated.
Parameters | |
---|---|
listener |
MediaPlayer.OnVideoSizeChangedListener : the callback that will be run |
public void setPlaybackParams (PlaybackParams params)
Sets playback rate using PlaybackParams
. The object sets its internal
PlaybackParams to the input, except that the object remembers previous speed
when input speed is zero. This allows the object to resume at previous speed
when start() is called. Calling it before the object is prepared does not change
the object state. After the object is prepared, calling it with zero speed is
equivalent to calling pause(). After the object is prepared, calling it with
non-zero speed is equivalent to calling start().
Parameters | |
---|---|
params |
PlaybackParams : the playback params.
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized or has been released. |
IllegalArgumentException |
if params is not supported. |
public boolean setPreferredDevice (AudioDeviceInfo deviceInfo)
Specifies an audio device (via an AudioDeviceInfo
object) to route
the output from this MediaPlayer.
Parameters | |
---|---|
deviceInfo |
AudioDeviceInfo : The AudioDeviceInfo specifying the audio sink or source.
If deviceInfo is null, default routing is restored. |
Returns | |
---|---|
boolean |
true if succesful, false if the specified AudioDeviceInfo is non-null and
does not correspond to a valid audio device. |
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 |
boolean : Supply true to keep the screen on, false to allow it
to turn off. |
public void setSurface (Surface surface)
Sets the Surface
to be used as the sink for the video portion of
the media. This is similar to setDisplay(android.view.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.
Parameters | |
---|---|
surface |
Surface : The Surface to be used for the video portion of
the media. |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized or has been released. |
public void setSyncParams (SyncParams params)
Sets A/V sync mode.
Parameters | |
---|---|
params |
SyncParams : the A/V sync params to apply
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized. |
IllegalArgumentException |
if params are not supported. |
public void setVideoScalingMode (int mode)
Sets video scaling mode. To make the target video scaling mode
effective during playback, this method must be called after
data source is set. If not called, the default video
scaling mode is VIDEO_SCALING_MODE_SCALE_TO_FIT
.
The supported video scaling modes are:
Parameters | |
---|---|
mode |
int : target video scaling mode. Must be one of the supported
video scaling modes; otherwise, IllegalArgumentException will be thrown. |
public void setVolume (float leftVolume, float rightVolume)
Sets the volume on this player.
This API is recommended for balancing the output of audio streams
within an application. Unless you are writing an application to
control user settings, this API should be used in preference to
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 in range 0.0 to 1.0.
UI controls should be scaled logarithmically.
Parameters | |
---|---|
leftVolume |
float : left volume scalar |
rightVolume |
float : 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(android.view.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 |
Context : the Context to use |
mode |
int : 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.
Throws | |
---|---|
IllegalStateException |
if it is called in an invalid state |
public void stop ()
Stops playback after playback has been started or paused.
Throws | |
---|---|
IllegalStateException |
if the internal player engine has not been initialized. |
protected void finalize ()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
A subclass overrides the finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the Java™ virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.