Most visited

Recently visited

Results for

Added in API level 1

MediaPlayer

public class MediaPlayer
extends Object

java.lang.Object
↳	android.media.MediaPlayer

MediaPlayer类可用于控制音频/视频文件和流的播放。有关如何使用此类中的方法的示例可以在VideoView找到。

这里涵盖的主题是：

State Diagram
Valid and Invalid States
Permissions
Register informational and error callbacks

Developer Guides

有关如何使用MediaPlayer的更多信息，请阅读 Media Playback开发人员指南。

State Diagram

音频/视频文件和流的播放控制作为状态机进行管理。下图显示了由支持的播放控制操作驱动的MediaPlayer对象的生命周期和状态。椭圆表示MediaPlayer对象可能驻留的状态。弧表示驱动对象状态转换的播放控制操作。有两种类型的弧线。带有单箭头的弧表示同步方法调用，而带有双箭头的则表示异步方法调用。

从这个状态图中，可以看到MediaPlayer对象具有以下状态：

When a MediaPlayer object is just created using 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.
- There is a subtle but important difference between a newly constructed MediaPlayer object and the MediaPlayer object after 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.
- It is also recommended that once a MediaPlayer object is no longer being used, call 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.
- Furthermore, the MediaPlayer objects created using 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.
In general, some playback control operation may fail due to various reasons, such as unsupported audio/video format, poorly interleaved audio/video, resolution too high, streaming timeout, and the like. Thus, error reporting and recovery is an important concern under these circumstances. Sometimes, due to programming errors, invoking a playback control operation in an invalid state may also occur. Under all these error conditions, the internal player engine invokes a user supplied OnErrorListener.onError() method if an OnErrorListener has been registered beforehand via setOnErrorListener(android.media.MediaPlayer.OnErrorListener).
- It is important to note that once an error occurs, the MediaPlayer object enters the Error state (except as noted above), even if an error listener has not been registered by the application.
- In order to reuse a MediaPlayer object that is in the Error state and recover from the error, reset() can be called to restore the object to its Idle state.
- It is good programming practice to have your application register a OnErrorListener to look out for error notifications from the internal player engine.
- IllegalStateException is thrown to prevent programming errors such as calling prepare(), prepareAsync(), or one of the overloaded setDataSource methods in an invalid state.
Calling setDataSource(FileDescriptor), or setDataSource(String), or setDataSource(Context, Uri), or setDataSource(FileDescriptor, long, long), or setDataSource(MediaDataSource) transfers a MediaPlayer object in the Idle state to the Initialized state.
- An IllegalStateException is thrown if setDataSource() is called in any other state.
- It is good programming practice to always look out for IllegalArgumentException and IOException that may be thrown from the overloaded setDataSource methods.
A MediaPlayer object must first enter the Prepared state before playback can be started.
- There are two ways (synchronous vs. asynchronous) that the Prepared state can be reached: either a call to 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).
- It is important to note that the Preparing state is a transient state, and the behavior of calling any method with side effect while a MediaPlayer object is in the Preparing state is undefined.
- An IllegalStateException is thrown if prepare() or prepareAsync() is called in any other state.
- While in the Prepared state, properties such as audio/sound volume, screenOnWhilePlaying, looping can be adjusted by invoking the corresponding set methods.
To start the playback, 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.
- While in the Started state, the internal player engine calls a user supplied OnBufferingUpdateListener.onBufferingUpdate() callback method if a OnBufferingUpdateListener has been registered beforehand via setOnBufferingUpdateListener(OnBufferingUpdateListener). This callback allows applications to keep track of the buffering status while streaming audio/video.
- Calling start() has not effect on a MediaPlayer object that is already in the Started state.
Playback can be paused and stopped, and the current playback position can be adjusted. Playback can be paused via 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.
- Calling 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.
- Calling pause() has no effect on a MediaPlayer object that is already in the Paused state.
Calling stop() stops playback and causes a MediaPlayer in the Started, Paused, Prepared or PlaybackCompleted state to enter the Stopped state.
- Once in the Stopped state, playback cannot be started until prepare() or prepareAsync() are called to set the MediaPlayer object to the Prepared state again.
- Calling stop() has no effect on a MediaPlayer object that is already in the Stopped state.
The playback position can be adjusted with a call to seekTo(int).
- Although the asynchronuous 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).
- Please note that seekTo(int) can also be called in the other states, such as Prepared, Paused and PlaybackCompleted state.
- Furthermore, the actual current playback position can be retrieved with a call to getCurrentPosition(), which is helpful for applications such as a Music player that need to keep track of the playback progress.

When the playback reaches the end of stream, the playback completes.

If the looping mode was being set to truewith setLooping(boolean), the MediaPlayer object shall remain in the Started state.
If the looping mode was set to false , the player engine calls a user supplied callback method, OnCompletion.onCompletion(), if a OnCompletionListener is registered beforehand via setOnCompletionListener(OnCompletionListener). The invoke of the callback signals that the object is now in the PlaybackCompleted state.
While in the PlaybackCompleted state, calling start() can restart the playback from the beginning of the audio/video source.

