SessionPlayer

abstract class SessionPlayer : AutoCloseable
kotlin.Any
   ↳ 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 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(long). 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(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, 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 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 PlayerResult#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 classes
abstract

A callback class to receive notifications for events on the session player.
open

Result class of the asynchronous APIs.

Constants
static Int

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

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

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

Buffering state is unknown.
static Int

Media item index is invalid.
static Int

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

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

State when the player's playback is paused
static Int

State when the player's playback is ongoing
static Int

Playing media list will be repeated.
static Int

Playback of the playing media group will be repeated.
static Int

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

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

Media list will be played in shuffled order.
static Int

Media group will be played in shuffled order.
static Int

Media list will be played in order.
static Long

Value indicating the time is unknown

Public constructors

Base interface for all media players that want media session.

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

Adds the media item to the playlist at position index.
abstract 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 MediaItem?

Gets the current media item, which is currently playing or would be played with later play.
abstract Int

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

Gets the current playback head position.
abstract Long

Gets the duration of the current media item, or UNKNOWN_TIME if unknown.
abstract 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 MutableList<MediaItem!>?

Gets the playlist.
abstract MediaMetadata?

Gets the playlist metadata.
abstract Int

Gets the previous item index in the playlist.
abstract Int

Gets the repeat mode.
abstract Int

Gets the shuffle mode.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Pauses playback.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Starts or resumes playback.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Prepares the media items for playback.
Unit
registerPlayerCallback(@NonNull executor: Executor, @NonNull callback: SessionPlayer.PlayerCallback)

Register PlayerCallback to listen changes.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Removes the media item from the playlist

abstract ListenableFuture<SessionPlayer.PlayerResult!>
replacePlaylistItem(index: Int, @NonNull item: MediaItem)

Replaces the media item at index in the playlist.
abstract ListenableFuture<SessionPlayer.PlayerResult!>
seekTo(position: Long)

Seeks to the specified position.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Sets the AudioAttributesCompat to be used during the playback of the media.
abstract ListenableFuture<SessionPlayer.PlayerResult!>
setMediaItem(@NonNull item: MediaItem)

Sets a MediaItem for playback.
abstract ListenableFuture<SessionPlayer.PlayerResult!>
setPlaybackSpeed(playbackSpeed: Float)

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

Sets a list of MediaItem with metadata.
abstract ListenableFuture<SessionPlayer.PlayerResult!>
setRepeatMode(repeatMode: Int)

Sets the repeat mode.
abstract ListenableFuture<SessionPlayer.PlayerResult!>
setShuffleMode(shuffleMode: Int)

Sets the shuffle mode.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the next item in the playlist.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the the media item.
abstract ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the previous item in the playlist.
Unit

Unregister the previously registered PlayerCallback.
abstract ListenableFuture<SessionPlayer.PlayerResult!>
updatePlaylistMetadata(@Nullable metadata: MediaMetadata?)

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

Protected methods
MutableList<Pair<SessionPlayer.PlayerCallback!, Executor!>!>

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

Constants

BUFFERING_STATE_BUFFERING_AND_PLAYABLE

static val BUFFERING_STATE_BUFFERING_AND_PLAYABLE: Int

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.

Value: 1

BUFFERING_STATE_BUFFERING_AND_STARVED

static val BUFFERING_STATE_BUFFERING_AND_STARVED: Int

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

Value: 2

BUFFERING_STATE_COMPLETE

static val BUFFERING_STATE_COMPLETE: Int

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

Value: 3

BUFFERING_STATE_UNKNOWN

static val BUFFERING_STATE_UNKNOWN: Int

Buffering state is unknown.

Value: 0

INVALID_ITEM_INDEX

static val INVALID_ITEM_INDEX: Int

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

Value: -1

PLAYER_STATE_ERROR

static val PLAYER_STATE_ERROR: Int

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

Value: 3

PLAYER_STATE_IDLE

static val PLAYER_STATE_IDLE: Int

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

Value: 0

PLAYER_STATE_PAUSED

static val PLAYER_STATE_PAUSED: Int

State when the player's playback is paused

Value: 1

PLAYER_STATE_PLAYING

static val PLAYER_STATE_PLAYING: Int

State when the player's playback is ongoing

Value: 2

REPEAT_MODE_ALL

static val REPEAT_MODE_ALL: Int

Playing media list will be repeated.

Value: 2

REPEAT_MODE_GROUP

static val REPEAT_MODE_GROUP: Int

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.

Value: 3

REPEAT_MODE_NONE

static val REPEAT_MODE_NONE: Int

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

Value: 0

REPEAT_MODE_ONE

static val REPEAT_MODE_ONE: Int

Playback of the current playing media item will be repeated.

Value: 1

SHUFFLE_MODE_ALL

static val SHUFFLE_MODE_ALL: Int

Media list will be played in shuffled order.

Value: 1

SHUFFLE_MODE_GROUP

static val SHUFFLE_MODE_GROUP: Int

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.

Value: 2

SHUFFLE_MODE_NONE

static val SHUFFLE_MODE_NONE: Int

Media list will be played in order.

Value: 0

UNKNOWN_TIME

static val UNKNOWN_TIME: Long

Value indicating the time is unknown

Value: Long.MIN_VALUE

Public constructors

<init>

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 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(long). 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(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, 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 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 PlayerResult#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}

Public methods

addPlaylistItem

@NonNull abstract fun addPlaylistItem(
    index: Int, 
    @NonNull item: MediaItem
): ListenableFuture<SessionPlayer.PlayerResult!>

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

The implementation may not change the currently playing media item. If index is less than or equal to the current index of the playlist, the current index of the playlist will be increased correspondingly.

The implementation must notify registered callbacks with PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) 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
index Int: the index of the item you want to add in the playlist
item MediaItem: the media item you want to add

getAudioAttributes

@Nullable abstract fun getAudioAttributes(): AudioAttributesCompat?

Gets the AudioAttributesCompat that media player has.

getBufferedPosition

abstract fun getBufferedPosition(): Long

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

Return
Long the buffered position in ms, or UNKNOWN_TIME.

getBufferingState

abstract fun getBufferingState(): Int

Returns the current buffering state of the player.

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

Return
Int the buffering state.

getCurrentMediaItem

@Nullable abstract fun getCurrentMediaItem(): MediaItem?

Gets the current media item, which is currently playing or would be played with later play. This value may be updated when PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) or PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) is called.

