MediaRouter2
public
final
class
MediaRouter2
extends Object
java.lang.Object | |
↳ | 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 | |
---|---|
class |
MediaRouter2.ControllerCallback
Callback for receiving |
interface |
MediaRouter2.OnGetControllerHintsListener
A listener interface to send optional app-specific hints when creating a |
class |
MediaRouter2.RouteCallback
Callback for receiving events about media route discovery. |
class |
MediaRouter2.RoutingController
A class to control media routing session in media route provider. |
class |
MediaRouter2.ScanRequest
Represents a set of parameters for scanning requests. |
class |
MediaRouter2.ScanToken
Represents an active scan request registered in the system. |
class |
MediaRouter2.TransferCallback
Callback for receiving events on media transfer. |
Public methods | |
---|---|
void
|
cancelScanRequest(MediaRouter2.ScanToken token)
Releases the active scan request linked to the provided |
MediaRouter2.RoutingController
|
getController(String id)
Gets a |
List<MediaRouter2.RoutingController>
|
getControllers()
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, String clientPackageName, Executor executor, Runnable onInstanceInvalidatedListener)
Returns a proxy MediaRouter2 instance that allows you to control the routing of an app
specified by |
RouteListingPreference
|
getRouteListingPreference()
Returns the current |
List<MediaRoute2Info>
|
getRoutes()
Gets the unmodifiable list of |
MediaRouter2.RoutingController
|
getSystemController()
Gets a |
void
|
registerControllerCallback(Executor executor, MediaRouter2.ControllerCallback callback)
Registers a |
void
|
registerRouteCallback(Executor executor, MediaRouter2.RouteCallback routeCallback, RouteDiscoveryPreference preference)
Registers a callback to discover routes and to receive events when they change. |
void
|
registerRouteListingPreferenceUpdatedCallback(Executor executor, Consumer<RouteListingPreference> routeListingPreferenceCallback)
Registers the given callback to be invoked when the |
void
|
registerTransferCallback(Executor executor, MediaRouter2.TransferCallback callback)
Registers a callback to get the result of |
MediaRouter2.ScanToken
|
requestScan(MediaRouter2.ScanRequest scanRequest)
Requests the system to actively scan for routes based on the router's |
void
|
setOnGetControllerHintsListener(MediaRouter2.OnGetControllerHintsListener listener)
Sets an |
void
|
setRouteListingPreference(RouteListingPreference routeListingPreference)
Sets the |
void
|
setRouteVolume(MediaRoute2Info route, int volume)
Sets the volume for a specific route. |
boolean
|
showSystemOutputSwitcher()
Shows the system output switcher dialog. |
void
|
stop()
Stops the current media routing. |
void
|
transferTo(MediaRoute2Info route)
Transfers the current media to the given route. |
void
|
unregisterControllerCallback(MediaRouter2.ControllerCallback callback)
Unregisters a |
void
|
unregisterRouteCallback(MediaRouter2.RouteCallback routeCallback)
Unregisters the given callback. |
void
|
unregisterRouteListingPreferenceUpdatedCallback(Consumer<RouteListingPreference> callback)
Unregisters the given callback to not receive |
void
|
unregisterTransferCallback(MediaRouter2.TransferCallback callback)
Unregisters the given callback. |
Inherited methods | |
---|---|
Public methods
cancelScanRequest
public void cancelScanRequest (MediaRouter2.ScanToken token)
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 . |
Throws | |
---|---|
IllegalArgumentException |
if the token does not match any active scan request. |
See also:
getController
public MediaRouter2.RoutingController getController (String id)
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 . |
Returns | |
---|---|
MediaRouter2.RoutingController |
getControllers
public List<MediaRouter2.RoutingController> getControllers ()
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
.
Returns | |
---|---|
List<MediaRouter2.RoutingController> |
This value cannot be null . |
getInstance
public static MediaRouter2 getInstance (Context context)
Gets an instance of the media router associated with the context.
Parameters | |
---|---|
context |
Context : This value cannot be null . |
Returns | |
---|---|
MediaRouter2 |
This value cannot be null . |
getInstance
public static MediaRouter2 getInstance (Context context, String clientPackageName, Executor executor, Runnable onInstanceInvalidatedListener)
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(Executor, RouteCallback, RouteDiscoveryPreference)
ignores anypreference
passed by a proxy router. UseERROR(RouteDiscoveryPreference#EMPTY/android.media.RouteDiscoveryPreference#EMPTY 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(OnGetControllerHintsListener)
are ignored.
Use this method when you only hold a revocable version of Manifest.permission.MEDIA_ROUTING_CONTROL
(e.g. acquired via the AppOpsManager
).
Otherwise, use ERROR(/#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 Manifest.permission.MEDIA_CONTENT_CONTROL
or 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 . |
Returns | |
---|---|
MediaRouter2 |
Throws | |
---|---|
IllegalArgumentException |
if clientPackageName does not exist in the calling
user. |
getRouteListingPreference
public RouteListingPreference getRouteListingPreference ()
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.
Returns | |
---|---|
RouteListingPreference |
This value may be null . |
getRoutes
public List<MediaRoute2Info> getRoutes ()
Gets the unmodifiable list of routes
currently known to the media
router.
Please note that the list can be changed before callbacks are invoked.
Returns | |
---|---|
List<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
public MediaRouter2.RoutingController getSystemController ()
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.
Returns | |
---|---|
MediaRouter2.RoutingController |
This value cannot be null . |
registerControllerCallback
public void registerControllerCallback (Executor executor, MediaRouter2.ControllerCallback callback)
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
public void registerRouteCallback (Executor executor, MediaRouter2.RouteCallback routeCallback, RouteDiscoveryPreference preference)
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 ERROR(proxy router/#getInstance(android.content.Context,java.lang.String) proxy router)
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
public void registerRouteListingPreferenceUpdatedCallback (Executor executor, Consumer<RouteListingPreference> routeListingPreferenceCallback)
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 : This value cannot be null . |
registerTransferCallback
public void registerTransferCallback (Executor executor, MediaRouter2.TransferCallback callback)
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
public MediaRouter2.ScanToken requestScan (MediaRouter2.ScanRequest scanRequest)
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 Manifest.permission.MEDIA_ROUTING_CONTROL
or Manifest.permission.MEDIA_CONTENT_CONTROL
.
Proxy routers use the registered RouteDiscoveryPreference
of their target routers.
Parameters | |
---|---|
scanRequest |
MediaRouter2.ScanRequest : This value cannot be null . |
Returns | |
---|---|
MediaRouter2.ScanToken |
A unique ScanToken that identifies the scan request.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
If a ScanRequest with MediaRouter2.ScanRequest.Builder.setScreenOffScan(boolean) true is passed, while not holding Manifest.permission.MEDIA_ROUTING_CONTROL or Manifest.permission.MEDIA_CONTENT_CONTROL . |
setOnGetControllerHintsListener
public void setOnGetControllerHintsListener (MediaRouter2.OnGetControllerHintsListener listener)
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
public void setRouteListingPreference (RouteListingPreference routeListingPreference)
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
callbacks
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
public void setRouteVolume (MediaRoute2Info route, int volume)
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 ERROR(proxy MediaRouter2
instances/#getInstance(android.content.Context,java.lang.String) proxy MediaRouter2
instances)
. Use RoutingController#setVolume(int)
instead for local MediaRouter2 instances
.
Requires
Manifest.permission.MEDIA_CONTENT_CONTROL
or Manifest.permission.MEDIA_ROUTING_CONTROL
Parameters | |
---|---|
route |
MediaRoute2Info : This value cannot be null . |
volume |
int : The new volume value between 0 and MediaRoute2Info#getVolumeMax . |
Throws | |
---|---|
UnsupportedOperationException |
If called on a local
router instance . |
showSystemOutputSwitcher
public boolean showSystemOutputSwitcher ()
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.
Returns | |
---|---|
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
public void stop ()
Stops the current media routing. If the system controller
controls the media routing, this method is a no-op.
transferTo
public void transferTo (MediaRoute2Info route)
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
public void unregisterControllerCallback (MediaRouter2.ControllerCallback callback)
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
public void unregisterRouteCallback (MediaRouter2.RouteCallback routeCallback)
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
public void unregisterRouteListingPreferenceUpdatedCallback (Consumer<RouteListingPreference> callback)
Unregisters the given callback to not receive RouteListingPreference
change events.
Parameters | |
---|---|
callback |
Consumer : This value cannot be null . |
unregisterTransferCallback
public void unregisterTransferCallback (MediaRouter2.TransferCallback callback)
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 . |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-09-03 UTC.