MediaControlIntent

public final class MediaControlIntent
extends Object

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


Constants for media control intents.

This class declares a set of standard media control intent categories and actions that applications can use to identify the capabilities of media routes and control them.

Media control intent categories

Media control intent categories specify means by which applications can send media to the destination of a media route. Categories are sometimes referred to as describing "types" or "kinds" of routes.

For example, if a route supports the remote playback category, then an application can ask it to play media remotely by sending a play or enqueue intent with the Uri of the media content to play. Such a route may then be referred to as a "remote playback route" because it supports remote playback requests. It is common for a route to support multiple categories of requests at the same time, such as live audio and live video.

The following standard route categories are defined.

  • Live audio: The route supports streaming live audio from the device to the destination. Live audio routes include local speakers and Bluetooth headsets.
  • Live video: The route supports streaming live video from the device to the destination. Live video routes include local displays and wireless displays that support mirroring and presentations. Live video routes typically also support live audio capabilities.
  • Remote playback: The route supports sending remote playback requests for media content to the destination. The content to be played is identified by a Uri and mime-type.

Media route providers may define custom media control intent categories of their own in addition to the standard ones. Custom categories can be used to provide a variety of features to applications that recognize and know how to use them. For example, a media route provider might define a custom category to indicate that its routes support a special device-specific control interface in addition to other standard features.

Applications can determine which categories a route supports by using the MediaRouter.RouteInfo.supportsControlCategory or MediaRouter.RouteInfo.getControlFilters methods. Applications can also specify the types of routes that they want to use by creating media route selectors that contain the desired categories and are used to filter routes in several parts of the media router API.

Media control intent actions

Media control intent actions specify particular functions that applications can ask the destination of a media route to perform. Media route control requests take the form of intents in a similar manner to other intents used to start activities or send broadcasts. The difference is that media control intents are directed to routes rather than activity or broadcast receiver components.

Each media route control intent specifies an action, a category and some number of parameters that are supplied as extras. Applications send media control requests to routes using the MediaRouter.RouteInfo.sendControlRequest method and receive results via a callback.

All media control intent actions are associated with the media control intent categories that support them. Thus only remote playback routes may perform remote playback actions. The documentation of each action specifies the category to which the action belongs, the parameters it requires, and the results it returns.

Live audio and live video routes

Live audio and live video routes present media using standard system interfaces such as audio streams, presentations or display mirroring. These routes are the easiest to use because applications simply render content locally on the device and the system streams it to the route destination automatically.

In most cases, applications can stream content to live audio and live video routes in the same way they would play the content locally without any modification. However, applications may also be able to take advantage of more sophisticated features such as second-screen presentation APIs that are particular to these routes.

Remote playback routes

Remote playback routes present media remotely by playing content from a Uri. These routes destinations take responsibility for fetching and rendering content on their own. Applications do not render the content themselves; instead, applications send control requests to initiate play, pause, resume, or stop media items and receive status updates as they change state.

Sessions

Each remote media playback action is conducted within the scope of a session. Sessions are used to prevent applications from accidentally interfering with one another because at most one session can be valid at a time.

A session can be created using the start session action and terminated using the end session action when the route provides explicit session management features.

Explicit session management was added in a later revision of the protocol so not all routes support it. If the route does not support explicit session management then implicit session management may still be used. Implicit session management relies on the use of the play and enqueue actions which have the side-effect of c