From d92e59985ca015c4a4662372f854f6a8bd75522d Mon Sep 17 00:00:00 2001 From: Wei Jia Date: Thu, 4 Oct 2018 16:52:09 -0700 Subject: [PATCH] MediaPlayer2: update javadoc Test: compiles Bug: 112549021 Change-Id: Ie889963a831be9bf39ddae157a21ea06d486d8a3 --- media/java/android/media/MediaPlayer2.java | 547 ++++++--------------- 1 file changed, 161 insertions(+), 386 deletions(-) diff --git a/media/java/android/media/MediaPlayer2.java b/media/java/android/media/MediaPlayer2.java index 0f83fd5803de6..8665f283ffb2a 100644 --- a/media/java/android/media/MediaPlayer2.java +++ b/media/java/android/media/MediaPlayer2.java @@ -47,414 +47,190 @@ import java.util.concurrent.Executor; /** * @hide - * MediaPlayer2 class can be used to control playback - * of audio/video files and streams. An example on how to use the methods in - * this class can be found in {@link android.widget.VideoView}. + * + * MediaPlayer2 class can be used to control playback of audio/video files and streams. * *

Topics covered here are: *

    - *
  1. State Diagram - *
  2. Valid and Invalid States + *
  3. Player states + *
  4. Invalid method calls *
  5. Permissions - *
  6. Register informational and error callbacks + *
  7. Callbacks *
* - *
- *

Developer Guides

- *

For more information about how to use MediaPlayer2, read the - * Media Playback developer guide.

- *
* - * - *

State Diagram

+ *

Player states

* - *

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 - * MediaPlayer2 object driven by the supported playback control operations. - * The ovals represent the states a MediaPlayer2 object may reside - * in. The arcs represent the playback control operations that drive the object - * state transition. There are two types of arcs. The arcs with a single arrow - * head represent synchronous method calls, while those with - * a double arrow head represent asynchronous method calls.

+ *

The playback control of audio/video files is managed as a state machine.

+ *

MediaPlayer2 State diagram

+ *

The MediaPlayer2 object has five states:

+ *
    + *

  1. {@link #PLAYER_STATE_IDLE}: MediaPlayer2 is in the Idle + * state after you create it using + * {@link #create()}, or after calling {@link #reset()}.

    * - *

    MediaPlayer State diagram

    + *

    While in this state, you should call + * {@link #setDataSource(DataSourceDesc2) setDataSource()}. It is a good + * programming practice to register an {@link EventCallback#onCallCompleted onCallCompleted} + * callback and watch for {@link #CALL_STATUS_BAD_VALUE} and + * {@link #CALL_STATUS_ERROR_IO}, which might be caused by setDataSource. + *

    + * + *

    Calling {@link #prepare()} transfers a MediaPlayer2 object to + * the Prepared state. Note + * that {@link #prepare()} is asynchronous. When the preparation completes, + * if you register an {@link EventCallback#onInfo onInfo} callback, + * the player executes the callback + * with {@link #MEDIA_INFO_PREPARED} and transitions to the + * Prepared state.

    + *
    2. + * + *
  2. {@link #PLAYER_STATE_PREPARED}: A MediaPlayer object must be in the + * Prepared state before playback can be started for the first time. + * While in this state, you can set player properties + * such as audio/sound volume and looping by invoking the corresponding set methods. + * Calling {@link #play()} transfers a MediaPlayer2 object to + * the Playing state. + *
    3. + * + *
  3. {@link #PLAYER_STATE_PLAYING}: + *

    The player plays the data source while in this state. + * If you register an {@link EventCallback#onInfo onInfo} callback, + * the player regularly executes the callback with + * {@link #MEDIA_INFO_BUFFERING_UPDATE}. + * This allows applications to keep track of the buffering status + * while streaming audio/video.

    + * + *

    When the playback reaches the end of stream, the behavior depends on whether or + * not you've enabled looping by calling {@link #loopCurrent(boolean) loopCurrent}:

    + *
      + *
    • If the looping mode was set to false, the player will transfer + * to the Paused state. If you registered an {@link EventCallback#onInfo + * onInfo} callback + * the player calls the callback with {@link #MEDIA_INFO_DATA_SOURCE_END} and enters + * the Paused state. + *
      • + *
    • If the looping mode was set to true, + * the MediaPlayer2 object remains in the Playing state and replays its + * data source from the beginning.
      • + *
    + *
    4. + * + *
  4. {@link #PLAYER_STATE_PAUSED}: Audio/video playback pauses while in this state. + * Call {@link #play()} to resume playback from the position where it paused.
    5. + * + *
  5. {@link #PLAYER_STATE_ERROR}:

    In general, playback might fail due to various + * reasons such as unsupported audio/video format, poorly interleaved + * audio/video, resolution too high, streaming timeout, and others. + * In addition, due to programming errors, a playback + * control operation might be performed from an invalid state. + * In these cases the player transitions to the Error state.

    + * + *

    If you register an {@link EventCallback#onError onError}} + * callback, + * the callback will be performed when entering the state. When programming errors happen, + * such as calling {@link #prepare() prepare} and + * {@link #setDataSource(DataSourceDesc) setDataSource} methods + * from an invalid state, the callback is called with + * {@link #CALL_STATUS_INVALID_OPERATION}. The MediaPlayer2 object enters the + * Error state whether or not a callback exists.

    + * + *

    To recover from an error and reuse a MediaPlayer2 object that is in the + * Error state, + * call {@link #reset() reset}. The object will return to the Idle + * state and all state information will be lost.

    + *
    6. + *
+ * + *

You should follow these best practices when coding an app that uses MediaPlayer2:

* - *

From this state diagram, one can see that a MediaPlayer2 object has the - * following states:

*