Summary: Nested Classes | Methods | Inherited Methods

MediaController

Kotlin |Java

public class MediaController
extends Object implements Closeable

java.lang.Object
↳	androidx.media2.session.MediaController

Known direct subclasses

MediaBrowser

MediaBrowser Browses media content offered by a MediaLibraryService.

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

MediaController objects are thread-safe.

Topics covered here:

Controller Lifecycle
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 MediaController.ControllerCallback.onConnected(MediaController, SessionCommandGroup) or MediaController.ControllerCallback.onDisconnected(MediaController) for the result.

When the connected session is closed, the controller will receive MediaController.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 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();

When a session gets a command from a controller, the session's MediaSession.SessionCallback.onCommandRequest(MediaSession, MediaSession.ControllerInfo, SessionCommand) 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 Future.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.

See also:

Summary

Nested classes
`class`	`MediaController.Builder` Builder for `MediaController`.
`class`	`MediaController.ControllerCallback` Interface for listening to change in activeness of the `MediaSession`.
`class`	`MediaController.PlaybackInfo` Holds information about the way volume is handled for this session.

Public methods
`ListenableFuture<SessionResult>`	`addPlaylistItem(int index, String mediaId)` Requests that the `SessionPlayer` associated with the connected `MediaSession` adds the media item to the playlist at the index with the media ID.
`ListenableFuture<SessionResult>`	`adjustVolume(int direction, int flags)` Requests that the connected `MediaSession` adjusts the volume of the output that is playing on.
`void`	`close()` Releases this object, and disconnects from the session.
`ListenableFuture<SessionResult>`	`deselectTrack(SessionPlayer.TrackInfo trackInfo)` Requests that the `SessionPlayer` associated with the connected `MediaSession` deselects the `SessionPlayer.TrackInfo` for the current media item.
`ListenableFuture<SessionResult>`	`fastForward()` Requests that the `SessionPlayer` associated with the connected `MediaSession` to fast forward playback.
`SessionCommandGroup`	`getAllowedCommands()` Gets the cached allowed commands from `MediaController.ControllerCallback.onAllowedCommandsChanged(MediaController, SessionCommandGroup)`.
`long`	`getBufferedPosition()` 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.
`int`	`getBufferingState()` Gets the current buffering state of the `SessionPlayer` associated with the connected `MediaSession`.
`SessionToken`	`getConnectedToken()` Returns the `SessionToken` of the connected session.
`MediaItem`	`getCurrentMediaItem()` Gets the current media item of the `SessionPlayer` associated with the connected `MediaSession`.
`int`	`getCurrentMediaItemIndex()` Gets the current item index in the playlist of the `SessionPlayer` associated with the connected `MediaSession`.
`long`	`getCurrentPosition()` Gets the playback position of the `SessionPlayer` associated with the connected `MediaSession`.
`long`	`getDuration()` Gets the duration of the current media item, or `SessionPlayer.UNKNOWN_TIME` if unknown or not connected.
`int`	`getNextMediaItemIndex()` Gets the next item index in the playlist of the `SessionPlayer` associated with the connected `MediaSession`.
`MediaController.PlaybackInfo`	`getPlaybackInfo()` Get the current playback info for this session.
`float`	`getPlaybackSpeed()` Gets the playback speed to be used by the of the `SessionPlayer` associated with the connected `MediaSession` when playing.
`int`	`getPlayerState()` Gets the state of the `SessionPlayer` associated with the connected `MediaSession`.
`List<MediaItem>`	`getPlaylist()` Gets the playlist of the `SessionPlayer` associated with the connected `MediaSession`.
`MediaMetadata`	`getPlaylistMetadata()` Gets the playlist metadata of the `SessionPlayer` associated with the connected `MediaSession`.
`int`	`getPreviousMediaItemIndex()` Gets the previous item index in the playlist of the `SessionPlayer` associated with the connected `MediaSession`.
`int`	`getRepeatMode()` Gets the repeat mode of the `SessionPlayer` associated with the connected `MediaSession`.
`SessionPlayer.TrackInfo`	`getSelectedTrack(int trackType)` Gets the currently selected track for the given track type of the `SessionPlayer` associated with the connected `MediaSession`.
`PendingIntent`	`getSessionActivity()` Gets an intent for launching UI associated with this session if one exists.
`int`	`getShuffleMode()` Gets the shuffle mode of the `SessionPlayer` associated with the connected `MediaSession`.
`List<SessionPlayer.TrackInfo>`	`getTracks()` Gets the full list of selected and unselected tracks that the media contains of the `SessionPlayer` associated with the connected `MediaSession`.
`VideoSize`	`getVideoSize()` Gets the video size of the `SessionPlayer` associated with the connected `MediaSession`.
`boolean`	`isConnected()` Returns whether this class is connected to active `MediaSession` or not.
`ListenableFuture<SessionResult>`	`movePlaylistItem(int fromIndex, int toIndex)` Requests that the `SessionPlayer` associated with the connected `MediaSession` moves the media item at `fromIdx` to `toIdx` in the playlist.
`ListenableFuture<SessionResult>`	`pause()` Requests that the `SessionPlayer` associated with the connected `MediaSession` pauses playback.
`ListenableFuture<SessionResult>`	`play()` Requests that the `SessionPlayer` associated with the connected `MediaSession` starts or resumes playback.
`ListenableFuture<SessionResult>`	`prepare()` Requests that the `SessionPlayer` associated with the connected `MediaSession` prepares the media items for playback.
`ListenableFuture<SessionResult>`	`removePlaylistItem(int index)` Requests that the `SessionPlayer` associated with the connected `MediaSession` removes the media item at index in the playlist.
`ListenableFuture<SessionResult>`	`replacePlaylistItem(int index, String mediaId)` Requests that the `SessionPlayer` associated with the connected `MediaSession` replaces the media item at index in the playlist with the media ID.
`ListenableFuture<SessionResult>`	`rewind()` Requests that the `SessionPlayer` associated with the connected `MediaSession` to rewind playback.
`ListenableFuture<SessionResult>`	`seekTo(long position)` Requests that the `SessionPlayer` associated with the connected `MediaSession` seeks to the specified position.
`ListenableFuture<SessionResult>`	`selectTrack(SessionPlayer.TrackInfo trackInfo)` Requests that the `SessionPlayer` associated with the connected `MediaSession` selects the `SessionPlayer.TrackInfo` for the current media item.
`ListenableFuture<SessionResult>`	`sendCustomCommand(SessionCommand command, Bundle args)` Sends a custom command to the session Interoperability: When connected to `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`.
`ListenableFuture<SessionResult>`	`setMediaItem(String mediaId)` Requests that the `SessionPlayer` associated with the connected `MediaSession` sets a `MediaItem` for playback.
`ListenableFuture<SessionResult>`	`setMediaUri(Uri uri, Bundle extras)` Requests that the connected `MediaSession` sets a specific `Uri` for playback.
`ListenableFuture<SessionResult>`	`setPlaybackSpeed(float playbackSpeed)` Requests that the `SessionPlayer` associated with the connected `MediaSession` sets the playback speed.
`ListenableFuture<SessionResult>`	`setPlaylist(List<String> list, MediaMetadata metadata)` Requests that the `SessionPlayer` associated with the connected `MediaSession` sets the playlist with the list of media IDs.
`ListenableFuture<SessionResult>`	`setRating(String mediaId, Rating rating)` Requests that the connected `MediaSession` rates the media.
`ListenableFuture<SessionResult>`	`setRepeatMode(int repeatMode)` Requests that the `SessionPlayer` associated with the connected `MediaSession` sets the repeat mode.
`ListenableFuture<SessionResult>`	`setShuffleMode(int shuffleMode)` Requests that the `SessionPlayer` associated with the connected `MediaSession` sets the shuffle mode.
`ListenableFuture<SessionResult>`	`setSurface(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.
`ListenableFuture<SessionResult>`	`setVolumeTo(int value, int flags)` Requests that the connected `MediaSession` sets the volume of the output that is playing on.
`ListenableFuture<SessionResult>`	`skipBackward()` Requests that the `SessionPlayer` associated with the connected `MediaSession` skips forward within the current media item.
`ListenableFuture<SessionResult>`	`skipForward()` Requests that the `SessionPlayer` associated with the connected `MediaSession` skips backward within the current media item.
`ListenableFuture<SessionResult>`	`skipToNextPlaylistItem()` Requests that the `SessionPlayer` associated with the connected `MediaSession` skips to the next item in the playlist.
`ListenableFuture<SessionResult>`	`skipToPlaylistItem(int index)` Requests that the `SessionPlayer` associated with the connected `MediaSession` skips to the item in the playlist at the index.
`ListenableFuture<SessionResult>`	`skipToPreviousPlaylistItem()` Requests that the `SessionPlayer` associated with the connected `MediaSession` skips to the previous item in the playlist.
`ListenableFuture<SessionResult>`	`updatePlaylistMetadata(MediaMetadata metadata)` Requests that the `SessionPlayer` associated with the connected `MediaSession` updates the playlist metadata while keeping the playlist as-is.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()`
`boolean`	`equals(Object arg0)`
`void`	`finalize()`
`final Class<?>`	`getClass()`
`int`	`hashCode()`
`final void`	`notify()`
`final void`	`notifyAll()`
`String`	`toString()`
`final void`	`wait(long arg0, int arg1)`
`final void`	`wait(long arg0)`
`final void`	`wait()`

