MediaBrowserCompat

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.

Callback for receiving the result of getItem.

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

Callback for receiving the result of search.

Callbacks for subscription related events.

Constants
const 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.
const 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.
const String!
EXTRA_DOWNLOAD_PROGRESS = "android.media.browse.extra.DOWNLOAD_PROGRESS"

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

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

Used as an int extra field to denote the page number to subscribe.
const 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!,
    serviceComponent: ComponentName!,
    callback: MediaBrowserCompat.ConnectionCallback!,
    rootHints: Bundle!
)

Creates a media browser for the specified media browse service.

Public functions
Unit

Connects to the media browse service.
Unit

Disconnects from the media browse service.
Bundle?

Gets any extras for the media service.
Unit

Retrieves a specific MediaItem from the connected service.
String

Gets the root id.
ComponentName

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

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

Returns whether the browser is connected to the service.
Unit
search(
    query: String,
    extras: Bundle!,
    callback: MediaBrowserCompat.SearchCallback
)

Searches media items from the connected service.
Unit
sendCustomAction(
    action: String,
    extras: Bundle!,
    callback: MediaBrowserCompat.CustomActionCallback?
)

Sends a custom action to the connected service.
Unit
subscribe(
    parentId: String,
    callback: MediaBrowserCompat.SubscriptionCallback
)

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

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.
Unit
unsubscribe(parentId: String)

Unsubscribes for changes to the children of the specified media id.
Unit
unsubscribe(
    parentId: String,
    callback: MediaBrowserCompat.SubscriptionCallback
)

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

Constants

CUSTOM_ACTION_DOWNLOAD

Added in 1.1.0
const val CUSTOM_ACTION_DOWNLOAD = "android.support.v4.media.action.DOWNLOAD": String!

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
const val CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE = "android.support.v4.media.action.REMOVE_DOWNLOADED_FILE": String!

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
const val EXTRA_DOWNLOAD_PROGRESS = "android.media.browse.extra.DOWNLOAD_PROGRESS": String!

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
const val EXTRA_MEDIA_ID = "android.media.browse.extra.MEDIA_ID": String!

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
const val EXTRA_PAGE = "android.media.browse.extra.PAGE": String!

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
const val EXTRA_PAGE_SIZE = "android.media.browse.extra.PAGE_SIZE": String!

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
MediaBrowserCompat(
    context: Context!,
    serviceComponent: ComponentName!,
    callback: MediaBrowserCompat.ConnectionCallback!,
    rootHints: Bundle!
)

Creates a media browser for the specified media browse service.

Parameters
context: Context!

The context.
serviceComponent: ComponentName!

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

The connection callback.
rootHints: Bundle!

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 functions

connect

Added in 1.1.0
fun connect(): Unit

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
fun disconnect(): Unit

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

getExtras

Added in 1.1.0
fun getExtras(): Bundle?

Gets any extras for the media service.

Returns
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
fun getItem(mediaId: String, cb: MediaBrowserCompat.ItemCallback): Unit

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

The id of the item to retrieve.
cb: MediaBrowserCompat.ItemCallback

The callback to receive the result on.

getRoot

Added in 1.1.0
fun getRoot(): String

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
fun getServiceComponent(): ComponentName

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

getSessionToken

Added in 1.1.0
fun getSessionToken(): MediaSessionCompat.Token

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
MediaSessionCompat.Token

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

if not connected.

isConnected

Added in 1.1.0
fun isConnected(): Boolean

Returns whether the browser is connected to the service.

search

Added in 1.1.0
fun search(
    query: String,
    extras: Bundle!,
    callback: MediaBrowserCompat.SearchCallback
): Unit

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

Parameters
query: String

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

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

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
fun sendCustomAction(
    action: String,
    extras: Bundle!,
    callback: MediaBrowserCompat.CustomActionCallback?
): Unit

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

Parameters
action: String

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

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

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
fun subscribe(
    parentId: String,
    callback: MediaBrowserCompat.SubscriptionCallback
): Unit

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
parentId: String

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

The callback to receive the list of children.

subscribe

Added in 1.1.0
fun subscribe(
    parentId: String,
    options: Bundle,
    callback: MediaBrowserCompat.SubscriptionCallback
): Unit

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
parentId: String

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

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.
callback: MediaBrowserCompat.SubscriptionCallback

The callback to receive the list of children.

unsubscribe

Added in 1.1.0
fun unsubscribe(parentId: String): Unit

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
parentId: String

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

unsubscribe

Added in 1.1.0
fun unsubscribe(
    parentId: String,
    callback: MediaBrowserCompat.SubscriptionCallback
): Unit

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
parentId: String

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

A callback sent to the media browse service to subscribe.