Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

MediaController

open class MediaController : Closeable
kotlin.Any
   ↳ androidx.media2.session.MediaController

Allows an app to interact with an active or a MediaSessionService which would provide . Media buttons and other commands can be sent to the session.

MediaController objects are thread-safe.

Topics covered here:

  1. Controller Lifecycle
  2. Controlling the MediaSession in the same process

Controller Lifecycle

When a controller is created with the SessionToken for a MediaSession (i.e. session token type is SessionToken#TYPE_SESSION), the controller will connect to the specific session.

When a controller is created with the SessionToken for a MediaSessionService (i.e. session token type is SessionToken#TYPE_SESSION_SERVICE or SessionToken#TYPE_LIBRARY_SERVICE), the controller binds to the service for connecting to a MediaSession in it. MediaSessionService will provide a session to connect.

When a controller connects to a session, MediaSession.SessionCallback#onConnect(MediaSession, MediaSession.ControllerInfo) will be called to either accept or reject the connection. Wait ControllerCallback#onConnected(MediaController, SessionCommandGroup) or ControllerCallback#onDisconnected(MediaController) for the result.

When the connected session is closed, the controller will receive ControllerCallback#onDisconnected(MediaController).

When you're done, use #close() to clean up resources. This also helps session service to be destroyed when there's no controller associated with it.

Controlling the MediaSession in the same process

When you control the MediaSession and its SessionPlayer, it's recommended to use them directly rather than creating MediaController. However, if you need to use MediaController in the same process, be careful not to block session callback executor's thread. Here's an example code that would never return due to the thread issue.

<code>// Code runs on the main thread.
  MediaSession session = new MediaSession.Builder(context, player)
     .setSessionCallback(sessionCallback, Context.getMainExecutor(context)).build();
  MediaController controller = new MediaController.Builder(context)
     .setSessionToken(session.getToken())
     .setControllerCallback(Context.getMainExecutor(context), controllerCallback)
     .build();
 
  // This will hang and never return.
  controller.play().get();</code>
When a session gets a command from a controller, the session's MediaSession.SessionCallback#onCommandRequest would be executed on the session's callback executor to decide whether to ignore or handle the incoming command. To do so, the session's callback executor shouldn't be blocked to handle the incoming calls. However, if you call ListenableFuture#get on the thread for the session callback executor, then your call wouldn't be executed and never return.

To avoid such issue, don't block the session callback executor's thread. Creating a dedicated thread for the session callback executor would be helpful. See Executors#newSingleThreadExecutor for creating a new thread.

Summary

Nested classes

Builder for MediaController.

abstract

Interface for listening to change in activeness of the MediaSession.

Holds information about the way volume is handled for this session.

Public methods
open ListenableFuture<SessionResult!>
addPlaylistItem(@IntRange(0) index: Int, @NonNull mediaId: String)

Requests that the SessionPlayer associated with the connected MediaSession adds the media item to the playlist at the index with the media ID.

open ListenableFuture<SessionResult!>
adjustVolume(direction: Int, flags: Int)

Requests that the connected MediaSession adjusts the volume of the output that is playing on.

open Unit

Releases this object, and disconnects from the session.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession deselects the TrackInfo for the current media item.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession to fast forward playback.

open SessionCommandGroup?

Gets the cached allowed commands from ControllerCallback#onAllowedCommandsChanged.

open Long

Gets the position for how much has been buffered of the SessionPlayer associated with the connected MediaSession, or SessionPlayer#UNKNOWN_TIME if unknown or not connected.

open Int

Gets the current buffering state of the SessionPlayer associated with the connected MediaSession.

open SessionToken?

Returns the SessionToken of the connected session.

open MediaItem?

Gets the current media item of the SessionPlayer associated with the connected MediaSession.

open Int

Gets the current item index in the playlist of the SessionPlayer associated with the connected MediaSession.

open Long

Gets the playback position of the SessionPlayer associated with the connected MediaSession.

open Long

Gets the duration of the current media item, or SessionPlayer#UNKNOWN_TIME if unknown or not connected.

open Int

Gets the next item index in the playlist of the SessionPlayer associated with the connected MediaSession.

open MediaController.PlaybackInfo?

Get the current playback info for this session.

open Float

Gets the playback speed to be used by the of the SessionPlayer associated with the connected MediaSession when playing.

open Int

Gets the state of the SessionPlayer associated with the connected MediaSession.

open MutableList<MediaItem!>?

Gets the playlist of the SessionPlayer associated with the connected MediaSession.

open MediaMetadata?

Gets the playlist metadata of the SessionPlayer associated with the connected MediaSession.

open Int

Gets the previous item index in the playlist of the SessionPlayer associated with the connected MediaSession.

open Int

Gets the repeat mode of the SessionPlayer associated with the connected MediaSession.

open SessionPlayer.TrackInfo?
getSelectedTrack(trackType: Int)

Gets the currently selected track for the given track type of the SessionPlayer associated with the connected MediaSession.

open PendingIntent?

Gets an intent for launching UI associated with this session if one exists.

open Int

Gets the shuffle mode of the SessionPlayer associated with the connected MediaSession.

open MutableList<SessionPlayer.TrackInfo!>

Gets the full list of selected and unselected tracks that the media contains of the SessionPlayer associated with the connected MediaSession.

open VideoSize

Gets the video size of the SessionPlayer associated with the connected MediaSession.

open Boolean

Returns whether this class is connected to active MediaSession or not.

open ListenableFuture<SessionResult!>
movePlaylistItem(@IntRange(0) fromIndex: Int, @IntRange(0) toIndex: Int)

Requests that the SessionPlayer associated with the connected MediaSession moves the media item at fromIdx to toIdx in the playlist.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession pauses playback.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession starts or resumes playback.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession prepares the media items for playback.

open ListenableFuture<SessionResult!>
removePlaylistItem(@IntRange(0) index: Int)

Requests that the SessionPlayer associated with the connected MediaSession removes the media item at index in the playlist.

open ListenableFuture<SessionResult!>
replacePlaylistItem(@IntRange(0) index: Int, @NonNull mediaId: String)

Requests that the SessionPlayer associated with the connected MediaSession replaces the media item at index in the playlist with the media ID.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession to rewind playback.

open ListenableFuture<SessionResult!>
seekTo(position: Long)

Requests that the SessionPlayer associated with the connected MediaSession seeks to the specified position.

open ListenableFuture<SessionResult!>
selectTrack(@NonNull trackInfo: SessionPlayer.TrackInfo)

Requests that the SessionPlayer associated with the connected MediaSession selects the TrackInfo for the current media item.

open ListenableFuture<SessionResult!>
sendCustomCommand(@NonNull command: SessionCommand, @Nullable args: Bundle?)

Sends a custom command to the session

open ListenableFuture<SessionResult!>
setMediaItem(@NonNull mediaId: String)

Requests that the SessionPlayer associated with the connected MediaSession sets a MediaItem for playback.

open ListenableFuture<SessionResult!>
setMediaUri(@NonNull uri: Uri, @Nullable extras: Bundle?)

Requests that the connected MediaSession sets a specific Uri for playback.

open ListenableFuture<SessionResult!>
setPlaybackSpeed(playbackSpeed: Float)

Requests that the SessionPlayer associated with the connected MediaSession sets the playback speed.

open ListenableFuture<SessionResult!>
setPlaylist(@NonNull list: MutableList<String!>, @Nullable metadata: MediaMetadata?)

Requests that the SessionPlayer associated with the connected MediaSession sets the playlist with the list of media IDs.

open ListenableFuture<SessionResult!>
setRating(@NonNull mediaId: String, @NonNull rating: Rating)

Requests that the connected MediaSession rates the media.

open ListenableFuture<SessionResult!>
setRepeatMode(repeatMode: Int)

Requests that the SessionPlayer associated with the connected MediaSession sets the repeat mode.

open ListenableFuture<SessionResult!>
setShuffleMode(shuffleMode: Int)

Requests that the SessionPlayer associated with the connected MediaSession sets the shuffle mode.

open ListenableFuture<SessionResult!>
setSurface(@Nullable surface: Surface?)

Requests that the SessionPlayer associated with the connected MediaSession sets the Surface to be used as the sink for the video portion of the media.

open ListenableFuture<SessionResult!>
setVolumeTo(value: Int, flags: Int)

Requests that the connected MediaSession sets the volume of the output that is playing on.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips forward within the current media item.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips backward within the current media item.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips to the next item in the playlist.

open ListenableFuture<SessionResult!>
skipToPlaylistItem(@IntRange(0) index: Int)

Requests that the SessionPlayer associated with the connected MediaSession skips to the item in the playlist at the index.

open ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips to the previous item in the playlist.

open ListenableFuture<SessionResult!>
updatePlaylistMetadata(@Nullable metadata: MediaMetadata?)

Requests that the SessionPlayer associated with the connected MediaSession updates the playlist metadata while keeping the playlist as-is.

Public methods

addPlaylistItem

@NonNull open fun addPlaylistItem(
    @IntRange(0) index: Int,
    @NonNull mediaId: String
): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession adds the media item to the playlist at the index with the media ID. 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 will be increased correspondingly.

On success, a SessionResult would be returned with item added.

Parameters
index Int: the index you want to add
mediaId String: the non-empty media id of the new item

adjustVolume

@NonNull open fun adjustVolume(
    direction: Int,
    flags: Int
): ListenableFuture<SessionResult!>

Requests that the connected MediaSession adjusts the volume of the output that is playing on. The direction must be one of AudioManager#ADJUST_LOWER, AudioManager#ADJUST_RAISE, or AudioManager#ADJUST_SAME.

The command will be ignored if the session does not support VolumeProviderCompat#VOLUME_CONTROL_RELATIVE or VolumeProviderCompat#VOLUME_CONTROL_ABSOLUTE.

If the session is local playback, this changes the device's volume with the stream that session's player is using. Flags will be specified for the AudioManager.

If the session is remote player (i.e. session has set volume provider), its volume provider will receive this request instead.

Parameters
direction Int: the direction to adjust the volume in
flags Int: flags from AudioManager to include with the volume request for local playback
Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

close

open fun close(): Unit

Releases this object, and disconnects from the session. After this, callbacks wouldn't be received.

deselectTrack

@NonNull open fun deselectTrack(@NonNull trackInfo: SessionPlayer.TrackInfo): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession 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 players.

Note: getSelectedTrack(int) returns the currently selected track per track type that can be deselected, but the list may be invalidated when ControllerCallback#onTracksChanged(MediaController, List) is called.

Parameters
trackInfo SessionPlayer.TrackInfo: track to be deselected
Return
ListenableFuture<SessionResult!> a ListenableFuture which represents the pending completion of the command

fastForward

@NonNull open fun fastForward(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession to fast forward playback.

The implementation may be different depending on the players. For example, it can be implemented by seeking forward once, series of seeking forward, or increasing playback speed. If you need full control, then use seekTo or setPlaybackSpeed directly.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

getAllowedCommands

@Nullable open fun getAllowedCommands(): SessionCommandGroup?

Gets the cached allowed commands from ControllerCallback#onAllowedCommandsChanged. If it is not connected yet, it returns null.

Return
SessionCommandGroup? the allowed commands

getBufferedPosition

open fun getBufferedPosition(): Long

Gets the position for how much has been buffered of the SessionPlayer associated with the connected MediaSession, or SessionPlayer#UNKNOWN_TIME if unknown or not connected.

Return
Long buffering position in ms, or SessionPlayer#UNKNOWN_TIME if unknown or not connected

getBufferingState

open fun getBufferingState(): Int

Gets the current buffering state of the SessionPlayer associated with the connected MediaSession.

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

Return
Int the buffering state, or SessionPlayer#BUFFERING_STATE_UNKNOWN if unknown or not connected

getConnectedToken

@Nullable open fun getConnectedToken(): SessionToken?

Returns the SessionToken of the connected session. If it is not connected yet, it returns null.

This may differ from the SessionToken from the constructor. For example, if the controller is created with the token for MediaSessionService, this would return token for the MediaSession in the service.

Return
SessionToken? SessionToken of the connected session, or null if not connected

getCurrentMediaItem

@Nullable open fun getCurrentMediaItem(): MediaItem?

Gets the current media item of the SessionPlayer associated with the connected MediaSession. This can be currently playing or would be played with later play. This value may be updated when ControllerCallback#onCurrentMediaItemChanged(MediaController, MediaItem) or ControllerCallback#onPlaylistChanged(MediaController, List, MediaMetadata) is called.

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

getCurrentMediaItemIndex

open fun getCurrentMediaItemIndex(): Int

Gets the current item index in the playlist of the SessionPlayer associated with the connected MediaSession. The value would be updated when ControllerCallback#onCurrentMediaItemChanged(MediaController, MediaItem) or ControllerCallback#onPlaylistChanged(MediaController, List, MediaMetadata) is called.

Return
Int the index of current item in playlist, or SessionPlayer#INVALID_ITEM_INDEX if current media item does not exist or playlist hasn't been set

getCurrentPosition

open fun getCurrentPosition(): Long

Gets the playback position of the SessionPlayer associated with the connected MediaSession.

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

Return
Long the current playback position in ms, or SessionPlayer#UNKNOWN_TIME if unknown or not connected

getDuration

open fun getDuration(): Long

Gets the duration of the current media item, or SessionPlayer#UNKNOWN_TIME if unknown or not connected. 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.

Return
Long the duration in ms, or SessionPlayer#UNKNOWN_TIME if unknonw or not connected.

getNextMediaItemIndex

open fun getNextMediaItemIndex(): Int

Gets the next item index in the playlist of the SessionPlayer associated with the connected MediaSession. This value would be updated when ControllerCallback#onCurrentMediaItemChanged(MediaController, MediaItem) or ControllerCallback#onPlaylistChanged(MediaController, List, MediaMetadata) is called.

Interoperability: When connected to android.support.v4.media.session.MediaSessionCompat, this will always return SessionPlayer#INVALID_ITEM_INDEX..

Return
Int the index of next item in playlist, or SessionPlayer#INVALID_ITEM_INDEX if next media item does not exist or playlist hasn't been set

getPlaybackInfo

@Nullable open fun getPlaybackInfo(): MediaController.PlaybackInfo?

Get the current playback info for this session. If it is not connected yet, it returns null.

Return
MediaController.PlaybackInfo? the current playback info or null

getPlaybackSpeed

open fun getPlaybackSpeed(): Float

Gets the playback speed to be used by the of the SessionPlayer associated with the connected MediaSession 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 speed the playback speed, or 0f if unknown or not connected

getPlayerState

open fun getPlayerState(): Int

Gets the state of the SessionPlayer associated with the connected MediaSession. If it is not connected yet, it returns SessionPlayer#PLAYER_STATE_IDLE.

Return
Int the player state

getPlaylist

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

Gets the playlist of the SessionPlayer associated with the connected MediaSession. It can be null if the playlist hasn't been set or it's reset by setMediaItem.

This list may differ from the list that was specified with setPlaylist(List, MediaMetadata) depending on the SessionPlayer implementation.

Return
MutableList<MediaItem!>? playlist, or null if the playlist hasn't been set or the controller isn't connected

getPlaylistMetadata

@Nullable open fun getPlaylistMetadata(): MediaMetadata?

Gets the playlist metadata of the SessionPlayer associated with the connected MediaSession.

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

getPreviousMediaItemIndex

open fun getPreviousMediaItemIndex(): Int

Gets the previous item index in the playlist of the SessionPlayer associated with the connected MediaSession. This value would be updated when ControllerCallback#onCurrentMediaItemChanged(MediaController, MediaItem) or ControllerCallback#onPlaylistChanged(MediaController, List, MediaMetadata) is called.

Interoperability: When connected to android.support.v4.media.session.MediaSessionCompat, this will always return SessionPlayer#INVALID_ITEM_INDEX.

Return
Int the index of previous item in playlist, or SessionPlayer#INVALID_ITEM_INDEX if previous media item does not exist or playlist hasn't been set

getRepeatMode

open fun getRepeatMode(): Int

Gets the repeat mode of the SessionPlayer associated with the connected MediaSession. If it is not connected yet, it returns SessionPlayer#REPEAT_MODE_NONE.

Return
Int repeat mode

getSelectedTrack

@Nullable open fun getSelectedTrack(trackType: Int): SessionPlayer.TrackInfo?

Gets the currently selected track for the given track type of the SessionPlayer associated with the connected MediaSession. If it is not connected yet, it returns null.

The returned value can be outdated after ControllerCallback#onTracksChanged(MediaController, List), ControllerCallback#onTrackSelected(MediaController, TrackInfo), or ControllerCallback#onTrackDeselected(MediaController, TrackInfo) is called.

Parameters
trackType Int: type of selected track
Return
SessionPlayer.TrackInfo? selected track info

getSessionActivity

@Nullable open fun getSessionActivity(): PendingIntent?

Gets an intent for launching UI associated with this session if one exists. If it is not connected yet, it returns null.

Return
PendingIntent? a PendingIntent to launch UI or null

getShuffleMode

open fun getShuffleMode(): Int

Gets the shuffle mode of the SessionPlayer associated with the connected MediaSession. If it is not connected yet, it returns SessionPlayer#SHUFFLE_MODE_NONE.

Return
Int the shuffle mode

getTracks

@NonNull open fun getTracks(): MutableList<SessionPlayer.TrackInfo!>

Gets the full list of selected and unselected tracks that the media contains of the SessionPlayer associated with the connected MediaSession. 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.

Return
MutableList<SessionPlayer.TrackInfo!> list of tracks. The total number of tracks is the size of the list. If empty, an empty list would be returned.

getVideoSize

@NonNull open fun getVideoSize(): VideoSize

Gets the video size of the SessionPlayer associated with the connected MediaSession. If it is not connected yet, it returns new VideoSize(0, 0).

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

isConnected

open fun isConnected(): Boolean

Returns whether this class is connected to active MediaSession or not.

movePlaylistItem

@NonNull open fun movePlaylistItem(
    @IntRange(0) fromIndex: Int,
    @IntRange(0) toIndex: Int
): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession moves the media item at fromIdx to toIdx in the playlist.

On success, a SessionResult would be returned with item set.

Parameters
fromIndex Int: the media item's initial index in the playlist
toIndex Int: the media item's target index in the playlist

pause

@NonNull open fun pause(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession pauses playback.

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

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

play

@NonNull open fun play(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession starts or resumes playback.

On success, this transfers the player state to SessionPlayer#PLAYER_STATE_PLAYING and a SessionResult would be returned with the current media item when the command was completed. If the player state is SessionPlayer#PLAYER_STATE_IDLE, the session would also call SessionPlayer#prepare and then SessionPlayer#play to start playback. If you want to have finer grained control of the playback start, call prepare manually before this. Calling prepare in advance would help this method to start playback faster and also help to take audio focus at the last moment.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

See Also

prepare

@NonNull open fun prepare(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession 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 SessionPlayer#PLAYER_STATE_IDLE to SessionPlayer#PLAYER_STATE_PAUSED and a SessionResult would be returned with the prepared media item when the command completed. If it's not called in SessionPlayer#PLAYER_STATE_IDLE, it would be ignored and SessionResult would be returned with SessionResult#RESULT_ERROR_INVALID_STATE.

Playback can be started without this. But this provides finer grained control of playback start. See play for details.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

See Also

removePlaylistItem

@NonNull open fun removePlaylistItem(@IntRange(0) index: Int): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession removes the media item at index in the playlist.

On success, a SessionResult would be returned with item removed.

Parameters
index Int: the media item you want to add

replacePlaylistItem

@NonNull open fun replacePlaylistItem(
    @IntRange(0) index: Int,
    @NonNull mediaId: String
): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession replaces the media item at index in the playlist with the media ID.

On success, a SessionResult would be returned with item set.

Parameters
index Int: the index of the item to replace
mediaId String: the non-empty media id of the new item

rewind

@NonNull open fun rewind(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession to rewind playback.

The implementation may be different depending on the players. For example, it can be implemented by seeking backward once, series of seeking backward, or decreasing playback speed. If you need full control, then use seekTo or setPlaybackSpeed directly.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

seekTo

@NonNull open fun seekTo(position: Long): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession 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 SessionResult would be returned with the current media item when the command completed. If it's called in SessionPlayer#PLAYER_STATE_IDLE, it is ignored and a SessionResult would be returned with SessionResult#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.
Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

selectTrack

@NonNull open fun selectTrack(@NonNull trackInfo: SessionPlayer.TrackInfo): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession 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 players.

Note: getTracks() returns the list of tracks that can be selected, but the list may be invalidated when ControllerCallback#onTracksChanged(MediaController, List) is called.

Parameters
trackInfo SessionPlayer.TrackInfo: track to be selected
Return
ListenableFuture<SessionResult!> a ListenableFuture which represents the pending completion of the command

sendCustomCommand

@NonNull open fun sendCustomCommand(
    @NonNull command: SessionCommand,
    @Nullable args: Bundle?
): ListenableFuture<SessionResult!>

Sends a custom command to the session

Interoperability: When connected to android.support.v4.media.session.MediaSessionCompat, SessionResult#getResultCode() will return the custom result code from the ResultReceiver#onReceiveResult(int, Bundle) instead of the standard result codes defined in the SessionResult.

A command is not accepted if it is not a custom command.

Parameters
command SessionCommand: custom command
args Bundle?: optional argument

setMediaItem

@NonNull open fun setMediaItem(@NonNull mediaId: String): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession sets a MediaItem for playback. Use this, setMediaUri, 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 SessionPlayer#PLAYER_STATE_ERROR. This would override previous call of this, setMediaUri, or setPlaylist.

The ControllerCallback#onPlaylistChanged and/or ControllerCallback#onCurrentMediaItemChanged would be called when it's completed.

On success, a SessionResult would be returned with item set.

Parameters
mediaId String: the non-empty media id of the item to play

setMediaUri

@NonNull open fun setMediaUri(
    @NonNull uri: Uri,
    @Nullable extras: Bundle?
): ListenableFuture<SessionResult!>

Requests that the connected MediaSession sets a specific Uri for playback. Use this, setMediaItem, or setPlaylist to specify which items to play.

This can be called multiple times in any states other than SessionPlayer#PLAYER_STATE_ERROR. This would override previous call of this, setMediaItem, or setPlaylist.

The ControllerCallback#onPlaylistChanged and/or ControllerCallback#onCurrentMediaItemChanged would be called when it's completed.

On success, a SessionResult would be returned with item set.

Parameters
uri Uri: the Uri of the item to play

setPlaybackSpeed

@NonNull open fun setPlaybackSpeed(playbackSpeed: Float): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession sets the playback speed. The default playback speed is 1.0f is the default, and negative values indicate reverse playback and 0.0f is not allowed.

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

On success, a SessionResult would be returned with the current media item when the command completed.

Parameters
playbackSpeed Float: the requested playback speed
Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command
Exceptions
IllegalArgumentException if the speed is equal to zero.

setPlaylist

@NonNull open fun setPlaylist(
    @NonNull list: MutableList<String!>,
    @Nullable metadata: MediaMetadata?
): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession sets the playlist with the list of media IDs. Use this, setMediaUri, or setMediaItem to specify which items to play.

All media IDs in the list shouldn't be an empty string.

This can be called multiple times in any states other than SessionPlayer#PLAYER_STATE_ERROR. This would override previous call of this, setMediaItem, or setMediaUri.

The ControllerCallback#onPlaylistChanged and/or ControllerCallback#onCurrentMediaItemChanged would be called when it's completed. The current item would be the first item in the playlist.

Parameters
list MutableList<String!>: list of media id. Shouldn't contain an empty id
metadata MediaMetadata?: metadata of the playlist
Exceptions
IllegalArgumentException if the list is null or contains any empty string.

setRating

@NonNull open fun setRating(
    @NonNull mediaId: String,
    @NonNull rating: Rating
): ListenableFuture<SessionResult!>

Requests that the connected MediaSession rates the media. This will cause the rating to be set for the current user. The rating style must follow the user rating style from the session.You can get the rating style from the session through the MediaMetadata#getRating(String) with the key MediaMetadata#METADATA_KEY_USER_RATING.

If the user rating was null, the media item does not accept setting user rating.

Parameters
mediaId String: the non-empty media id
rating Rating: the rating to set

setRepeatMode

@NonNull open fun setRepeatMode(repeatMode: Int): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession sets the repeat mode.

On success, a SessionResult would be returned with the current media item when the command completed.

Parameters
repeatMode Int: repeat mode
Return
ListenableFuture<SessionResult!> a ListenableFuture which represents the pending completion of the command

setShuffleMode

@NonNull open fun setShuffleMode(shuffleMode: Int): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession sets the shuffle mode.

On success, a SessionResult would be returned with the current media item when the command completed.

Parameters
shuffleMode Int: the shuffle mode
Return
ListenableFuture<SessionResult!> a ListenableFuture which represents the pending completion of the command

setSurface

@NonNull open fun setSurface(@Nullable surface: Surface?): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession 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 SessionResult is returned with the current media item when the command completed.

Parameters
surface Surface?: the Surface to be used for the video portion of the media
Return
ListenableFuture<SessionResult!> a ListenableFuture which represents the pending completion of the command

setVolumeTo

@NonNull open fun setVolumeTo(
    value: Int,
    flags: Int
): ListenableFuture<SessionResult!>

Requests that the connected MediaSession sets the volume of the output that is playing on. The command will be ignored if it does not support VolumeProviderCompat#VOLUME_CONTROL_ABSOLUTE.

If the session is local playback, this changes the device's volume with the stream that session's player is using. Flags will be specified for the AudioManager.

If the session is remote player (i.e. session has set volume provider), its volume provider will receive this request instead.

Parameters
value Int: the value to set it to, between 0 and the reported max
flags Int: flags from AudioManager to include with the volume request for local playback
Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

skipBackward

@NonNull open fun skipBackward(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips forward within the current media item.

The implementation may be different depending on the players. For example, it can be implemented by seeking backward once with the fixed amount of seconds, or seeking backward to the nearest bookmark. If you need full control, then use seekTo directly.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

skipForward

@NonNull open fun skipForward(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips backward within the current media item.

The implementation may be different depending on the players. For example, it can be implemented by seeking forward once with the fixed amount of seconds, or seeking forward to the nearest bookmark. If you need full control, then use seekTo directly.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

skipToNextPlaylistItem

@NonNull open fun skipToNextPlaylistItem(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips to the next item in the playlist.

On success, a SessionResult would be returned with the current media item when the command completed.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

skipToPlaylistItem

@NonNull open fun skipToPlaylistItem(@IntRange(0) index: Int): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips to the item in the playlist at the index.

On success, a SessionResult would 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
Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

skipToPreviousPlaylistItem

@NonNull open fun skipToPreviousPlaylistItem(): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession skips to the previous item in the playlist.

On success, a SessionResult would be returned with the current media item when the command completed.

Return
ListenableFuture<SessionResult!> a ListenableFuture representing the pending completion of the command

updatePlaylistMetadata

@NonNull open fun updatePlaylistMetadata(@Nullable metadata: MediaMetadata?): ListenableFuture<SessionResult!>

Requests that the SessionPlayer associated with the connected MediaSession updates the playlist metadata while keeping the playlist as-is.

On success, a SessionResult would be returned with the current media item when the command completed.

Parameters
metadata MediaMetadata?: metadata of the playlist