SessionPlayer

Added in 1.0.0
Deprecated in 1.3.0

public abstract class SessionPlayer implements Closeable

Known direct subclasses
MediaPlayer

This class is deprecated.

androidx.media2 is deprecated.
RemoteSessionPlayer

This class is deprecated.

androidx.media2 is deprecated.

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 PlayerCallback invocations instead of 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. Although the asynchronous seekTo call returns right away, the actual seek operation may take a while to finish, especially for audio/video being streamed.
  • You can call seekTo 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 or setPlaylist. 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, onBufferingStateChanged 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. 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 state.

Subclasses may have extra methods to reset the player state to PLAYER_STATE_IDLE from other states. Take a look at documentations of specific subclass that you're interested in.

Invalid method calls

The only method you safely call from the PLAYER_STATE_ERROR is close. Any other methods might return meaningless data.

Subclasses of the SessionPlayer may have extra methods that are safe to be called in the error state and/or provide a method to recover from the error state. Take a look at documentations of specific subclass that you're interested in.

Most methods can be called from any non-Error state. In case they're called in invalid state, the implementation should ignore and would return PlayerResult with RESULT_ERROR_INVALID_STATE. The following table lists the methods that aren't guaranteed to successfully running if they're called from the associated invalid states.

Method Name Invalid States
setAudioAttributes {Paused, Playing}
prepare {Paused, Playing}
play {Idle}
pause {Idle}
seekTo {Idle}

Summary

Nested types
public abstract class SessionPlayer.PlayerCallback

This class is deprecated.

androidx.media2 is deprecated.

This class is deprecated.

androidx.media2 is deprecated.

This class is deprecated.

androidx.media2 is deprecated.

Constants
static final int

Buffering state indicating the player is buffering but enough has been buffered for this player to be able to play the content.
static final int

Buffering state indicating the player is buffering, but the player is currently starved for data, and cannot play.
static final int

Buffering state indicating the player is done buffering, and the remainder of the content is available for playback.
static final int

Buffering state is unknown.
static final int

Media item index is invalid.
static final int

State when the player is in error state and cannot be recovered self.
static final int

State when the player is idle, and needs configuration to start playback.
static final int

State when the player's playback is paused
static final int

State when the player's playback is ongoing
static final int

Playing media list will be repeated.
static final int

Playback of the playing media group will be repeated.
static final int

Playback will be stopped at the end of the playing media list.
static final int

Playback of the current playing media item will be repeated.
static final int

Media list will be played in shuffled order.
static final int

Media group will be played in shuffled order.
static final int

Media list will be played in order.
static final long
UNKNOWN_TIME = -9223372036854775808

Value indicating the time is unknown

Public constructors

Public methods
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
addPlaylistItem(int index, @NonNull MediaItem item)

Adds the media item to the playlist at the index.
void

Removes all existing references to callbacks and executors.
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

Deselects the TrackInfo for the current media item.
abstract @Nullable AudioAttributesCompat

Gets the AudioAttributesCompat that media player has.
abstract long

Gets the position for how much has been buffered, or UNKNOWN_TIME if unknown.
abstract int

Returns the current buffering state of the player.
abstract @Nullable MediaItem

Gets the current media item, which is currently playing or would be played with later play.
abstract @IntRange(from = -1) int

Gets the index of current media item in playlist.
abstract long

Gets the current playback position.
abstract long

Gets the duration of the current media item, or UNKNOWN_TIME if unknown.
abstract @IntRange(from = -1) int

Gets the next item index in the playlist.
abstract float

Gets the actual playback speed to be used by the player when playing.
abstract int

Gets the current player state.
abstract @Nullable List<MediaItem>

Gets the playlist.
abstract @Nullable MediaMetadata

Gets the playlist metadata.
abstract @IntRange(from = -1) int

Gets the previous item index in the playlist.
abstract int

Gets the repeat mode.
@Nullable SessionPlayer.TrackInfo
getSelectedTrack(int trackType)

Gets currently selected track's TrackInfo for the given track type.
abstract int

Gets the shuffle mode.
@NonNull List<SessionPlayer.TrackInfo>

Gets the full list of selected and unselected tracks that the media contains.
@NonNull VideoSize

Gets the size of the video.
@NonNull ListenableFuture<SessionPlayer.PlayerResult>
movePlaylistItem(
    @IntRange(from = 0) int fromIndex,
    @IntRange(from = 0) int toIndex
)

