HAKUNAMATATA: [AndroidMultimedia] Mediaplayer APIs

當在執行 MediaPlayer 中有錯，則會呼叫 OnErrorListener.onError()。

You must always be aware of when writing your code, because certain operations are only valid when then player is in specific states.
If you perform an operation while in the wrong state, the system may throw an exception or cause other undesireable behaviors.For example,

When you create a new MediaPlayer, it is in the Idle state. At that point, you should initialize it by calling setDataSource(), bringing it to the Initialized state.
After that, you have to prepare it using either the prepare() or prepareAsync() method. When the MediaPlayer is done preparing, it will then enter the Prepared state, which means you can call start() to make it play the media.
At that point, as the diagram illustrates, you can move between the Started, Paused and PlaybackCompleted states by calling such methods as start(), pause(), and seekTo(), amongst others.

=> Create successful -> Idle -> setDataResource() -> Initialized -> prepare() or prepareAsync() -> Prepared -> start()/pause()/seekTo() -> Started/Paused/PlaybackCompleted

When you call stop(), however, notice that you cannot call start() again until you prepare the MediaPlayer again.

getCurrentPosition(), getDuration(),getVideoHeight(), getVideoWidth(), setAudioStreamType(int), setLooping(boolean),setVolume(float, float), pause(), start(), stop(), seekTo(int), prepare() or prepareAsync(), If any of these methods is called right after...

Prepared state

Preparing state is a transient state.
A MediaPlayer object must first enter the Prepared state before playback can be started.
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 (setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener)).
While in the Prepared state, properties such as audio/sound volume, screenOnWhilePlaying, looping can be adjusted by invoking the corresponding set methods.
The call to prepare() can take a long time to execute, because it might involve fetching and decoding media data. So, you should never call it from your application's UI thread.

To avoid hanging your UI thread, spawn another thread to prepare the MediaPlayer and notify the main thread when done.
Convenient way to accomplish this task by using the prepareAsync() method.

This method starts preparing the media in the background and returns immediately.
When the media is done preparing, the onPrepared() method of the MediaPlayer.OnPreparedListener is called.

Start state

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.
While in the Started state, the internal player engine calls a user supplied OnBufferingUpdateListener.onBufferingUpdate()

This callback allows applications to keep track of the buffering status while streaming audio/video.

Note that the transition from the Started state to the Paused state and vice versa happens asynchronously in the player engine.

Stop state

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.

Play position

When the actual seek operation completes, the internal player engine calls a user supplied OnSeekComplete.onSeekComplete().
The actual current playback position can be retrieved with a call to getCurrentPosition()

When the playback reaches the end of stream, the playback completes.

True: the MediaPlayer object shall remain in the Started state.
False, the player engine calls a user supplied callback method, OnCompletion.onCompletion(), (setOnCompletionListener(OnCompletionListener)) The invoke of the callback signals that the object is now in the PlaybackCompleted state.

While in the PlaybackCompleted state, calling start() can restart the playback from the beginning of the audio/video source.

Permission

If your player application needs to keep the screen from dimming or the processor from sleeping, or uses the MediaPlayer.setScreenOnWhilePlaying() or MediaPlayer.setWakeMode() methods

States

Create successful -> Idle -> setDataResource() -> Initialized -> prepare() or prepareAsync() -> Prepared -> start()/pause()/seekTo() -> Started/Paused/PlaybackCompleted
Error -> reset() -> Idle
Calling start()/pause()/stop() has not effect on a MediaPlayer object that is already in the Started/Paused/Stopped state.

HAKUNAMATATA