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 |
abstract |
A listener interface to send optional app-specific hints when creating a |
abstract |
Callback for receiving events about media route discovery. |
A class to control media routing session in media route provider. |
|
abstract |
Callback for receiving events on media transfer. |
Public methods | |
---|---|
MediaRouter2.RoutingController? |
getController(id: String) Gets a |
MutableList<MediaRouter2.RoutingController!> |
Gets the list of currently active |
static MediaRouter2 |
getInstance(context: Context) Gets an instance of the media router associated with the context. |
static MediaRouter2? |
getInstance(context: Context, clientPackageName: String) Returns a proxy MediaRouter2 instance that allows you to control the routing of an app specified by |
RouteListingPreference? |
Returns the current |
MutableList<MediaRoute2Info!> |
Gets the unmodifiable list of |
MediaRouter2.RoutingController |
Gets a |
Unit |
registerControllerCallback(executor: Executor, callback: MediaRouter2.ControllerCallback) Registers a |
Unit |
registerRouteCallback(executor: Executor, routeCallback: MediaRouter2.RouteCallback, preference: RouteDiscoveryPreference) Registers a callback to discover routes and to receive events when they change. |
Unit |
registerRouteListingPreferenceUpdatedCallback(executor: Executor, routeListingPreferenceCallback: Consumer<RouteListingPreference!>) Registers the given callback to be invoked when the |
Unit |
registerTransferCallback(executor: Executor, callback: MediaRouter2.TransferCallback) Registers a callback to get the result of |
Unit |
Sets an |
Unit |
setRouteListingPreference(routeListingPreference: RouteListingPreference?) Sets the |
Unit |
setRouteVolume(route: MediaRoute2Info, volume: Int) Sets the volume for a specific route. |
Boolean |
Shows the system output switcher dialog. |
Unit |
stop() Stops the current media routing. |
Unit |
transferTo(route: MediaRoute2Info) Transfers the current media to the given route. |
Unit |
Unregisters a |
Unit |
unregisterRouteCallback(routeCallback: MediaRouter2.RouteCallback) Unregisters the given callback. |
Unit |
Unregisters the given callback to not receive |
Unit |
Unregisters the given callback. |
Public methods
getController
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
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
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
static fun getInstance(
context: Context,
clientPackageName: String
): MediaRouter2?
Returns a proxy MediaRouter2 instance that allows you to control the routing of an app specified by clientPackageName
. Returns null
if the specified package name does not exist.
Proxy MediaRouter2 instances operate differently than regular MediaRouter2 instances:
-
registerRouteCallback
ignores anypreference
passed by a proxy router. Use android.media.RouteDiscoveryPreference#EMPTY when setting a route callback. -
Methods returning non-system
controllers
always return new instances with the latest data. Do not attempt to compare or store them. Instead, usegetController(java.lang.String)
orgetControllers()
to query the most up-to-date state. -
Calls to
setOnGetControllerHintsListener
are ignored.
Requires
android.Manifest.permission#MEDIA_CONTENT_CONTROL
or android.Manifest.permission#MEDIA_ROUTING_CONTROL
Parameters | |
---|---|
clientPackageName |
String: the package name of the app to control This value cannot be null . |
context |
Context: This value cannot be null . |
Return | |
---|---|
MediaRouter2? |
a proxy MediaRouter2 instance if clientPackageName exists or null . |
getRouteListingPreference
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
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
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
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
fun registerRouteCallback(
executor: Executor,
routeCallback: MediaRouter2.RouteCallback,
preference: RouteDiscoveryPreference
): Unit
Registers a callback to discover routes and to receive events when they change.
If the specified callback is already registered, its registration will be updated for the given executor
and discovery preference
.
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
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
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 . |
See Also
setOnGetControllerHintsListener
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
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:
- 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. - 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.
- 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
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 proxy MediaRouter2
. 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
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
fun stop(): Unit
Stops the current media routing. If the system controller
controls the media routing, this method is a no-op.
transferTo
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
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
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 . |
See Also
unregisterRouteListingPreferenceUpdatedCallback
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
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 . |
See Also