Android(安卓)MediaPlayer

android.media.MediaPlayer

MediaPlayer类可以用来控制音频/视频文件的播放， android.widget.VideoView类演示了如何使用 MediaPlayer 这个类的方法。
本章的主题包括以下几个方面： 1. State Diagram（状态转换图） 2. Valid and Invalid States（有效与无效状态） 3. Permissions（权限） 4. Register informational and error callbacks（注册消息与错误回调）

State Diagram

音/视频文件的回放及流的播放控制可以用一个状态机来描述。下面的这张图展示了一个 MediaPlayer 对象的生命周期及各种可能的状态，这些状态的转换都是由回放控制操作来完成的。其中的椭圆代表了一个 MediaPlayer 对象可以处于的状态，而那些弧线代表了回放控制操作使对象发生的状态转换。下图有两种类型的弧线，带单个箭头的弧线表示同步（synchronous）方法调用，而带有双箭头的弧线表示异步（asynchronous）方法调用。

从这个状态机图中可以看到，一个 MediaPlayer 对象有下面这些状态：
1. 当一个 MediaPlayer 对象刚通过 new 来创建或在调用 reset() 方法被调用后，这个对象就处于 Idle 状态；而在 release() 方法被调用后，该对象就处于 End 状态。MediaPlayer 对象的生命周期就处于这两个状态之间。
（1）一个刚由 new 创建的全新的 MediaPlayer 对象与被调用了 reset() 方法的 MediaPlayer 对象之间有一个微小但是却非常重要的差别。在 Idle 状态下，调用这两种对象的 getCurrentPosition(),getDuration(),getVideoHeight(),getVideoWidth(),setAudioStreamType(int),setLooping(boolean),setVolume(float, float),pause(),start(),stop(),seekTo(int),prepare()or prepareAsync()方法都是错误的用法。在一个 MediaPlayer 对象刚被创建之后，就马上调用这些方法中的任意一个或多个，那么提供给用户的 OnErrorListener.onError() 回调方法是不会被内部的播放引擎调用的，且对象状态保持不变。但是如果在调用 reset() 方法后，就马上调用这些方法中的一个或多个，OnErrorListener.onError()回调方法就会被内部的播放引擎调用，且对象会转换到 Error 状态。（2）当一个 MediaPlayer 对象不再被使用时，建议马上调用 release() 方法，这样 MediaPlayer 对象的相关播放引擎所使用的资源就会立即被释放掉，这些资源可能包括单例资源（如硬件加速组件）。如果调用 release() 方法失败，会导致 MediaPlayer 对象无法正确地回退到相应的状态。一旦一个 MediaPlayer 对象进入 End 状态，它就不可再使用了，也不可能使它转换到其它任何一种状态。（3）此外，用 new 来创建的 MediaPlayer 对象在创建刚完成时处于 Idle 状态，而那些通过重载的 create() 方法所创建的对象在创建刚完成时是不会处于 Idle 对象的。事实上，如果 create() 方法调用成功，那么这些对象就会处理 Prepared 状态。
2.通过，一些播放控制操作可能会由于各种原因而失败，如 audio/video 格式不受支持、音/视频交错模式有错、分辨率太高、流超时等。所以在这种情况下，错误报告和恢复就显得非常重要。有时，可能也会由于编程上的失误，在 Invalid 状态下调用播放控制操作。在所有这些错误发生时，如果事先已经通过setOnErrorListener(android.media.MediaPlayer.OnErrorListener)方法注册了一个OnErrorListener 对象，那么内部的播放引擎就会调用提供给用户的 OnErrorListener.onError() 方法。
（1）注意当错误发生时，即使 error listener 对象没有被注册，MediaPlayer 对象也会进入 Error 状态（除了上面提到的那种情况之外）；（2）为了重新使用一个处于 Error 状态的 MediaPlayer 对象及从错误中恢复过来，可以通过调用 reset() 方法来使该对象恢复到 Idle 状态；（3）为了方便查看内部播放引擎所报告的出错情况，建议你要为自己的应用注册 OnErrorListener 监听器；（4）为了防止编程失误，如在 Invalid 状态调用 prepare(), prepareAsync(), 或任意一种重载的 setDataSource方法，在进行一些非常操作时会抛出 IllegalStateException错误。
3. 调用 setDataSource(FileDescriptor), or setDataSource(String), or setDataSource(Context, Uri), or setDataSource(FileDescriptor, long, long)方法会使一个 MediaPlayer 对象从 Idle 状态转换到 Initialized 状态。
（1）在 Idle 状态之外的其它任一状态下调用 setDataSource() 方法，会抛出一个 IllegalStateException 错误；（2）建议注意调用 setDataSource() 重载方法时所可能抛出的 IllegalArgumentException和IOException 错误。
4.在播放开始前，一个 MediaPlayer 对象必须先进入 Prepared 状态。
（1）有两种途径（同步、异步）可以进入 Prepared 状态：第一种是通过调用 prepare() （同步）方法，当这个方法返回时，MediaPlayer 对象就进入 Prepared 状态了；第二种方法是通过调用 prepareAsync() （异步）方法，这个方法返回后，内部的播放引擎会继续进行一系列的准备工作，直到这些工作全部完成后，MediaPlayer 对象就进入 Prepared 状态了。紧接着，如果用户事先通过setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener)方法注册了一个监听器，那么内部播放引擎就会回调用 OnPrepareListener 接口的 onPrepared() 方法。（2）注意 Praparing 状态是一个瞬时状态，在 Preparing 状态下调用任何方法可能产生的副作用还没有定义；（3）在其它任何状态下调用 prepare()or prepareAsync()都抛出 IllegalStateException 错误；（4）在 Prepared 状态下，可以通过相关方法调用来调整 audio/sound volume, screenOnWhilePlaying, looping 等属性。
5.开始播放一定得由 start() 方法来完成，在 start() 方法成功返回后，MediaPlayer 对象就处于 Started 状态。可以通过调用 isPlaying() 方法来检测 MediaPlayer 对象是否处于 Started 状态。
（1）在 Started 状态下，如果用户事先通过setOnBufferingUpdateListener(OnBufferingUpdateListener) 方法注册了一个 OnBufferingUpdateListener 监听器，那么内部的播放引擎就会调用它提供给用户的 OnBufferingUpdateListener.onBufferingUpdate() 回调方法。这个回调方法可实现应用程序对音/视频流缓冲状态的跟踪。（2）如果一个 MediaPlayer 对象已经处于 Started 状态，那么再调用 stasrt() 方法将不会再起什么作用了。
6.播放可以暂停或停止，当前播放的位置也可以进行调整。可以通过调用 pause() 来暂停播放，这个方法返回后，MediaPlayer 对象就进入 Paused 状态。注意内部播放引擎进行的从 Started 状态到 Paused 状态的转换是异步的，反之亦然。在调用 isPlaying() 后，状态的更新可能需要花一点时间。
（1）调用 start() 方法可以使 MediaPlayer 对象从 paused 状态恢复到播放状态，播放起始位置就是之前它停止时候的位置，当 start() 方法返回时，MediaPlayer 就回到 Started 状态了；（2）如果一个 MediaPlayer 已经处于 Paused 状态，那么再调用 pause() 将不会再起什么使用了。
7.调用 stop() 方法可以停止播放，也可以使一个 MediaPlayer 对象从 Started, Paused, Prepared 或PlaybackCompleted 进入 Stopped 状态。（1）一旦进入 Stopped 状态，就无法再开始播放直到再次调用 prepare() 或 prepareAsync() 方法使 MediaPlayer 对象重新进入 Prepared 状态；（2）如果 MediaPlayer 对象已经处于 Stopped 状态，那么再调用 stop() 方法将不会再起什么使用了。
8.可以通过 seekTo(int) 方法调整播放位置。（1）虽然异步的 seekTo(int) 方法会立即返回，但是实际上 seek 操作需要一点时间才可完成，特别是当 audio/video 已经被转换成流了以后。当重定位完成后，如果用户事先已经通过setOnSeekCompleteListener(OnSeekCompleteListener)方法注册了一个 OnSeekCompleteListener 对象，那么播放引擎就会回调提供给用户的 OnSeekComplete.onSeekComplete() 方法；（2）注意在其它状态下，seekTo(int) 方法也可以被调用，如在 Prepared、Paused 和 PlaybackComleted 状态下。（3）此外，可以通过 getCurrentPosition() 方法来获取当前的播放位置，这对于跟踪当前播放进度是非常有用的。
9.当播放到流的末尾时，播放就完成了。（1）如果设置了 looping 模式已经通过setLooping(boolean) 设置为 true ，那么 MediaPlayer 对象就会保持在 Started 状态（即播放到流的末尾后再重复播放）；（2）如果 looping 模式设置为 false ，那么如果用户事先已经通过setOnCompletionListener(OnCompletionListener) 方法注册了一个 OnCompletionListener 监听器，那么播放引擎就会回调提供给用户的 OnCompletion.onCompletion() 方法；（3）在处于 PlaybackCompleted 状态时，如果调用 start() 方法，那么就会重新从 audio/video 源的开始处播放。

