Added in API level 30

MediaRouter2

class MediaRouter2
kotlin.Any
   ↳ android.media.MediaRouter2

This API is not generally intended for third party application developers. Use the AndroidX Media Router Library for consistent behavior across all devices.

MediaRouter2 allows applications to control the routing of media channels and streams from the current device to remote speakers and devices.

Summary

Nested classes
abstract

Callback for receiving RoutingController updates.
abstract

A listener interface to send optional app-specific hints when creating a RoutingController.
abstract

Callback for receiving events about media route discovery.

Controls a media routing session.

Represents a set of parameters for scanning requests.

Represents an active scan request registered in the system.
abstract

Callback for receiving events on media transfer.
Public methods
Unit

Releases the active scan request linked to the provided ScanToken.
MediaRouter2.RoutingController?

Gets a RoutingController whose ID is equal to the given ID.
MutableList<MediaRouter2.RoutingController!>

Gets the list of currently active routing controllers on which media can be played.
static MediaRouter2
getInstance(context: Context)

Gets an instance of the media router associated with the context.
static MediaRouter2
getInstance(context: Context, clientPackageName: String, executor: Executor, onInstanceInvalidatedListener: Runnable)

Returns a proxy MediaRouter2 instance that allows you to control the routing of an app specified by clientPackageName.
RouteListingPreference?

Returns the current RouteListingPreference of the target router.
MutableList<MediaRoute2Info!>

Gets the unmodifiable list of routes currently known to the media router.
MediaRouter2.RoutingController

Gets a RoutingController which can control the routes provided by system.
Unit

Registers a ControllerCallback.
Unit

Registers a callback to discover routes and to receive events when they change.
Unit

Registers the given callback to be invoked when the RouteListingPreference of the target router changes.
Unit

Registers a callback to get the result of transferTo(android.media.MediaRoute2Info).
MediaRouter2.ScanToken

Requests the system to actively scan for routes based on the router's route discovery preference.
Unit

Sets an OnGetControllerHintsListener to send hints when creating a RoutingController.
Unit

Sets the RouteListingPreference of the app associated to this media router.
Unit

Sets the volume for a specific route.
Boolean

Shows the system output switcher dialog.
Unit

Stops the current media routing.
Unit

Transfers the current media to the given route.
Unit

Unregisters a ControllerCallback.
Unit

Unregisters the given callback.
Unit

Unregisters the given callback to not receive RouteListingPreference change events.
Unit

Unregisters the given callback.

Public methods

cancelScanRequest

Added in API level 35
fun cancelScanRequest(token: MediaRouter2.ScanToken): Unit

Releases the active scan request linked to the provided ScanToken.

Parameters
token MediaRouter2.ScanToken: ScanToken of the ScanRequest to release. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the token does not match any active scan request.

getController

Added in API level 31
fun getController(id: String): MediaRouter2.RoutingController?

Gets a RoutingController whose ID is equal to the given ID. Returns null if there is no matching controller.

Parameters
id String: This value cannot be null.

getControllers

Added in API level 30
fun getControllers(): MutableList<MediaRouter2.RoutingController!>

Gets the list of currently active routing controllers on which media can be played.

Note: The list returned here will never be empty. The first element in the list is always the system controller.

Return
MutableList<MediaRouter2.RoutingController!> This value cannot be null.

getInstance

Added in API level 30
static fun getInstance(context: Context): MediaRouter2

Gets an instance of the media router associated with the context.

Parameters
context Context: This value cannot be null.
Return
MediaRouter2 This value cannot be null.

getInstance

Added in API level 35
static fun getInstance(
    context: Context, 
    clientPackageName: String, 
    executor: Executor, 
    onInstanceInvalidatedListener: Runnable
): MediaRouter2

Returns a proxy MediaRouter2 instance that allows you to control the routing of an app specified by clientPackageName.

Proxy MediaRouter2 instances operate differently than regular MediaRouter2 instances:

Use this method when you only hold a revocable version of android.Manifest.permission#MEDIA_ROUTING_CONTROL (e.g. acquired via the AppOpsManager). Otherwise, use #getInstance(android.content.Context,java.lang.String).

onInstanceInvalidatedListener is called when the instance is invalidated because the calling app has lost Manifest.permission.MEDIA_ROUTING_CONTROL and does not hold Manifest.permission.MEDIA_CONTENT_CONTROL. Do not use the invalidated instance after receiving this callback, as the system will ignore all operations. Call getInstance(android.content.Context,java.lang.String,java.util.concurrent.Executor,java.lang.Runnable) again after reacquiring the relevant permissions.
Requires android.Manifest.permission#MEDIA_CONTENT_CONTROL or android.Manifest.permission#MEDIA_ROUTING_CONTROL

