RemoteSessionPlayer

Kotlin |Java

abstract class RemoteSessionPlayer : SessionPlayer

kotlin.Any
↳	androidx.media2.common.SessionPlayer
	↳	androidx.media2.session.RemoteSessionPlayer

Base interface for all remote media players that want media session and playback happens on the remote device through MediaRouter.

If you use this to the MediaSession, session would dispatch incoming volume change event to the player instead of changing device stream volume.

Summary

Nested classes
open	`Callback` A callback class to receive notifications for events on the remote session player.

Constants
static Int	`VOLUME_CONTROL_ABSOLUTE` The volume control uses an absolute value.
static Int	`VOLUME_CONTROL_FIXED` The volume is fixed and can not be modified.
static Int	`VOLUME_CONTROL_RELATIVE` The volume control uses relative adjustment via `adjustVolume(int)`.

Inherited constants

From class SessionPlayer

`Int`	`BUFFERING_STATE_BUFFERING_AND_PLAYABLE` 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.
`Int`	`BUFFERING_STATE_BUFFERING_AND_STARVED` Buffering state indicating the player is buffering, but the player is currently starved for data, and cannot play.
`Int`	`BUFFERING_STATE_COMPLETE` Buffering state indicating the player is done buffering, and the remainder of the content is available for playback.
`Int`	`BUFFERING_STATE_UNKNOWN` Buffering state is unknown.
`Int`	`INVALID_ITEM_INDEX` Media item index is invalid. This value will be returned when the corresponding media item does not exist.
`Int`	`PLAYER_STATE_ERROR` State when the player is in error state and cannot be recovered self.
`Int`	`PLAYER_STATE_IDLE` State when the player is idle, and needs configuration to start playback.
`Int`	`PLAYER_STATE_PAUSED` State when the player's playback is paused
`Int`	`PLAYER_STATE_PLAYING` State when the player's playback is ongoing
`Int`	`REPEAT_MODE_ALL` Playing media list will be repeated.
`Int`	`REPEAT_MODE_GROUP` 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.
`Int`	`REPEAT_MODE_NONE` Playback will be stopped at the end of the playing media list.
`Int`	`REPEAT_MODE_ONE` Playback of the current playing media item will be repeated.
`Int`	`SHUFFLE_MODE_ALL` Media list will be played in shuffled order.
`Int`	`SHUFFLE_MODE_GROUP` 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.
`Int`	`SHUFFLE_MODE_NONE` Media list will be played in order.
`Long`	`UNKNOWN_TIME` Value indicating the time is unknown

Public constructors
`<init>()` Base interface for all remote media players that want media session and playback happens on the remote device through MediaRouter.

Public methods
abstract Future<SessionPlayer.PlayerResult!>	`adjustVolume(direction: Int)` Adjusts player volume with the direction.
abstract Int	`getMaxVolume()` Gets the maximum volume that can be used in `setVolume(int)`.
abstract Int	`getVolume()` Gets the current volume of this player to this player.
abstract Int	`getVolumeControlType()` Gets the volume type.
abstract Future<SessionPlayer.PlayerResult!>	`setVolume(volume: Int)` Sets the volume of the audio of the media to play, expressed as a linear multiplier on the audio samples.

Inherited functions

From class SessionPlayer