From interface


        
          java.io.Closeable

abstract void close()

From interface


        
          java.lang.AutoCloseable

abstract void close()

Public methods

addPlaylistItem

public ListenableFuture<SessionResult> addPlaylistItem (int index, 
                String mediaId)

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

Returns
`ListenableFuture<SessionResult>`

See also:

adjustVolume

public ListenableFuture<SessionResult> adjustVolume (int direction, 
                int flags)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

getPlaybackInfo()

close

public void close ()

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

deselectTrack

public ListenableFuture<SessionResult> deselectTrack (SessionPlayer.TrackInfo trackInfo)

Requests that the SessionPlayer associated with the connected MediaSession deselects the SessionPlayer.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 MediaController.ControllerCallback.onTracksChanged(MediaController, List) is called.

Parameters
`trackInfo`	`SessionPlayer.TrackInfo`: track to be deselected

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` which represents the pending completion of the command

See also:

fastForward

public ListenableFuture<SessionResult> fastForward ()

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(long) or setPlaybackSpeed(float) directly.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaSession.SessionCallback.onFastForward(MediaSession, MediaSession.ControllerInfo)

getAllowedCommands

public SessionCommandGroup getAllowedCommands ()

Gets the cached allowed commands from MediaController.ControllerCallback.onAllowedCommandsChanged(MediaController, SessionCommandGroup). If it is not connected yet, it returns null.

Returns
`SessionCommandGroup`	the allowed commands

getBufferedPosition

public long getBufferedPosition ()

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.

Returns
`long`	buffering position in ms, or `SessionPlayer.UNKNOWN_TIME` if unknown or not connected

getBufferingState

public int getBufferingState ()

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.

Returns
`int`	the buffering state, or `SessionPlayer.BUFFERING_STATE_UNKNOWN` if unknown or not connected

getConnectedToken

public SessionToken getConnectedToken ()

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.

Returns
`SessionToken`	SessionToken of the connected session, or `null` if not connected

getCurrentMediaItem

public MediaItem getCurrentMediaItem ()

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 MediaController.ControllerCallback.onCurrentMediaItemChanged(MediaController, MediaItem) or MediaController.ControllerCallback.onPlaylistChanged(MediaController, List, MediaMetadata) is called.

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

See also:

getCurrentMediaItemIndex

public int getCurrentMediaItemIndex ()

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

Returns
`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