Moves the media item at fromIdx to toIdx in the playlist.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Pauses playback.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Starts or resumes playback.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Prepares the media items for playback.
final void

Register PlayerCallback to listen changes.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
removePlaylistItem(@IntRange(from = 0) int index)

Removes the media item from the playlist

abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Replaces the media item at index in the playlist.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
seekTo(long position)

Seeks to the specified position.
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

Selects the TrackInfo for the current media item.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Sets the AudioAttributesCompat to be used during the playback of the media.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Sets a MediaItem for playback.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
setPlaybackSpeed(float playbackSpeed)

Sets the playback speed.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
setPlaylist(
    @NonNull List<MediaItem> list,
    @Nullable MediaMetadata metadata
)

Sets a list of MediaItem with metadata.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
setRepeatMode(int repeatMode)

Sets the repeat mode.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
setShuffleMode(int shuffleMode)

Sets the shuffle mode.
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

Sets the Surface to be used as the sink for the video portion of the media.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Skips to the next item in the playlist.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>
skipToPlaylistItem(@IntRange(from = 0) int index)

Skips to the item in the playlist at the index.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Skips to the previous item in the playlist.
final void

Unregister the previously registered PlayerCallback.
abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult>

Updates the playlist metadata while keeping the playlist as-is.

Protected methods
final @NonNull List<Pair<SessionPlayer.PlayerCallback, Executor>>

Gets the callbacks with executors for subclasses to notify player events.

Constants

BUFFERING_STATE_BUFFERING_AND_PLAYABLE

Added in 1.0.0
Deprecated in 1.3.0
public static final int BUFFERING_STATE_BUFFERING_AND_PLAYABLE = 1

Buffering state indicating the player is buffering but enough has been buffered for this player to be able to play the content. See getBufferedPosition for how far is buffered already.

BUFFERING_STATE_BUFFERING_AND_STARVED

Added in 1.0.0
Deprecated in 1.3.0
public static final int BUFFERING_STATE_BUFFERING_AND_STARVED = 2

Buffering state indicating the player is buffering, but the player is currently starved for data, and cannot play.

BUFFERING_STATE_COMPLETE

Added in 1.0.0
Deprecated in 1.3.0
public static final int BUFFERING_STATE_COMPLETE = 3

Buffering state indicating the player is done buffering, and the remainder of the content is available for playback.

BUFFERING_STATE_UNKNOWN

Added in 1.0.0
Deprecated in 1.3.0
public static final int BUFFERING_STATE_UNKNOWN = 0

Buffering state is unknown.

INVALID_ITEM_INDEX

Added in 1.0.0
Deprecated in 1.3.0
public static final int INVALID_ITEM_INDEX = -1

Media item index is invalid. This value will be returned when the corresponding media item does not exist.

PLAYER_STATE_ERROR

Added in 1.0.0
Deprecated in 1.3.0
public static final int PLAYER_STATE_ERROR = 3

State when the player is in error state and cannot be recovered self.

PLAYER_STATE_IDLE

Added in 1.0.0
Deprecated in 1.3.0
public static final int PLAYER_STATE_IDLE = 0

State when the player is idle, and needs configuration to start playback.

PLAYER_STATE_PAUSED

Added in 1.0.0
Deprecated in 1.3.0
public static final int PLAYER_STATE_PAUSED = 1

State when the player's playback is paused

PLAYER_STATE_PLAYING

Added in 1.0.0
Deprecated in 1.3.0
public static final int PLAYER_STATE_PLAYING = 2

State when the player's playback is ongoing

REPEAT_MODE_ALL

Added in 1.0.0
Deprecated in 1.3.0
public static final int REPEAT_MODE_ALL = 2

Playing media list will be repeated.

REPEAT_MODE_GROUP

Added in 1.0.0
Deprecated in 1.3.0
public static final int REPEAT_MODE_GROUP = 3

Playback of the playing media group will be repeated. A group is a logical block of media items which is specified in the section 5.7 of the Bluetooth AVRCP 1.6. An example of a group is the playlist.

REPEAT_MODE_NONE

Added in 1.0.0
Deprecated in 1.3.0
public static final int REPEAT_MODE_NONE = 0

Playback will be stopped at the end of the playing media list.

REPEAT_MODE_ONE

Added in 1.0.0
Deprecated in 1.3.0
public static final int REPEAT_MODE_ONE = 1