Valid and invalid states

在官方文档中，有一个表格说明了在 Valid 与 Invalid 状态下，可以调用及不可调用的方法，在出错时请留意，在此省略......
Permissions
如果你需要声明相关的 WAKE_LOCK ，那请在配置文件中通过<uses-permission>元素来定义；如果你要在 MediaPlayer 类中使用网络资源，请在配置文件中申请android.Manifest.permission.INTERNET权限。

Callbacks

如果应用程序需要对内部状态的更新或在播放时出错的信息进行监听捕获，那么就可以通过注册适当的监听器来实现，下面是一些常用的注册监听器的方法

via calls to

setOnPreparedListener(OnPreparedListener)setOnPreparedListener,

setOnVideoSizeChangedListener(OnVideoSizeChangedListener)setOnVideoSizeChangedListener,

setOnSeekCompleteListener(OnSeekCompleteListener)setOnSeekCompleteListener,

setOnCompletionListener(OnCompletionListener)setOnCompletionListener,

setOnBufferingUpdateListener(OnBufferingUpdateListener)setOnBufferingUpdateListener,

setOnInfoListener(OnInfoListener)setOnInfoListener,

setOnErrorListener(OnErrorListener)setOnErrorListener, etc).

In order to receive the respective callback associated with these listeners, applications are required to create MediaPlayer objects on a thread with its own Looper running (main UI thread by default has a Looper running).