Valid and invalid states

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, 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	{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.

Permissions

可能需要声明相应的WAKE_LOCK权限 <uses-permission>元素。

此类在与基于网络的内容一起使用时需要INTERNET权限。

Callbacks

应用程序可能需要注册信息和错误事件，以便在播放或流式传输过程中获知某些内部状态更新和可能的运行时错误。注册这些事件是由正确设置相应的监听器（通过调用完成setOnPreparedListener(OnPreparedListener) setOnPreparedListener， setOnVideoSizeChangedListener(OnVideoSizeChangedListener) setOnVideoSizeChangedListener， setOnSeekCompleteListener(OnSeekCompleteListener) setOnSeekCompleteListener， setOnCompletionListener(OnCompletionListener) setOnCompletionListener， setOnBufferingUpdateListener(OnBufferingUpdateListener) setOnBufferingUpdateListener， setOnInfoListener(OnInfoListener) setOnInfoListener， setOnErrorListener(OnErrorListener) setOnErrorListener等）。为了接收与这些监听器相关的相应回调，应用程序需要在运行其自己的Looper的线程上创建MediaPlayer对象（主UI线程默认情况下Looper正在运行）。

Summary

Nested classes
`interface`	`MediaPlayer.OnBufferingUpdateListener` 要调用的回调的接口定义，指示通过网络流式传输的媒体资源的缓冲状态。
`interface`	`MediaPlayer.OnCompletionListener` 在媒体源播放完成时调用回调的接口定义。
`interface`	`MediaPlayer.OnErrorListener` 在异步操作期间发生错误时要调用的回调的接口定义（其他错误将在方法调用时引发异常）。
`interface`	`MediaPlayer.OnInfoListener` 要调用的回调的接口定义，以传达有关介质或其播放的一些信息和/或警告。
`interface`	`MediaPlayer.OnPreparedListener` 当媒体源准备好播放时调用回调的接口定义。
`interface`	`MediaPlayer.OnSeekCompleteListener` 要调用的回调的接口定义，指示查找操作的完成。
`interface`	`MediaPlayer.OnTimedMetaDataAvailableListener` 当轨道具有可用的定时元数据时要调用的回调的接口定义。
`interface`	`MediaPlayer.OnTimedTextListener` 定时文本可用于显示时要调用的回调的接口定义。
`interface`	`MediaPlayer.OnVideoSizeChangedListener` 第一次知道或更新视频大小时要调用的回调的接口定义
`class`	`MediaPlayer.TrackInfo` MediaPlayer类返回每个音频/视频/字幕轨道的元数据。

Constants
`int`	`MEDIA_ERROR_IO` 文件或网络相关的操作错误。
`int`	`MEDIA_ERROR_MALFORMED` 比特流不符合相关的编码标准或文件规范。
`int`	`MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK` 视频流式传输，其容器无法用于渐进式播放，即视频的索引（例如moov atom）不在文件的起始位置。
`int`	`MEDIA_ERROR_SERVER_DIED` 媒体服务器死亡。
`int`	`MEDIA_ERROR_TIMED_OUT` 某些操作需要很长时间才能完成，通常需要3-5秒以上。
`int`	`MEDIA_ERROR_UNKNOWN` 未指定的媒体播放器错误。
`int`	`MEDIA_ERROR_UNSUPPORTED` 比特流符合相关的编码标准或文件规范，但媒体框架不支持该功能。
`int`	`MEDIA_INFO_BAD_INTERLEAVING` 错误的交错意味着媒体已被不恰当地交错或者根本不交错，例如，首先是所有的视频样本，然后是所有的音频样本。
`int`	`MEDIA_INFO_BUFFERING_END` MediaPlayer在填充缓冲区后恢复播放。
`int`	`MEDIA_INFO_BUFFERING_START` MediaPlayer暂时在内部暂停播放以缓冲更多数据。
`int`	`MEDIA_INFO_METADATA_UPDATE` 一组新的元数据可用。
`int`	`MEDIA_INFO_NOT_SEEKABLE` 媒体无法查找（例如直播）
`int`	`MEDIA_INFO_SUBTITLE_TIMED_OUT` 阅读字幕轨道需要很长时间。
`int`	`MEDIA_INFO_UNKNOWN` 未指定的媒体播放器信息。
`int`	`MEDIA_INFO_UNSUPPORTED_SUBTITLE` 字幕轨道不被媒体框架支持。
`int`	`MEDIA_INFO_VIDEO_RENDERING_START` 玩家只是推动了第一个视频帧进行渲染。
`int`	`MEDIA_INFO_VIDEO_TRACK_LAGGING` 视频对于解码器来说太复杂了：它不能足够快地解码帧。
`String`	`MEDIA_MIMETYPE_TEXT_SUBRIP` SubRip（SRT）容器的MIME类型。
`int`	`VIDEO_SCALING_MODE_SCALE_TO_FIT` 指定视频缩放模式。
`int`	`VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING` 指定视频缩放模式。

Fields
`protected AudioAttributes`	`mAttributes`
`protected float`	`mAuxEffectSendLevel`
`protected float`	`mLeftVolume`
`protected float`	`mRightVolume`

Public constructors
`MediaPlayer()` 默认的构造函数。

Public methods
`void`	`addTimedTextSource(FileDescriptor fd, String mimeType)` 添加一个外部定时文本源文件（FileDescriptor）。
`void`	`addTimedTextSource(String path, String mimeType)` 添加一个外部定时文本源文件。
`void`	`addTimedTextSource(FileDescriptor fd, long offset, long length, String mime)` 添加一个外部定时文本文件（FileDescriptor）。
`void`	`addTimedTextSource(Context context, Uri uri, String mimeType)` 添加一个外部定时文本源文件（Uri）。
`void`	`attachAuxEffect(int effectId)` 附加一个辅助效果给玩家。
`static MediaPlayer`	`create(Context context, Uri uri, SurfaceHolder holder, AudioAttributes audioAttributes, int audioSessionId)` 与 `create(Context, Uri, SurfaceHolder)`相同的工厂方法，但可让您指定要由新MediaPlayer实例使用的音频属性和会话ID。
`static MediaPlayer`	`create(Context context, int resid, AudioAttributes audioAttributes, int audioSessionId)` 与 `create(Context, int)`工厂方法相同，但允许您指定新MediaPlayer实例要使用的音频属性和会话ID。
`static MediaPlayer`	`create(Context context, Uri uri, SurfaceHolder holder)` 为给定的Uri创建MediaPlayer的便捷方法。
`static MediaPlayer`	`create(Context context, int resid)` 为给定资源ID创建MediaPlayer的便捷方法。
`static MediaPlayer`	`create(Context context, Uri uri)` 为给定的Uri创建MediaPlayer的便捷方法。
`void`	`deselectTrack(int index)` 取消选择一个曲目。
`int`	`getAudioSessionId()` 返回音频会话ID。
`int`	`getCurrentPosition()` 获取当前播放位置。
`int`	`getDuration()` 获取文件的持续时间。
`PlaybackParams`	`getPlaybackParams()` 获取包含当前回放速率的回放参数。
`int`	`getSelectedTrack(int trackType)` 返回当前选定播放的音频，视频或字幕轨道的索引，返回值是 `getTrackInfo()`返回的数组中的索引，可用于调用 `selectTrack(int)`或 `deselectTrack(int)` 。
`SyncParams`	`getSyncParams()` 获取A / V同步模式。
`MediaTimestamp`	`getTimestamp()` 获取当前播放位置为 `MediaTimestamp` 。
`TrackInfo[]`	`getTrackInfo()` 返回一系列轨道信息。
`int`	`getVideoHeight()` 返回视频的高度。
`int`	`getVideoWidth()` 返回视频的宽度。
`boolean`	`isLooping()` 检查MediaPlayer是循环还是非循环。
`boolean`	`isPlaying()` 检查MediaPlayer是否正在播放。
`void`	`pause()` 暂停播放。
`void`	`prepare()` 准备播放器同步播放。
`void`	`prepareAsync()` 准备播放器进行异步播放。
`void`	`release()` 释放与此MediaPlayer对象关联的资源。
`void`	`reset()` 将MediaPlayer重置为未初始化状态。
`void`	`seekTo(int msec)` 寻求指定的时间位置。
`void`	`selectTrack(int index)` 选择一首曲目。
`void`	`setAudioAttributes(AudioAttributes attributes)` 设置此MediaPlayer的音频属性。
`void`	`setAudioSessionId(int sessionId)` 设置音频会话ID。
`void`	`setAudioStreamType(int streamtype)` 设置此MediaPlayer的音频流类型。
`void`	`setAuxEffectSendLevel(float level)` 将播放器的发送电平设置为所附的辅助效果。
`void`	`setDataSource(AssetFileDescriptor afd)` 设置要使用的数据源（AssetFileDescriptor）。
`void`	`setDataSource(FileDescriptor fd)` 设置要使用的数据源（FileDescriptor）。
`void`	`setDataSource(FileDescriptor fd, long offset, long length)` 设置要使用的数据源（FileDescriptor）。
`void`	`setDataSource(String path)` 设置要使用的数据源（文件路径或http / rtsp URL）。
`void`	`setDataSource(Context context, Uri uri, Map<String, String> headers)` 将数据源设置为内容Uri。
`void`	`setDataSource(MediaDataSource dataSource)` 设置要使用的数据源（MediaDataSource）。
`void`	`setDataSource(Context context, Uri uri)` 将数据源设置为内容Uri。
`void`	`setDisplay(SurfaceHolder sh)` 设置 `SurfaceHolder`用于显示媒体的视频部分。
`void`	`setLooping(boolean looping)` 将玩家设置为循环或非循环。
`void`	`setNextMediaPlayer(MediaPlayer next)` 将MediaPlayer设置为在此MediaPlayer完成播放时启动（即
`void`	`setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener listener)` 当网络流的缓冲区状态发生变化时，注册一个要调用的回调函数。
`void`	`setOnCompletionListener(MediaPlayer.OnCompletionListener listener)` 在播放过程中到达媒体源结束时注册要调用的回调。
`void`	`setOnErrorListener(MediaPlayer.OnErrorListener listener)` 在异步操作期间发生错误时注册要调用的回调。
`void`	`setOnInfoListener(MediaPlayer.OnInfoListener listener)` 当信息/警告可用时，注册要调用的回调。
`void`	`setOnPreparedListener(MediaPlayer.OnPreparedListener listener)` 当媒体源准备好播放时，注册一个要调用的回调。
`void`	`setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener listener)` 当查找操作完成时，注册要调用的回调。
`void`	`setOnTimedMetaDataAvailableListener(MediaPlayer.OnTimedMetaDataAvailableListener listener)` 当选定的音轨具有可用的定时元数据时，注册要调用的回调。
`void`	`setOnTimedTextListener(MediaPlayer.OnTimedTextListener listener)` 当定时文本可用于显示时，注册要调用的回调。
`void`	`setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener)` 在视频大小已知或更新时注册要调用的回调。
`void`	`setPlaybackParams(PlaybackParams params)` 使用 `PlaybackParams`设置回放速率。
`void`	`setScreenOnWhilePlaying(boolean screenOn)` 控制在视频播放过程中是否应使用附加的SurfaceHolder保持屏幕开启。
`void`	`setSurface(Surface surface)` 将 `Surface`设置为媒体视频部分的接收器。
`void`	`setSyncParams(SyncParams params)` 设置A / V同步模式。
`void`	`setVideoScalingMode(int mode)` 设置视频缩放模式。
`void`	`setVolume(float leftVolume, float rightVolume)` 设定此播放器的音量。
`void`	`setWakeMode(Context context, int mode)` 设置此MediaPlayer的低级电源管理行为。
`void`	`start()` 开始或继续播放。
`void`	`stop()` 播放停止或暂停后停止播放。

Protected methods
`void`	`finalize()` 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。

Inherited methods

From class java.lang.Object

Constants

MEDIA_ERROR_IO

Added in API level 17

int MEDIA_ERROR_IO

文件或网络相关的操作错误。

常量值：-1004（0xfffffc14）

MEDIA_ERROR_MALFORMED

Added in API level 17

int MEDIA_ERROR_MALFORMED

比特流不符合相关的编码标准或文件规范。

常量值：-1007（0xfffffc11）

MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

Added in API level 3

int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

视频流式传输，其容器无法用于渐进式播放，即视频的索引（例如moov atom）不在文件的起始位置。

也可以看看：

MediaPlayer.OnErrorListener

常量值：200（0x000000c8）

MEDIA_ERROR_SERVER_DIED

Added in API level 1

int MEDIA_ERROR_SERVER_DIED

媒体服务器死亡。在这种情况下，应用程序必须释放MediaPlayer对象并实例化一个新对象。

也可以看看：

MediaPlayer.OnErrorListener

常量值：100（0x00000064）

MEDIA_ERROR_TIMED_OUT

Added in API level 17

int MEDIA_ERROR_TIMED_OUT

某些操作需要很长时间才能完成，通常需要3-5秒以上。

常量值：-110（0xffffff92）

MEDIA_ERROR_UNKNOWN

Added in API level 1

int MEDIA_ERROR_UNKNOWN

未指定的媒体播放器错误。

也可以看看：

MediaPlayer.OnErrorListener

常数值：1（0x00000001）

MEDIA_ERROR_UNSUPPORTED

Added in API level 17

int MEDIA_ERROR_UNSUPPORTED

比特流符合相关的编码标准或文件规范，但媒体框架不支持该功能。

常量值：-1010（0xfffffc0e）

MEDIA_INFO_BAD_INTERLEAVING

Added in API level 3

int MEDIA_INFO_BAD_INTERLEAVING

错误的交错意味着媒体已被不恰当地交错或者根本不交错，例如，首先是所有的视频样本，然后是所有的音频样本。视频正在播放，但很多磁盘搜索可能正在发生。

也可以看看：

MediaPlayer.OnInfoListener

常量值：800（0x00000320）

MEDIA_INFO_BUFFERING_END

Added in API level 9

int MEDIA_INFO_BUFFERING_END

MediaPlayer在填充缓冲区后恢复播放。

也可以看看：

MediaPlayer.OnInfoListener

常量值：702（0x000002be）

MEDIA_INFO_BUFFERING_START

Added in API level 9

int MEDIA_INFO_BUFFERING_START

MediaPlayer暂时在内部暂停播放以缓冲更多数据。

也可以看看：

MediaPlayer.OnInfoListener

常量值：701（0x000002bd）

MEDIA_INFO_METADATA_UPDATE

Added in API level 5

int MEDIA_INFO_METADATA_UPDATE

一组新的元数据可用。

也可以看看：

MediaPlayer.OnInfoListener

常量值：802（0x00000322）

MEDIA_INFO_NOT_SEEKABLE

Added in API level 3

int MEDIA_INFO_NOT_SEEKABLE

媒体无法查找（例如直播）

也可以看看：

MediaPlayer.OnInfoListener

常量值：801（0x00000321）

MEDIA_INFO_SUBTITLE_TIMED_OUT

Added in API level 19

int MEDIA_INFO_SUBTITLE_TIMED_OUT

阅读字幕轨道需要很长时间。

也可以看看：

MediaPlayer.OnInfoListener

常量值：902（0x00000386）

MEDIA_INFO_UNKNOWN

Added in API level 3

int MEDIA_INFO_UNKNOWN

未指定的媒体播放器信息。

也可以看看：

MediaPlayer.OnInfoListener

常数值：1（0x00000001）

MEDIA_INFO_UNSUPPORTED_SUBTITLE

Added in API level 19

int MEDIA_INFO_UNSUPPORTED_SUBTITLE

字幕轨道不被媒体框架支持。

也可以看看：

MediaPlayer.OnInfoListener

常量值：901（0x00000385）

MEDIA_INFO_VIDEO_RENDERING_START

Added in API level 17

int MEDIA_INFO_VIDEO_RENDERING_START

玩家只是推动了第一个视频帧进行渲染。

也可以看看：

MediaPlayer.OnInfoListener

常量值：3（0x00000003）

MEDIA_INFO_VIDEO_TRACK_LAGGING

Added in API level 3

int MEDIA_INFO_VIDEO_TRACK_LAGGING

视频对于解码器来说太复杂了：它不能足够快地解码帧。在这个阶段可能只有音频播放正常。

也可以看看：

MediaPlayer.OnInfoListener

常量值：700（0x000002bc）

MEDIA_MIMETYPE_TEXT_SUBRIP

Added in API level 16

String MEDIA_MIMETYPE_TEXT_SUBRIP

SubRip（SRT）容器的MIME类型。用于addTimedTextSource API。

常量值：“application / x-subrip”

VIDEO_SCALING_MODE_SCALE_TO_FIT

Added in API level 16

int VIDEO_SCALING_MODE_SCALE_TO_FIT

指定视频缩放模式。内容被拉伸到表面渲染区域。当表面具有与内容相同的纵横比时，内容的纵横比保持不变; 否则，视频正在呈现时，内容的宽高比不会保持。与VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING不同，使用此视频缩放模式不会剪裁内容。

常数值：1（0x00000001）

VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING

Added in API level 16

int VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING

指定视频缩放模式。内容被缩放，保持其宽高比。整个表面区域总是被使用。当内容的纵横比与表面相同时，不剪裁内容; 否则，内容将被裁剪以适应表面。

常量值：2（0x00000002）

Fields

mAttributes

AudioAttributes mAttributes

mAuxEffectSendLevel

float mAuxEffectSendLevel

mLeftVolume

float mLeftVolume

mRightVolume

float mRightVolume

Public constructors

MediaPlayer

Added in API level 1

MediaPlayer ()

默认的构造函数。考虑使用其中一个create（）方法从Uri或资源同步实例化MediaPlayer。

使用MediaPlayer完成后，您应该调用release() ，以释放资源。如果未发布，则过多的MediaPlayer实例可能导致异常。

Public methods

addTimedTextSource

Added in API level 16

void addTimedTextSource (FileDescriptor fd, 
                String mimeType)

添加一个外部定时文本源文件（FileDescriptor）。调用者有责任关闭文件描述符。一旦这个通话返回，这样做是安全的。目前支持的格式是SubRip。请注意，一个外部定时文本源可能包含多个轨道。可以使用getTrackInfo()查找可用轨道的总数，以查看该方法调用后可用的额外轨道。

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.

addTimedTextSource

Added in API level 16

void addTimedTextSource (String path, 
                String mimeType)

添加一个外部定时文本源文件。目前支持的格式是SubRip，文件扩展名为.srt，不区分大小写。请注意，一个外部定时文本源可能包含多个轨道。可以使用getTrackInfo()查找可用轨道的总数，以查看此方法调用后可用的额外轨道。

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.

addTimedTextSource

Added in API level 16

void addTimedTextSource (FileDescriptor fd, 
                long offset, 
                long length, 
                String mime)

添加一个外部定时文本文件（FileDescriptor）。调用者有责任关闭文件描述符。一旦这个通话返回，这样做是安全的。目前支持的格式是SubRip。请注意，一个外部定时文本源可能包含多个轨道。可以使用getTrackInfo()查找可用轨道的总数，以查看此方法调用后可用的额外轨道。

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.

addTimedTextSource

Added in API level 16

void addTimedTextSource (Context context, 
                Uri uri, 
                String mimeType)

添加一个外部定时文本源文件（Uri）。目前支持的格式是SubRip，文件扩展名为.srt，不区分大小写。请注意，一个外部定时文本源可能包含多个轨道。可以使用getTrackInfo()查找可用轨道的总数，以查看此方法调用后可用的额外轨道。

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.

attachAuxEffect

Added in API level 9

void attachAuxEffect (int effectId)

附加一个辅助效果给玩家。典型的辅助效果是混响效果，可以应用在任何声源上，这些声源将其一定量的能量引导至该效果。这个数量由setAuxEffectSendLevel（）定义。见setAuxEffectSendLevel(float) 。

创建辅助效果（例如 EnvironmentalReverb ）后，请用 getId()检索其ID，并在调用此方法将其附加到效果器时使用它。

要从玩家分离效果，请使用空效果ID调用此方法。

必须在重载的 setDataSource方法之一后调用此方法。

Parameters
`effectId`	`int`: system wide unique id of the effect to attach

create

Added in API level 21

MediaPlayer create (Context context, 
                Uri uri, 
                SurfaceHolder holder, 
                AudioAttributes audioAttributes, 
                int audioSessionId)

与 create(Context, Uri, SurfaceHolder)相同的工厂方法，但可让您指定要由新MediaPlayer实例使用的音频属性和会话ID。

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 `generateAudioSessionId()` to obtain a new session.

Returns
`MediaPlayer`	a MediaPlayer object, or null if creation failed

create

Added in API level 21

MediaPlayer create (Context context, 
                int resid, 
                AudioAttributes audioAttributes, 
                int audioSessionId)

与 create(Context, int)相同的工厂方法，但可让您指定要由新MediaPlayer实例使用的音频属性和会话ID。

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 `generateAudioSessionId()` to obtain a new session.

Returns
`MediaPlayer`	a MediaPlayer object, or null if creation failed

create

Added in API level 1

MediaPlayer create (Context context, 
                Uri uri, 
                SurfaceHolder holder)

为给定的Uri创建MediaPlayer的便捷方法。成功时， prepare()已经被调用，不能再次调用。

使用MediaPlayer完成后，应该调用release()来释放资源。如果未发布，则过多的MediaPlayer实例将导致异常。

注意，由于 prepare()在这种方法自动调用，你不能改变音频流类型（见 setAudioStreamType(int) ），音频会话ID（见 setAudioSessionId(int) ）或音频属性（见 setAudioAttributes(AudioAttributes)新的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

create

Added in API level 1

MediaPlayer create (Context context, 
                int resid)

为给定资源ID创建MediaPlayer的便捷方法。成功时， prepare()已经被调用，不能再次调用。

完成MediaPlayer后，您应该致电release() ，以释放资源。如果未发布，则过多的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

create

Added in API level 1

MediaPlayer create (Context context, 
                Uri uri)

为给定的Uri创建MediaPlayer的便捷方法。成功时， prepare()已经被调用，不能再次调用。

完成MediaPlayer后，您应该致电release() ，以释放资源。如果未发布，则过多的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

deselectTrack

Added in API level 16

void deselectTrack (int index)

取消选择一个曲目。

目前，曲目必须是定时文字曲目，并且不能取消选择音频或视频曲目。如果索引标识的定时文本轨道以前未被选中，则会引发异常。

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.

也可以看看：

getTrackInfo()

getAudioSessionId

Added in API level 9

int getAudioSessionId ()

返回音频会话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.

getCurrentPosition

Added in API level 1

int getCurrentPosition ()

获取当前播放位置。

Returns
`int`	the current position in milliseconds

getDuration

Added in API level 1

int getDuration ()

获取文件的持续时间。

Returns
`int`	the duration in milliseconds, if no duration is available (for example, if streaming live content), -1 is returned.

getPlaybackParams

Added in API level 23

PlaybackParams getPlaybackParams ()

获取包含当前回放速率的回放参数。

Returns
`PlaybackParams`	the playback params.

Throws
`IllegalStateException`	if the internal player engine has not been initialized.

getSelectedTrack

Added in API level 21

int getSelectedTrack (int trackType)

返回当前选定播放的音频，视频或字幕轨道的索引，返回值是由 getTrackInfo()返回的数组中的索引，可用于调用 selectTrack(int)或 deselectTrack(int) 。

Parameters
`trackType`	`int`: should be one of `MEDIA_TRACK_TYPE_VIDEO`, `MEDIA_TRACK_TYPE_AUDIO`, or `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()`

也可以看看：

getSyncParams

Added in API level 23

SyncParams getSyncParams ()

获取A / V同步模式。

Returns
`SyncParams`	the A/V sync params

Throws
`IllegalStateException`	if the internal player engine has not been initialized.

getTimestamp

Added in API level 23

MediaTimestamp getTimestamp ()

获取当前播放位置为 MediaTimestamp 。

MediaTimestamp表示媒体时间如何使用锚点和时钟频率以线性方式与系统时间相关联。在正常播放过程中，媒体时间会相当持续地移动（尽管锚帧可能会重新设置为当前系统时间，但线性相关保持稳定）。因此，这种方法不需要经常调用。

为了帮助用户获得当前播放位置，此方法始终将时间戳固定到当前的 system time ，因此 getAnchorMediaTimeUs()可用作当前播放位置。

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.

也可以看看：

MediaTimestamp

getTrackInfo

Added in API level 16

TrackInfo[] getTrackInfo ()

返回一系列轨道信息。

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.

getVideoHeight

Added in API level 1

int getVideoHeight ()

返回视频的高度。

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(OnVideoSizeChangedListener)` to provide a notification when the height is available.

getVideoWidth

Added in API level 1

int getVideoWidth ()

返回视频的宽度。

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(OnVideoSizeChangedListener)` to provide a notification when the width is available.

isLooping

Added in API level 3

boolean isLooping ()

检查MediaPlayer是循环还是非循环。

Returns
`boolean`	true if the MediaPlayer is currently looping, false otherwise

isPlaying

Added in API level 1

boolean isPlaying ()

检查MediaPlayer是否正在播放。

Returns
`boolean`	true if currently playing, false otherwise

Throws
`IllegalStateException`	if the internal player engine has not been initialized or has been released.

pause

Added in API level 1

void pause ()

暂停播放。调用start（）来恢复。

Throws
`IllegalStateException`	if the internal player engine has not been initialized.

prepare

Added in API level 1

void prepare ()

准备播放器同步播放。设置数据源和显示界面后，您需要调用prepare（）或prepareAsync（）。对于文件，可以调用prepare（），这会阻塞，直到MediaPlayer准备好播放。

Throws
`IllegalStateException`	if it is called in an invalid state
`IOException`

prepareAsync

Added in API level 1

void prepareAsync ()

准备播放器进行异步播放。设置数据源和显示界面后，您需要调用prepare（）或prepareAsync（）。对于流，你应该调用prepareAsync（），它会立即返回，而不是阻塞，直到有足够的数据被缓冲。

Throws
`IllegalStateException`	if it is called in an invalid state

release

Added in API level 1

void release ()

释放与此MediaPlayer对象关联的资源。当您完成使用MediaPlayer时，调用此方法被认为是很好的做法。特别是，每当应用程序的活动暂停（调用其onPause（）方法）或停止（它的onStop（）方法被调用）时，应调用此方法以释放MediaPlayer对象，除非应用程序有特殊需要保持周围的物体。除了保存不必要的资源（例如内存和编解码器实例）之外，如果不再需要MediaPlayer对象，则无法立即调用此方法也可能导致移动设备的电池消耗持续，并且如果没有其他应用程序，则会导致播放失败设备支持同一编码解码器的多个实例。即使支持同一编解码器的多个实例，当不必要的多个实例同时使用时，也可能会导致性能下降。

reset

Added in API level 1

void reset ()

将MediaPlayer重置为未初始化状态。调用此方法后，必须通过设置数据源并调用prepare（）来重新初始化它。

seekTo

Added in API level 1

void seekTo (int msec)

寻求指定的时间位置。

Parameters
`msec`	`int`: the offset in milliseconds from the start to seek to

Throws
`IllegalStateException`	if the internal player engine has not been initialized

selectTrack

Added in API level 16

void selectTrack (int index)

选择一首曲目。

如果MediaPlayer处于无效状态，则会引发IllegalStateException异常。如果MediaPlayer处于启动状态，则会立即显示选定的曲目。如果MediaPlayer未处于启动状态，则只会标记要播放的曲目。

在任何有效的状态下，如果在同一类型的音轨上（即视频，音频，定时文本）多次调用它，则会选择最近的一个。

即使未调用此方法，第一个音频和视频轨道也会默认选中（如果可用）。但是，在调用此函数之前，不会选择定时文本轨道。

目前，只有定时的文字曲目或音轨可以通过此方法选择。另外，在运行时选择音轨的支持相当有限，因为只能在准备状态中选择音轨。

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.

也可以看看：

getTrackInfo()

setAudioAttributes

Added in API level 21

void setAudioAttributes (AudioAttributes attributes)

设置此MediaPlayer的音频属性。有关如何构建和配置此类的实例，请参阅AudioAttributes 。您必须在prepare()或prepareAsync()之前调用此方法，以便此后的音频属性生效。

Parameters
`attributes`	`AudioAttributes`: a non-null set of audio attributes

Throws
`IllegalArgumentException`

setAudioSessionId

Added in API level 9

void setAudioSessionId (int sessionId)

设置音频会话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`

setAudioStreamType

Added in API level 1

void setAudioStreamType (int streamtype)

设置此MediaPlayer的音频流类型。有关流类型的列表，请参阅AudioManager 。在prepare（）或prepareAsync（）之前必须调用此方法，以便目标流类型此后生效。

Parameters
`streamtype`	`int`: the audio stream type

也可以看看：

AudioManager

setAuxEffectSendLevel

Added in API level 9

void setAuxEffectSendLevel (float level)

将播放器的发送电平设置为所附的辅助效果。见attachAuxEffect(int) 。等级值范围是0到1.0。

默认情况下，发送电平为0，因此即使将效果附加到播放器上，也必须调用此方法才能应用效果。

请注意，传递的级别值是一个原始标量。 UI控件应该按对数进行缩放：音频框架应用的增益范围从-72dB到0dB，因此从线性UI输入x到等级的适当转换为：x == 0 - > level = 0 0 <x <= R - >水平= 10 ^（72 *（xR）/ 20 / R）

Parameters
`level`	`float`: send level scalar

setDataSource

Added in API level 24

void setDataSource (AssetFileDescriptor afd)

设置要使用的数据源（AssetFileDescriptor）。调用者有责任关闭文件描述符。一旦这个通话返回，这样做是安全的。

Parameters
`afd`	`AssetFileDescriptor`: the AssetFileDescriptor for the file you want to play

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

setDataSource

Added in API level 1

void setDataSource (FileDescriptor fd)

设置要使用的数据源（FileDescriptor）。调用者有责任关闭文件描述符。一旦这个通话返回，这样做是安全的。

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

setDataSource

Added in API level 1

void setDataSource (FileDescriptor fd, 
                long offset, 
                long length)

设置要使用的数据源（FileDescriptor）。 FileDescriptor必须可查找（注意LocalSocket不可查找）。调用者有责任关闭文件描述符。一旦这个通话返回，这样做是安全的。

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

setDataSource

Added in API level 1

void setDataSource (String path)

设置要使用的数据源（文件路径或http / rtsp URL）。

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 当`path`引用一个本地文件时，该文件实际上可能被调用应用程序以外的进程打开。这意味着路径名应该是绝对路径（因为任何其他进程都在未指定的当前工作目录下运行），并且路径名应该引用世界可读的文件。作为替代，应用程序可以先打开文件进行读取，然后使用文件描述符表单`setDataSource(FileDescriptor)` 。
`IOException`
`IllegalArgumentException`
`SecurityException`

setDataSource

Added in API level 14

void setDataSource (Context context, 
                Uri uri, 
                Map<String, String> headers)

将数据源设置为内容Uri。

Parameters
`context`	`Context`: the Context to use when resolving the Uri
`uri`	`Uri`: the Content URI of the data you want to play
`headers`	`Map`: the headers to be sent together with the request for the data 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.

Throws
`IllegalStateException`	if it is called in an invalid state
`IOException`
`IllegalArgumentException`
`SecurityException`

setDataSource

Added in API level 23

void setDataSource (MediaDataSource dataSource)

设置要使用的数据源（MediaDataSource）。

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

setDataSource

Added in API level 1

void setDataSource (Context context, 
                Uri uri)

将数据源设置为内容Uri。

Parameters
`context`	`Context`: the Context to use when resolving the Uri
`uri`	`Uri`: the Content URI of the data you want to play

Throws
`IllegalStateException`	if it is called in an invalid state
`IOException`
`IllegalArgumentException`
`SecurityException`

setDisplay

Added in API level 1

void setDisplay (SurfaceHolder sh)

设置SurfaceHolder用于显示媒体的视频部分。如果需要显示器或视频接收器，则必须设置表面固定器或表面。在回放视频时不调用此方法或setSurface(Surface)将导致只播放音频曲目。零表面支架或表面将导致只播放音轨。

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.

setLooping

Added in API level 1

void setLooping (boolean looping)

将玩家设置为循环或非循环。

Parameters
`looping`	`boolean`: whether to loop or not

setNextMediaPlayer

Added in API level 16

void setNextMediaPlayer (MediaPlayer next)

将MediaPlayer设置为在此MediaPlayer完成播放时开始（即到达流尾）。媒体框架将尽可能无缝地尝试从这个玩家转换到下一个玩家。下一位玩家可以在完成前随时设置。下一个玩家必须由应用程序准备，应用程序不应该调用start（）。下一个MediaPlayer必须与“this”不同。如果next == this，则会引发异常。应用程序可能会调用setNextMediaPlayer（null）来指示在播放结束时不应再启动下一个播放器。如果当前玩家正在循环，它将保持循环，并且下一个玩家不会被启动。

Parameters
`next`	`MediaPlayer`: the player to start after this one completes playback.

setOnBufferingUpdateListener

Added in API level 1

void setOnBufferingUpdateListener (MediaPlayer.OnBufferingUpdateListener listener)

当网络流的缓冲区状态发生变化时，注册一个要调用的回调函数。

Parameters
`listener`	`MediaPlayer.OnBufferingUpdateListener`: the callback that will be run.

setOnCompletionListener

Added in API level 1

void setOnCompletionListener (MediaPlayer.OnCompletionListener listener)

在播放过程中到达媒体源结束时注册要调用的回调。

Parameters
`listener`	`MediaPlayer.OnCompletionListener`: the callback that will be run

setOnErrorListener

Added in API level 1

void setOnErrorListener (MediaPlayer.OnErrorListener listener)

在异步操作期间发生错误时注册要调用的回调。

Parameters
`listener`	`MediaPlayer.OnErrorListener`: the callback that will be run

setOnInfoListener

Added in API level 3

void setOnInfoListener (MediaPlayer.OnInfoListener listener)

当信息/警告可用时，注册要调用的回调。

Parameters
`listener`	`MediaPlayer.OnInfoListener`: the callback that will be run

setOnPreparedListener

Added in API level 1

void setOnPreparedListener (MediaPlayer.OnPreparedListener listener)

当媒体源准备好播放时，注册一个要调用的回调。

Parameters
`listener`	`MediaPlayer.OnPreparedListener`: the callback that will be run

setOnSeekCompleteListener

Added in API level 1

void setOnSeekCompleteListener (MediaPlayer.OnSeekCompleteListener listener)

当查找操作完成时，注册要调用的回调。

Parameters
`listener`	`MediaPlayer.OnSeekCompleteListener`: the callback that will be run

setOnTimedMetaDataAvailableListener

Added in API level 23

void setOnTimedMetaDataAvailableListener (MediaPlayer.OnTimedMetaDataAvailableListener listener)

当选定的音轨具有可用的定时元数据时，注册要调用的回调。

目前只有嵌入了定时ID3标签的HTTP实况流数据URI生成 TimedMetaData 。

Parameters
`listener`	`MediaPlayer.OnTimedMetaDataAvailableListener`: the callback that will be run

也可以看看：

setOnTimedTextListener

Added in API level 16

void setOnTimedTextListener (MediaPlayer.OnTimedTextListener listener)

当定时文本可用于显示时，注册要调用的回调。

Parameters
`listener`	`MediaPlayer.OnTimedTextListener`: the callback that will be run

setOnVideoSizeChangedListener

Added in API level 3

void setOnVideoSizeChangedListener (MediaPlayer.OnVideoSizeChangedListener listener)

在视频大小已知或更新时注册要调用的回调。

Parameters
`listener`	`MediaPlayer.OnVideoSizeChangedListener`: the callback that will be run

setPlaybackParams

Added in API level 23

void setPlaybackParams (PlaybackParams params)

使用PlaybackParams设置播放速率。该对象将其内部PlaybackParams设置为输入，除了对象在输入速度为零时会记住之前的速度。这允许在调用start（）时以先前的速度恢复对象。在对象准备好之前调用它不会更改对象状态。对象准备好后，以零速度调用它相当于调用pause（）。对象准备好后，以非零速度调用它相当于调用start（）。

Parameters
`params`	`PlaybackParams`: the playback params.

Throws
`IllegalStateException`	if the internal player engine has not been initialized or has been released.
`IllegalArgumentException`	if params is not supported.

setScreenOnWhilePlaying

Added in API level 1

void setScreenOnWhilePlaying (boolean screenOn)

控制在视频播放过程中是否应使用附加的SurfaceHolder保持屏幕开启。在可能的情况下，这是setWakeMode(Context, int)以上的首选方法，因为它不要求应用程序具有低级别唤醒锁访问权限。

Parameters
`screenOn`	`boolean`: Supply true to keep the screen on, false to allow it to turn off.

setSurface

Added in API level 14

void setSurface (Surface surface)

将Surface设置为媒体视频部分的接收器。这与setDisplay(SurfaceHolder)类似，但不支持setScreenOnWhilePlaying(boolean) 。设置Surface将取消设置先前设置的任何Surface或SurfaceHolder。零曲面将导致只有正在播放的音轨。如果曲面将帧发送到SurfaceTexture ，则从getTimestamp()返回的时间戳将具有未指定的零点。这些时间戳不能直接在不同媒体源，相同媒体源的不同实例或同一程序的多个运行之间进行比较。时间戳通常是单调递增的，并且不受时间调整的影响，但是在设置位置时它会被重置。

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.

setSyncParams

Added in API level 23

void setSyncParams (SyncParams params)

设置A / V同步模式。

Parameters
`params`	`SyncParams`: the A/V sync params to apply

Throws
`IllegalStateException`	if the internal player engine has not been initialized.
`IllegalArgumentException`	if params are not supported.

setVideoScalingMode

Added in API level 16

void setVideoScalingMode (int mode)

设置视频缩放模式。要在播放过程中使目标视频缩放模式有效，必须在设置数据源后调用此方法。如果未调用，则默认的视频缩放模式为VIDEO_SCALING_MODE_SCALE_TO_FIT 。

支持的视频缩放模式是：

Parameters
`mode`	`int`: target video scaling mode. Must be one of the supported video scaling modes; otherwise, IllegalArgumentException will be thrown.

也可以看看：

setVolume

Added in API level 1

void setVolume (float leftVolume, 
                float rightVolume)

设定此播放器的音量。建议使用此API来平衡应用程序中音频流的输出。除非您正在编写用于控制用户设置的应用程序，否则应优先使用此API，而setStreamVolume(int, int, int)用于设置特定类型的所有流的音量的setStreamVolume(int, int, int) 。请注意，传递的音量值是0.0到1.0范围内的原始标量。 UI控件应该以对数形式进行缩放。

Parameters
`leftVolume`	`float`: left volume scalar
`rightVolume`	`float`: right volume scalar

setWakeMode

Added in API level 1

void setWakeMode (Context context, 
                int mode)

设置此MediaPlayer的低级电源管理行为。当MediaPlayer不通过使用setDisplay(SurfaceHolder)设置的SurfaceHolder进行setDisplay(SurfaceHolder) ，可以使用此功能，因此可以使用高级setScreenOnWhilePlaying(boolean)功能。

此功能让MediaPlayer访问低级电源管理器服务，以在播放过程中控制设备的用电量。该参数是PowerManager唤醒标志的组合。使用此方法需要WAKE_LOCK权限。默认情况下，不会尝试在播放过程中使设备保持唤醒状态。

Parameters
`context`	`Context`: the Context to use
`mode`	`int`: the power/wake mode to set

也可以看看：

PowerManager

start

Added in API level 1

void start ()

开始或继续播放。如果播放先前已暂停，播放将从暂停的位置继续播放。如果播放已停止，或从未开始播放，播放将从头开始。

Throws
`IllegalStateException`	if it is called in an invalid state

stop

Added in API level 1

void stop ()

播放停止或暂停后停止播放。

Throws
`IllegalStateException`	if the internal player engine has not been initialized.

Protected methods

finalize

Added in API level 1

void finalize ()

当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。子类会覆盖finalize方法来处置系统资源或执行其他清理。

的常规协定finalize是，它被调用，如果当在Java ^TM虚拟机已确定不再有由该目的可以通过还没有死亡，除了作为一个动作的结果的任何线程访问的任何手段取决于某些其他可以完成的对象或类别的最终定稿。 finalize方法可以采取任何行动，包括使该对象再次可用于其他线程; 然而， finalize的通常目的是在对象被不可撤销地丢弃之前执行清理操作。例如，表示输入/输出连接的对象的finalize方法可能会执行显式I / O事务，以在永久丢弃该对象之前中断连接。

类Object的finalize方法Object执行特殊操作; 它只是正常返回。 Object子类可能会覆盖此定义。

Java编程语言不保证哪个线程将为任何给定的对象调用finalize方法。但是，保证调用finalize的线程在调用finalize时不会保留任何用户可见的同步锁。如果finalize方法引发未捕获的异常，则忽略该异常，并终止该对象的终止。

在针对某个对象调用 finalize方法之后，在Java虚拟机再次确定不再有任何方法可以通过尚未死亡的任何线程访问此对象，包括可能的操作通过准备完成的其他对象或类别，此时该对象可能被丢弃。

对于任何给定的对象，Java虚拟机永远不会多次调用 finalize方法。

由 finalize方法抛出的任何异常 finalize导致此对象的终止被暂停，但会被忽略。

Most visited

Recently visited

Results for

MediaPlayer

Developer Guides

State Diagram

Valid and invalid states

Permissions

Callbacks

Summary

Nested classes

Constants

Fields

Public constructors

Public methods

Protected methods

Inherited methods

Constants

MEDIA_ERROR_IO

MEDIA_ERROR_MALFORMED

MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

MEDIA_ERROR_SERVER_DIED

MEDIA_ERROR_TIMED_OUT

MEDIA_ERROR_UNKNOWN

MEDIA_ERROR_UNSUPPORTED

MEDIA_INFO_BAD_INTERLEAVING

MEDIA_INFO_BUFFERING_END

MEDIA_INFO_BUFFERING_START

MEDIA_INFO_METADATA_UPDATE

MEDIA_INFO_NOT_SEEKABLE

MEDIA_INFO_SUBTITLE_TIMED_OUT

MEDIA_INFO_UNKNOWN

MEDIA_INFO_UNSUPPORTED_SUBTITLE

MEDIA_INFO_VIDEO_RENDERING_START

MEDIA_INFO_VIDEO_TRACK_LAGGING

MEDIA_MIMETYPE_TEXT_SUBRIP

VIDEO_SCALING_MODE_SCALE_TO_FIT

VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING

Fields

mAttributes

mAuxEffectSendLevel

mLeftVolume

mRightVolume

Public constructors

MediaPlayer

Public methods

addTimedTextSource

addTimedTextSource

addTimedTextSource

addTimedTextSource

attachAuxEffect

create

create

create

create

create

deselectTrack

getAudioSessionId

getCurrentPosition

getDuration

getPlaybackParams

getSelectedTrack

getSyncParams

getTimestamp

getTrackInfo

getVideoHeight

getVideoWidth

isLooping

isPlaying

pause

prepare

prepareAsync

release

reset

seekTo

selectTrack

setAudioAttributes

setAudioSessionId

setAudioStreamType

setAuxEffectSendLevel