MediaRouter

const val AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE = 1: Int

Flag for isRouteAvailable: 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.

const val AVAILABILITY_FLAG_REQUIRE_MATCH = 2: Int

Flag for isRouteAvailable: Require an actual route to be matched.

If this flag is not set, then isRouteAvailable 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 will only return true if a matching route has actually been discovered.

const val CALLBACK_FLAG_FORCE_DISCOVERY = 8: Int

Flag for addCallback: 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.

const val CALLBACK_FLAG_PERFORM_ACTIVE_SCAN = 1: Int

Flag for addCallback: 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.

const val CALLBACK_FLAG_REQUEST_DISCOVERY = 4: Int

Flag for addCallback: 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 this flag 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'sonStart 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.

const val CALLBACK_FLAG_UNFILTERED_EVENTS = 2: Int

Flag for addCallback: 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.

const val UNSELECT_REASON_DISCONNECTED = 1: Int

Passed to onUnselect, onRouteUnselected and onRouteSelected when the user pressed the disconnect button to disconnect and keep playing.

const val UNSELECT_REASON_ROUTE_CHANGED = 3: Int

Passed to onUnselect, onRouteUnselected and onRouteSelected when the user selected a different route.

const val UNSELECT_REASON_STOPPED = 2: Int

Passed to onUnselect, onRouteUnselected and onRouteSelected when the user pressed the stop casting button.

Media should stop when this reason is passed.

const val UNSELECT_REASON_UNKNOWN = 0: Int

Passed to onUnselect, onRouteUnselected and onRouteSelected when the reason the route was unselected is unknown.

@MainThread
fun addCallback(selector: MediaRouteSelector, callback: MediaRouter.Callback): Unit

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 without flags.

Must be called on the main thread.

@MainThread
fun addCallback(
    selector: MediaRouteSelector,
    callback: MediaRouter.Callback,
    flags: Int
): Unit

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 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. Once active scan is requested, it will be effective for 30 seconds and will be suppressed after the delay. If you need active scan after this duration, you have to add your callback again with the CALLBACK_FLAG_PERFORM_ACTIVE_SCAN flag.

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_DISCOVERY on stop by calling
    // addCallback() again in order to tell the media router that it no longer
    // needs to invest effort trying to discover routes of these kinds for now.
    public void onStop() {
        mRouter.addCallback(mSelector, mCallback, /* flags= */ 0);

        super.onStop();
    }

    // Remove the callback when the activity is destroyed.
    public void onDestroy() {
        mRouter.removeCallback(mCallback);

        super.onDestroy();
    }

    private final class MyCallback extends MediaRouter.Callback {
        // Implement callback methods as needed.
    }
}

Must be called on the main thread.

@MainThread
fun addProvider(providerInstance: MediaRouteProvider): Unit

Registers a media route provider within this application process.

The provider will be added to the list of providers that all MediaRouter instances within this process can use to discover routes.

Must be called on the main thread.

@MainThread
fun addRemoteControlClient(remoteControlClient: Any): Unit

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

The remote control client must have previously been registered with the audio manager using the AudioManager.registerRemoteControlClient method.

Must be called on the main thread.

@MainThread
fun getBluetoothRoute(): MediaRouter.RouteInfo?

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

Must be called on the main thread.

@MainThread
fun getDefaultRoute(): MediaRouter.RouteInfo

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

The system always provides a default route.

Must be called on the main thread.

@MainThread
java-static fun getInstance(context: Context): MediaRouter

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

The application is responsible for holding a strong reference to the returned MediaRouter instance, such as by storing the instance in a field of the android.app.Activity, to ensure that the media router remains alive as long as the application is using its features.

In other words, the support library only holds a weak reference to each media router instance. When there are no remaining strong references to the media router instance, all of its callbacks will be removed and route discovery will no longer be performed on its behalf.

Must be called on the main thread.

@MainThread
fun getProviders(): (Mutable)List<MediaRouter.ProviderInfo!>

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

Must be called on the main thread.

@MainThread
fun getRouterParams(): MediaRouterParams?

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

Must be called on the main thread.

