MediaPlayer class can be used to control audio / video files or streaming playback. On how to use the methods of this class can also read VideoView class documentation.
1. State diagram
For playing audio / video files and streams is controlled by a state machine to manage. The following figure shows a MediaPlayer object is to support the playback control operation and status-driven life cycle. Elliptical objects may reside on behalf of the state of MediaPlayer. MediaPlayer arc that drive migration between states in the various playback control operation. There are two types of arcs. Arrow to start the arc by a representative of synchronous method calls, and the double arrow at the beginning of the curve on behalf of the representatives of the asynchronous method call.
Through this picture, we can know that a MediaPlayer object has the following states:
1) When a MediaPlayer object is just created with the new operator or call the reset () method, it is in Idle state. When you call the release () method, it is in End state. MediaPlayer between these two states is the object life cycle.
1.1) Construction of a new MediaPlayer object and a call reset () method MediaPlayer objects have a small but very important difference. In the Idle state is calling 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 when the playback engine and the internal state of the object are not changed, more than at this time call those methods, the framework will be unable to register client callback OnErrorListener.onError () method; if The MediaPlayer object called reset () method, then call those methods above, the playback engine will call back within the client program register OnErrorListener.onError () method, and will be passed in the wrong state.
1.2) We propose that once a MediaPlayer object is no longer being used, should immediately call the release () method to release the internal playback engine associated with the MediaPlayer object resources. Resources may include components such as hardware acceleration components of a single state, if not call the release () method may lead to the MediaPlayer object instance after that one state can not use the hardware resources to run back to the software or failure. Once the MediaPlayer object into the End state, it can no longer be used, there is no way to migrate to other states.
1.3) In addition, the use of new operator to create a MediaPlayer object is in Idle state, and those by overloading of the create () convenience method to create the MediaPlayer object is not in the Idle state. In fact, if a successful call to the overloaded create () method, then the object is already Prepare state of the.
2) Under normal circumstances, for various reasons some players control operation may fail if not supported audio / video formats, the lack of interlaced audio / video, high resolution, flow-out and other reasons, and so on. Therefore, the error reporting and recovery in this case is very important. Sometimes, due to programming errors, in the case of an invalid state is called a playback control operation may occur. In all of these error conditions, the internal playback engine will call a client programmer to provide the OnErrorListener.onError () method. The client programmer can call MediaPlayer.setOnErrorListener (android.media.MediaPlayer.OnErrorListener) method to register OnErrorListener.
2.1) in the event of an error, MediaPlayer object into the Error state.
2.2) In order to reuse an object in the Error state MediaPlayer, you can call reset () method to restore this object into Idle state.
2.3) up to learn a OnErrorListener errors that occur within the playback engine is good programming practice.
2.4) in illegal state called a number of ways, such as the prepare (), prepareAsync () and setDataSource () method throws an IllegalStateException.
3) call setDataSource (FileDescriptor) method, or setDataSource (String) method, or setDataSource (Context, Uri) method, or setDataSource (FileDescriptor, long, long) method is in Idle state of the object will migrate to the Initialized state.
3.1) If when the MediaPlayer in the other state, call the setDataSource () method throws an IllegalStateException.
3.2), good programming practice is to not neglect the call setDataSource () method when an exception may be thrown IllegalArgumentException and IOException exceptions.
4) before playback begins, MediaPlayer object must enter the Prepared state.
4.1) There are two methods (synchronous and asynchronous) can make the MediaPlayer object into Prepared state: either call prepare () method (synchronous), this method returns to that of the MediaPlayer object has entered the Prepared state; or call prepareAsync () method ( asynchronous), this method will make the MediaPlayer object into the Preparing state and return, and the internal playback engine to finish his preparations. When the synchronous or asynchronous version returns fully completed version of the preparatory work for the client will be called when the programmer provides OnPreparedListener.onPrepared () listener method. Can call MediaPlayer.setOnPreparedListener (android.media.MediaPlayer.OnPreparedListener) method to register OnPreparedListener.
4.2) Preparing an intermediate state, in this state to call any way with the result of side effects are unknown!
4.3) is called in inappropriate state prepare () and prepareAsync () method throws an IllegalStateException. Prepared state when the MediaPlayer object is the time to adjust the audio / video properties, such as volume, play time is always on screen, loop and so on.
5) To start playing, you must call the start () method. When this method returns successfully, MediaPlayer object is in Started state. isPlaying () method can be called to test whether an object is in the Started state MediaPlayer.
5.1) When in the Started state, the internal playback engine will call the client programmer's OnBufferingUpdateListener.onBufferingUpdate () callback method, this callback allows an application to track the current state of play of the buffer.
5.2) is already in a state of the MediaPlayer object Started calling start () method has no effect.
6) Play can be pause, stop, and adjust the current playback position. When you call the pause () method and returns, will MediaPlayer object into the Paused state. Note Started with the Paused state conversion in the internal playback engine is asynchronous. It may take a little time in isPlaying () method to update the state, if the streaming content, this time there may be a few seconds.
6.1) calls start () method in the Paused state would make a MediaPlayer object suspended from the place before the resumption of play. When you call start () method returns the time, MediaPlayer object's status has become a Started state.
6.2) is already in a state of the MediaPlayer object Paused pause () method has no effect.
7) call stop () method will stop playing, and will make a in Started, Paused, Prepared or PlaybackCompleted state MediaPlayer into Stopped state.
7.1) is already in a state of the MediaPlayer object Stopped stop () method has no effect.
8) Call seekTo () method can adjust the playback position.
8.1) seekTo (int) method is executed asynchronously, so it can return immediately, but the actual operation of the positioning of players may take some time to complete, especially in the form of play streaming audio / video. When the actual positioning Play operation is completed, the internal playback engine will call the client programmer's OnSeekComplete.onSeekComplete () callback method. By setOnSeekCompleteListener (OnSeekCompleteListener) method to register.
8.2) Note, seekTo (int) method can also be invoked in other states, such as Prepared, Paused and PlaybackCompleted state. In addition, the current playback position, the actual can call getCurrentPosition () method available, it can help, such as music player application that plays continuously updated progress
9) When playing to the end of the stream, the player is complete.
9.1) If you call the setLooping (boolean) method to open a circular pattern, then the MediaPlayer object will re-enter the Started state.
9.2) if there is no open loop mode, the playback engine will call within the client programmer's OnCompletion.onCompletion () callback method. By calling MediaPlayer.setOnCompletionListener (OnCompletionListener) method to set. Once inside the playback engine called OnCompletion.onCompletion () callback method to prove that the MediaPlayer object into the PlaybackCompleted state.
9.3) When in PlaybackCompleted state, they can then call the start () method to let this MediaPlayer object re-enter the Started state.