MediaLibraryService.MediaLibrarySession

public final class MediaLibraryService.MediaLibrarySession extends MediaSession

java.lang.Object
   ↳ 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
static final int

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

No library service errors are replicated.
static final 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 methods
void

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.
void
notifyChildrenChanged(
    String parentId,
    @IntRange(from = 0) int itemCount,
    @Nullable MediaLibraryService.LibraryParams params
)

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

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

Notifies a browser of a change to the search result.

Inherited methods
From androidx.media3.session.MediaSession
final void

Broadcasts a custom command to all connected controllers.
final BitmapLoader

Returns the BitmapLoader.
final List<MediaSession.ControllerInfo>

Returns the list of connected controllers.
final @Nullable 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.
final String

Returns the session ID.
ImmutableList<CommandButton>

Returns the media button preferences of the session.
@Nullable MediaSession.ControllerInfo

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

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

Returns the underlying Player.
final @Nullable PendingIntent

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

This method is deprecated.

Use getPlatformToken instead.
Bundle

Returns the session extras.
final boolean

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

Returns the SessionToken for creating MediaController instances.
final boolean

Returns whether the given ControllerInfo belongs to an Android Auto companion app controller.
final 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.
final void

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

Sends a custom command to a specific controller.
final void

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

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

Sets the new available commands for the controller.
final void

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

Sets the custom layout for the given controller.
final void

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

Sets the media button preferences for the given controller.
final void
setPlayer(Player player)

Sets the underlying Player for this session to dispatch incoming events to.
final void

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

Sends the session activity to the connected controller.
final void
setSessionExtras(Bundle sessionExtras)

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

Sends the session extras to the connected controller.

Constants

LIBRARY_ERROR_REPLICATION_MODE_FATAL

@UnstableApi
public static final int LIBRARY_ERROR_REPLICATION_MODE_FATAL = 1

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
public static final int LIBRARY_ERROR_REPLICATION_MODE_NONE = 0

No library service errors are replicated.

LIBRARY_ERROR_REPLICATION_MODE_NON_FATAL

@UnstableApi
public static final int LIBRARY_ERROR_REPLICATION_MODE_NON_FATAL = 2

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

Public methods

clearReplicatedLibraryError

@UnstableApi
public void clearReplicatedLibraryError()

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
public ImmutableList<MediaSession.ControllerInfo> getSubscribedControllers(String mediaId)

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
String mediaId

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

public void notifyChildrenChanged(
    String parentId,
    @IntRange(from = 0) int itemCount,
    @Nullable MediaLibraryService.LibraryParams params
)

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

Parameters
String parentId

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

The number of children.
@Nullable MediaLibraryService.LibraryParams params

The optional parameters.

notifyChildrenChanged

public void notifyChildrenChanged(
    MediaSession.ControllerInfo browser,
    String parentId,
    @IntRange(from = 0) int itemCount,
    @Nullable MediaLibraryService.LibraryParams params
)

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
MediaSession.ControllerInfo browser

The browser to notify.
String parentId

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

The number of children, or MAX_VALUE if unknown.
@Nullable MediaLibraryService.LibraryParams params

The parameters given by onSubscribe.

notifySearchResultChanged

public void notifySearchResultChanged(
    MediaSession.ControllerInfo browser,
    String query,
    @IntRange(from = 0) int itemCount,
    @Nullable MediaLibraryService.LibraryParams params
)

Notifies a browser of a change to the search result.

Parameters
MediaSession.ControllerInfo browser

The browser to notify.
String query

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

The number of items that have been found in the search.
@Nullable MediaLibraryService.LibraryParams params

The parameters given by onSearch.