Return
MediaItem? the current media item. Can be null only when media item or playlist hasn't been set.

getCurrentMediaItemIndex

abstract fun getCurrentMediaItemIndex(): Int

Gets the index of current media item in playlist. This value may be updated when PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) or PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) is called.

Return
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

abstract fun getCurrentPosition(): Long

Gets the current playback head position.

Return
Long the current playback position in ms, or UNKNOWN_TIME if unknown.

getDuration

abstract fun getDuration(): Long

Gets the duration of the current media item, or UNKNOWN_TIME if unknown.

Return
Long the duration in ms, or UNKNOWN_TIME.

getNextMediaItemIndex

abstract fun getNextMediaItemIndex(): Int

Gets the next item index in the playlist. The returned value can be outdated after PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) or PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) is called.

Return
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

abstract fun getPlaybackSpeed(): Float

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(float).

Return
Float the actual playback speed

getPlayerState

abstract fun getPlayerState(): Int

Gets the current player state.

Return
Int the current player state

getPlaylist

@Nullable abstract fun getPlaylist(): MutableList<MediaItem!>?

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

Return
MutableList<MediaItem!>? playlist, or null

getPlaylistMetadata

@Nullable abstract fun getPlaylistMetadata(): MediaMetadata?

Gets the playlist metadata.

Return
MediaMetadata? metadata metadata of the playlist, or null if none is set

getPreviousMediaItemIndex

abstract fun getPreviousMediaItemIndex(): Int

Gets the previous item index in the playlist. The returned value can be outdated after PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) or PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) is called.

Return
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

abstract fun getRepeatMode(): Int

Gets the repeat mode.

Return
Int repeat mode

getShuffleMode

abstract fun getShuffleMode(): Int

Gets the shuffle mode.

Return
Int The shuffle mode

pause

@NonNull abstract fun pause(): ListenableFuture<SessionPlayer.PlayerResult!>

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 PlayerResult#RESULT_ERROR_INVALID_STATE.

play

@NonNull abstract fun play(): ListenableFuture<SessionPlayer.PlayerResult!>

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 PlayerResult#RESULT_ERROR_INVALID_STATE.

prepare

@NonNull abstract fun prepare(): ListenableFuture<SessionPlayer.PlayerResult!>

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, sets 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 is ignored and PlayerResult should be returned with PlayerResult#RESULT_ERROR_INVALID_STATE.

registerPlayerCallback

fun registerPlayerCallback(
    @NonNull executor: Executor, 
    @NonNull callback: SessionPlayer.PlayerCallback
): Unit

Register PlayerCallback to listen changes.

Parameters
executor Executor: a callback Executor
callback SessionPlayer.PlayerCallback: a PlayerCallback
Exceptions
IllegalArgumentException if executor or callback is null.

removePlaylistItem

@NonNull abstract fun removePlaylistItem(index: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Removes the media item from the playlist

The implementation may not change the currently playing media item even when it's removed.

The implementation must notify registered callbacks with PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) when it's completed.

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