Playback of the current playing media item will be repeated.

SHUFFLE_MODE_ALL

Added in 1.0.0
Deprecated in 1.3.0
public static final int SHUFFLE_MODE_ALL = 1

Media list will be played in shuffled order.

SHUFFLE_MODE_GROUP

Added in 1.0.0
Deprecated in 1.3.0
public static final int SHUFFLE_MODE_GROUP = 2

Media group will be played in shuffled order. A group is a logical block of media items which is specified in the section 5.7 of the Bluetooth AVRCP 1.6. An example of a group is the playlist.

SHUFFLE_MODE_NONE

Added in 1.0.0
Deprecated in 1.3.0
public static final int SHUFFLE_MODE_NONE = 0

Media list will be played in order.

UNKNOWN_TIME

Added in 1.0.0
Deprecated in 1.3.0
public static final long UNKNOWN_TIME = -9223372036854775808

Value indicating the time is unknown

Public constructors

SessionPlayer

Added in 1.0.0
Deprecated in 1.3.0
public SessionPlayer()

Public methods

addPlaylistItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> addPlaylistItem(int index, @NonNull MediaItem item)

Adds the media item to the playlist at the index. Index equals to or greater than the current playlist size (e.g. MAX_VALUE) will add the item at the end of the playlist.

If index is less than or equal to the current index of the playlist, the current index of the playlist should be increased correspondingly.

The implementation must notify registered callbacks with onPlaylistChanged when it's completed.

The implementation must close the ParcelFileDescriptor in the FileMediaItem if the given media item is a FileMediaItem.

On success, a PlayerResult should be returned with item added.

Parameters
int index

the index of the item you want to add in the playlist
@NonNull MediaItem item

the media item you want to add
See also
onPlaylistChanged

close

Added in 1.1.0
Deprecated in 1.3.0
@CallSuper
public void close()

Removes all existing references to callbacks and executors. Note: Sub classes of SessionPlayer that override this API should call this super method.

deselectTrack

Added in 1.1.0
Deprecated in 1.3.0
public @NonNull ListenableFuture<SessionPlayer.PlayerResult> deselectTrack(@NonNull SessionPlayer.TrackInfo trackInfo)

Deselects the TrackInfo for the current media item.

Generally, a track should already be selected in order to be deselected, and audio and video tracks should not be deselected.

The types of tracks supported may vary based on player implementation.

Note: getSelectedTrack returns the currently selected track per track type that can be deselected, but the list may be invalidated when onTracksChanged is called.

Parameters
@NonNull SessionPlayer.TrackInfo trackInfo

track to be deselected
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture which represents the pending completion of the command
See also
MEDIA_TRACK_TYPE_VIDEO
MEDIA_TRACK_TYPE_AUDIO
MEDIA_TRACK_TYPE_SUBTITLE
MEDIA_TRACK_TYPE_METADATA
onTrackDeselected

getAudioAttributes

Added in 1.0.0
Deprecated in 1.3.0
public abstract @Nullable AudioAttributesCompat getAudioAttributes()

Gets the AudioAttributesCompat that media player has.

getBufferedPosition

Added in 1.0.0
Deprecated in 1.3.0
public abstract long getBufferedPosition()

Gets the position for how much has been buffered, or UNKNOWN_TIME if unknown.

The position is the relative position based on the getStartPosition. So the position 0 means the start position of the MediaItem.

Returns
long

the buffered position in ms, or UNKNOWN_TIME if unknown

getBufferingState

Added in 1.0.0
Deprecated in 1.3.0
public abstract int getBufferingState()

Returns the current buffering state of the player.

During the buffering, see getBufferedPosition for the quantifying the amount already buffered.

Returns
int

the buffering state, or BUFFERING_STATE_UNKNOWN if unknown
See also
getBufferedPosition

getCurrentMediaItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @Nullable MediaItem getCurrentMediaItem()

Gets the current media item, which is currently playing or would be played with later play. This value may be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

Returns
@Nullable MediaItem

the current media item. Can be null only when the player is in PLAYER_STATE_IDLE and a media item or playlist hasn't been set.
See also
setMediaItem
setPlaylist

getCurrentMediaItemIndex

Added in 1.0.0
Deprecated in 1.3.0
public abstract @IntRange(from = -1) int getCurrentMediaItemIndex()

Gets the index of current media item in playlist. This value should be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

Returns
@IntRange(from = -1) int

