Android (Java) Learning Note 241: API call graph for multimedia Media Player

The MediaPlayer class can be used to control the playback of audio/video files or streams. You can also read the documentation for the Videoview class on how to use this class.

1. State diagram
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 Prepareasync () Methods are programming errors. 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 registration of the Onerrorlistener.onerror () method But if the MediaPlayer object calls the Reset () method and then calls the methods above, the internal playback engine will call back the Onerrorlistener.onerror () method registered by the client program and pass in the wrong state.

1.2) We recommend that once a MediaPlayer object is no longer in use, the release () method should be called immediately to release the resources associated with this MediaPlayer object in the internal playback engine. 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, while those created by the overloaded create () convenience method are 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, the MediaPlayer 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) calls some methods in an illegal state, such as prepare (), Prepareasync (), and the Setdatasource () method to throw a 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 this mediaplayer is in a different state, calling the Setdatasource () method throws a IllegalStateException exception.

3.2) good programming habits are not to neglect the illegalargumentexception exceptions and IOException exceptions that may be thrown when calling the Setdatasource () method.


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 call the Prepare () method (synchronous), This method returns to indicate that the MediaPlayer object has entered the prepared state, or to call the Prepareasync () method (async), which causes the MediaPlayer object to enter the preparing state and return it. The internal playback engine will continue to prepare for unfinished work. 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 the 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 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) has 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) calls the start () method to have a MediaPlayer object in the paused state resume playback from where it was previously paused. When the start () method is called to return, the state of the MediaPlayer object becomes the started state again.

6.2) has no effect on the pause () method of 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) has no effect on the Stop () method of 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 the Seekto (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 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 playbackcompleted state, you can call the start () method again to let the MediaPlayer object enter the started state again.

Android (Java) Learning Note 241: API call graph for multimedia Media player