public abstract class SessionPlayer
extends Object implements Closeable

   ↳ androidx.media2.common.SessionPlayer

Base interface for all media players that want media session.

APIs that return ListenableFuture should be the asynchronous calls and shouldn't block the calling thread. This guarantees the APIs are safe to be called on the main thread.

Topics covered here are:

  1. Best practices
  2. Player states
  3. Invalid method calls

Best practices

Here are best practices when implementing/using SessionPlayer:
  • When updating UI, you should respond to SessionPlayer.PlayerCallback invocations instead of SessionPlayer.PlayerResult objects since the player can be controlled by others.
  • When a SessionPlayer object is no longer being used, call close() as soon as possible to release the resources used by the internal player engine associated with the SessionPlayer. For example, if a player uses hardware decoder, other player instances may fallback to software decoders or fail to play. You cannot use SessionPlayer instance after you call close(). There is no way to reuse the instance.
  • The current playback position can be retrieved with a call to getCurrentPosition(), which is helpful for applications such as a music player that need to keep track of the playback progress.
  • The playback position can be adjusted with a call to seekTo(long). Although the asynchronous seekTo(long) call returns right away, the actual seek operation may take a while to finish, especially for audio/video being streamed.
  • You can call seekTo(long) from the PLAYER_STATE_PAUSED. In these cases, if you are playing a video stream and the requested position is valid, one video frame may be displayed.

Player states

The playback control of audio/video files is managed as a state machine. The SessionPlayer defines four states:
  1. PLAYER_STATE_IDLE: Initial state after the instantiation.

    While in this state, you should call setMediaItem(MediaItem) or setPlaylist(List, MediaMetadata). Check returned ListenableFuture for potential error.

    Calling prepare() transfers this object to PLAYER_STATE_PAUSED.

  2. PLAYER_STATE_PAUSED: State when the audio/video playback is paused.

    Call play() to resume or start playback from the position where it paused.

  3. PLAYER_STATE_PLAYING: State when the player plays the media item.

    In this state, SessionPlayer.PlayerCallback.onBufferingStateChanged(SessionPlayer, MediaItem, int) will be called regularly to tell the buffering status.

    Playback state would remain PLAYER_STATE_PLAYING when the currently playing media item is changed.

    When the playback reaches the end of stream, the behavior depends on repeat mode, set by setRepeatMode(int). If the repeat mode was set to REPEAT_MODE_NONE, the player will transfer to the PLAYER_STATE_PAUSED. Otherwise, the SessionPlayer object remains in the PLAYER_STATE_PLAYING and playback will be ongoing.

  4. PLAYER_STATE_ERROR: State when the playback failed and player cannot be recovered by itself.

    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 may transition to this sta