the index of current media item. Can be INVALID_ITEM_INDEX when current media item is null or not in the playlist, and when the playlist hasn't been set.

getCurrentPosition

Added in 1.0.0
Deprecated in 1.3.0
public abstract long getCurrentPosition()

Gets the current playback position.

The position is the relative position based on the getStartPosition. So the position 0 means the start position of the MediaItem.

Returns
long

the current playback position in ms, or UNKNOWN_TIME if unknown

getDuration

Added in 1.0.0
Deprecated in 1.3.0
public abstract long getDuration()

Gets the duration of the current media item, or UNKNOWN_TIME if unknown. If the current MediaItem has either start or end position, then duration would be adjusted accordingly instead of returning the whole size of the MediaItem.

Returns
long

the duration in ms, or UNKNOWN_TIME if unknown

getNextMediaItemIndex

Added in 1.0.0
Deprecated in 1.3.0
public abstract @IntRange(from = -1) int getNextMediaItemIndex()

Gets the next item index in the playlist. This value should be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

Returns
@IntRange(from = -1) int

the index of next media item. Can be INVALID_ITEM_INDEX only when next media item does not exist or playlist hasn't been set.

getPlaybackSpeed

Added in 1.0.0
Deprecated in 1.3.0
public abstract float getPlaybackSpeed()

Gets the actual playback speed to be used by the player when playing. A value of 1.0f is the default playback value, and a negative value indicates reverse playback.

Note that it may differ from the speed set in setPlaybackSpeed.

Returns
float

the actual playback speed

getPlayerState

Added in 1.0.0
Deprecated in 1.3.0
public abstract int getPlayerState()

Gets the current player state.

Returns
int

the current player state
See also
onPlayerStateChanged
PLAYER_STATE_IDLE
PLAYER_STATE_PAUSED
PLAYER_STATE_PLAYING
PLAYER_STATE_ERROR

getPlaylist

Added in 1.0.0
Deprecated in 1.3.0
public abstract @Nullable List<MediaItem> getPlaylist()

Gets the playlist. It can be null if the playlist hasn't been set or it's reset by setMediaItem.

Returns
@Nullable List<MediaItem>

playlist, or null
See also
onPlaylistChanged

getPlaylistMetadata

Added in 1.0.0
Deprecated in 1.3.0
public abstract @Nullable MediaMetadata getPlaylistMetadata()

Gets the playlist metadata.

Returns
@Nullable MediaMetadata

metadata metadata of the playlist, or null if none is set
See also
onPlaylistChanged
onPlaylistMetadataChanged

getPreviousMediaItemIndex

Added in 1.0.0
Deprecated in 1.3.0
public abstract @IntRange(from = -1) int getPreviousMediaItemIndex()

Gets the previous item index in the playlist. This value should be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

Returns
@IntRange(from = -1) int

the index of previous media item. Can be INVALID_ITEM_INDEX only when previous media item does not exist or playlist hasn't been set.

getRepeatMode

Added in 1.0.0
Deprecated in 1.3.0
public abstract int getRepeatMode()

Gets the repeat mode.

Returns
int

repeat mode
See also
REPEAT_MODE_NONE
REPEAT_MODE_ONE
REPEAT_MODE_ALL
REPEAT_MODE_GROUP
onRepeatModeChanged

getSelectedTrack

Added in 1.1.0
Deprecated in 1.3.0
public @Nullable SessionPlayer.TrackInfo getSelectedTrack(int trackType)

Gets currently selected track's TrackInfo for the given track type.

The returned value can be outdated after onTracksChanged, onTrackSelected, or onTrackDeselected is called.

Parameters
int trackType

type of selected track
Returns
@Nullable SessionPlayer.TrackInfo

selected track info
See also
MEDIA_TRACK_TYPE_VIDEO
MEDIA_TRACK_TYPE_AUDIO
MEDIA_TRACK_TYPE_SUBTITLE
MEDIA_TRACK_TYPE_METADATA

getShuffleMode

Added in 1.0.0
Deprecated in 1.3.0
public abstract int getShuffleMode()

Gets the shuffle mode.

Returns
int

the shuffle mode
See also
SHUFFLE_MODE_NONE
SHUFFLE_MODE_ALL
SHUFFLE_MODE_GROUP
onShuffleModeChanged

getTracks

Added in 1.1.0
Deprecated in 1.3.0
public @NonNull List<SessionPlayer.TrackInfo> getTracks()

