Subclasses:

MediaLibraryService.MediaLibrarySession.MediaLibrarySessionCallback

Overview

Callback to be called for all incoming commands from MediaControllers.

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

Summary

Constructors
public	SessionCallback()

Methods
public int	onCommandRequest(MediaSession session, MediaSession.ControllerInfo controller, SessionCommand command) Called when a controller sent a command which will be sent directly to one of the following: SessionPlayer android.media.AudioManager
public SessionCommandGroup	onConnect(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller is created for this session.
public MediaItem	onCreateMediaItem(MediaSession session, MediaSession.ControllerInfo controller, java.lang.String mediaId) Called when a controller has sent a command with a MediaItem to add a new media item to this session.
public SessionResult	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 int	onFastForward(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller called MediaController.fastForward().
public void	onPostConnect(MediaSession session, MediaSession.ControllerInfo controller) Called immediately after a controller is connected.
public int	onRewind(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller called MediaController.rewind().
public int	onSetMediaUri(MediaSession session, MediaSession.ControllerInfo controller, Uri uri, Bundle extras) Called when a controller requested to set the specific media item(s) represented by a URI through MediaController.setMediaUri(Uri, Bundle).
public int	onSetRating(MediaSession session, MediaSession.ControllerInfo controller, java.lang.String mediaId, Rating rating) Called when a controller set rating of a media item through MediaController.setRating(String, Rating).
public int	onSkipBackward(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller called MediaController.skipBackward().
public int	onSkipForward(MediaSession session, MediaSession.ControllerInfo controller) Called when a controller called MediaController.skipForward().
from java.lang.Object	clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructors

Methods

Called when a controller is created for this session. Return allowed commands for controller. By default it allows all connection requests and commands.

You can reject the connection by return null. In that case, the controller receives MediaController.ControllerCallback.onDisconnected(MediaController) and cannot be used.

The controller hasn't connected yet in this method, so calls to the controller (e.g. MediaSession.sendCustomCommand(MediaSession.ControllerInfo, SessionCommand, Bundle), MediaSession.setCustomLayout(MediaSession.ControllerInfo, List)) would be ignored. Override MediaSession.SessionCallback.onPostConnect(MediaSession, MediaSession.ControllerInfo) for the custom initialization for the controller instead.

Parameters:

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

Returns:

allowed commands. Can be null to reject connection.

See also: MediaSession.SessionCallback

Called immediately after a controller is connected. This is a convenient method to add custom initialization between the session and a 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.SessionCallback.onConnect(MediaSession, MediaSession.ControllerInfo) because the controller hasn't connected yet in MediaSession.SessionCallback.onConnect(MediaSession, MediaSession.ControllerInfo).

Parameters:

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

Called when a controller is disconnected.

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

Parameters:

session: the session for this event
controller: controller information

Called when a controller sent a command which will be sent directly to one of the following:

• SessionPlayer
• android.media.AudioManager

Return SessionResult.RESULT_SUCCESS to proceed the command. If something else is returned, command wouldn't be sent and the controller would receive the code with it.

Parameters:

session: the session for this event
controller: controller information.
command: a command. This method will be called for every single command.

Returns:

RESULT_SUCCESS if you want to proceed with incoming command. Another code for ignore.

See also: SessionCommand.COMMAND_CODE_PLAYER_PLAY, SessionCommand.COMMAND_CODE_PLAYER_PAUSE, SessionCommand.COMMAND_CODE_PLAYER_SKIP_TO_NEXT_PLAYLIST_ITEM, SessionCommand.COMMAND_CODE_PLAYER_SKIP_TO_PREVIOUS_PLAYLIST_ITEM, SessionCommand.COMMAND_CODE_PLAYER_PREPARE, SessionCommand.COMMAND_CODE_PLAYER_SEEK_TO, SessionCommand.COMMAND_CODE_PLAYER_SKIP_TO_PLAYLIST_ITEM, SessionCommand.COMMAND_CODE_PLAYER_SET_SHUFFLE_MODE, SessionCommand.COMMAND_CODE_PLAYER_SET_REPEAT_MODE, SessionCommand.COMMAND_CODE_PLAYER_ADD_PLAYLIST_ITEM, SessionCommand.COMMAND_CODE_PLAYER_REMOVE_PLAYLIST_ITEM, SessionCommand.COMMAND_CODE_PLAYER_REPLACE_PLAYLIST_ITEM, SessionCommand.COMMAND_CODE_PLAYER_GET_PLAYLIST, SessionCommand.COMMAND_CODE_PLAYER_SET_PLAYLIST, SessionCommand.COMMAND_CODE_PLAYER_GET_PLAYLIST_METADATA, SessionCommand.COMMAND_CODE_PLAYER_UPDATE_LIST_METADATA, SessionCommand.COMMAND_CODE_VOLUME_SET_VOLUME, SessionCommand.COMMAND_CODE_VOLUME_ADJUST_VOLUME

Called when a controller has sent a command with a MediaItem to add a new media item to this session. Being specific, this will be called for following APIs.

1. MediaController.addPlaylistItem(int, String)
2. MediaController.replacePlaylistItem(int, String)
3. MediaController.setPlaylist(List, MediaMetadata)
4. MediaController.setMediaItem(String)

Override this to translate incoming mediaId to a MediaItem to be understood by your player. For example, a player may only understand FileMediaItem, UriMediaItem, and CallbackMediaItem. Check the documentation of the player that you're using.

If the given media ID is valid, you should return the media item with the given media ID. If the ID doesn't match, an java.lang.RuntimeException will be thrown. You may return null if the given item is invalid. Here's the behavior when it happens.

Controller command	Behavior when null is returned
addPlaylistItem	Ignore
replacePlaylistItem	Ignore
setPlaylist	Ignore null items, and build a list with non-null items. Call SessionPlayer.setPlaylist(List, MediaMetadata) with the list
setMediaItem	Ignore

This will be called on the same thread where MediaSession.SessionCallback.onCommandRequest(MediaSession, MediaSession.ControllerInfo, SessionCommand) and commands with the media controller will be executed.

Default implementation returns the null.

Parameters:

session: the session for this event
controller: controller information
mediaId: non-empty media id for creating item with

Returns:

translated media item for player with the mediaId. Can be null to ignore.

See also: MediaMetadata.METADATA_KEY_MEDIA_ID

Called when a controller set rating of a media item through MediaController.setRating(String, Rating).

To allow setting user rating for a MediaItem, the media item's metadata should have Rating with the key MediaMetadata.METADATA_KEY_USER_RATING, in order to provide possible rating style for controller. Controller will follow the rating style.

Parameters:

session: the session for this event
controller: controller information
mediaId: non-empty media id
rating: new rating from the controller

See also: SessionCommand.COMMAND_CODE_SESSION_SET_RATING

Called when a controller requested to set the specific media item(s) represented by a URI through MediaController.setMediaUri(Uri, Bundle).

The implementation should create proper media item(s) for the given uri and call SessionPlayer.setMediaItem(MediaItem) or SessionPlayer.setPlaylist(List, MediaMetadata).

When android.support.v4.media.session.MediaControllerCompat is connected and sends commands with following methods, the uri would have the following patterns:

Method	Uri pattern
	The uri passed as argument
	androidx://media2-session/prepareFromMediaId?id=[mediaId]
	androidx://media2-session/prepareFromSearch?query=[query]
	The uri passed as argument
	androidx://media2-session/playFromMediaId?id=[mediaId]
	androidx://media2-session/playFromSearch?query=[query]

SessionPlayer.prepare() or SessionPlayer.play() would be followed if this is called by above methods.

Parameters:

session: the session for this event
controller: controller information
uri: uri
extras: optional extra bundle

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

Interoperability: This would be also called by #sendCustomAction(String, Bundle, CustomActionCallback). If so, extra from sendCustomAction will be considered as args and customCommand would have null extra.

Parameters:

session: the session for this event
controller: controller information
customCommand: custom command.
args: optional arguments

Returns:

result of handling custom command. A runtime exception will be thrown if null is returned.

See also: SessionCommand.COMMAND_CODE_CUSTOM

Called when a controller called MediaController.fastForward().

It can be implemented in many ways. For example, it can be implemented by seeking forward once, series of seeking forward, or increasing playback speed.

Parameters:

session: the session for this event
controller: controller information

See also: SessionCommand.COMMAND_CODE_SESSION_FAST_FORWARD

Called when a controller called MediaController.rewind().

It can be implemented in many ways. For example, it can be implemented by seeking backward once, series of seeking backward, or decreasing playback speed.

Parameters:

session: the session for this event
controller: controller information

See also: SessionCommand.COMMAND_CODE_SESSION_REWIND

Called when a controller called MediaController.skipForward().

It's recommended to seek forward within the current media item, but its detail may vary. For example, it can be implemented by seeking forward for the fixed amount of seconds, or seeking forward to the nearest bookmark.

Parameters:

session: the session for this event
controller: controller information

See also: SessionCommand.COMMAND_CODE_SESSION_SKIP_FORWARD

Called when a controller called MediaController.skipBackward().

It's recommended to seek backward within the current media item, but its detail may vary. For example, it can be implemented by seeking backward for the fixed amount of seconds, or seeking backward to the nearest bookmark.

Parameters:

session: the session for this event
controller: controller information

See also: SessionCommand.COMMAND_CODE_SESSION_SKIP_BACKWARD