--------下面是这个类的内部接口（类）、常量、方法等具体内容--------

Nested Classes（内部类）
interface	MediaPlayer.OnBufferingUpdateListener	定义了当从网络上接收 media source 时的缓冲状态的回调
interface	MediaPlayer.OnCompletionListener	定义了当 media source 播放完成时的回调
interface	MediaPlayer.OnErrorListener	定义了当进行异步操作出错时的回调（其它错误将会在方法调用时就抛出）
interface	MediaPlayer.OnInfoListener	定义了一些通信信息和媒体播放过程中出现警告时的回调
interface	MediaPlayer.OnPreparedListener	当 media source 准备好播放时回调
interface	MediaPlayer.OnSeekCompleteListener	当 seek 操作完成时的回调
interface	MediaPlayer.OnTimedTextListener	当一个定时的文本可用于显示时的回调
interface	MediaPlayer.OnVideoSizeChangedListener	当 video size 第一次被知道或更新时的回调
class	MediaPlayer.TrackInfo	一个用于给 MediaPlayer 返回每个 audio/video/subtitle track's 的元信息的类

这个常量表的用处非常大，当程序出错时，在 Log 里会打印出相应的错误信息。在这些信息中，每个 Constant Value: 701 (0x000002bd) 形式的信息对应一个具体的常理，所以你可以根据这个表知道程序出了什么错。

Constants（常量）
int	MEDIA_ERROR_IO	文件或网络相关操作出错
int	MEDIA_ERROR_MALFORMED	Bitstream 与相关的编码标准或具体文件不相匹配
int	MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK	video 已经被转换成流且其容器不支持 progressive 播放，如 video 的下标没有从文件的开始处算起
int	MEDIA_ERROR_SERVER_DIED	Media server 挂掉了
int	MEDIA_ERROR_TIMED_OUT	一些操作长时间没完成（超时），通常是3-5秒
int	MEDIA_ERROR_UNKNOWN	一些未定义的 media 播放器错误
int	MEDIA_ERROR_UNSUPPORTED	Bitstream 与相关的编码标准相符合，但是 media 框架并不支持其特性要求
int	MEDIA_INFO_BAD_INTERLEAVING	交错出错意味着交错存储的 media 有错误或者根本没交错
int	MEDIA_INFO_BUFFERING_END	MediaPlayer is resuming playback after filling buffers.
int	MEDIA_INFO_BUFFERING_START	为了缓冲更多的数据，MediaPlayer 暂停播放
int	MEDIA_INFO_METADATA_UPDATE	一个新的元数据集可用
int	MEDIA_INFO_NOT_SEEKABLE	media 无法定位播放（如直播）
int	MEDIA_INFO_SUBTITLE_TIMED_OUT	读取字幕 track 超时
int	MEDIA_INFO_UNKNOWN	未定义的 media player 信息
int	MEDIA_INFO_UNSUPPORTED_SUBTITLE	media framework 不支持 subtitle track
int	MEDIA_INFO_VIDEO_RENDERING_START	The player just pushed the very first video frame for rendering.
int	MEDIA_INFO_VIDEO_TRACK_LAGGING	video 太复杂，以致于 decoder 无法解码，即 decode 帧的速度太慢
String	MEDIA_MIMETYPE_TEXT_SUBRIP	MIME type for SubRip (SRT) container.
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() 默认的构造方法