Gets the full list of selected and unselected tracks that the media contains. The order of the list is irrelevant as different players expose tracks in different ways, but the tracks will generally be ordered based on track type.

The types of tracks supported may vary based on player implementation.

Returns
@NonNull List<SessionPlayer.TrackInfo>

list of tracks. The total number of tracks is the size of the list. If empty, the implementation should return an empty list instead of null.
See also
MEDIA_TRACK_TYPE_VIDEO
MEDIA_TRACK_TYPE_AUDIO
MEDIA_TRACK_TYPE_SUBTITLE
MEDIA_TRACK_TYPE_METADATA

getVideoSize

Added in 1.1.0
Deprecated in 1.3.0
public @NonNull VideoSize getVideoSize()

Gets the size of the video.

Returns
@NonNull VideoSize

the size of the video. The width and height of size could be 0 if there is no video or the size has not been determined yet.
See also
onVideoSizeChanged

movePlaylistItem

Added in 1.1.0
Deprecated in 1.3.0
public @NonNull ListenableFuture<SessionPlayer.PlayerResult> movePlaylistItem(
    @IntRange(from = 0) int fromIndex,
    @IntRange(from = 0) int toIndex
)

Moves the media item at fromIdx to toIdx in the playlist.

The implementation must notify registered callbacks with onPlaylistChanged when it's completed.

On success, a PlayerResult should be returned with item set.

Parameters
@IntRange(from = 0) int fromIndex

the media item's initial index in the playlist
@IntRange(from = 0) int toIndex

the media item's target index in the playlist
See also
onPlaylistChanged

pause

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> pause()

Pauses playback.

On success, this transfers the player state to PLAYER_STATE_PAUSED and a PlayerResult should be returned with the current media item when the command was completed. If it is called in PLAYER_STATE_IDLE or PLAYER_STATE_ERROR, it should be ignored and a PlayerResult should be returned with RESULT_ERROR_INVALID_STATE.

Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command

play

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> play()

Starts or resumes playback.

On success, this transfers the player state to PLAYER_STATE_PLAYING and a PlayerResult should be returned with the current media item when the command was completed. If it is called in PLAYER_STATE_IDLE or PLAYER_STATE_ERROR, it should be ignored and a PlayerResult should be returned with RESULT_ERROR_INVALID_STATE.

Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command

prepare

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> prepare()

Prepares the media items for playback. During this time, the player may allocate resources required to play, such as audio and video decoders. Before calling this API, set media item(s) through either setMediaItem or setPlaylist.

On success, this transfers the player state from PLAYER_STATE_IDLE to PLAYER_STATE_PAUSED and a PlayerResult should be returned with the prepared media item when the command completed. If it's not called in PLAYER_STATE_IDLE, it should be ignored and PlayerResult should be returned with RESULT_ERROR_INVALID_STATE.

Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command

registerPlayerCallback

Added in 1.0.0
Deprecated in 1.3.0
public final void registerPlayerCallback(
    @NonNull Executor executor,
    @NonNull SessionPlayer.PlayerCallback callback
)

Register PlayerCallback to listen changes.

Parameters
@NonNull Executor executor

a callback Executor
@NonNull SessionPlayer.PlayerCallback callback

a PlayerCallback
Throws
java.lang.IllegalArgumentException

if executor or callback is null.

removePlaylistItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> removePlaylistItem(@IntRange(from = 0) int index)

Removes the media item from the playlist

The implementation must notify registered callbacks with onPlaylistChanged when it's completed.

On success, a PlayerResult should be returned with item removed.

If the last item is removed, the player should be moved to PLAYER_STATE_IDLE.

Parameters
@IntRange(from = 0) int index

the index of the item you want to remove in the playlist
See also
onPlaylistChanged

replacePlaylistItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> replacePlaylistItem(int index, @NonNull MediaItem item)

Replaces the media item at index in the playlist. This can be also used to update metadata of an item.

The implementation must notify registered callbacks with onPlaylistChanged when it's completed.

The implementation must close the ParcelFileDescriptor in the FileMediaItem if the given media item is a FileMediaItem.

On success, a PlayerResult should be returned with item set.

Parameters
int index

the index of the item to replace in the playlist
@NonNull MediaItem item

the new item
See also
onPlaylistChanged

seekTo

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> seekTo(long position)

Seeks to the specified position.

