MediaRouter

public final class MediaRouter
extends Object

java.lang.Object
   ↳ androidx.mediarouter.media.MediaRouter


MediaRouter allows applications to control the routing of media channels and streams from the current device to external speakers and destination devices.

A MediaRouter instance is retrieved through getInstance(Context). Applications can query the media router about the currently selected route and its capabilities to determine how to send content to the route's destination. Applications can also send control requests to the route to ask the route's destination to perform certain remote control functions such as playing media.

See also MediaRouteProvider for information on how an application can publish new media routes to the media router.

The media router API is not thread-safe; all interactions with it must be done from the main thread of the process.

Summary

Nested classes

class MediaRouter.Callback

Interface for receiving events about media routing changes. 

class MediaRouter.ControlRequestCallback

Callback which is invoked with the result of a media control request. 

interface MediaRouter.OnPrepareTransferListener

Listener for receiving events when the selected route is about to be changed. 

class MediaRouter.ProviderInfo

Provides information about a media route provider. 

class MediaRouter.RouteInfo

Provides information about a media route. 

Constants

int AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE

Flag for isRouteAvailable(MediaRouteSelector, int): Ignore the default route.

int AVAILABILITY_FLAG_REQUIRE_MATCH

Flag for isRouteAvailable(MediaRouteSelector, int): Require an actual route to be matched.

int CALLBACK_FLAG_FORCE_DISCOVERY

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Request passive route discovery while this callback is registered, even on low-RAM devices.

int CALLBACK_FLAG_PERFORM_ACTIVE_SCAN

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Actively scan for routes while this callback is registered.

int CALLBACK_FLAG_REQUEST_DISCOVERY

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Request passive route discovery while this callback is registered, except on low-RAM devices.

int CALLBACK_FLAG_UNFILTERED_EVENTS

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Do not filter route events.

int UNSELECT_REASON_DISCONNECTED

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the user pressed the disconnect button to disconnect and keep playing.

int UNSELECT_REASON_ROUTE_CHANGED

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the user selected a different route.

int UNSELECT_REASON_STOPPED

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the user pressed the stop casting button.

int UNSELECT_REASON_UNKNOWN

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the reason the route was unselected is unknown.

Public methods

void addCallback(MediaRouteSelector selector, MediaRouter.Callback callback)

Registers a callback to discover routes that match the selector and to receive events when they change.

void addCallback(MediaRouteSelector selector, MediaRouter.Callback callback, int flags)

Registers a callback to discover routes that match the selector and to receive events when they change.

void addProvider(MediaRouteProvider providerInstance)

Registers a media route provider within this application process.

void addRemoteControlClient(Object remoteControlClient)

Adds a remote control client to enable remote control of the volume of the selected route.

MediaRouter.RouteInfo getBluetoothRoute()

Gets a bluetooth route for playing media content on the system.

MediaRouter.RouteInfo getDefaultRoute()

Gets the default route for playing media content on the system.

static MediaRouter getInstance(Context context)

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

MediaSessionCompat.Token getMediaSessionToken()
List<MediaRouter.ProviderInfo> getProviders()

Gets information about the route providers currently known to this media router.

MediaRouterParams getRouterParams()

Gets parameters of the media router service associated with this media router.

List<MediaRouter.RouteInfo> getRoutes()

Gets information about the routes currently known to this media router.

MediaRouter.RouteInfo getSelectedRoute()

Gets the currently selected route.

boolean isRouteAvailable(MediaRouteSelector selector, int flags)

Returns true if there is a route that matches the specified selector.

void removeCallback(MediaRouter.Callback callback)

Removes the specified callback.

void removeProvider(MediaRouteProvider providerInstance)

Unregisters a media route provider within this application process.

void removeRemoteControlClient(Object remoteControlClient)

Removes a remote control client.

void selectRoute(MediaRouter.RouteInfo route)

Selects the specified route.

void setMediaSession(Object mediaSession)

Sets the media session to enable remote control of the volume of the selected route.

void setMediaSessionCompat(MediaSessionCompat mediaSession)

Sets a compat media session to enable remote control of the volume of the selected route.

