Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

SessionCallback

abstract class SessionCallback
kotlin.Any
   ↳ androidx.media2.session.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

Callback to be called for all incoming commands from MediaControllers.

Public methods

open Int
onCommandRequest(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo, @NonNull command: SessionCommand)

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

open SessionCommandGroup?
onConnect(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called when a controller is created for this session.

open MediaItem?
onCreateMediaItem(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo, @NonNull mediaId: String)

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

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

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

open Unit
onDisconnected(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called when a controller is disconnected

open Int
onFastForward(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called when a controller called MediaController#fastForward().

open Unit
onPostConnect(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called immediately after a controller is connected.

open Int
onRewind(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called when a controller called MediaController#rewind().

open Int
onSetRating(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo, @NonNull mediaId: String, @NonNull rating: Rating)

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

open Int
onSkipBackward(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called when a controller called MediaController#skipBackward().

open Int
onSkipForward(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo)

Called when a controller called MediaController#skipForward().

Public constructors

<init>

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.

Public methods

onCommandRequest

open fun onCommandRequest(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo, @NonNull command: SessionCommand): Int

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

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 MediaSession: the session for this event
controller MediaSession: controller information.
command MediaSession: a command. This method will be called for every single command.
Return
Int: RESULT_SUCCESS if you want to proceed with incoming command. Another code for ignore.

See Also

onConnect

@Nullable open fun onConnect(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): SessionCommandGroup?

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. sendCustomCommand, setCustomLayout) would be ignored. Override onPostConnect for the custom initialization for the controller instead.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information.
Return
SessionCommandGroup?: allowed commands. Can be null to reject connection.

onCreateMediaItem

@Nullable open fun onCreateMediaItem(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo, @NonNull mediaId: String): MediaItem?

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 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 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 onCommandRequest and commands with the media controller will be executed.

Default implementation returns the null.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information
mediaId MediaSession: non-empty media id for creating item with
Return
MediaItem?: translated media item for player with the mediaId. Can be null to ignore.

onCustomCommand

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

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

Interoperability: This would be also called by . If so, extra from sendCustomAction will be considered as args and customCommand would have null extra.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information
customCommand MediaSession: custom command.
args MediaSession: optional arguments
Return
SessionResult: result of handling custom command. A runtime exception will be thrown if null is returned.

onDisconnected

open fun onDisconnected(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): Unit

Called when a controller is disconnected

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information

onFastForward

open fun onFastForward(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): Int

Called when a controller called MediaController#fastForward().

It's recommended to increase the playback speed when this method is called.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information

onPostConnect

open fun onPostConnect(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): Unit

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
session MediaSession: the session for this event
controller MediaSession: controller information.

onRewind

open fun onRewind(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): Int

Called when a controller called MediaController#rewind().

It's recommended to decrease the playback speed when this method is called.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information

onSetRating

open fun onSetRating(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo, @NonNull mediaId: String, @NonNull rating: Rating): Int

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 MediaSession: the session for this event
controller MediaSession: controller information
mediaId MediaSession: non-empty media id
rating MediaSession: new rating from the controller

onSkipBackward

open fun onSkipBackward(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): Int

Called when a controller called MediaController#skipBackward().

It's recommended to seek backward within the current media item when this method is called.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information

onSkipForward

open fun onSkipForward(@NonNull session: MediaSession, @NonNull controller: MediaSession.ControllerInfo): Int

Called when a controller called MediaController#skipForward().

It's recommended to seek forward within the current media item when this method is called.

Parameters
session MediaSession: the session for this event
controller MediaSession: controller information