public long getCurrentPosition ()

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.

Returns
`long`	the current playback position in ms, or `SessionPlayer.UNKNOWN_TIME` if unknown or not connected

getDuration

public long getDuration ()

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.

Returns
`long`	the duration in ms, or `SessionPlayer.UNKNOWN_TIME` if unknonw or not connected.

getNextMediaItemIndex

public int getNextMediaItemIndex ()

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

Interoperability: When connected to MediaSessionCompat, this will always return SessionPlayer.INVALID_ITEM_INDEX..

Returns
`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

public MediaController.PlaybackInfo getPlaybackInfo ()

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

Returns
`MediaController.PlaybackInfo`	the current playback info or null

getPlaybackSpeed

public float getPlaybackSpeed ()

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

Returns
`float`	speed the playback speed, or 0f if unknown or not connected

getPlayerState

public int getPlayerState ()

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

Returns
`int`	the player state

See also:

getPlaylist

public List<MediaItem> getPlaylist ()

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

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

Returns
`List<MediaItem>`	playlist, or `null` if the playlist hasn't been set or the controller isn't connected

See also:

SessionCommand.COMMAND_CODE_PLAYER_GET_PLAYLIST

getPlaylistMetadata

public MediaMetadata getPlaylistMetadata ()

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

Returns
`MediaMetadata`	metadata of the playlist, or null if none is set or the controller is not connected

See also:

getPreviousMediaItemIndex

public int getPreviousMediaItemIndex ()

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

Interoperability: When connected to MediaSessionCompat, this will always return SessionPlayer.INVALID_ITEM_INDEX.

Returns
`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