The position is the relative position based on the getStartPosition. So calling seekTo with 0 means the seek to the start position.

On success, a PlayerResult should be returned with the current media item when the command completed. If it's called in PLAYER_STATE_IDLE, it is ignored and a PlayerResult should be returned with RESULT_ERROR_INVALID_STATE.

Parameters
long position

the new playback position in ms. The value should be in the range of start and end positions defined in MediaItem.
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command

selectTrack

Added in 1.1.0
Deprecated in 1.3.0
public @NonNull ListenableFuture<SessionPlayer.PlayerResult> selectTrack(@NonNull SessionPlayer.TrackInfo trackInfo)

Selects the TrackInfo for the current media item.

Generally one track will be selected for each track type.

The types of tracks supported may vary based on player implementation.

Note: getTracks returns the list of tracks that can be selected, but the list may be invalidated when onTracksChanged is called.

Parameters
@NonNull SessionPlayer.TrackInfo trackInfo

track to be selected
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command
See also
MEDIA_TRACK_TYPE_VIDEO
MEDIA_TRACK_TYPE_AUDIO
MEDIA_TRACK_TYPE_SUBTITLE
MEDIA_TRACK_TYPE_METADATA
onTrackSelected

setAudioAttributes

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> setAudioAttributes(@NonNull AudioAttributesCompat attributes)

Sets the AudioAttributesCompat to be used during the playback of the media.

You must call this method in PLAYER_STATE_IDLE in order for the audio attributes to become effective thereafter. Otherwise, the call would be ignored and PlayerResult should be returned with RESULT_ERROR_INVALID_STATE.

On success, a PlayerResult should be returned with the current media item when the command completed.

Parameters
@NonNull AudioAttributesCompat attributes

non-null AudioAttributes.

setMediaItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> setMediaItem(@NonNull MediaItem item)

Sets a MediaItem for playback. Use this or setPlaylist to specify which items to play. If you want to change current item in the playlist, use one of skipToPlaylistItem, skipToNextPlaylistItem, or skipToPreviousPlaylistItem instead of this method.

This can be called multiple times in any states other than PLAYER_STATE_ERROR. This would override previous setMediaItem or setPlaylist calls.

It's recommended to fill MediaMetadata in MediaItem especially for the duration information with the key METADATA_KEY_DURATION. Without the duration information in the metadata, session will do extra work to get the duration and send it to the controller.

The implementation must notify registered callbacks with onPlaylistChanged and onCurrentMediaItemChanged when it's completed. The current item would be the item given here.

The implementation must close the ParcelFileDescriptor in the FileMediaItem if the given media item is a FileMediaItem.

On success, a PlayerResult should be returned with item set.

Parameters
@NonNull MediaItem item

the descriptor of media item you want to play
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture which represents the pending completion of the command
Throws
java.lang.IllegalArgumentException

if the given item is null.
See also
setPlaylist
onPlaylistChanged
onCurrentMediaItemChanged

setPlaybackSpeed

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> setPlaybackSpeed(float playbackSpeed)

Sets the playback speed. The default playback speed is 1.0f, and negative values indicate reverse playback and 0.0f is not allowed.

The supported playback speed range depends on the underlying player implementation, so it is recommended to query the actual speed of the player via getPlaybackSpeed after the operation completes. In particular, please note that player implementations may not support reverse playback.

On success, a PlayerResult should be returned with the current media item when the command completed.

Parameters
float playbackSpeed

the requested playback speed
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command
See also
getPlaybackSpeed
onPlaybackSpeedChanged

setPlaylist

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> setPlaylist(
    @NonNull List<MediaItem> list,
    @Nullable MediaMetadata metadata
)

Sets a list of MediaItem with metadata. Use this or setMediaItem to specify which items to play.

This can be called multiple times in any states other than PLAYER_STATE_ERROR. This would override previous setMediaItem or setPlaylist calls.

Ensure uniqueness of each MediaItem in the playlist so the session can uniquely identity individual items. All MediaItems shouldn't be null as well.

It's recommended to fill MediaMetadata in each MediaItem especially for the duration information with the key METADATA_KEY_DURATION. Without the duration information in the metadata, session will do extra work to get the duration and send it to the controller.

The implementation must notify registered callbacks with onPlaylistChanged and onCurrentMediaItemChanged when it's completed. The current media item would be the first item in the playlist.

