android MediaPlayer

Playback control of audio/video files and streams is managed as a state machine. The following diagram shows

thelife 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.

(此图为播放控制的生命周期状态图，椭圆形代表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.

（当一个MediaPlayer对象被new初始化，或者调用reset()时处于Idle状态，调用release()后处于End状态，在这两

种状态之间则处于MediaPlayer对象的生命周期）

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.

（新创建的MediaPlayer对象与调用reset()后的对象有微妙的区别，调用路上英文所述中的方法在Idle状态之后

对于这两种情况来说都是一个编程错误，在创建MediaPlayer对象后调用如上英文所述的任何一个方法都不会调

用OnErrorListener.onError()回调，而且状态也不会改变，但是在reset()后调用如上英文所述的任何一个方法

将调用OnErrorListener.onError()回调并进入错误状态）

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.

(建议一旦MediaPlayer对象不再使用就要调用release()释放资源，一旦MediaPlayer 对象调用release()处于

End状态后将不能回到前面任何一个状态)

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

（使用new创建的MediaPlayer对象处于Idle状态，那些使用create静态便利方法创建的MediaPlayer对象不是处

于Idle状态而是进入了Prepared状态）

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).

（播放控制将会失败由于各种原因，如：不支持的格式，分辨率太高，流超时等等，因此错误报告和恢复将是重要的

在这些情况下，这些所有原因将会调用用户已经注册的回调函数OnErrorListener.onError()）

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.

（一旦错误发生，MediaPlayer对象将进入Error状态，不管有没有注册错误监听）

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.

（为了重用MediaPlayer对象，调用reset()方法将从错误状态恢复到Idle状态）

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.

（IllegalStateException错误将被抛出，在调用prepare()，prepareAsync()或任何一个setDataSource()方法

在无效的状态）

Calling setDataSource(FileDescriptor), or setDataSource(String), or setDataSource(Context, Uri), or

setDataSource(FileDescriptor, long, long) transfers a MediaPlayer object in the Idle state to the Initialized state.

（调用任何一个重载的setDataSource方法将从Idle状态进入初始化状态）

An IllegalStateException is thrown if setDataSource() is called in any other state.

（在非Idle状态下调用setDataSource()将抛出IllegalStateEx异常ception）

It is good programming practice to always look out for IllegalArgumentException and IOException that may be

thrown from the overloaded setDataSource methods.

（在调用setDataSource后检测是否会抛出IllegalArgumentException和IOException异常是一个好的编程习

惯）

A MediaPlayer object must first enter the Prepared state before playback can be started.

（MediaPlayer对象必须进入Prepared状态下播放才能够被开始）

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).

（有两种方式进入Prepared状态，第一种是synchronous方式，只要调用prepare()后一旦该方法返回就进入了

Prepared状态，第二种是asynchronous方式，调用prepareAsync()将进入Preparing状态，当Preparing状态

完成并返回才进入Prepared状态，如果Preparing状态完成或者调用prepare()并返回之后将调用已经注册了的

OnPreparedListener的onPrepared()方法，通过setOnPreparedListener方式注册）

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.

（Preparing是一个短暂的状态并且没有定义的）

An IllegalStateException is thrown if prepare() or prepareAsync() is called in any other state.

（在非初始化状态下下调用prepare()和prepareAsync()将抛出IllegalStateException异常）

While in the Prepared state, properties such as audio/sound volume, screenOnWhilePlaying, looping can be

adjusted by invoking the corresponding set methods.

（当在Prepared状态下调用相应的设置属性方法）

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.

（为了开始播放必须调用start()方法，调用start()返回成功后进入Started状态，isPlaying()可以用来测试是否在

Started状态）

While in the Started state, the internal player engine calls a

usersuppliedOnBufferingUpdateListener.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.

（当在Started时，播放引擎调用用户设置的OnBufferingUpdateListener.onBufferingUpdate() 回调，这个回

调运行程序跟踪音频和视频流的状态）

Calling start() has not effect on a MediaPlayer object that is already in the Started state.

（已经在Started状态后在调用start()方法是没有效果的）

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.

（播放器能被暂停，停止或者调整播放位置，当调用pause()方法返回后进入Paused状态，从Started进入Paused状

态或从Paused状态进入Started状态时异步的，这将花费一定时间，可用isPlaying()进行判断状态）

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.

（在Paused状态下调用start()将恢复到原来的暂停时的位置）

Calling pause() has no effect on a MediaPlayer object that is already in the Paused state.

（已经在Paused状态下调用pause()是没有影响的）

Calling stop() stops playback and causes a MediaPlayer in the Started, Paused, Prepared or PlaybackCompleted

state to enter the Stopped state.

（调用stop()方法导致播放器从Started状态，Prepared状态，Paused状态或PlaybackCompleted状态进入

Stopped状态）

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.

（一旦进入了Stopped状态，播放器不能只有调用prepare()或prepareAsync()设置后才能再次进入Prepared状

态）

Calling stop() has no effect on a MediaPlayer object that is already in the Stopped state.

（已经处于Stopped的MediaPlayer再次调用stop()没有影响的）

The playback position can be adjusted with a call to seekTo(int).

（能够通过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).

（seekTo(int)调用会花费一定的时间完成尤其在audio/video流的情况下，当seek方法嗲用完成会回调由用户

通过setOnSeekCompleteListener(OnSeekCompleteListener)注册的OnSeekComplete.onSeekComplete()

方法监听方法）

Please note that seekTo(int) can also be called in the other states, such as Prepared, Paused and

PlaybackCompleted state.

（注意，seekTo(int)也能被调用在Prepared状态，Prepared状态或者PlaybackCompleted状态）

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.

（此外，播放器的确切位置通过调用getCurrentPosition()方法来检索，能够帮助进度条跟踪播放器的进度）

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.

（通过调用setLooping(boolean)设置循环模式，MediaPlayer对象会停留在Started状态）

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.

（当looping模式设置为false，播放引擎在播放完成的时候回调用户通过

setOnCompletionListener(OnCompletionListener)注册的OnCompletion.onCompletion()方法）

While in the PlaybackCompleted state, calling start() can restart the playback from the beginning of the

audio/video source.

（在PlaybackCompleted状态时调用start()能重新启动播放器到Started状态，并位于audio/video source的开

始位置）

详情参见：http://developer.android.com/reference/android/media/MediaPlayer.html