SessionPlayer

const val BUFFERING_STATE_BUFFERING_AND_PLAYABLE = 1: 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.

const val BUFFERING_STATE_BUFFERING_AND_STARVED = 2: Int

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

const val BUFFERING_STATE_COMPLETE = 3: Int

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

const val BUFFERING_STATE_UNKNOWN = 0: Int

Buffering state is unknown.

const val INVALID_ITEM_INDEX = -1: Int

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

const val PLAYER_STATE_ERROR = 3: Int

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

const val PLAYER_STATE_IDLE = 0: Int

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

const val PLAYER_STATE_PAUSED = 1: Int

State when the player's playback is paused

const val PLAYER_STATE_PLAYING = 2: Int

State when the player's playback is ongoing

const val REPEAT_MODE_ALL = 2: Int

Playing media list will be repeated.

const val REPEAT_MODE_GROUP = 3: 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.

const val REPEAT_MODE_NONE = 0: Int

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

const val REPEAT_MODE_ONE = 1: Int

Playback of the current playing media item will be repeated.

const val SHUFFLE_MODE_ALL = 1: Int

Media list will be played in shuffled order.

const val SHUFFLE_MODE_GROUP = 2: 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.

const val SHUFFLE_MODE_NONE = 0: Int

Media list will be played in order.

const val UNKNOWN_TIME = -9223372036854775808: Long

Value indicating the time is unknown

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

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.

@CallSuper
fun close(): Unit

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

fun deselectTrack(trackInfo: SessionPlayer.TrackInfo): ListenableFuture<SessionPlayer.PlayerResult!>

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.

abstract fun getAudioAttributes(): AudioAttributesCompat?

Gets the AudioAttributesCompat that media player has.

abstract fun getBufferedPosition(): Long

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.

abstract fun getBufferingState(): Int

Returns the current buffering state of the player.

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

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 onCurrentMediaItemChanged or onPlaylistChanged is called.

abstract fun getCurrentMediaItemIndex(): @IntRange(from = -1) Int

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

abstract fun getCurrentPosition(): Long

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.

abstract fun getDuration(): Long

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.

abstract fun getNextMediaItemIndex(): @IntRange(from = -1) Int

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

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.

abstract fun getPlayerState(): Int

Gets the current player state.

abstract fun getPlaylist(): (Mutable)List<MediaItem!>?

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

abstract fun getPlaylistMetadata(): MediaMetadata?

Gets the playlist metadata.

abstract fun getPreviousMediaItemIndex(): @IntRange(from = -1) Int

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

abstract fun getRepeatMode(): Int

Gets the repeat mode.

fun getSelectedTrack(trackType: Int): SessionPlayer.TrackInfo?

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

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

abstract fun getShuffleMode(): Int

Gets the shuffle mode.

fun getTracks(): (Mutable)List<SessionPlayer.TrackInfo!>

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.

fun getVideoSize(): VideoSize

Gets the size of the video.

fun movePlaylistItem(
    fromIndex: @IntRange(from = 0) Int,
    toIndex: @IntRange(from = 0) Int
): ListenableFuture<SessionPlayer.PlayerResult!>

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.

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

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

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, 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.

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

Register PlayerCallback to listen changes.

abstract fun removePlaylistItem(index: @IntRange(from = 0) Int): ListenableFuture<SessionPlayer.PlayerResult!>

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.

abstract fun replacePlaylistItem(index: Int, 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 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.

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

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.

fun selectTrack(trackInfo: SessionPlayer.TrackInfo): ListenableFuture<SessionPlayer.PlayerResult!>

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.

abstract fun setAudioAttributes(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 RESULT_ERROR_INVALID_STATE.

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

abstract fun setMediaItem(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 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.

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

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.

abstract fun setPlaylist(list: (Mutable)List<MediaItem!>, 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 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.

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

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.

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

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.

fun setSurface(surface: Surface?): ListenableFuture<SessionPlayer.PlayerResult!>

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.

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

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.

abstract fun skipToPlaylistItem(index: @IntRange(from = 0) Int): ListenableFuture<SessionPlayer.PlayerResult!>

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.

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

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.

fun unregisterPlayerCallback(callback: SessionPlayer.PlayerCallback): Unit

Unregister the previously registered PlayerCallback.

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

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.

protected fun getCallbacks(): (Mutable)List<Pair<SessionPlayer.PlayerCallback!, Executor!>!>

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