MediaLibraryService.MediaLibrarySession

class MediaLibraryService.MediaLibrarySession : MediaSession

kotlin.Any
   ↳ androidx.media3.session.MediaSession
     ↳ androidx.media3.session.MediaLibraryService.MediaLibrarySession

An extended MediaSession for the MediaLibraryService. Build an instance with Builder and return it from onGetSession.

Backward compatibility with legacy media browser APIs

A library session supports connection from both MediaBrowser and android.support.v4.media.MediaBrowserCompat, but the ControllerInfo may not be precise. Here are the details.

Summary when controller info isn't precise
SDK version for legacy browser for legacy browser
SDK_INT < 28 for onConnect and onGetLibraryRoot Actual package name via getPackageName Actual UID
SDK_INT < 28 for other callbacks LEGACY_CONTROLLER_PACKAGE_NAME Negative value
28 <= SDK_INT Actual package name via getPackageName Actual UID

Summary

Nested types

A builder for MediaLibrarySession.

An extended MediaSession.Callback for the MediaLibrarySession.

Constants
const Int

Session errors returned by the MediaLibrarySession.Callback as part of a LibraryResult are replicated to the platform session as a fatal error.
const Int

No library service errors are replicated.
const Int

Session errors returned by the MediaLibrarySession.Callback as part of a LibraryResult are replicated to the platform session as a non-fatal error.

Public functions
Unit

Clears the replicated library error in the platform session that was set when a with an error result code was returned by the that is replicated and if legacy session error replication is not turned off.
ImmutableList<MediaSession.ControllerInfo!>!

Returns the controllers that are currently subscribed to the given mediaId.
Unit
notifyChildrenChanged(
    parentId: String!,
    itemCount: @IntRange(from = 0) Int,
    params: MediaLibraryService.LibraryParams?
)

Notifies all browsers that are subscribing to the parent of the change to its children regardless of the params given by onSubscribe.
Unit
notifyChildrenChanged(
    browser: MediaSession.ControllerInfo!,
    parentId: String!,
    itemCount: @IntRange(from = 0) Int,
    params: MediaLibraryService.LibraryParams?
)

Notifies a browser that is subscribed to a browsable media item that the children of the item have changed.
Unit
notifySearchResultChanged(
    browser: MediaSession.ControllerInfo!,
    query: String!,
    itemCount: @IntRange(from = 0) Int,
    params: MediaLibraryService.LibraryParams?
)

Notifies a browser of a change to the search result.

Inherited functions
From androidx.media3.session.MediaSession
Unit

Broadcasts a custom command to all connected controllers.
BitmapLoader!

Returns the BitmapLoader.
(Mutable)List<MediaSession.ControllerInfo!>!

Returns the list of connected controllers.
MediaSession.ControllerInfo?

Returns the ControllerInfo for the controller that sent the current request for a Player method.
ImmutableList<CommandButton!>!

Returns the custom layout of the session.
String!

Returns the session ID.
ImmutableList<CommandButton!>!

Returns the media button preferences of the session.
MediaSession.ControllerInfo?

Returns the ControllerInfo of the media notification controller.
MediaSession.Token!

Returns the platform android.media.session.MediaSession.Token of the created internally by this session.
Player!

Returns the underlying Player.
PendingIntent?

Returns the PendingIntent to launch the session activity or null if not set.
MediaSessionCompat.Token!

This function is deprecated.

Use getPlatformToken instead.
Bundle!

Returns the session extras.
Boolean

Returns whether a play button is shown if playback is suppressed.
SessionToken!

Returns the SessionToken for creating MediaController instances.
Boolean

Returns whether the given ControllerInfo belongs to an Android Auto companion app controller.
Boolean

Returns whether the given ControllerInfo belongs to an Automotive OS controller.
Boolean

Returns whether the given media controller info belongs to the media notification controller.
Unit

Releases the session and disconnects all connected controllers.
ListenableFuture<SessionResult!>!
sendCustomCommand(
    controller: MediaSession.ControllerInfo!,
    command: SessionCommand!,
    args: Bundle!
)

Sends a custom command to a specific controller.
Unit

Sends a non-fatal error to all connected controllers.
Unit
@UnstableApi
sendError(
    controllerInfo: MediaSession.ControllerInfo!,
    sessionError: SessionError!
)

Sends a non-fatal error to the given controller.
Unit
setAvailableCommands(
    controller: MediaSession.ControllerInfo!,
    sessionCommands: SessionCommands!,
    playerCommands: Player.Commands!
)

Sets the new available commands for the controller.
Unit

Sets the custom layout for all controllers.
ListenableFuture<SessionResult!>!

