Go Android MediaPlayer State Machine

Translate Android Reference Manual's MediaPlayer state machine

control over the playback of audio/video files and streams is managed through a state machine. Displays the life cycle and state of a MediaPlayer object that is supported by the playback control operation. The ellipse represents the state where the MediaPlayer object might reside. An arc represents a playback control operation that drives the migration of MediaPlayer between various states. There are two types of arcs here. An arc that starts with an arrow represents a synchronous method call, whereas an arc represented by a double-headed arrow represents an asynchronous method call .
 


with this diagram, we can see that a MediaPlayer object has the following status:

1) When a MediaPlayer object has just been created with the new operator or called the Reset () method, it is in an idle state. When the release () method is called, it is in the end state. Between these two states is the life cycle of the MediaPlayer object.
1.1) There is a small but very important difference between a newly constructed MediaPlayer object and a MediaPlayer object that calls the reset () method. In the idle state, call getcurrentposition (), getduration (), getvideoheight (), getvideowidth ( ), setaudiostreamtype (int), setlooping (Boolean), setvolume (float, float), Pause (), start (), Stop (), seekto (int), prepare () , or The Prepareasync () method is a programming error. When a MediaPlayer object has just been built, the internal playback engine and the state of the object have not changed, at this time to call the above methods, the framework will not be able to callback the client program registered Onerrorlistener.onerror () method, but if the MediaPlayer object calls the Reset () method, and then calls the above methods, the internal playback engine will callback the client program to register the The Onerrorlistener.onerror () method is used and the wrong state is passed in.
1.2) We recommend that once a MediaPlayer object is no longer being used, the release () method should be called immediately to release the internal playback engine with this MediaPlayer The resource associated with the object. Resources may include single-state components such as hardware-accelerated components, and failing to call the release () method may result in the subsequent MediaPlayer object instance being unable to use the single-state hardware resource, thereby returning to the software implementation or failure. Once the MediaPlayer object enters the end state, it can no longer be used, and there is no way to migrate to another state.
1.3) In addition, MediaPlayer objects created with the new operator are in an idle state, and those created by the overloaded create () convenience method The MediaPlayer object is not in an idle state. In fact, if the overloaded create () method is called successfully, then these objects are already prepare state.

2) in general, for various reasons some playback control operations may fail, such as unsupported audio/video format, lack of interlaced audio/video, resolution too high, stream timeout, and so on. Therefore, error reporting and recovery are very important in this case. Sometimes, because of a programming error, a playback control operation may occur in the case of an invalid state. Under all these error conditions, the internal playback engine invokes a Onerrorlistener.onerror () method provided by the client programmer. Client programmers can register Onerrorlistener by calling the Mediaplayer.setonerrorlistener (Android.media.MediaPlayer.OnErrorListener) method.
2.1) Once an error occurs, theMediaPlayer object enters the error state.
2.2) In order to reuse a MediaPlayer object in the error state, you can call the reset () method to restore the object to an idle state.
2.3) Registering a Onerrorlistener to learn that the internal playback engine error is a good programming habit.
2.4) Calling some methods in an illegal state, such as prepare (), Prepareasync (), and Setdatasource () methods will throw  IllegalStateException exception.

3) call the Setdatasource (FileDescriptor) method, or the Setdatasource (String) method, or the Setdatasource (Context,uri) method, or the Setdatasource (Filedescriptor,long,long) method migrates the idle object to the initialized state.
3.1) If the MediaPlayer is in a different state, calling the Setdatasource () method throws a illegalstateexception exception.
3.2) Good programming habits are not to be negligent when calling the Setdatasource () method when the illegalargumentexception exception may be thrown and  IOException exception.

4) Before starting playback, the MediaPlayer object must enter the prepared state.
4.1) There are two methods (synchronous and asynchronous) that enable the MediaPlayer object to enter the prepared state: either the prepare () method ( synchronous ) is called, and this method returns to represent the The MediaPlayer object has entered the prepared state, or the Prepareasync () method ( async ) is called, and this method causes this MediaPlayer The object enters the preparing state and returns, while the internal playback engine continues the unfinished preparations. The onpreparedlistener.onprepared () listener method provided by the client programmer is invoked when the synchronous version returns or when the asynchronous version preparation is complete. You can call the Mediaplayer.setonpreparedlistener (Android.media.MediaPlayer.OnPreparedListener) method to register Onpreparedlistener.
4.2) Preparing is an intermediate state in which the result of invoking any method with an edge effect is unknown!
4.3) Calling the prepare () and Prepareasync () methods in an inappropriate state throws a illegalstateexception exception. When the MediaPlayer object is in the Prepared state, you can adjust the audio/video properties, such as the volume, whether the playback is always on, looping, and so on.

5) to start playback, you must call the start () method. When this method returns successfully, the MediaPlayer object is in the started state. The IsPlaying () method can be called to test whether a MediaPlayer object is in the started state.
5.1) When in the started state, the internal playback engine invokes the onbufferingupdatelistener.onbufferingupdate () callback method provided by the client programmer, This callback method allows the application to track the buffered state of the stream playback.
5.2) There is no effect on invoking the start () method on a MediaPlayer object that is already in the started state.

6) Playback can be paused, stop, and adjust the current playback position. When the pause () method is called and returned, the MediaPlayer object is brought into the paused state. Note that the reciprocal conversion of the started to the paused state is asynchronous in the internal playback engine. So it may take a little time to update the state in the IsPlaying () method, which may take a few seconds if the stream content is being played.
6.1) Calling the start () method causes a MediaPlayer object in the paused state to resume playback from where it was previously paused. When the start () method is called to return, the state of theMediaPlayer object becomes the started state again.
6.2) The pause () method has no effect on a MediaPlayer object that is already in the paused state.

7) calling the Stop () method stops playback and also causes a mediaplayer in the started,paused,prepared or playbackcompleted state to enter the stopped state.
7.1) The Stop () method has no effect on a MediaPlayer object that is already in the stopped state.

8) Call the Seekto () method to adjust the playback position.
8.1) The seekto (int) method is executed asynchronously, so it can be returned immediately, but the actual location play operation may take some time to complete, especially audio/video in the form of a stream. When the actual location play operation is complete, the internal playback engine invokes the Onseekcomplete.onseekcomplete () callback method provided by the client programmer. Can be registered through the Setonseekcompletelistener (Onseekcompletelistener) method.
8.2) Note that theseekto (int) method can also be called in other states, such as prepared,paused and playbackcompleted states. In addition, the current playback position can actually call the GetCurrentPosition () method to get, it can help the application such as music player to constantly update the playback progress

9) When playing to the end of the stream, playback is complete.
9.1) If the setlooping (Boolean) method is called to turn on the loop mode, the MediaPlayer object will re-enter the started state.
9.2) If no loop mode is turned on, the internal playback engine invokes the oncompletion.oncompletion () callback method provided by the client programmer. Can be set by calling the Mediaplayer.setoncompletionlistener (Oncompletionlistener) method. The internal playback engine once called the oncompletion.oncompletion () callback method, indicating that the MediaPlayer object entered the playbackcompleted state.
9.3) When in the playbackcompleted state, the start () method can be called again to let the MediaPlayer object Enter the started state again.

[Transfer from: http://blog.csdn.net/thl789/article/details/7370438]