MediaBrowserCompat

public final class MediaBrowserCompat

Browses media content offered by a MediaBrowserServiceCompat.

The app targeting API level 30 or higher must include a <queries> element in their manifest to connect to a media browser service in another app. See the following example and this guide for more information.

<!-- As an intent action -->
<intent>
  <action android:name="android.media.browse.MediaBrowserService" />
</intent>
<!-- Or, as a package name -->
<package android:name="package_name_of_the_other_app" />

This object is not thread-safe. All calls should happen on the thread on which the browser was constructed. All callback methods will be called from the thread on which the browser was constructed.

Summary

Nested types

Callbacks for connection related events.

Callback for receiving the result of sendCustomAction.
public abstract class MediaBrowserCompat.ItemCallback

Callback for receiving the result of getItem.

A class with information on a single media item for use in browsing/searching media.
public abstract class MediaBrowserCompat.SearchCallback

Callback for receiving the result of search.

Callbacks for subscription related events.

Constants
static final String
CUSTOM_ACTION_DOWNLOAD = "android.support.v4.media.action.DOWNLOAD"

Predefined custom action to ask the connected service to download a specific MediaItem for offline playback.
static final String
CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE = "android.support.v4.media.action.REMOVE_DOWNLOADED_FILE"

Predefined custom action to ask the connected service to remove the downloaded file of MediaItem by the download action.
static final String
EXTRA_DOWNLOAD_PROGRESS = "android.media.browse.extra.DOWNLOAD_PROGRESS"

Used as a float extra field to denote the current progress during download.
static final String
EXTRA_MEDIA_ID = "android.media.browse.extra.MEDIA_ID"

Used as a string extra field to denote the target MediaItem.
static final String
EXTRA_PAGE = "android.media.browse.extra.PAGE"

Used as an int extra field to denote the page number to subscribe.
static final String
EXTRA_PAGE_SIZE = "android.media.browse.extra.PAGE_SIZE"

Used as an int extra field to denote the number of media items in a page.

Public constructors
MediaBrowserCompat(
    Context context,
    ComponentName serviceComponent,
    MediaBrowserCompat.ConnectionCallback callback,
    Bundle rootHints
)

Creates a media browser for the specified media browse service.

Public methods
void

Connects to the media browse service.
void

Disconnects from the media browse service.
@Nullable Bundle

Gets any extras for the media service.
void

Retrieves a specific MediaItem from the connected service.
@NonNull String

Gets the root id.
@NonNull ComponentName

Gets the service component that the media browser is connected to.
@NonNull MediaSessionCompat.Token

Gets the media session token associated with the media browser.
boolean

Returns whether the browser is connected to the service.
void
search(
    @NonNull String query,
    Bundle extras,
    @NonNull MediaBrowserCompat.SearchCallback callback
)

Searches media items from the connected service.
void
sendCustomAction(
    @NonNull String action,
    Bundle extras,
    @Nullable MediaBrowserCompat.CustomActionCallback callback
)

Sends a custom action to the connected service.
void

Queries for information about the media items that are contained within the specified id and subscribes to receive updates when they change.
void
subscribe(
    @NonNull String parentId,
    @NonNull Bundle options,
    @NonNull MediaBrowserCompat.SubscriptionCallback callback
)

Queries with service-specific arguments for information about the media items that are contained within the specified id and subscribes to receive updates when they change.
void

Unsubscribes for changes to the children of the specified media id.
void

Unsubscribes for changes to the children of the specified media id.

Constants

CUSTOM_ACTION_DOWNLOAD

Added in 1.1.0
public static final String CUSTOM_ACTION_DOWNLOAD = "android.support.v4.media.action.DOWNLOAD"

Predefined custom action to ask the connected service to download a specific MediaItem for offline playback. The id of the media item must be passed in an extra bundle. The download progress might be delivered to the browser via onProgressUpdate.

See also
EXTRA_MEDIA_ID
EXTRA_DOWNLOAD_PROGRESS
CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE

CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE

Added in 1.1.0
public static final String CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE = "android.support.v4.media.action.REMOVE_DOWNLOADED_FILE"

Predefined custom action to ask the connected service to remove the downloaded file of MediaItem by the download action. The id of the media item must be passed in an extra bundle.

See also
EXTRA_MEDIA_ID
CUSTOM_ACTION_DOWNLOAD

EXTRA_DOWNLOAD_PROGRESS

Added in 1.1.0
public static final String EXTRA_DOWNLOAD_PROGRESS = "android.media.browse.extra.DOWNLOAD_PROGRESS"

Used as a float extra field to denote the current progress during download. The value of this field must be a float number within [0.0, 1.0].

See also
CUSTOM_ACTION_DOWNLOAD
onProgressUpdate

EXTRA_MEDIA_ID

Added in 1.1.0
public static final String EXTRA_MEDIA_ID = "android.media.browse.extra.MEDIA_ID"

Used as a string extra field to denote the target MediaItem.

See also
CUSTOM_ACTION_DOWNLOAD
CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE

EXTRA_PAGE

Added in 1.1.0
public static final String EXTRA_PAGE = "android.media.browse.extra.PAGE"

Used as an int extra field to denote the page number to subscribe. The value of EXTRA_PAGE should be greater than or equal to 0.

See also
MediaBrowserService.BrowserRoot
EXTRA_PAGE_SIZE

EXTRA_PAGE_SIZE

Added in 1.1.0
public static final String EXTRA_PAGE_SIZE = "android.media.browse.extra.PAGE_SIZE"

Used as an int extra field to denote the number of media items in a page. The value of EXTRA_PAGE_SIZE should be greater than or equal to 1.

See also
MediaBrowserService.BrowserRoot
EXTRA_PAGE

Public constructors

MediaBrowserCompat

Added in 1.1.0
public MediaBrowserCompat(
    Context context,
    ComponentName serviceComponent,
    MediaBrowserCompat.ConnectionCallback callback,
    Bundle rootHints
)

Creates a media browser for the specified media browse service.

Parameters
Context context

The context.
ComponentName serviceComponent

The component name of the media browse service.
MediaBrowserCompat.ConnectionCallback callback

The connection callback.
Bundle rootHints

An optional bundle of service-specific arguments to send to the media browse service when connecting and retrieving the root id for browsing, or null if none. The contents of this bundle may affect the information returned when browsing.
See also
EXTRA_RECENT
EXTRA_OFFLINE
EXTRA_SUGGESTED

Public methods

connect

Added in 1.1.0
public void connect()

Connects to the media browse service. Internally, it binds to the service.

The connection callback specified in the constructor will be invoked when the connection completes or fails.

disconnect

Added in 1.1.0
public void disconnect()

Disconnects from the media browse service. After this, no more callbacks will be received.

getExtras

Added in 1.1.0
public @Nullable Bundle getExtras()

Gets any extras for the media service.

Returns
@Nullable Bundle

The extra bundle if it is connected and set, and null otherwise.
Throws
java.lang.IllegalStateException

if not connected.

getItem

Added in 1.1.0
public void getItem(
    @NonNull String mediaId,
    @NonNull MediaBrowserCompat.ItemCallback cb
)

Retrieves a specific MediaItem from the connected service. Not all services may support this, so falling back to subscribing to the parent's id should be used when unavailable.

Parameters
@NonNull String mediaId

The id of the item to retrieve.
@NonNull MediaBrowserCompat.ItemCallback cb

The callback to receive the result on.

getRoot

Added in 1.1.0
public @NonNull String getRoot()

Gets the root id.

Note that the root id may become invalid or change when when the browser is disconnected.

Throws
java.lang.IllegalStateException

if not connected.

getServiceComponent

Added in 1.1.0
public @NonNull ComponentName getServiceComponent()

Gets the service component that the media browser is connected to.

getSessionToken

Added in 1.1.0
public @NonNull MediaSessionCompat.Token getSessionToken()