public int getRepeatMode ()

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

Returns
`int`	repeat mode

See also:

getSelectedTrack

public SessionPlayer.TrackInfo getSelectedTrack (int trackType)

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 MediaController.ControllerCallback.onTracksChanged(MediaController, List), MediaController.ControllerCallback.onTrackSelected(MediaController, TrackInfo), or MediaController.ControllerCallback.onTrackDeselected(MediaController, TrackInfo) is called.

Parameters
`trackType`	`int`: type of selected track

Returns
`SessionPlayer.TrackInfo`	selected track info

See also:

getSessionActivity

public PendingIntent getSessionActivity ()

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

Returns
`PendingIntent`	a `PendingIntent` to launch UI or null

getShuffleMode

public int getShuffleMode ()

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

Returns
`int`	the shuffle mode

See also:

getTracks

public List<SessionPlayer.TrackInfo> getTracks ()

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.

Returns
`List<SessionPlayer.TrackInfo>`	list of tracks. The total number of tracks is the size of the list. If empty, an empty list would be returned.

See also:

getVideoSize

public VideoSize getVideoSize ()

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

Returns
`VideoSize`	the size of the video. The width and height of size could be 0 if there is no video or the size has not been determined yet.

See also:

MediaController.ControllerCallback.onVideoSizeChanged(MediaController, VideoSize)

isConnected

public boolean isConnected ()

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

Returns
`boolean`

movePlaylistItem

public ListenableFuture<SessionResult> movePlaylistItem (int fromIndex, 
                int toIndex)

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

Returns
`ListenableFuture<SessionResult>`

See also:

MediaController.ControllerCallback.onPlaylistChanged(MediaController, List, MediaMetadata)

pause

public ListenableFuture<SessionResult> pause ()

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.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

play

public ListenableFuture<SessionResult> play ()

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.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

prepare()

prepare

public ListenableFuture<SessionResult> prepare ()

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(String) or setPlaylist(List, MediaMetadata).

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.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

play()

removePlaylistItem

public ListenableFuture<SessionResult> removePlaylistItem (int index)

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

Returns
`ListenableFuture<SessionResult>`

See also:

MediaController.ControllerCallback.onPlaylistChanged(MediaController, List, MediaMetadata)

replacePlaylistItem

public ListenableFuture<SessionResult> replacePlaylistItem (int index, 
                String mediaId)

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

Returns
`ListenableFuture<SessionResult>`

See also:

rewind

public ListenableFuture<SessionResult> rewind ()

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(long) or setPlaybackSpeed(float) directly.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaSession.SessionCallback.onRewind(MediaSession, MediaSession.ControllerInfo)

seekTo

public ListenableFuture<SessionResult> seekTo (long position)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

selectTrack

public ListenableFuture<SessionResult> selectTrack (SessionPlayer.TrackInfo trackInfo)

Requests that the SessionPlayer associated with the connected MediaSession selects the SessionPlayer.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 MediaController.ControllerCallback.onTracksChanged(MediaController, List) is called.

