| 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 {@link #CATEGORY_REMOTE_PLAYBACK remote playback category},
then an application can ask it to play media remotely by sending a
{@link #ACTION_PLAY play} or {@link #ACTION_ENQUEUE 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.
- {@link #CATEGORY_LIVE_AUDIO Live audio}: The route supports streaming live audio
from the device to the destination. Live audio routes include local speakers
and Bluetooth headsets.
- {@link #CATEGORY_LIVE_VIDEO 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
{@link android.app.Presentation presentations}. Live video routes typically also
support live audio capabilities.
- {@link #CATEGORY_REMOTE_PLAYBACK 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
{@link MediaRouter.RouteInfo#supportsControlCategory MediaRouter.RouteInfo.supportsControlCategory}
or {@link MediaRouter.RouteInfo#getControlFilters MediaRouter.RouteInfo.getControlFilters}
methods. Applications can also specify the types of routes that they want to use by
creating {@link MediaRouteSelector 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
{@link MediaRouter.RouteInfo#sendControlRequest 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
{@link #CATEGORY_LIVE_AUDIO Live audio} and {@link #CATEGORY_LIVE_VIDEO live video}
routes present media using standard system interfaces such as audio streams,
{@link android.app.Presentation 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
{@link #CATEGORY_REMOTE_PLAYBACK 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 {@link #ACTION_START_SESSION start session action}
and terminated using the {@link #ACTION_END_SESSION 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 {@link #ACTION_PLAY play} and {@link #ACTION_ENQUEUE enqueue}
actions which have the side-effect of creating a new session if none is provided
as argument.
When a new session is created, the previous session is invalidated and any ongoing
media playback is stopped before the requested action is performed. Any attempt
to use an invalidated session will result in an error. (Protocol implementations
are encouraged to aggressively discard information associated with invalidated sessions
since it is no longer of use.)
Each session is identified by a unique session id that may be used to control
the session using actions such as pause, resume, stop and end session.
Media items
Each successful {@link #ACTION_PLAY play} or {@link #ACTION_ENQUEUE enqueue} action
returns a unique media item id that an application can use to monitor and control
playback. The media item id may be passed to other actions such as
{@link #ACTION_SEEK seek} or {@link #ACTION_GET_STATUS get status}. It will also appear
as a parameter in status update broadcasts to identify the associated playback request.
Each media item is scoped to the session in which it was created. Therefore media item
ids are only ever used together with session ids. Media item ids are meaningless
on their own. When the session is invalidated, all of its media items are also
invalidated.
The playback queue
Each session has its own playback queue that consists of the media items that
are pending, playing, buffering or paused. Items are added to the queue when
a playback request is issued. Items are removed from the queue when they are no
longer eligible for playback (enter terminal states).
As described in the {@link MediaItemStatus} class, media items initially
start in a pending state, transition to the playing (or buffering or paused) state
during playback, and end in a finished, canceled, invalidated or error state.
Once the current item enters a terminal state, playback proceeds on to the
next item.
The application should determine whether the route supports queuing by checking
whether the {@link #ACTION_ENQUEUE} action is declared in the route's control filter
using {@link MediaRouter.RouteInfo#supportsControlRequest RouteInfo.supportsControlRequest}.
If the {@link #ACTION_ENQUEUE} action is supported by the route, then the route promises
to allow at least two items (possibly more) to be enqueued at a time. Enqueued items play
back to back one after the other as the previous item completes. Ideally there should
be no audible pause between items for standard audio content types.
If the {@link #ACTION_ENQUEUE} action is not supported by the route, then the queue
effectively contains at most one item at a time. Each play action has the effect of
clearing the queue and resetting its state before the next item is played.
Impact of pause, resume, stop and play actions on the playback queue
The pause, resume and stop actions affect the session's whole queue. Pause causes
the playback queue to be suspended no matter which item is currently playing.
Resume reverses the effects of pause. Stop clears the queue and also resets
the pause flag just like resume.
As described earlier, the play action has the effect of clearing the queue
and completely resetting its state (like the stop action) then enqueuing a
new media item to be played immediately. Play is therefore equivalent
to stop followed by an action to enqueue an item.
The play action is also special in that it can be used to create new sessions.
An application with simple needs may find that it only needs to use play
(and occasionally stop) to control playback.
Resolving conflicts between applications
When an application has a valid session, it is essentially in control of remote playback
on the route. No other application can view or modify the remote playback state
of that applicaton's session without knowing its id.
However, other applications can perform actions that have the effect of stopping
playback and invalidating the current session. When this occurs, the former application
will be informed that it has lost control by way of individual media item status
update broadcasts that indicate that its queued media items have become
{@link MediaItemStatus#PLAYBACK_STATE_INVALIDATED invalidated}. This broadcast
implies that playback was terminated abnormally by an external cause.
Applications should handle conflicts conservatively to allow other applications to
smoothly assume control over the route. When a conflict occurs, the currently playing
application should release its session and allow the new application to use the
route until such time as the user intervenes to take over the route again and begin
a new playback session.
Basic actions
The following basic actions must be supported (all or nothing) by all remote
playback routes. These actions form the basis of the remote playback protocol
and are required in all implementations.
- {@link #ACTION_PLAY Play}: Starts playing content specified by a given Uri
and returns a new media item id to describe the request. Implicitly creates a new
session if no session id was specified as a parameter.
- {@link #ACTION_SEEK Seek}: Sets the content playback position of a specific media item.
- {@link #ACTION_GET_STATUS Get status}: Gets the status of a media item
including the item's current playback position and progress.
- {@link #ACTION_PAUSE Pause}: Pauses playback of the queue.
- {@link #ACTION_RESUME Resume}: Resumes playback of the queue.
- {@link #ACTION_STOP Stop}: Stops playback, clears the queue, and resets the
pause state.
Queue actions
The following queue actions must be supported (all or nothing) by remote
playback routes that offer optional queuing capabilities.
- {@link #ACTION_ENQUEUE Enqueue}: Enqueues content specified by a given Uri
and returns a new media item id to describe the request. Implicitly creates a new
session if no session id was specified as a parameter.
- {@link #ACTION_REMOVE Remove}: Removes a specified media item from the queue.
Session actions
The following session actions must be supported (all or nothing) by remote
playback routes that offer optional session management capabilities.
- {@link #ACTION_START_SESSION Start session}: Starts a new session explicitly.
- {@link #ACTION_GET_SESSION_STATUS Get session status}: Gets the status of a session.
- {@link #ACTION_END_SESSION End session}: Ends a session explicitly.
Implementation note
Implementations of the remote playback protocol must implement all of the
documented actions, parameters and results. Note that the documentation is written from
the perspective of a client of the protocol. In particular, whenever a parameter
is described as being "optional", it is only from the perspective of the client.
Compliant media route provider implementations of this protocol must support all
of the features described herein.
| 