@MainThread
fun getRoutes(): (Mutable)List<MediaRouter.RouteInfo!>

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

Must be called on the main thread.

@MainThread
fun getSelectedRoute(): MediaRouter.RouteInfo

Gets the currently selected route.

The application should examine the route's media control intent filters to assess the capabilities of the route before attempting to use it.

Example

public boolean playMovie() {
    MediaRouter mediaRouter = MediaRouter.getInstance(context);
    MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute();

    // First try using the remote playback interface, if supported.
    if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
        // The route supports remote playback.
        // Try to send it the Uri of the movie to play.
        Intent intent = new Intent(MediaControlIntent.ACTION_PLAY);
        intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
        intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4");
        if (route.supportsControlRequest(intent)) {
            route.sendControlRequest(intent, null);
            return true; // sent the request to play the movie
        }
    }

    // If remote playback was not possible, then play locally.
    if (route.supportsControlCategory(MediaControlIntent.CATEGORY_LIVE_VIDEO)) {
        // The route supports live video streaming.
        // Prepare to play content locally in a window or in a presentation.
        return playMovieInWindow();
    }

    // Neither interface is supported, so we can't play the movie to this route.
    return false;
}

Must be called on the main thread.

@MainThread
fun isRouteAvailable(selector: MediaRouteSelector, flags: Int): Boolean

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

This method returns true if there are any available routes that match the selector regardless of whether they are enabled or disabled. If the AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE flag is specified, then the method will only consider non-default routes.

On low-RAM devices this method 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. Use AVAILABILITY_FLAG_REQUIRE_MATCH to require an actual match.

Must be called on the main thread.

@MainThread
fun removeCallback(callback: MediaRouter.Callback): Unit

Removes the specified callback. It will no longer receive events about changes to media routes.

Must be called on the main thread.

@MainThread
fun removeProvider(providerInstance: MediaRouteProvider): Unit

Unregisters a media route provider within this application process.

The provider will be removed from the list of providers that all MediaRouter instances within this process can use to discover routes.

Must be called on the main thread.

@MainThread
fun removeRemoteControlClient(remoteControlClient: Any): Unit

Removes a remote control client.

Must be called on the main thread.

@MainThread
fun selectRoute(route: MediaRouter.RouteInfo): Unit

Selects the specified route.

Must be called on the main thread.

@MainThread
fun setMediaSession(mediaSession: Any?): Unit

Equivalent to setMediaSessionCompat, except it takes an .

@MainThread
fun setMediaSessionCompat(mediaSession: MediaSessionCompat?): Unit

Associates the provided MediaSessionCompat to this router.

Maintains the internal state of the provided session to signal it's linked to the currently selected route at any given time. This guarantees that the system UI shows the correct route name when applicable.

Must be called on the main thread.

@MainThread
fun setOnPrepareTransferListener(
    listener: MediaRouter.OnPrepareTransferListener?
): Unit

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

Must be called on the main thread.

@MainThread
fun setRouteListingPreference(
    routeListingPreference: RouteListingPreference?
): Unit

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

This method does nothing on devices running API 33 or older.

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 immediately after creating an instance and immediately after receiving any route list changes 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 (which reflect in the system's Output Switcher).

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 change how routes are listed using dynamic criteria. For example, you can disable routing while an ad is playing).

@MainThread
fun setRouterParams(params: MediaRouterParams?): Unit

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

Must be called on the main thread.

@MainThread
fun unselect(reason: Int): Unit

Unselects the current route and selects the default route instead.

The reason given must be one of:

• UNSELECT_REASON_UNKNOWN
• UNSELECT_REASON_DISCONNECTED
• UNSELECT_REASON_STOPPED
• UNSELECT_REASON_ROUTE_CHANGED

Must be called on the main thread.

@MainThread
fun updateSelectedRoute(selector: MediaRouteSelector): MediaRouter.RouteInfo

Returns the selected route if it matches the specified selector, otherwise selects the default route and returns it. If there is one live audio route (usually Bluetooth A2DP), it will be selected instead of default route.

Must be called on the main thread.