Parameters
context Context: The Context of the caller. This value cannot be null.
clientPackageName String: The package name of the app you want to control the routing of. This value cannot be null.
executor Executor: The Executor on which to invoke onInstanceInvalidatedListener. This value cannot be null.
onInstanceInvalidatedListener Runnable: Callback for when the MediaRouter2 instance is invalidated due to lost permissions. This value cannot be null.
Return
MediaRouter2 This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if clientPackageName does not exist in the calling user.

getRouteListingPreference

Added in API level 35
fun getRouteListingPreference(): RouteListingPreference?

Returns the current RouteListingPreference of the target router.

If this instance was created using getInstance(Context, String), then it returns the last RouteListingPreference set by the process this router was created for.

Return
RouteListingPreference? This value may be null.

getRoutes

Added in API level 30
fun getRoutes(): MutableList<MediaRoute2Info!>

Gets the unmodifiable list of routes currently known to the media router.

Please note that the list can be changed before callbacks are invoked.

Return
MutableList<MediaRoute2Info!> the list of routes that contains at least one of the route features in discovery preferences registered by the application This value cannot be null.

getSystemController

Added in API level 30
fun getSystemController(): MediaRouter2.RoutingController

Gets a RoutingController which can control the routes provided by system. e.g. Phone speaker, wired headset, Bluetooth, etc.

Note: The system controller can't be released. Calling RoutingController.release() will be ignored.

This method always returns the same instance.

Return
MediaRouter2.RoutingController This value cannot be null.

registerControllerCallback

Added in API level 30
fun registerControllerCallback(
    executor: Executor, 
    callback: MediaRouter2.ControllerCallback
): Unit

Registers a ControllerCallback. If you register the same callback twice or more, it will be ignored.

Parameters
executor Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback MediaRouter2.ControllerCallback: This value cannot be null.

registerRouteCallback

Added in API level 30
fun registerRouteCallback(
    executor: Executor, 
    routeCallback: MediaRouter2.RouteCallback, 
    preference: RouteDiscoveryPreference
): Unit

Registers a callback to discover routes and to receive events when they change.

Clients can register multiple callbacks, as long as the RouteCallback instances are different. Each callback can provide a unique preference and will only receive updates related to that set preference.

If the specified callback is already registered, its registration will be updated for the given executor and discovery preference.

Local routers must register a route callback to register in the system and start receiving updates. Otherwise, all operations will be no-ops.

Any discovery preference passed by a #getInstance(android.content.Context,java.lang.String) will be ignored and will receive route updates based on the preference set by its matching local router.

Parameters
executor Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
routeCallback MediaRouter2.RouteCallback: This value cannot be null.
preference RouteDiscoveryPreference: This value cannot be null.

registerRouteListingPreferenceUpdatedCallback

Added in API level 35
fun registerRouteListingPreferenceUpdatedCallback(
    executor: Executor, 
    routeListingPreferenceCallback: Consumer<RouteListingPreference!>
): Unit

Registers the given callback to be invoked when the RouteListingPreference of the target router changes.

Calls using a previously registered callback will overwrite the previous executor.

Parameters
executor Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
routeListingPreferenceCallback Consumer<RouteListingPreference!>: This value cannot be null.

registerTransferCallback

Added in API level 30
fun registerTransferCallback(
    executor: Executor, 
    callback: MediaRouter2.TransferCallback
): Unit

Registers a callback to get the result of transferTo(android.media.MediaRoute2Info). If you register the same callback twice or more, it will be ignored.

Parameters
executor Executor: the executor to execute the callback on This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback MediaRouter2.TransferCallback: the callback to register This value cannot be null.

requestScan

Added in API level 35
fun requestScan(scanRequest: MediaRouter2.ScanRequest): MediaRouter2.ScanToken

Requests the system to actively scan for routes based on the router's route discovery preference.

You must call cancelScanRequest(android.media.MediaRouter2.ScanToken) promptly to preserve system resources like battery. Avoid scanning unless there is clear intention from the user to start routing their media.

scanRequest specifies relevant scanning options, like whether the system should scan with the screen off. Screen off scanning requires android.Manifest.permission#MEDIA_ROUTING_CONTROL or android.Manifest.permission#MEDIA_CONTENT_CONTROL.

Proxy routers use the registered RouteDiscoveryPreference of their target routers.

Parameters
scanRequest MediaRouter2.ScanRequest: This value cannot be null.
Return
MediaRouter2.ScanToken A unique ScanToken that identifies the scan request. This value cannot be null.
Exceptions
java.lang.SecurityException If a ScanRequest with ScanRequest.Builder#setScreenOffScan true is passed, while not holding android.Manifest.permission#MEDIA_ROUTING_CONTROL or android.Manifest.permission#MEDIA_CONTENT_CONTROL.