void setOnPrepareTransferListener(MediaRouter.OnPrepareTransferListener listener)

Sets a listener for receiving events when the selected route is about to be changed.

void setRouterParams(MediaRouterParams params)

Sets parameters of the media router service associated with this media router.

void unselect(int reason)

Unselects the current route and selects the default route instead.

MediaRouter.RouteInfo updateSelectedRoute(MediaRouteSelector selector)

Returns the selected route if it matches the specified selector, otherwise selects the default route and returns it.

Inherited methods

Constants

AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE

public static final int AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE

Flag for isRouteAvailable(MediaRouteSelector, int): Ignore the default route.

This flag is used to determine whether a matching non-default route is available. This constraint may be used to decide whether to offer the route chooser dialog to the user. There is no point offering the chooser if there are no non-default choices.

Constant Value: 1 (0x00000001)

AVAILABILITY_FLAG_REQUIRE_MATCH

public static final int AVAILABILITY_FLAG_REQUIRE_MATCH

Flag for isRouteAvailable(MediaRouteSelector, int): Require an actual route to be matched.

If this flag is not set, then isRouteAvailable(MediaRouteSelector, int) will return true if it is possible to discover a matching route even if discovery is not in progress or if no matching route has yet been found. This feature is used to save resources by removing the need to perform passive route discovery on low-RAM devices.

If this flag is set, then isRouteAvailable(MediaRouteSelector, int) will only return true if a matching route has actually been discovered.

Constant Value: 2 (0x00000002)

CALLBACK_FLAG_FORCE_DISCOVERY

public static final int CALLBACK_FLAG_FORCE_DISCOVERY

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Request passive route discovery while this callback is registered, even on low-RAM devices.

This flag has a significant performance impact on low-RAM devices since it may cause many media route providers to be started simultaneously. It is much better to use CALLBACK_FLAG_REQUEST_DISCOVERY instead to avoid performing passive discovery on these devices altogether. Refer to addCallback for details.

Constant Value: 8 (0x00000008)

CALLBACK_FLAG_PERFORM_ACTIVE_SCAN

public static final int CALLBACK_FLAG_PERFORM_ACTIVE_SCAN

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Actively scan for routes while this callback is registered.

When this flag is specified, the media router will actively scan for new routes. Certain routes, such as wifi display routes, may not be discoverable except when actively scanning. This flag is typically used when the route picker dialog has been opened by the user to ensure that the route information is up to date.

Active scanning may consume a significant amount of power and may have intrusive effects on wireless connectivity. Therefore it is important that active scanning only be requested when it is actually needed to satisfy a user request to discover and select a new route.

This flag implies CALLBACK_FLAG_REQUEST_DISCOVERY but performing active scans is much more expensive than a normal discovery request.

Constant Value: 1 (0x00000001)

CALLBACK_FLAG_REQUEST_DISCOVERY

public static final int CALLBACK_FLAG_REQUEST_DISCOVERY

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Request passive route discovery while this callback is registered, except on low-RAM devices.

When this flag is specified, the media router will try to discover routes. Although route discovery is intended to be efficient, checking for new routes may result in some network activity and could slowly drain the battery. Therefore applications should only specify CALLBACK_FLAG_REQUEST_DISCOVERY when they are running in the foreground and would like to provide the user with the option of connecting to new routes.

Applications should typically add a callback using this flag in the activity's onStart method and remove it in the onStop method. The MediaRouteDiscoveryFragment fragment may also be used for this purpose.

On low-RAM devices this flag will be ignored. Refer to addCallback for details.

Constant Value: 4 (0x00000004)

CALLBACK_FLAG_UNFILTERED_EVENTS

public static final int CALLBACK_FLAG_UNFILTERED_EVENTS

Flag for addCallback(MediaRouteSelector, MediaRouter.Callback): Do not filter route events.

When this flag is specified, the callback will be invoked for events that affect any route even if they do not match the callback's filter.

Constant Value: 2 (0x00000002)

UNSELECT_REASON_DISCONNECTED

public static final int UNSELECT_REASON_DISCONNECTED

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the user pressed the disconnect button to disconnect and keep playing.

Constant Value: 1 (0x00000001)

