MediaSession.SessionCallback

Added in 1.0.0
Deprecated in 1.3.0

public abstract class MediaSession.SessionCallback


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

Public constructors

Public methods

int
onCommandRequest(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull SessionCommand command
)

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

@Nullable SessionCommandGroup
onConnect(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller is created for this session.

@Nullable MediaItem
onCreateMediaItem(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull String mediaId
)

Called when a controller has sent a command with a MediaItem to add a new media item to this session.

@NonNull SessionResult
onCustomCommand(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull SessionCommand customCommand,
    @Nullable Bundle args
)

Called when a controller sent a custom command through sendCustomCommand.

void

Called when a controller is disconnected.

int
onFastForward(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called fastForward.

void
onPostConnect(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called immediately after a controller is connected.

int
onRewind(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called rewind.

int
onSetMediaUri(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull Uri uri,
    @Nullable Bundle extras
)

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

int
onSetRating(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull String mediaId,
    @NonNull Rating rating
)

Called when a controller set rating of a media item through setRating.

int

Called when a controller called skipBackward.

int
onSkipForward(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called skipForward.

Public constructors

SessionCallback

Added in 1.0.0
Deprecated in 1.3.0
public SessionCallback()

Public methods

onCommandRequest

Added in 1.0.0
Deprecated in 1.3.0
public int onCommandRequest(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull SessionCommand command
)

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

Return 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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information.

@NonNull SessionCommand command

a command. This method will be called for every single command.

Returns
int

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

onConnect

Added in 1.0.0
Deprecated in 1.3.0
public @Nullable SessionCommandGroup onConnect(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

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 onDisconnected and cannot be used.

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

Parameters
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information.

Returns
@Nullable SessionCommandGroup

allowed commands. Can be null to reject connection.

See also
onPostConnect

onCreateMediaItem

Added in 1.0.0
Deprecated in 1.3.0
public @Nullable MediaItem onCreateMediaItem(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull String mediaId
)

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. addPlaylistItem
  2. replacePlaylistItem
  3. setPlaylist
  4. setMediaItem
Override this to translate incoming mediaId to a MediaItem to be understood by your player. For example, a player may only understand androidx.media2.common.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 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 is returned
addPlaylistItem Ignore
replacePlaylistItem Ignore
setPlaylist Ignore null items, and build a list with non-null items. Call setPlaylist with the list
setMediaItem Ignore

This will be called on the same thread where onCommandRequest and commands with the media controller will be executed.

Default implementation returns the null.

Parameters
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

@NonNull String mediaId

non-empty media id for creating item with

Returns
@Nullable MediaItem

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

onCustomCommand

Added in 1.0.0
Deprecated in 1.3.0
public @NonNull SessionResult onCustomCommand(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull SessionCommand customCommand,
    @Nullable Bundle args
)

Called when a controller sent a custom command through sendCustomCommand.

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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

@NonNull SessionCommand customCommand

custom command.

@Nullable Bundle args

optional arguments

Returns
@NonNull SessionResult

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

onDisconnected

Added in 1.0.0
Deprecated in 1.3.0
public void onDisconnected(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

onFastForward

Added in 1.0.0
Deprecated in 1.3.0
public int onFastForward(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called 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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

onPostConnect

Added in 1.0.0
Deprecated in 1.3.0
public void onPostConnect(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

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. sendCustomCommand, setCustomLayout) work here but don't work in onConnect because the controller hasn't connected yet in onConnect.

Parameters
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information.

onRewind

Added in 1.0.0
Deprecated in 1.3.0
public int onRewind(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called 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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

onSetMediaUri

Added in 1.1.0
Deprecated in 1.3.0
public int onSetMediaUri(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull Uri uri,
    @Nullable Bundle extras
)

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

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

When MediaControllerCompat is connected and sends commands with following methods, the uri would have the following patterns:

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

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

Parameters
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

@NonNull Uri uri

uri

@Nullable Bundle extras

optional extra bundle

onSetRating

Added in 1.0.0
Deprecated in 1.3.0
public int onSetRating(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller,
    @NonNull String mediaId,
    @NonNull Rating rating
)

Called when a controller set rating of a media item through setRating.

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

Parameters
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

@NonNull String mediaId

non-empty media id

@NonNull Rating rating

new rating from the controller

onSkipBackward

Added in 1.0.0
Deprecated in 1.3.0
public int onSkipBackward(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called 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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information

onSkipForward

Added in 1.0.0
Deprecated in 1.3.0
public int onSkipForward(
    @NonNull MediaSession session,
    @NonNull MediaSession.ControllerInfo controller
)

Called when a controller called 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
@NonNull MediaSession session

the session for this event

@NonNull MediaSession.ControllerInfo controller

controller information