Sets the custom layout for the given controller.
Unit
@UnstableApi
setMediaButtonPreferences(
    mediaButtonPreferences: (Mutable)List<CommandButton!>!
)

Sets the media button preferences for all controllers.
ListenableFuture<SessionResult!>!

Sets the media button preferences for the given controller.
Unit
setPlayer(player: Player!)

Sets the underlying Player for this session to dispatch incoming events to.
Unit
@UnstableApi
setSessionActivity(activityPendingIntent: PendingIntent!)

Updates the session activity that was set when building the session.
Unit
@UnstableApi
setSessionActivity(
    controller: MediaSession.ControllerInfo!,
    activityPendingIntent: PendingIntent!
)

Sends the session activity to the connected controller.
Unit
setSessionExtras(sessionExtras: Bundle!)

Sets the session extras and sends them to connected controllers.
Unit
setSessionExtras(
    controller: MediaSession.ControllerInfo!,
    sessionExtras: Bundle!
)

Sends the session extras to the connected controller.

Constants

LIBRARY_ERROR_REPLICATION_MODE_FATAL

@UnstableApi
const val LIBRARY_ERROR_REPLICATION_MODE_FATAL = 1: Int

Session errors returned by the MediaLibrarySession.Callback as part of a LibraryResult are replicated to the platform session as a fatal error.

LIBRARY_ERROR_REPLICATION_MODE_NONE

@UnstableApi
const val LIBRARY_ERROR_REPLICATION_MODE_NONE = 0: Int

No library service errors are replicated.

LIBRARY_ERROR_REPLICATION_MODE_NON_FATAL

@UnstableApi
const val LIBRARY_ERROR_REPLICATION_MODE_NON_FATAL = 2: Int

Session errors returned by the MediaLibrarySession.Callback as part of a LibraryResult are replicated to the platform session as a non-fatal error.

Public functions

clearReplicatedLibraryError

@UnstableApi
fun clearReplicatedLibraryError(): Unit

Clears the replicated library error in the platform session that was set when a with an error result code was returned by the that is replicated and if legacy session error replication is not turned off.

Note: If a RESULT_SUCCESS was returned by a method of that is considered for replication, the error is cleared automatically by the library.

Calling this method updates the platform session playback state in case there was a replicated error set. If no error was set, calling this method is a no-op.

getSubscribedControllers

@UnstableApi
fun getSubscribedControllers(mediaId: String!): ImmutableList<MediaSession.ControllerInfo!>!

Returns the controllers that are currently subscribed to the given mediaId.

Use the returned controller infos to call notifyChildrenChanged in case the children of the media item with the given media ID have changed and the connected controller should fetch them again.

Note that calling notifyChildrenChanged for a controller that didn't subscribe to the media ID results in a no-op.

Parameters
mediaId: String!

The ID of the media item for which to get subscribed controllers.
Returns
ImmutableList<MediaSession.ControllerInfo!>!

A list with the subscribed controllers, may be empty.

notifyChildrenChanged

fun notifyChildrenChanged(
    parentId: String!,
    itemCount: @IntRange(from = 0) Int,
    params: MediaLibraryService.LibraryParams?
): Unit

Notifies all browsers that are subscribing to the parent of the change to its children regardless of the params given by onSubscribe.

Parameters
parentId: String!

The non-empty id of the parent with changes to its children.
itemCount: @IntRange(from = 0) Int

The number of children.
params: MediaLibraryService.LibraryParams?

The optional parameters.

notifyChildrenChanged

fun notifyChildrenChanged(
    browser: MediaSession.ControllerInfo!,
    parentId: String!,
    itemCount: @IntRange(from = 0) Int,
    params: MediaLibraryService.LibraryParams?
): Unit

Notifies a browser that is subscribed to a browsable media item that the children of the item have changed. This method is also called immediately after subscribing was successful.

Parameters
browser: MediaSession.ControllerInfo!

The browser to notify.
parentId: String!

The non-empty id of the parent with changes to its children.
itemCount: @IntRange(from = 0) Int

The number of children, or MAX_VALUE if unknown.
params: MediaLibraryService.LibraryParams?

The parameters given by onSubscribe.

notifySearchResultChanged

fun notifySearchResultChanged(
    browser: MediaSession.ControllerInfo!,
    query: String!,
    itemCount: @IntRange(from = 0) Int,
    params: MediaLibraryService.LibraryParams?
): Unit

Notifies a browser of a change to the search result.

Parameters
browser: MediaSession.ControllerInfo!

The browser to notify.
query: String!

The non-empty search query given by onSearch.
itemCount: @IntRange(from = 0) Int

The number of items that have been found in the search.
params: MediaLibraryService.LibraryParams?

The parameters given by onSearch.