UNSELECT_REASON_ROUTE_CHANGED

public static final int UNSELECT_REASON_ROUTE_CHANGED

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the user selected a different route.

Constant Value: 3 (0x00000003)

UNSELECT_REASON_STOPPED

public static final int UNSELECT_REASON_STOPPED

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the user pressed the stop casting button.

Media should stop when this reason is passed.

Constant Value: 2 (0x00000002)

UNSELECT_REASON_UNKNOWN

public static final int UNSELECT_REASON_UNKNOWN

Passed to MediaRouteProvider.RouteController.onUnselect(int), MediaRouter.Callback.onRouteUnselected(MediaRouter, RouteInfo, int) and MediaRouter.Callback.onRouteSelected(MediaRouter, RouteInfo, int) when the reason the route was unselected is unknown.

Constant Value: 0 (0x00000000)

Public methods

addCallback

public void addCallback (MediaRouteSelector selector, 
                MediaRouter.Callback callback)

Registers a callback to discover routes that match the selector and to receive events when they change.

This is a convenience method that has the same effect as calling addCallback(MediaRouteSelector, Callback, int) without flags.

Parameters
selector MediaRouteSelector: A route selector that indicates the kinds of routes that the callback would like to discover.

callback MediaRouter.Callback: The callback to add.

addCallback

public void addCallback (MediaRouteSelector selector, 
                MediaRouter.Callback callback, 
                int flags)

Registers a callback to discover routes that match the selector and to receive events when they change.

The selector describes the kinds of routes that the application wants to discover. For example, if the application wants to use live audio routes then it should include the live audio media control intent category in its selector when it adds a callback to the media router. The selector may include any number of categories.

If the callback has already been registered, then the selector is added to the set of selectors being monitored by the callback.

By default, the callback will only be invoked for events that affect routes that match the specified selector. Event filtering may be disabled by specifying the CALLBACK_FLAG_UNFILTERED_EVENTS flag when the callback is registered.

Applications should use the isRouteAvailable(MediaRouteSelector, int) method to determine whether is it possible to discover a route with the desired capabilities and therefore whether the media route button should be shown to the user.

The CALLBACK_FLAG_REQUEST_DISCOVERY flag should be used while the application is in the foreground to request that passive discovery be performed if there are sufficient resources to allow continuous passive discovery. On low-RAM devices this flag will be ignored to conserve resources.

The CALLBACK_FLAG_FORCE_DISCOVERY flag should be used when passive discovery absolutely must be performed, even on low-RAM devices. This flag has a significant performance impact on low-RAM devices since it may cause many media route providers to be started simultaneously. It is much better to use CALLBACK_FLAG_REQUEST_DISCOVERY instead to avoid performing passive discovery on these devices altogether.

The CALLBACK_FLAG_PERFORM_ACTIVE_SCAN flag should be used when the media route chooser dialog is showing to confirm the presence of available routes that the user may connect to. This flag may use substantially more power.

Example

 public class MyActivity extends Activity {
     private MediaRouter mRouter;
     private MediaRouter.Callback mCallback;
     private MediaRouteSelector mSelector;

     // Add the callback on start to tell the media router what kinds of routes
     // the application is interested in so that it can get events about media routing changes
     // from the system.
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);

         mRouter = MediaRouter.getInstance(this);
         mCallback = new MyCallback();
         mSelector = new MediaRouteSelector.Builder()
                 .addControlCategory(MediaControlIntent.CATEGORY_LIVE_AUDIO)
                 .addControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
                 .build();
         mRouter.addCallback(mSelector, mCallback, /* flags= */ 0);
     }

     // Add the callback flag CALLBACK_FLAG_REQUEST_DISCOVERY on start by calling
     // addCallback() again so that the media router can try to discover suitable ones.
     public void onStart() {
         super.onStart();

         mRouter.addCallback(mSelector, mCallback,
                 MediaRouter.CALLBACK_FLAG_REQUEST_DISCOVERY);

         MediaRouter.RouteInfo route = mRouter.updateSelectedRoute(mSelector);
         // do something with the route...
     }

     // Remove the callback flag CALLBACK_FLAG_REQUEST