Parameters
index Int: the index of the item you want to remove in the playlist

replacePlaylistItem

@NonNull abstract fun replacePlaylistItem(
    index: Int, 
    @NonNull item: MediaItem
): ListenableFuture<SessionPlayer.PlayerResult!>

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 PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata) 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
index Int: the index of the item to replace in the playlist
item MediaItem: the new item

seekTo

@NonNull abstract fun seekTo(position: Long): ListenableFuture<SessionPlayer.PlayerResult!>

Seeks to the specified position. Moves the playback head to the specified 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 PlayerResult#RESULT_ERROR_INVALID_STATE.

Parameters
position Long: the new playback position in ms. The value should be in the range of start and end positions defined in MediaItem.

setAudioAttributes

@NonNull abstract fun setAudioAttributes(@NonNull attributes: AudioAttributesCompat): ListenableFuture<SessionPlayer.PlayerResult!>

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 PlayerResult#RESULT_ERROR_INVALID_STATE.

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

Parameters
attributes AudioAttributesCompat: non-null AudioAttributes.

setMediaItem

@NonNull abstract fun setMediaItem(@NonNull item: MediaItem): ListenableFuture<SessionPlayer.PlayerResult!>

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 MediaMetadata#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 PlayerCallback#onPlaylistChanged and PlayerCallback#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
item MediaItem: the descriptor of media item you want to play
Return
ListenableFuture<SessionPlayer.PlayerResult!> a ListenableFuture which represents the pending completion of the command.
Exceptions
IllegalArgumentException if the given item is null.

setPlaybackSpeed

@NonNull abstract fun setPlaybackSpeed(playbackSpeed: Float): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the playback speed. 1.0f is the default, 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
playbackSpeed Float: The requested playback speed.
Return
ListenableFuture<SessionPlayer.PlayerResult!> A ListenableFuture representing the pending completion of the command.

setPlaylist

@NonNull abstract fun setPlaylist(
    @NonNull list: MutableList<MediaItem!>, 
    @Nullable metadata: MediaMetadata?
): ListenableFuture<SessionPlayer.PlayerResult!>

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 MediaMetadata#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 PlayerCallback#onPlaylistChanged and PlayerCallback#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
list MutableList<MediaItem!>: A list of MediaItem objects to set as a play list.
Return
ListenableFuture<SessionPlayer.PlayerResult!> a ListenableFuture which represents the pending completion of the command.
Exceptions
IllegalArgumentException if the given list is null or empty, or has duplicated media items.

setRepeatMode

@NonNull abstract fun setRepeatMode(repeatMode: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the repeat mode.

The implementation must notify registered callbacks with PlayerCallback#onRepeatModeChanged(SessionPlayer, int) when it's completed.

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

Parameters
repeatMode Int: repeat mode

setShuffleMode

@NonNull abstract fun setShuffleMode(shuffleMode: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the shuffle mode.

The implementation must notify registered callbacks with PlayerCallback#onShuffleModeChanged(SessionPlayer, int) when it's completed.

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

Parameters
shuffleMode Int: The shuffle mode

skipToNextPlaylistItem

@NonNull abstract fun skipToNextPlaylistItem(): ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the next item in the playlist.

The implementation must notify registered callbacks with PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) when it's completed.

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

skipToPlaylistItem

@NonNull abstract fun skipToPlaylistItem(index: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the the media item.

The implementation must notify registered callbacks with PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) when it's completed.

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

Parameters
index Int: The index of the item you want to play in the playlist

skipToPreviousPlaylistItem

@NonNull abstract fun skipToPreviousPlaylistItem(): ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the previous item in the playlist.

The implementation must notify registered callbacks with PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem) when it's completed.

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

unregisterPlayerCallback

fun unregisterPlayerCallback(@NonNull callback: SessionPlayer.PlayerCallback): Unit

Unregister the previously registered PlayerCallback.

Parameters
callback SessionPlayer.PlayerCallback: the callback to be removed
Exceptions
IllegalArgumentException if the callback is null.

updatePlaylistMetadata

@NonNull abstract fun updatePlaylistMetadata(@Nullable metadata: MediaMetadata?): ListenableFuture<SessionPlayer.PlayerResult!>

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

The implementation must notify registered callbacks with PlayerCallback#onPlaylistMetadataChanged(SessionPlayer, MediaMetadata) when it's completed.

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

Parameters
metadata MediaMetadata?: metadata of the playlist

Protected methods

getCallbacks

@NonNull protected fun getCallbacks(): MutableList<Pair<SessionPlayer.PlayerCallback!, Executor!>!>

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

Return
MutableList<Pair<SessionPlayer.PlayerCallback!, Executor!>!> map of callbacks and its executors