The implementation must close the ParcelFileDescriptor in the FileMediaItem when a media item in the playlist is a FileMediaItem.

On success, a PlayerResult should be returned with the first media item of the playlist when the command completed.

Parameters
@NonNull List<MediaItem> list

a list of MediaItem objects to set as a play list
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture which represents the pending completion of the command
Throws
java.lang.IllegalArgumentException

if the given list is null or empty, or has duplicated media items.
See also
setMediaItem
onPlaylistChanged
onCurrentMediaItemChanged

setRepeatMode

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> setRepeatMode(int repeatMode)

Sets the repeat mode.

The implementation must notify registered callbacks with onRepeatModeChanged when it's completed.

On success, a PlayerResult should be returned with the current media item when the command completed.

Parameters
int repeatMode

repeat mode
See also
REPEAT_MODE_NONE
REPEAT_MODE_ONE
REPEAT_MODE_ALL
REPEAT_MODE_GROUP
onRepeatModeChanged

setShuffleMode

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> setShuffleMode(int shuffleMode)

Sets the shuffle mode.

The implementation must notify registered callbacks with onShuffleModeChanged when it's completed.

On success, a PlayerResult should be returned with the current media item when the command completed.

Parameters
int shuffleMode

the shuffle mode
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command
See also
SHUFFLE_MODE_NONE
SHUFFLE_MODE_ALL
SHUFFLE_MODE_GROUP
onShuffleModeChanged

setSurface

Added in 1.1.0
Deprecated in 1.3.0
public @NonNull ListenableFuture<SessionPlayer.PlayerResult> setSurface(@Nullable Surface surface)

Sets the Surface to be used as the sink for the video portion of the media.

A null surface will reset any Surface and result in only the audio track being played.

On success, a SessionPlayer.PlayerResult is returned with the current media item when the command completed.

Parameters
@Nullable Surface surface

the Surface to be used for the video portion of the media
Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture which represents the pending completion of the command

skipToNextPlaylistItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> skipToNextPlaylistItem()

Skips to the next item in the playlist.

The implementation must notify registered callbacks with onCurrentMediaItemChanged when it's completed.

On success, a PlayerResult should be returned with the current media item when the command completed.

Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command
See also
onCurrentMediaItemChanged

skipToPlaylistItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> skipToPlaylistItem(@IntRange(from = 0) int index)

Skips to the item in the playlist at the index.

The implementation must notify registered callbacks with onCurrentMediaItemChanged when it's completed.

On success, a PlayerResult should be returned with the current media item when the command completed.

Parameters
@IntRange(from = 0) int index

the index of the item you want to play in the playlist
See also
onCurrentMediaItemChanged

skipToPreviousPlaylistItem

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> skipToPreviousPlaylistItem()

Skips to the previous item in the playlist.

The implementation must notify registered callbacks with onCurrentMediaItemChanged when it's completed.

On success, a PlayerResult should be returned with the current media item when the command completed.

Returns
@NonNull ListenableFuture<SessionPlayer.PlayerResult>

a ListenableFuture representing the pending completion of the command
See also
onCurrentMediaItemChanged

unregisterPlayerCallback

Added in 1.0.0
Deprecated in 1.3.0
public final void unregisterPlayerCallback(@NonNull SessionPlayer.PlayerCallback callback)

Unregister the previously registered PlayerCallback.

Parameters
@NonNull SessionPlayer.PlayerCallback callback

the callback to be removed
Throws
java.lang.IllegalArgumentException

if the callback is null.

updatePlaylistMetadata

Added in 1.0.0
Deprecated in 1.3.0
public abstract @NonNull ListenableFuture<SessionPlayer.PlayerResult> updatePlaylistMetadata(@Nullable MediaMetadata metadata)

Updates the playlist metadata while keeping the playlist as-is.

The implementation must notify registered callbacks with onPlaylistMetadataChanged when it's completed.

On success, a PlayerResult should be returned with the current media item when the command completed.

Parameters
@Nullable MediaMetadata metadata

metadata of the playlist
See also
onPlaylistMetadataChanged

Protected methods

getCallbacks

Added in 1.0.0
Deprecated in 1.3.0
protected final @NonNull List<Pair<SessionPlayer.PlayerCallback, Executor>> getCallbacks()

Gets the callbacks with executors for subclasses to notify player events.

Returns
@NonNull List<Pair<SessionPlayer.PlayerCallback, Executor>>

map of callbacks and its executors