MediaSession.Callback

fun onAddMediaItems(
    mediaSession: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    mediaItems: (Mutable)List<MediaItem!>!
): ListenableFuture<(Mutable)List<MediaItem!>!>!

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

In addition, unless onSetMediaItems 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 MediaItem.LocalConfiguration (for example, a URI), then the callback returns the list unaltered. Otherwise, the default implementation returns an UnsupportedOperationException.

If the requested media items don't have a MediaItem.LocalConfiguration, 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 mediaId and/or the requestMetadata.

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

Interoperability: This method will be called, unless onSetMediaItems is overridden, in response to the following android.support.v4.media.session.MediaControllerCompat methods:

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

fun onConnect(session: MediaSession!, controller: MediaSession.ControllerInfo!): MediaSession.ConnectionResult!

Called when a controller is about to connect to this session. Return a result for the controller by using accept or the 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 media button preferences of the session are included.

Note that the player commands in 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 reject rejects the connection. In that case, the controller will get SecurityException when resolving the ListenableFuture returned by buildAsync.

The controller isn't connected yet, so calls to the controller (e.g. sendCustomCommand, setMediaButtonPreferences) will be ignored. Use onPostConnect for custom initialization of the controller instead.

Interoperability: If a platform or 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 platform or 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.

fun onCustomCommand(
    session: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    customCommand: SessionCommand!,
    args: Bundle!
): ListenableFuture<SessionResult!>!

Called when a controller sent a custom command through sendCustomCommand.

Note: By default onCustomCommand delegates all calls to this method and drops the option to send progress updates. If you want to implement progress updates you should override onCustomCommand instead to get access to the ProgressReporter in case a controller requests progress updates.

MediaController instances are only allowed to send a command if the command has been added to the list of available session commands in onConnect or set via setAvailableCommands.

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 nullcustomExtras.

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

@UnstableApi
fun onCustomCommand(
    session: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    customCommand: SessionCommand!,
    args: Bundle!,
    progressReporter: MediaSession.ProgressReporter?
): ListenableFuture<SessionResult!>!

Called when a controller sent a custom command through sendCustomCommand.

By default this callback delegates to onCustomCommand. If this method is overridden, the callback onCustomCommand is never called.

If a non-null ProgressReporter is passed in, then the session can report progress updates to the controller. It's the decision of the session whether or not to send progress updates. In any case, the transaction ends by completing the ListenableFuture returned by this method.

MediaController instances are only allowed to send a command if the command has been added to the list of available session commands in onConnect or set via setAvailableCommands.

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 nullcustomExtras.

Return a ListenableFuture to send a SessionResult back to the controller asynchronously. You can also return a SessionResult directly by using Guava's immediateFuture. Progress updates are dispatched only until the future has completed.

fun onDisconnected(
    session: MediaSession!,
    controller: MediaSession.ControllerInfo!
): Unit

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.

@UnstableApi
fun onMediaButtonEvent(
    session: MediaSession!,
    controllerInfo: MediaSession.ControllerInfo!,
    intent: Intent!
): Boolean

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.

@UnstableApi
fun onPlaybackResumption(
    mediaSession: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    isForPlayback: Boolean
): ListenableFuture<MediaSession.MediaItemsWithStartPosition!>!

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.

If isForPlayback is false, the controller only requests metadata about the item that will be played once playback resumption is requested without an immediate intention to start playback. For example, this may happen immediately after reboot of the device for System UI to populate its playback resumption notification. In these cases, only one MediaItem is needed and it's useful to provide additional metadata to allow System UI to generate the notification:

• Use artworkData or artworkUri with a content URI to set locally available artwork data for the playback resumption notification. Note that network access may not be available when this method is called during boot time.
• Use EXTRAS_KEY_COMPLETION_STATUS and EXTRAS_KEY_COMPLETION_PERCENTAGE to statically indicate the completion status.

If isForPlayback is true, return the initial playlist for the Player and the intended start position. setMediaItem, setMediaItems, prepare and play will be called automatically as required. Any additional initial setup like setting playback speed, repeat mode or shuffle mode can be done from within this callback.

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

@UnstableApi
fun onPlayerInteractionFinished(
    session: MediaSession!,
    controllerInfo: MediaSession.ControllerInfo!,
    playerCommands: Player.Commands!
): Unit

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

A controller may call multiple Player methods within a single Looper 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 setMediaItems, or setMediaItems and play together.

fun onPostConnect(
    session: MediaSession!,
    controller: MediaSession.ControllerInfo!
): Unit

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

Note that calls to the controller (e.g. sendCustomCommand, setMediaButtonPreferences) work here but don't work in onConnect because the controller isn't connected yet in onConnect.

@UnstableApi
fun onSetMediaItems(
    mediaSession: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    mediaItems: (Mutable)List<MediaItem!>!,
    startIndex: Int,
    startPositionMs: Long
): ListenableFuture<MediaSession.MediaItemsWithStartPosition!>!

Called when a controller requested to set media items to the playlist via one of the Player.setMediaItem(s) methods. The default implementation calls onAddMediaItems. 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 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 MediaItem.LocalConfiguration (for example, a URI), then the callback returns the list unaltered. Otherwise, the default implementation returns an UnsupportedOperationException.

If the requested media items don't have a MediaItem.LocalConfiguration, 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 mediaId and/or the requestMetadata.

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

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

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

fun onSetRating(
    session: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    rating: Rating!
): ListenableFuture<SessionResult!>!

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

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 ListenableFuture to send a SessionResult back to the controller asynchronously. You can also return a SessionResult directly by using Guava's immediateFuture.

fun onSetRating(
    session: MediaSession!,
    controller: MediaSession.ControllerInfo!,
    mediaId: String!,
    rating: Rating!
): ListenableFuture<SessionResult!>!

Called when a controller requested to set a rating to a media for the current user by setRating.

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 ListenableFuture to send a SessionResult back to the controller asynchronously. You can also return a SessionResult directly by using Guava's immediateFuture.