MediaLibraryService.MediaLibrarySession.Callback

public interface MediaLibraryService.MediaLibrarySession.Callback extends MediaSession.Callback

An extended MediaSession.Callback for the MediaLibrarySession.

When you return LibraryResult with media items, each item must have valid mediaId and specify isBrowsable and isPlayable in its mediaMetadata.

Summary

Public methods
default ListenableFuture<LibraryResult<ImmutableList<MediaItem>>>
onGetChildren(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String parentId,
    @IntRange(from = 0) int page,
    @IntRange(from = 1) int pageSize,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser requests the child media items of the given parent id by getChildren.
default ListenableFuture<LibraryResult<MediaItem>>
onGetItem(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String mediaId
)

Called when a MediaBrowser requests a MediaItem by getItem.
default ListenableFuture<LibraryResult<MediaItem>>

Called when a MediaBrowser requests the root MediaItem by getLibraryRoot.
default ListenableFuture<LibraryResult<ImmutableList<MediaItem>>>
onGetSearchResult(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String query,
    @IntRange(from = 0) int page,
    @IntRange(from = 1) int pageSize,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser requests a search result with getSearchResult.
default ListenableFuture<LibraryResult<Void>>

Called when a MediaBrowser requests a search with search.
default ListenableFuture<LibraryResult<Void>>

Called when a MediaBrowser subscribes to the given parent id by subscribe.
default ListenableFuture<LibraryResult<Void>>

Called when a MediaBrowser unsubscribes from the given parent ID by unsubscribe.

Inherited methods
From androidx.media3.session.MediaSession.Callback
default ListenableFuture<List<MediaItem>>
onAddMediaItems(
    MediaSession mediaSession,
    MediaSession.ControllerInfo controller,
    List<MediaItem> mediaItems
)

Called when a controller requested to add new media items to the playlist via one of the Player.addMediaItem(s) methods.
default MediaSession.ConnectionResult

Called when a controller is about to connect to this session.
default ListenableFuture<SessionResult>
onCustomCommand(
    MediaSession session,
    MediaSession.ControllerInfo controller,
    SessionCommand customCommand,
    Bundle args
)

Called when a controller sent a custom command through sendCustomCommand.
default void
onDisconnected(
    MediaSession session,
    MediaSession.ControllerInfo controller
)

Called when a controller is disconnected.
default boolean
@UnstableApi
onMediaButtonEvent(
    MediaSession session,
    MediaSession.ControllerInfo controllerInfo,
    Intent intent
)

Called when a media button event has been received by the session.
default ListenableFuture<MediaSession.MediaItemsWithStartPosition>

Returns the playlist with which the player should be prepared when a controller requests to play without a current MediaItem.
default int
@SessionResult.Code
onPlayerCommandRequest(
    MediaSession session,
    MediaSession.ControllerInfo controller,
    @Player.Command int playerCommand
)

This method is deprecated.

Modify the available commands of the player or use setAvailableCommands instead.
default void
@UnstableApi
onPlayerInteractionFinished(
    MediaSession session,
    MediaSession.ControllerInfo controllerInfo,
    Player.Commands playerCommands
)

Called after all concurrent interactions with the session player from a controller have finished.
default void
onPostConnect(
    MediaSession session,
    MediaSession.ControllerInfo controller
)

Called immediately after a controller is connected.
default ListenableFuture<MediaSession.MediaItemsWithStartPosition>
@UnstableApi
onSetMediaItems(
    MediaSession mediaSession,
    MediaSession.ControllerInfo controller,
    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.
default ListenableFuture<SessionResult>
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 setRating.
default ListenableFuture<SessionResult>
onSetRating(
    MediaSession session,
    MediaSession.ControllerInfo controller,
    String mediaId,
    Rating rating
)

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

Public methods

onGetChildren

default ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> onGetChildren(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String parentId,
    @IntRange(from = 0) int page,
    @IntRange(from = 1) int pageSize,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser requests the child media items of the given parent id by getChildren.

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

The params should be the same as the given params.

To allow getting the children, return a LibraryResult with RESULT_SUCCESS and a list of media items. Return an empty list for no children rather than using error codes.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event
MediaSession.ControllerInfo browser

The browser information.
String parentId

The non-empty parent id.
@IntRange(from = 0) int page

The page number to get the paginated result starting from 0.
@IntRange(from = 1) int pageSize

The page size to get the paginated result. Will be greater than 0.
@Nullable MediaLibraryService.LibraryParams params

The optional parameters passed by the browser.
Returns
ListenableFuture<LibraryResult<ImmutableList<MediaItem>>>

A pending result that will be resolved with a list of media items.
See also
COMMAND_CODE_LIBRARY_GET_CHILDREN

onGetItem

default ListenableFuture<LibraryResult<MediaItem>> onGetItem(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String mediaId
)

Called when a MediaBrowser requests a MediaItem by getItem.

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

To allow getting the item, return a LibraryResult with RESULT_SUCCESS and a MediaItem with a valid mediaId.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event.
MediaSession.ControllerInfo browser

The browser information.
String mediaId

The non-empty media id of the requested item.
Returns
ListenableFuture<LibraryResult<MediaItem>>

A pending result that will be resolved with a media item.
See also
COMMAND_CODE_LIBRARY_GET_ITEM

onGetLibraryRoot

default ListenableFuture<LibraryResult<MediaItem>> onGetLibraryRoot(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser requests the root MediaItem by getLibraryRoot.

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

The params may differ from the given params if the session can't provide a root that matches with the params.

To allow browsing the media library, return a LibraryResult with RESULT_SUCCESS and a root MediaItem with a valid mediaId. The media id is required for the browser to get the children under the root.

Interoperability: If this callback is called because a legacy android.support.v4.media.MediaBrowserCompat has requested a androidx.media.MediaBrowserServiceCompat.BrowserRoot, then the main thread may be blocked until the returned future is done. If your service may be queried by a legacy android.support.v4.media.MediaBrowserCompat, you should ensure that the future completes quickly to avoid blocking the main thread for a long period of time.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event.
MediaSession.ControllerInfo browser

The browser information.
@Nullable MediaLibraryService.LibraryParams params

The optional parameters passed by the browser.
Returns
ListenableFuture<LibraryResult<MediaItem>>

A pending result that will be resolved with a root media item.
See also
COMMAND_CODE_LIBRARY_GET_LIBRARY_ROOT

onGetSearchResult

default ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> onGetSearchResult(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String query,
    @IntRange(from = 0) int page,
    @IntRange(from = 1) int pageSize,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser requests a search result with getSearchResult.

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

The params should be the same as the given params.

To allow getting the search result, return a LibraryResult with RESULT_SUCCESS and a list of media items. Return an empty list for no children rather than using error codes.

Typically, the query is requested through onSearch before, but it may not especially when android.support.v4.media.MediaBrowserCompat.search() is used.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event.
MediaSession.ControllerInfo browser

The browser information.
String query

The non-empty search query.
@IntRange(from = 0) int page

The page number to get the paginated result starting from 0.
@IntRange(from = 1) int pageSize

The page size to get the paginated result. Will be greater than 0.
@Nullable MediaLibraryService.LibraryParams params

The optional parameters passed by the browser.
Returns
ListenableFuture<LibraryResult<ImmutableList<MediaItem>>>

A pending result that will be resolved with a list of media items.
See also
COMMAND_CODE_LIBRARY_GET_SEARCH_RESULT

onSearch

default ListenableFuture<LibraryResult<Void>> onSearch(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String query,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser requests a search with search.

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

The params should be the same as the given params.

Return LibraryResult with a result code for the search and notify the number of search result (media items) through notifySearchResultChanged. will ask the search result afterwards through onGetSearchResult.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event.
MediaSession.ControllerInfo browser

The browser information.
String query

The non-empty search query.
@Nullable MediaLibraryService.LibraryParams params

The optional parameters passed by the browser.
Returns
ListenableFuture<LibraryResult<Void>>

A pending result that will be resolved with a result code.
See also
COMMAND_CODE_LIBRARY_SEARCH

onSubscribe

default ListenableFuture<LibraryResult<Void>> onSubscribe(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String parentId,
    @Nullable MediaLibraryService.LibraryParams params
)

Called when a MediaBrowser subscribes to the given parent id by subscribe.

See getSubscribedControllers also.

By default, the library calls onGetItem for the parentId that the browser requests to subscribe to. If onGetItem returns RESULT_SUCCESS with a browsable item, the subscription is accepted and notifyChildrenChanged is immediately called with an itemCount of MAX_VALUE. In all other cases, the subscription is rejected and a result value different to RESULT_SUCCESS is returned from this method.

To implement a different behavior, an app can safely override this method without calling super. Return a result code RESULT_SUCCESS to accept the subscription, or return a result different to RESULT_SUCCESS to prevent controllers from subscribing.

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

The params returned to the caller should be the same as the params passed into this method.

Interoperability: This will be called by android.support.v4.media.MediaBrowserCompat.subscribe(), but won't be called by subscribe.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event.
MediaSession.ControllerInfo browser

The browser information.
String parentId

The non-empty parent id.
@Nullable MediaLibraryService.LibraryParams params

The optional parameters passed by the browser.
Returns
ListenableFuture<LibraryResult<Void>>

A pending result that will be resolved with a result code.
See also
COMMAND_CODE_LIBRARY_SUBSCRIBE

onUnsubscribe

default ListenableFuture<LibraryResult<Void>> onUnsubscribe(
    MediaLibraryService.MediaLibrarySession session,
    MediaSession.ControllerInfo browser,
    String parentId
)

Called when a MediaBrowser unsubscribes from the given parent ID by unsubscribe.

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

Apps normally don't need to implement this method, because the library maintains the subscribed controllers internally and an app can use getSubscribedControllers to get subscribed controllers for which to call notifyChildrenChanged.

Interoperability: This will be called by android.support.v4.media.MediaBrowserCompat.unsubscribe(), but won't be called by unsubscribe.

Parameters
MediaLibraryService.MediaLibrarySession session

The session for this event.
MediaSession.ControllerInfo browser

The browser information.
String parentId

The non-empty parent id.
Returns
ListenableFuture<LibraryResult<Void>>

A pending result that will be resolved with a result code.
See also
COMMAND_CODE_LIBRARY_UNSUBSCRIBE