android MediaPlayer

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 suppZ喎?/kf/ware/vc/" target="_blank" class="keylink">vcnRlZCBwbGF5YmFjayBjb250cm9sIG9wZXJhdGlvbnMuIFRoZSBvdmFsczwvcD4KPHA+IHJlcHJlc2VudCB0aGUgc3RhdGVzIGEgTWVkaWFQbGF5ZXIgb2JqZWN0IG1heSByZXNpZGUgaW4uIFRoZSBhcmNzIHJlcHJlc2VudCB0aGUgcGxheWJhY2sgY29udHJvbCBvcGVyYXRpb25zIHRoYXQ8L3A+CjxwPiBkcml2ZSB0aGUgb2JqZWN0IHN0YXRlIHRyYW5zaXRpb24uIFRoZXJlIGFyZSB0d28gdHlwZXMgb2YgYXJjcy4gVGhlIGFyY3Mgd2l0aCBhIHNpbmdsZSBhcnJvdyBoZWFkIHJlcHJlc2VudDwvcD4KPHA+IHN5bmNocm9ub3VzIG1ldGhvZCBjYWxscywgd2hpbGUgdGhvc2Ugd2l0aCBhIGRvdWJsZSBhcnJvdyBoZWFkIHJlcHJlc2VudCBhc3luY2hyb25vdXMgbWV0aG9kIGNhbGxzPHN0cm9uZz4uPC9zdHJvbmc+PC9wPgo8cD48c3Ryb25nPjxicj4KPC9zdHJvbmc+PC9wPgo8cD48c3Ryb25nPii0y828zqqypbfFPC9zdHJvbmc+PHN0cm9uZz6/2NbGtcTJ+sP81tzG2te0zKzNvKOszdbUstDOtPqx7U1lZGlhUGxheWVyttTP88v5xNzXpMH0tcTXtMyso6y1pbj2vP3Nt7T6se3NrLK9t723qLX308OjrMurPC9zdHJvbmc+PC9wPgo8cD48c3Ryb25nPjxicj4KPC9zdHJvbmc+PC9wPgo8cD48c3Ryb25nPrj2vP3Nt7T6se08L3N0cm9uZz48c3Ryb25nPtLssr23vbeotffTwyk8L3N0cm9uZz48c3Ryb25nPsjnzbzL+cq+sPy6rMjnz8LL+cr217TMrKO6PC9zdHJvbmc+PC9wPgo8cD48c3Ryb25nPjxicj4KPC9zdHJvbmc+PC9wPgo8cD5XaGVuIGEgTWVkaWFQbGF5ZXIgb2JqZWN0IGlzIGp1c3QgY3JlYXRlZCB1c2luZyBuZXcgb3IgYWZ0ZXIgcmVzZXQoKSBpcyBjYWxsZWQsIGl0IGlzIGluIHRoZSBJZGxlIHN0YXRlOyBhbmQgYWZ0ZXI8L3A+CjxwPiByZWxlYXNlKCkgaXMgY2FsbGVkLCBpdCBpcyBpbiB0aGUgRW5kIHN0YXRlLiBCZXR3ZWVuIHRoZXNlIHR3byBzdGF0ZXMgaXMgdGhlIGxpZmUgY3ljbGUgb2YgdGhlIE1lZGlhUGxheWVyIG9iamVjdC48L3A+CjxwPjxicj4KPC9wPgo8cD48c3Ryb25nPqOotbHSuzwvc3Ryb25nPjxzdHJvbmc+uPZNZWRpYVBsYXllcrbUz/Oxu25ld7P1yry7r6Osu/LV37X308NyZXNldCgpyrG0ptPaSWRsZde0zKyjrLX308NyZWxlYXNlKCm687Sm09pFbmTXtMyso6zU2tXiwb08L3N0cm9uZz48L3A+CjxwPjxzdHJvbmc+PGJyPgo8L3N0cm9uZz48L3A+CjxwPjxzdHJvbmc+1tbXtMysPC9zdHJvbmc+PHN0cm9uZz7Wrrzk1PK0ptPaTWVkaWFQbGF5ZXK21M/ztcTJ+sP81tzG2qOpPC9zdHJvbmc+PC9wPgo8cD48c3Ryb25nPjxicj4KPC9zdHJvbmc+PC9wPgo8cD48L3A+CjxibG9ja3F1b3RlPgo8cD5UaGVyZSBpcyBhIHN1YnRsZSBidXQgaW1wb3J0YW50IGRpZmZlcmVuY2UgYmV0d2VlbiBhIG5ld2x5IGNvbnN0cnVjdGVkIE1lZGlhUGxheWVyIG9iamVjdCBhbmQgdGhlPC9wPgo8cD4gTWVkaWFQbGF5ZXIgb2JqZWN0IGFmdGVyIHJlc2V0KCkgaXMgY2FsbGVkLiBJdCBpcyBhIHByb2dyYW1taW5nIGVycm9yIHRvIGludm9rZSBtZXRob2RzIHN1Y2ggYXM8L3A+CjxwPiBnZXRDdXJyZW50UG9zaXRpb24oKSwgZ2V0RHVyYXRpb24oKSwgZ2V0VmlkZW9IZWlnaHQoKSwgZ2V0VmlkZW9XaWR0aCgpLCBzZXRBdWRpb1N0cmVhbVR5cGUoaW50KSw8L3A+CjxwPiBzZXRMb29waW5nKGJvb2xlYW4pLCBzZXRWb2x1bWUoZmxvYXQsIGZsb2F0KSwgcGF1c2UoKSwgc3RhcnQoKSwgc3RvcCgpLCBzZWVrVG8oaW50KSwgcHJlcGFyZSgpIG9yIHByZXBhcmVBc3luYygpPC9wPgo8cD4gaW4gdGhlIElkbGUgc3RhdGUgZm9yIGJvdGggY2FzZXMuIElmIGFueSBvZiB0aGVzZSBtZXRob2RzIGlzIGNhbGxlZCByaWdodCBhZnRlciBhIE1lZGlhUGxheWVyIG9iamVjdCBpcyBjb25zdHJ1Y3RlZCw8L3A+CjxwPiB0aGUgdXNlciBzdXBwbGllZCBjYWxsYmFjayBtZXRob2QgT25FcnJvckxpc3RlbmVyLm9uRXJyb3IoKSB3b24="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

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.

（當在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