setOnGetControllerHintsListener

Added in API level 30
fun setOnGetControllerHintsListener(listener: MediaRouter2.OnGetControllerHintsListener?): Unit

Sets an OnGetControllerHintsListener to send hints when creating a RoutingController. To send the hints, listener should be set BEFORE calling transferTo(android.media.MediaRoute2Info).

Parameters
listener MediaRouter2.OnGetControllerHintsListener?: A listener to send optional app-specific hints when creating a controller. null for unset.

setRouteListingPreference

Added in API level 34
fun setRouteListingPreference(routeListingPreference: RouteListingPreference?): Unit

Sets the RouteListingPreference of the app associated to this media router.

Use this method to inform the system UI of the routes that you would like to list for media routing, via the Output Switcher.

You should call this method before registering any route and immediately after receiving any updates in order to keep the system UI in a consistent state. You can also call this method at any other point to update the listing preference dynamically.

Any calls to this method from a privileged router will throw an UnsupportedOperationException.

Notes:

  1. You should not include the ids of two or more routes with a match in their deduplication ids. If you do, the system will deduplicate them using its own criteria.
  2. You can use this method to rank routes in the output switcher, placing the more important routes first. The system might override the proposed ranking.
  3. You can use this method to avoid listing routes using dynamic criteria. For example, you can limit access to a specific type of device according to runtime criteria.
Parameters
routeListingPreference RouteListingPreference?: The RouteListingPreference for the system to use for route listing. When null, the system uses its default listing criteria.

setRouteVolume

Added in API level 35
fun setRouteVolume(
    route: MediaRoute2Info, 
    volume: Int
): Unit

Sets the volume for a specific route.

The call may have no effect if the route is currently not selected.

This method is only supported by #getInstance(android.content.Context,java.lang.String). Use RoutingController#setVolume(int) instead for local MediaRouter2 instances.


Requires android.Manifest.permission#MEDIA_CONTENT_CONTROL or android.Manifest.permission#MEDIA_ROUTING_CONTROL
Parameters
volume Int: The new volume value between 0 and MediaRoute2Info.getVolumeMax.
route MediaRoute2Info: This value cannot be null.
Exceptions
java.lang.UnsupportedOperationException If called on a local.

showSystemOutputSwitcher

Added in API level 34
fun showSystemOutputSwitcher(): Boolean

Shows the system output switcher dialog.

Should only be called when the context of MediaRouter2 is in the foreground and visible on the screen.

The appearance and precise behaviour of the system output switcher dialog may vary across different devices, OS versions, and form factors, but the basic functionality stays the same.

See Output Switcher documentation for more details.

Return
Boolean true if the output switcher dialog is being shown, or false if the call is ignored because the app is in the background.

stop

Added in API level 30
fun stop(): Unit

Stops the current media routing. If the system controller controls the media routing, this method is a no-op.

transferTo

Added in API level 30
fun transferTo(route: MediaRoute2Info): Unit

Transfers the current media to the given route. If it's necessary a new RoutingController is created or it is handled within the current routing controller.

Parameters
route MediaRoute2Info: the route you want to transfer the current media to. Pass null to stop routing of the current media.

unregisterControllerCallback

Added in API level 30
fun unregisterControllerCallback(callback: MediaRouter2.ControllerCallback): Unit

Unregisters a ControllerCallback. The callback will no longer receive events. If the callback has not been added or been removed already, it is ignored.

Parameters
callback MediaRouter2.ControllerCallback: This value cannot be null.

unregisterRouteCallback

Added in API level 30
fun unregisterRouteCallback(routeCallback: MediaRouter2.RouteCallback): Unit

Unregisters the given callback. The callback will no longer receive events. If the callback has not been added or been removed already, it is ignored.

Parameters
routeCallback MediaRouter2.RouteCallback: the callback to unregister This value cannot be null.

unregisterRouteListingPreferenceUpdatedCallback

Added in API level 35
fun unregisterRouteListingPreferenceUpdatedCallback(callback: Consumer<RouteListingPreference!>): Unit

Unregisters the given callback to not receive RouteListingPreference change events.

Parameters
callback Consumer<RouteListingPreference!>: This value cannot be null.

unregisterTransferCallback

Added in API level 30
fun unregisterTransferCallback(callback: MediaRouter2.TransferCallback): Unit

Unregisters the given callback. The callback will no longer receive events. If the callback has not been added or been removed already, it is ignored.

Parameters
callback MediaRouter2.TransferCallback: the callback to unregister This value cannot be null.