MediaController
public
class
MediaController
extends Object
implements
Closeable
java.lang.Object | |
↳ | androidx.media2.session.MediaController |
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
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 theMediaSession
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 |
class |
MediaController.ControllerCallback
Interface for listening to change in activeness of the |
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 |
ListenableFuture<SessionResult>
|
adjustVolume(int direction, int flags)
Requests that the connected |
void
|
close()
Releases this object, and disconnects from the session. |
ListenableFuture<SessionResult>
|
deselectTrack(SessionPlayer.TrackInfo trackInfo)
Requests that the |
ListenableFuture<SessionResult>
|
fastForward()
Requests that the |
SessionCommandGroup
|
getAllowedCommands()
Gets the cached allowed commands from |
long
|
getBufferedPosition()
Gets the position for how much has been buffered of the |
int
|
getBufferingState()
Gets the current buffering state of the |
SessionToken
|
getConnectedToken()
Returns the |
MediaItem
|
getCurrentMediaItem()
Gets the current media item of the |
int
|
getCurrentMediaItemIndex()
Gets the current item index in the playlist of the |
long
|
getCurrentPosition()
Gets the playback position of the |
long
|
getDuration()
Gets the duration of the current media item, or |
int
|
getNextMediaItemIndex()
Gets the next item index in the playlist of the |
MediaController.PlaybackInfo
|
getPlaybackInfo()
Get the current playback info for this session. |
float
|
getPlaybackSpeed()
Gets the playback speed to be used by the of the |
int
|
getPlayerState()
Gets the state of the |
List<MediaItem>
|
getPlaylist()
Gets the playlist of the |
MediaMetadata
|
getPlaylistMetadata()
Gets the playlist metadata of the |
int
|
getPreviousMediaItemIndex()
Gets the previous item index in the playlist of the |
int
|
getRepeatMode()
Gets the repeat mode of the |
SessionPlayer.TrackInfo
|
getSelectedTrack(int trackType)
Gets the currently selected track for the given track type of the |
PendingIntent
|
getSessionActivity()
Gets an intent for launching UI associated with this session if one exists. |
int
|
getShuffleMode()
Gets the shuffle mode of the |
List<SessionPlayer.TrackInfo>
|
getTracks()
Gets the full list of selected and unselected tracks that the media contains of the
|
VideoSize
|
getVideoSize()
Gets the video size of the |
boolean
|
isConnected()
Returns whether this class is connected to active |
ListenableFuture<SessionResult>
|
movePlaylistItem(int fromIndex, int toIndex)
Requests that the |
ListenableFuture<SessionResult>
|
pause()
Requests that the |
ListenableFuture<SessionResult>
|
play()
Requests that the |
ListenableFuture<SessionResult>
|
prepare()
Requests that the |
ListenableFuture<SessionResult>
|
removePlaylistItem(int index)
Requests that the |
ListenableFuture<SessionResult>
|
replacePlaylistItem(int index, String mediaId)
Requests that the |
ListenableFuture<SessionResult>
|
rewind()
Requests that the |
ListenableFuture<SessionResult>
|
seekTo(long position)
Requests that the |
ListenableFuture<SessionResult>
|
selectTrack(SessionPlayer.TrackInfo trackInfo)
Requests that the |
ListenableFuture<SessionResult>
|
sendCustomCommand(SessionCommand command, Bundle args)
Sends a custom command to the session
Interoperability: When connected to
|
ListenableFuture<SessionResult>
|
setMediaItem(String mediaId)
Requests that the |
ListenableFuture<SessionResult>
|
setMediaUri(Uri uri, Bundle extras)
Requests that the connected |
ListenableFuture<SessionResult>
|
setPlaybackSpeed(float playbackSpeed)
Requests that the |
ListenableFuture<SessionResult>
|
setPlaylist(List<String> list, MediaMetadata metadata)
Requests that the |
ListenableFuture<SessionResult>
|
setRating(String mediaId, Rating rating)
Requests that the connected |
ListenableFuture<SessionResult>
|
setRepeatMode(int repeatMode)
Requests that the |
ListenableFuture<SessionResult>
|
setShuffleMode(int shuffleMode)
Requests that the |
ListenableFuture<SessionResult>
|
setSurface(Surface surface)
Requests that the |
ListenableFuture<SessionResult>
|
setVolumeTo(int value, int flags)
Requests that the connected |
ListenableFuture<SessionResult>
|
skipBackward()
Requests that the |
ListenableFuture<SessionResult>
|
skipForward()
Requests that the |
ListenableFuture<SessionResult>
|
skipToNextPlaylistItem()
Requests that the |
ListenableFuture<SessionResult>
|
skipToPlaylistItem(int index)
Requests that the |
ListenableFuture<SessionResult>
|
skipToPreviousPlaylistItem()
Requests that the |
ListenableFuture<SessionResult>
|
updatePlaylistMetadata(MediaMetadata metadata)
Requests that the |
Inherited methods | |
---|---|
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> |
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:
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 |
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 |
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. |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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. |
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> |
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
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
.
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:
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> |
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> |
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 |
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 |
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
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
.
The MediaController.ControllerCallback.onPlaylistChanged(MediaController, List
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> |
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
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
.
The MediaController.ControllerCallback.onPlaylistChanged(MediaController, List
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 | |
---|---|
uri |
Uri : the Uri of the item to play |
extras |
Bundle |
Returns | |
---|---|
ListenableFuture<SessionResult> |
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.
|
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)
.
The MediaController.ControllerCallback.onPlaylistChanged(MediaController, List
and/or
MediaController.ControllerCallback.onCurrentMediaItemChanged(MediaController, MediaItem)
would be called when it's completed.
The current item would be the first item in the playlist.
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.
|
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 |
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 |
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:
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 |
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 |
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 |
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 |
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 |
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> |
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-30 UTC.