Subclasses:

MediaLibraryService.MediaLibrarySession.Callback

Overview

A callback to handle incoming commands from MediaController.

The callback methods will be called from the application thread associated with the application looper of the underlying Player.

If it's not set by MediaSession.Builder, the session will accept all controllers and all incoming commands by default.

Summary

Methods
public <any>	onAddMediaItems(MediaSession mediaSession, MediaSession.ControllerInfo controller, java.util.List<MediaItem> mediaItems) Called when a controller requested to add new media items to the playlist via one of the Player.addMediaItem(s) methods.
public MediaSession.ConnectionResult	onConnect(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller is about to connect to this session.
public <any>	onCustomCommand(MediaSession session, MediaSession.ControllerInfo controller, SessionCommand customCommand, Bundle args) Called when a controller sent a custom command through MediaController.sendCustomCommand(SessionCommand, Bundle).
public void	onDisconnected(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller is disconnected.
public boolean	onMediaButtonEvent(MediaSession session, MediaSession.ControllerInfo controllerInfo, Intent intent) Called when a media button event has been received by the session.
public <any>	onPlaybackResumption(MediaSession mediaSession, MediaSession.ControllerInfo controller) Returns the playlist with which the player should be prepared when a controller requests to play without a current MediaItem.
public int	onPlayerCommandRequest(MediaSession session, MediaSession.ControllerInfo controller, int playerCommand)
public void	onPlayerInteractionFinished(MediaSession session, MediaSession.ControllerInfo controllerInfo, Player.Commands playerCommands) Called after all concurrent interactions with the session player from a controller have finished.
public void	onPostConnect(MediaSession session, MediaSession.ControllerInfo controller) Called immediately after a controller is connected.
public <any>	onSetMediaItems(MediaSession mediaSession, MediaSession.ControllerInfo controller, java.util.List<MediaItem> mediaItems, int startIndex, long startPositionMs) Called when a controller requested to set media items to the playlist via one of the Player.setMediaItem(s) methods.
public <any>	onSetRating(MediaSession session, MediaSession.ControllerInfo controller, Rating rating) Called when a controller requested to set a rating for the current media item for the current user by MediaController.setRating(Rating).
public <any>	onSetRating(MediaSession session, MediaSession.ControllerInfo controller, java.lang.String mediaId, Rating rating) Called when a controller requested to set a rating to a media for the current user by MediaController.setRating(String, Rating).

Methods

Called when a controller is about to connect to this session. Return a result for the controller by using MediaSession.ConnectionResult.accept(SessionCommands, Player.Commands) or the MediaSession.ConnectionResult.AcceptedResultBuilder.

If this callback is not overridden, it allows all controllers to connect that can access the session. All session and player commands are made available and the custom layout of the session is included.

Note that the player commands in MediaSession.ConnectionResult.availablePlayerCommands will be intersected with the available commands of the underlying Player and the controller will only be able to call the commonly available commands.

Returning MediaSession.ConnectionResult.reject() rejects the connection. In that case, the controller will get java.lang.SecurityException when resolving the returned by MediaController.Builder.buildAsync().

The controller isn't connected yet, so calls to the controller (e.g. MediaSession.sendCustomCommand(MediaSession.ControllerInfo, SessionCommand, Bundle), MediaSession.setCustomLayout(MediaSession.ControllerInfo, List)) will be ignored. Use MediaSession.Callback.onPostConnect(MediaSession, MediaSession.ControllerInfo) for custom initialization of the controller instead.

Interoperability: If a legacy controller is connecting to the session then this callback may block the main thread, even if it's called on a different application thread. If it's possible that legacy controllers will connect to the session, you should ensure that the callback returns quickly to avoid blocking the main thread for a long period of time.

Parameters:

session: The session for this event.
controller: The controller information.

Returns:

The MediaSession.ConnectionResult.

Called immediately after a controller is connected. This is for custom initialization of the controller.

Note that calls to the controller (e.g. MediaSession.sendCustomCommand(MediaSession.ControllerInfo, SessionCommand, Bundle), MediaSession.setCustomLayout(MediaSession.ControllerInfo, List)) work here but don't work in MediaSession.Callback.onConnect(MediaSession, MediaSession.ControllerInfo) because the controller isn't connected yet in MediaSession.Callback.onConnect(MediaSession, MediaSession.ControllerInfo).

Parameters:

session: The session for this event.
controller: The controller information.

Called when a controller is disconnected.

Interoperability: For legacy controllers, this is called when the controller doesn't send any command for a while. It's because there were no explicit disconnection in legacy controller APIs.

Parameters:

session: The session for this event.
controller: The controller information.

Deprecated: Modify the available commands of the player or use MediaSession.setAvailableCommands(MediaSession.ControllerInfo, SessionCommands, Player.Commands) instead. The controller triggering a Player method can be obtained via MediaSession.getControllerForCurrentRequest().

Called when a controller requested to set a rating to a media for the current user by MediaController.setRating(String, Rating).

To allow setting the user rating for a MediaItem, the item's metadata should have the Rating field in order to provide possible rating style for controllers. Controllers will follow the rating style.

Return a to send a SessionResult back to the controller asynchronously. You can also return a SessionResult directly by using Guava's .

Parameters:

session: The session for this event.
controller: The controller information.
mediaId: The media id.
rating: The new rating from the controller.

See also: SessionCommand.COMMAND_CODE_SESSION_SET_RATING

Called when a controller requested to set a rating for the current media item for the current user by MediaController.setRating(Rating).

To allow setting the user rating for the current MediaItem, the item's metadata should have the Rating field in order to provide possible rating style for controllers. Controllers will follow the rating style.

Return a to send a SessionResult back to the controller asynchronously. You can also return a SessionResult directly by using Guava's .

Parameters:

session: The session for this event.
controller: The controller information.
rating: The new rating from the controller.

See also: SessionCommand.COMMAND_CODE_SESSION_SET_RATING

Called when a controller sent a custom command through MediaController.sendCustomCommand(SessionCommand, Bundle).

MediaController instances are only allowed to send a command if the command has been added to the list of available session commands in MediaSession.Callback.onConnect(MediaSession, MediaSession.ControllerInfo) or set via MediaSession.setAvailableCommands(MediaSession.ControllerInfo, SessionCommands, Player.Commands).

Interoperability: This will be also called by android.support.v4.media.MediaBrowserCompat.sendCustomAction(). If so, extras from android.support.v4.media.MediaBrowserCompat.sendCustomAction() will be considered as args and the custom command will have null SessionCommand.customExtras.

Return a to send a SessionResult back to the controller asynchronously. You can also return a SessionResult directly by using Guava's .

Parameters:

session: The session for this event.
controller: The controller information.
customCommand: The custom command.
args: A for additional arguments. May be empty.

Returns:

The result of handling the custom command.

See also: SessionCommand.COMMAND_CODE_CUSTOM

Called when a controller requested to add new media items to the playlist via one of the Player.addMediaItem(s) methods. Unless overridden, MediaSession.Callback.onSetMediaItems(MediaSession, MediaSession.ControllerInfo, List, int, long) will direct Player.setMediaItem(s) to this method as well.

In addition, unless MediaSession.Callback.onSetMediaItems(MediaSession, MediaSession.ControllerInfo, List, int, long) is overridden, this callback is also called when an app is using a legacy android.support.v4.media.session.MediaControllerCompat.TransportControls to prepare or play media (for instance when browsing the catalogue and then selecting an item for preparation from Android Auto that is using the legacy Media1 library).

By default, if and only if each of the provided media items has a set (for example, a URI), then the callback returns the list unaltered. Otherwise, the default implementation returns an java.lang.UnsupportedOperationException.

If the requested media items don't have a , they need to be updated to make them playable by the underlying Player. Typically, this callback would be overridden with implementation that identifies the correct item by its MediaItem.mediaId and/or the MediaItem.requestMetadata.

Return a with the resolved media items. You can also return the items directly by using Guava's . Once the media items have been resolved, the session will call Player.setMediaItems(List) or Player.addMediaItems(List) as requested.

Interoperability: This method will be called, unless MediaSession.Callback.onSetMediaItems(MediaSession, MediaSession.ControllerInfo, List, int, long) is overridden, in response to the following android.support.v4.media.session.MediaControllerCompat methods:

• prepareFromUri
• playFromUri
• prepareFromMediaId
• playFromMediaId
• prepareFromSearch
• playFromSearch
• addQueueItem

The values of MediaItem.mediaId, , and will be set to match the legacy method call. The session will call Player.setMediaItems(List) or Player.addMediaItems(List), followed by Player.prepare() and Player.play() as appropriate once the MediaItem has been resolved.

Parameters:

mediaSession: The session for this event.
controller: The controller information.
mediaItems: The list of requested media items.

Returns:

A for the list of resolved media items that are playable by the underlying Player.

Called when a controller requested to set media items to the playlist via one of the Player.setMediaItem(s) methods. The default implementation calls MediaSession.Callback.onAddMediaItems(MediaSession, MediaSession.ControllerInfo, List). Override this method if you want to modify/set the starting index/position for the Player.setMediaItem(s) methods.

This callback is also called when an app is using a legacy to prepare or play media (for instance when browsing the catalogue and then selecting an item for preparation from Android Auto that is using the legacy Media1 library).

By default, if and only if each of the provided media items has a set (for example, a URI), then the callback returns the list unaltered. Otherwise, the default implementation returns an java.lang.UnsupportedOperationException.

If the requested media items don't have a , they need to be updated to make them playable by the underlying Player. Typically, this callback would be overridden with implementation that identifies the correct item by its MediaItem.mediaId and/or the MediaItem.requestMetadata.

Return a with the resolved media items and starting index and position. You can also return the items directly by using Guava's . Once the MediaSession.MediaItemsWithStartPosition has been resolved, the session will call Player.setMediaItems(List) as requested. If the resolved startIndex is C.INDEX_UNSET then the session will call Player.setMediaItem(MediaItem, boolean) with resetPosition set to true.

Interoperability: This method will be called in response to the following MediaControllerCompat methods:

• addQueueItem

The values of MediaItem.mediaId, , and will be set to match the legacy method call. The session will call Player.setMediaItems(List) or Player.addMediaItems(List), followed by Player.prepare() and Player.play() as appropriate once the MediaItem has been resolved.

Parameters:

mediaSession: The session for this event.
controller: The controller information.
mediaItems: The list of requested media items.
startIndex: The start index in the MediaItem list from which to start playing, or C.INDEX_UNSET to start playing from the default index in the playlist.
startPositionMs: The starting position in the media item from where to start playing, or C.TIME_UNSET to start playing from the default position in the media item. This value is ignored if startIndex is C.INDEX_UNSET

Returns:

A with a MediaSession.MediaItemsWithStartPosition containing a list of resolved media items, and a starting index and position that are playable by the underlying Player. If returned MediaSession.MediaItemsWithStartPosition.startIndex is C.INDEX_UNSET and MediaSession.MediaItemsWithStartPosition.startPositionMs is C.TIME_UNSET, then Player#setMediaItems(List, true) will be called to set media items with default index and position.

Returns the playlist with which the player should be prepared when a controller requests to play without a current MediaItem.

This happens, for example, if playback resumption is requested from a media button receiver or the System UI notification.

The method will only be called if the Player has Player.COMMAND_GET_CURRENT_MEDIA_ITEM and either Player.COMMAND_SET_MEDIA_ITEM or Player.COMMAND_CHANGE_MEDIA_ITEMS available.

Parameters:

mediaSession: The media session for which playback resumption is requested.
controller: The controller that requests the playback resumption. This may be a short living controller created only for issuing a play command for resuming playback.

Returns:

The playlist to resume playback with.

Called when a media button event has been received by the session.

Media3 handles media button events internally. An app can override the default behaviour by overriding this method.

Return true to stop propagating the event any further. When false is returned, Media3 handles the event and calls the session player accordingly.

Apps normally don't need to override this method. When overriding this method, an app can/needs to handle all API-level specifics on its own. The intent passed to this method can come directly from the system that routed a media key event (for instance sent by Bluetooth) to your session.

Parameters:

session: The session that received the media button event.
controllerInfo: The controller to which the media button event is attributed to.
intent: The media button intent.

Returns:

True if the event was handled, false otherwise.

Called after all concurrent interactions with the session player from a controller have finished.

A controller may call multiple Player methods within a single message. Those Player method calls are batched together and once finished, this callback is called to signal that no further Player interactions coming from this controller are expected for now.

Apps can use this callback if they need to trigger different logic depending on whether certain methods are called together, for example just Player.setMediaItems(List), or Player.setMediaItems(List) and Player.play() together.

Parameters:

session: The MediaSession that received the Player calls.
controllerInfo: The controller sending the calls.
playerCommands: The set of used to send these calls.