`ListenableFuture<SessionPlayer.PlayerResult!>`	`addPlaylistItem(index: Int, @NonNull item: MediaItem)` Adds the media item to the playlist at the index. Index equals to or greater than the current playlist size (e.g. `Integer#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 `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.
`Unit`	`close()` Removes all existing references to callbacks and executors. Note: Sub classes of `SessionPlayer` that override this API should call this super method.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`deselectTrack(@NonNull trackInfo: SessionPlayer.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(int)` returns the currently selected track per track type that can be deselected, but the list may be invalidated when `PlayerCallback#onTracksChanged(SessionPlayer, List)` is called.
`AudioAttributesCompat?`	`getAudioAttributes()` Gets the `AudioAttributesCompat` that media player has.
`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 `MediaItem#getStartPosition()`. So the position `0` means the start position of the `MediaItem`.
`Int`	`getBufferingState()` Returns the current buffering state of the player. During the buffering, see `getBufferedPosition()` for the quantifying the amount already buffered.
`MutableList<Pair<SessionPlayer.PlayerCallback!, Executor!>!>`	`getCallbacks()` Gets the callbacks with executors for subclasses to notify player events.
`MediaItem?`	`getCurrentMediaItem()` 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.
`Int`	`getCurrentMediaItemIndex()` Gets the index of current media item in playlist. This value should be updated when `PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem)` or `PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata)` is called.
`Long`	`getCurrentPosition()` Gets the current playback position. The position is the relative position based on the `MediaItem#getStartPosition()`. So the position `0` means the start position of the `MediaItem`.
`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`.
`Int`	`getNextMediaItemIndex()` Gets the next item index in the playlist. This value should be updated when `PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem)` or `PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata)` is called.
`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(float)`.
`Int`	`getPlayerState()` Gets the current player state.
`MutableList<MediaItem!>?`	`getPlaylist()` Gets the playlist. It can be `null` if the playlist hasn't been set or it's reset by `setMediaItem`.
`MediaMetadata?`	`getPlaylistMetadata()` Gets the playlist metadata.
`Int`	`getPreviousMediaItemIndex()` Gets the previous item index in the playlist. This value should be updated when `PlayerCallback#onCurrentMediaItemChanged(SessionPlayer, MediaItem)` or `PlayerCallback#onPlaylistChanged(SessionPlayer, List, MediaMetadata)` is called.
`Int`	`getRepeatMode()` Gets the repeat mode.
`SessionPlayer.TrackInfo?`	`getSelectedTrack(trackType: Int)` Gets currently selected track's `TrackInfo` for the given track type. The returned value can be outdated after `PlayerCallback#onTracksChanged(SessionPlayer, List)`, `PlayerCallback#onTrackSelected(SessionPlayer, TrackInfo)`, or `PlayerCallback#onTrackDeselected(SessionPlayer, TrackInfo)` is called.
`Int`	`getShuffleMode()` Gets the shuffle mode.
`MutableList<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.
`VideoSize`	`getVideoSize()` Gets the size of the video.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`movePlaylistItem(@IntRange(0) fromIndex: Int, @IntRange(0) toIndex: Int)` Moves the media item at `fromIdx` to `toIdx` in the playlist. 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` set.
`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 `PlayerResult#RESULT_ERROR_INVALID_STATE`.
`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 `PlayerResult#RESULT_ERROR_INVALID_STATE`.
`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 `PlayerResult#RESULT_ERROR_INVALID_STATE`.
`Unit`	`registerPlayerCallback(@NonNull executor: Executor, @NonNull callback: SessionPlayer.PlayerCallback)` Register `PlayerCallback` to listen changes.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`removePlaylistItem(@IntRange(0) index: Int)` Removes the media item from the playlist 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`replacePlaylistItem(index: Int, @NonNull item: MediaItem)` 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`seekTo(position: Long)` Seeks to the specified position. The position is the relative position based on the `MediaItem#getStartPosition()`. So calling `seekTo(long)` 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 `PlayerResult#RESULT_ERROR_INVALID_STATE`.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`selectTrack(@NonNull trackInfo: SessionPlayer.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 `PlayerCallback#onTracksChanged(SessionPlayer, List)` is called.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`setAudioAttributes(@NonNull attributes: AudioAttributesCompat)` 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`setMediaItem(@NonNull item: MediaItem)` 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`setPlaybackSpeed(playbackSpeed: Float)` 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`setPlaylist(@NonNull list: MutableList<MediaItem!>, @Nullable metadata: MediaMetadata?)` 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 `MediaItem`s 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`setRepeatMode(repeatMode: Int)` 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`setShuffleMode(shuffleMode: Int)` 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.
`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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`skipToNextPlaylistItem()` 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`skipToPlaylistItem(@IntRange(0) index: Int)` Skips to the item in the playlist at the index. 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.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`skipToPreviousPlaylistItem()` 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.
`Unit`	`unregisterPlayerCallback(@NonNull callback: SessionPlayer.PlayerCallback)` Unregister the previously registered `PlayerCallback`.
`ListenableFuture<SessionPlayer.PlayerResult!>`	`updatePlaylistMetadata(@Nullable metadata: MediaMetadata?)` 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.

Constants

VOLUME_CONTROL_ABSOLUTE

static val VOLUME_CONTROL_ABSOLUTE: Int

The volume control uses an absolute value. It may be adjusted using adjustVolume(int) or set directly using setVolume(int).

Value: 2

VOLUME_CONTROL_FIXED

static val VOLUME_CONTROL_FIXED: Int

The volume is fixed and can not be modified. Requests to change volume should be ignored.

Value: 0

VOLUME_CONTROL_RELATIVE

static val VOLUME_CONTROL_RELATIVE: Int

The volume control uses relative adjustment via adjustVolume(int). Attempts to set the volume to a specific value should be ignored.

Value: 1

Public constructors

<init>

RemoteSessionPlayer()

Base interface for all remote media players that want media session and playback happens on the remote device through MediaRouter.

If you use this to the MediaSession, session would dispatch incoming volume change event to the player instead of changing device stream volume.

Public methods

adjustVolume

@NonNull abstract fun adjustVolume(direction: Int): Future<SessionPlayer.PlayerResult!>

Adjusts player volume with the direction. Override this API to customize volume change in remote device.

This would be ignored when volume control type is VOLUME_CONTROL_FIXED.

Parameters
`direction`	Int: direction of the volume changes. Positive value for volume up, negative for volume down.

Return
`Future<SessionPlayer.PlayerResult!>`	result of adjusting the volume. Shouldn't be `null`.

getMaxVolume

abstract fun getMaxVolume(): Int

Gets the maximum volume that can be used in setVolume(int).

Return
`Int`	the maximum volume. Shouldn't be negative.

getVolume

abstract fun getVolume(): Int

Gets the current volume of this player to this player.

Note that it does not take into account the associated stream volume because the playback is happening outside of the phone device.

Return
`Int`	the player volume.

getVolumeControlType

abstract fun getVolumeControlType(): Int

Gets the volume type.

This shouldn't be changed after instantiation.

Return
`Int`	one of the volume type

See Also

setVolume

@NonNull abstract fun setVolume(volume: Int): Future<SessionPlayer.PlayerResult!>

Sets the volume of the audio of the media to play, expressed as a linear multiplier on the audio samples.

Note that this volume is specific to the player, and is separate from stream volume used across the platform.

A value of 0 indicates muting. See getMaxVolume() for the volume range supported by this player.

Parameters
`volume`	Int: a value between `0` and `getMaxVolume()`.

Return
`Future<SessionPlayer.PlayerResult!>`	result of setting the volume. Shouldn't be `null`.

Jun	JUL	Aug
	31
2019	2020	2021