Gets the media session token associated with the media browser.

Note that the session token may become invalid or change when when the browser is disconnected.

Returns
@NonNull MediaSessionCompat.Token

The session token for the browser, never null.
Throws
java.lang.IllegalStateException

if not connected.

isConnected

Added in 1.1.0
public boolean isConnected()

Returns whether the browser is connected to the service.

search

Added in 1.1.0
public void search(
    @NonNull String query,
    Bundle extras,
    @NonNull MediaBrowserCompat.SearchCallback callback
)

Searches media items from the connected service. Not all services may support this, and onError will be called if not implemented.

Parameters
@NonNull String query

The search query that contains keywords separated by space. Should not be an empty string.
Bundle extras

The bundle of service-specific arguments to send to the media browser service. The contents of this bundle may affect the search result.
@NonNull MediaBrowserCompat.SearchCallback callback

The callback to receive the search result. Must be non-null.
Throws
java.lang.IllegalStateException

if the browser is not connected to the media browser service.

sendCustomAction

Added in 1.1.0
public void sendCustomAction(
    @NonNull String action,
    Bundle extras,
    @Nullable MediaBrowserCompat.CustomActionCallback callback
)

Sends a custom action to the connected service. If the service doesn't support the given action, onError will be called.

Parameters
@NonNull String action

The custom action that will be sent to the connected service. Should not be an empty string.
Bundle extras

The bundle of service-specific arguments to send to the media browser service.
@Nullable MediaBrowserCompat.CustomActionCallback callback

The callback to receive the result of the custom action.
See also
CUSTOM_ACTION_DOWNLOAD
CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE

subscribe

Added in 1.1.0
public void subscribe(
    @NonNull String parentId,
    @NonNull MediaBrowserCompat.SubscriptionCallback callback
)

Queries for information about the media items that are contained within the specified id and subscribes to receive updates when they change.

The list of subscriptions is maintained even when not connected and is restored after the reconnection. It is ok to subscribe while not connected but the results will not be returned until the connection completes.

If the id is already subscribed with a different callback then the new callback will replace the previous one and the child data will be reloaded.

Parameters
@NonNull String parentId

The id of the parent media item whose list of children will be subscribed.
@NonNull MediaBrowserCompat.SubscriptionCallback callback

The callback to receive the list of children.

subscribe

Added in 1.1.0
public void subscribe(
    @NonNull String parentId,
    @NonNull Bundle options,
    @NonNull MediaBrowserCompat.SubscriptionCallback callback
)

Queries with service-specific arguments for information about the media items that are contained within the specified id and subscribes to receive updates when they change.

The list of subscriptions is maintained even when not connected and is restored after the reconnection. It is ok to subscribe while not connected but the results will not be returned until the connection completes.

If the id is already subscribed with a different callback then the new callback will replace the previous one and the child data will be reloaded.

Parameters
@NonNull String parentId

The id of the parent media item whose list of children will be subscribed.
@NonNull Bundle options

A bundle of service-specific arguments to send to the media browse service. The contents of this bundle may affect the information returned when browsing.
@NonNull MediaBrowserCompat.SubscriptionCallback callback

The callback to receive the list of children.

unsubscribe

Added in 1.1.0
public void unsubscribe(@NonNull String parentId)

Unsubscribes for changes to the children of the specified media id.

The query callback will no longer be invoked for results associated with this id once this method returns.

Parameters
@NonNull String parentId

The id of the parent media item whose list of children will be unsubscribed.

unsubscribe

Added in 1.1.0
public void unsubscribe(
    @NonNull String parentId,
    @NonNull MediaBrowserCompat.SubscriptionCallback callback
)

Unsubscribes for changes to the children of the specified media id.

The query callback will no longer be invoked for results associated with this id once this method returns.

Parameters
@NonNull String parentId

The id of the parent media item whose list of children will be unsubscribed.
@NonNull MediaBrowserCompat.SubscriptionCallback callback

A callback sent to the media browse service to subscribe.