Parameters
`trackInfo`	`SessionPlayer.TrackInfo`: track to be selected

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` which represents the pending completion of the command

See also:

sendCustomCommand

public ListenableFuture<SessionResult> sendCustomCommand (SessionCommand command, 
                Bundle args)

Sends a custom command to the session

Interoperability: When connected to 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

Returns
`ListenableFuture<SessionResult>`

setMediaItem

public ListenableFuture<SessionResult> setMediaItem (String mediaId)

Requests that the SessionPlayer associated with the connected MediaSession sets a MediaItem for playback. Use this, setMediaUri(Uri, Bundle), or setPlaylist(List, MediaMetadata) to specify which items to play. If you want to change current item in the playlist, use one of skipToPlaylistItem(int), 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(Uri, Bundle), or setPlaylist(List, MediaMetadata).

The MediaController.ControllerCallback.onPlaylistChanged(MediaController, List, MediaMetadata) and/or MediaController.ControllerCallback.onCurrentMediaItemChanged(MediaController, MediaItem) 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

Returns
`ListenableFuture<SessionResult>`

See also:

setMediaUri

public ListenableFuture<SessionResult> setMediaUri (Uri uri, 
                Bundle extras)

Requests that the connected MediaSession sets a specific Uri for playback. Use this, setMediaItem(String), or setPlaylist(List, MediaMetadata) 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(String), or setPlaylist(List, MediaMetadata).

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

Parameters
`uri`	`Uri`: the Uri of the item to play
`extras`	`Bundle`

Returns
`ListenableFuture<SessionResult>`

See also:

setPlaybackSpeed

public ListenableFuture<SessionResult> setPlaybackSpeed (float playbackSpeed)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

Throws
`IllegalArgumentException`	if the `speed` is equal to zero.

See also:

setPlaylist

public ListenableFuture<SessionResult> setPlaylist (List<String> list, 
                MediaMetadata metadata)

Requests that the SessionPlayer associated with the connected MediaSession sets the playlist with the list of media IDs. Use this, setMediaUri(Uri, Bundle), or setMediaItem(String) 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(String), or setMediaUri(Uri, Bundle).

Parameters
`list`	`List`: list of media id. Shouldn't contain an empty id
`metadata`	`MediaMetadata`: metadata of the playlist

Returns
`ListenableFuture<SessionResult>`

Throws
`IllegalArgumentException`	if the list is `null` or contains any empty string.

See also:

setRating

public ListenableFuture<SessionResult> setRating (String mediaId, 
                Rating rating)

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

Returns
`ListenableFuture<SessionResult>`

setRepeatMode

public ListenableFuture<SessionResult> setRepeatMode (int repeatMode)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` which represents the pending completion of the command

See also:

setShuffleMode

public ListenableFuture<SessionResult> setShuffleMode (int shuffleMode)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` which represents the pending completion of the command

See also:

setSurface

public ListenableFuture<SessionResult> setSurface (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.

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` which represents the pending completion of the command

setVolumeTo

public ListenableFuture<SessionResult> setVolumeTo (int value, 
                int flags)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

getPlaybackInfo()

skipBackward

public ListenableFuture<SessionResult> skipBackward ()

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(long) directly.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaSession.SessionCallback.onSkipBackward(MediaSession, MediaSession.ControllerInfo)

skipForward

public ListenableFuture<SessionResult> skipForward ()

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(long) directly.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaSession.SessionCallback.onSkipForward(MediaSession, MediaSession.ControllerInfo)

skipToNextPlaylistItem

public ListenableFuture<SessionResult> skipToNextPlaylistItem ()

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.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaController.ControllerCallback.onCurrentMediaItemChanged(MediaController, MediaItem)

skipToPlaylistItem

public ListenableFuture<SessionResult> skipToPlaylistItem (int index)

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

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaController.ControllerCallback.onCurrentMediaItemChanged(MediaController, MediaItem)

skipToPreviousPlaylistItem

public ListenableFuture<SessionResult> skipToPreviousPlaylistItem ()

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.

Returns
`ListenableFuture<SessionResult>`	a `ListenableFuture` representing the pending completion of the command

See also:

MediaController.ControllerCallback.onCurrentMediaItemChanged(MediaController, MediaItem)

updatePlaylistMetadata

public ListenableFuture<SessionResult> updatePlaylistMetadata (MediaMetadata metadata)

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

Returns
`ListenableFuture<SessionResult>`

See also:

MediaController.ControllerCallback.onPlaylistMetadataChanged(MediaController, MediaMetadata)

MediaController

Controller Lifecycle

Controlling the MediaSession in the same process

Summary

Nested classes

Public methods

Inherited methods

Public methods

addPlaylistItem

adjustVolume

close

deselectTrack

fastForward

getAllowedCommands

getBufferedPosition

getBufferingState

getConnectedToken

getCurrentMediaItem

getCurrentMediaItemIndex

getCurrentPosition

getDuration

getNextMediaItemIndex

getPlaybackInfo

getPlaybackSpeed

getPlayerState

getPlaylist

getPlaylistMetadata

getPreviousMediaItemIndex

getRepeatMode

getSelectedTrack

getSessionActivity

getShuffleMode

getTracks

getVideoSize

isConnected

movePlaylistItem

pause

play

prepare

removePlaylistItem

replacePlaylistItem

rewind

seekTo

selectTrack

sendCustomCommand

setMediaItem

setMediaUri

setPlaybackSpeed

setPlaylist

setRating

setRepeatMode

setShuffleMode

setSurface

setVolumeTo

skipBackward

skipForward

skipToNextPlaylistItem

skipToPlaylistItem

skipToPreviousPlaylistItem

updatePlaylistMetadata