Public Methods（公有方法）
void	addTimedTextSource(Contextcontext,Uriuri,StringmimeType) Adds an external timed text source file (Uri).增加一个外部的 timed text 源文件（Uri）
void	addTimedTextSource(Stringpath,StringmimeType) 增加一个外部的 timed text 源文件
void	addTimedTextSource(FileDescriptorfd, long offset, long length,StringmimeType) 增加一个外部的 timed text 源文件(FileDescriptor).
void	addTimedTextSource(FileDescriptorfd,StringmimeType) 增加一个外部的 timed text 源文件(FileDescriptor).
void	attachAuxEffect(int effectId) Attaches an auxiliary effect to the player.
staticMediaPlayer	create(Contextcontext,Uriuri,SurfaceHolderholder) 为指定的 Uri 创建一个 MediaPlayer 对象
staticMediaPlayer	create(Contextcontext, int resid) 为指定的 resource id 创建一个MediaPlayer 对象
staticMediaPlayer	create(Contextcontext,Uriuri) 为指定的 Uri 创建一个 MediaPlayer 对象
void	deselectTrack(int index) 取消一个 track
int	getAudioSessionId() 返回 audio session 的 ID
int	getCurrentPosition() 返回当前播放的位置
int	getDuration() 返回 file 的时长
TrackInfo[]	getTrackInfo() 通过一个数组返回一个 track 的信息
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	release() Releases resources associated with this MediaPlayer object.
void	reset() Resets the MediaPlayer to its uninitialized state.
void	seekTo(int msec) Seeks to specified time position.
void	selectTrack(int index) Selects a track.
void	setAudioSessionId(int sessionId) Sets the audio session ID.
void	setAudioStreamType(int streamtype) Sets the audio stream type for this MediaPlayer.
void	setAuxEffectSendLevel(float level) Sets the send level of the player to the attached auxiliary effect .
void	setDataSource(Stringpath) Sets the data source (file-path or http/rtsp URL) to use.
void	setDataSource(Contextcontext,Uriuri,Map<String,String> headers) Sets the data source as a content Uri.
void	setDataSource(Contextcontext,Uriuri) Sets the data source as a content Uri.
void	setDataSource(FileDescriptorfd, long offset, long length) Sets the data source (FileDescriptor) to use.
void	setDataSource(FileDescriptorfd) Sets the data source (FileDescriptor) to use.
void	setDisplay(SurfaceHoldersh) Sets the `SurfaceHolder`to use for displaying the video portion of the media.
void	setLooping(boolean looping) Sets the player to be looping or non-looping.
void	setNextMediaPlayer(MediaPlayernext) Set the MediaPlayer to start when this MediaPlayer finishes playback (i.e.
void	setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListenerlistener) Register a callback to be invoked when the status of a network stream's buffer has changed.
void	setOnCompletionListener(MediaPlayer.OnCompletionListenerlistener) Register a callback to be invoked when the end of a media source has been reached during playback.
void	setOnErrorListener(MediaPlayer.OnErrorListenerlistener) Register a callback to be invoked when an error has happened during an asynchronous operation.
void	setOnInfoListener(MediaPlayer.OnInfoListenerlistener) Register a callback to be invoked when an info/warning is available.
void	setOnPreparedListener(MediaPlayer.OnPreparedListenerlistener) Register a callback to be invoked when the media source is ready for playback.
void	setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListenerlistener) Register a callback to be invoked when a seek operation has been completed.
void	setOnTimedTextListener(MediaPlayer.OnTimedTextListenerlistener) Register a callback to be invoked when a timed text is available for display.
void	setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListenerlistener) Register a callback to be invoked when the video size is known or updated.
void	setScreenOnWhilePlaying(boolean screenOn) Control whether we should use the attached SurfaceHolder to keep the screen on while video playback is occurring.
void	setSurface(Surfacesurface) Sets the `Surface`to be used as the sink for the video portion of the media.
void	setVideoScalingMode(int mode) Sets video scaling mode.
void	setVolume(float leftVolume, float rightVolume) 设置播放声音
void	setWakeMode(Contextcontext, int mode) Set the low-level power management behavior for this MediaPlayer.
void	start() 开始或恢复播放
void	stop() 停止播放

Protected Methods（保护方法）
void	finalize() 当垃圾回收器发现某个对象不可达时，调用此方法以回收该对象的内存

State Diagram

Valid and invalid states

Callbacks

更多相关文章

随机推荐