added in version 22.1.0
belongs to Maven artifact com.android.support:mediarouter-v7:28.0.0-alpha1

MediaControlIntent

public final class MediaControlIntent
extends Object

java.lang.Object
   ↳ android.support.v7.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 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 play or 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 seek or 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 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 ACTION_ENQUEUE action is declared in the route's control filter using RouteInfo.supportsControlRequest.

If the 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 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 application'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 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.

  • 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.
  • Seek: Sets the content playback position of a specific media item.
  • Get status: Gets the status of a media item including the item's current playback position and progress.
  • Pause: Pauses playback of the queue.
  • Resume: Resumes playback of the queue.
  • 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.

  • 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.
  • 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.

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.

Summary

Constants

String ACTION_END_SESSION

Remote playback media control action: End session.

String ACTION_ENQUEUE

Remote playback media control action: Enqueue media item.

String ACTION_GET_SESSION_STATUS

Remote playback media control action: Get media session status information.

String ACTION_GET_STATUS

Remote playback media control action: Get media item playback status and progress information.

String ACTION_PAUSE

Remote playback media control action: Pause media playback.

String ACTION_PLAY

Remote playback media control action: Play media item.

String ACTION_REMOVE

Remote playback media control action: Remove media item from session's queue.

String ACTION_RESUME

Remote playback media control action: Resume media playback (unpause).

String ACTION_SEEK

Remote playback media control action: Seek media item to a new playback position.

String ACTION_SEND_MESSAGE

Custom media control action: Send EXTRA_MESSAGE.

String ACTION_START_SESSION

Remote playback media control action: Start session.

String ACTION_STOP

Remote playback media control action: Stop media playback (clear queue and unpause).

String CATEGORY_LIVE_AUDIO

Media control category: Live audio.

String CATEGORY_LIVE_VIDEO

Media control category: Live video.

String CATEGORY_REMOTE_PLAYBACK

Media control category: Remote playback.

int ERROR_INVALID_ITEM_ID

Error code: The item id specified in the request was invalid.

int ERROR_INVALID_SESSION_ID

Error code: The session id specified in the request was invalid.

int ERROR_UNKNOWN

Error code: An unknown error occurred.

int ERROR_UNSUPPORTED_OPERATION

Error code: The operation is not supported.

String EXTRA_ERROR_CODE

Integer extra: Error code.

String EXTRA_ITEM_CONTENT_POSITION

Long extra: Media item content position.

String EXTRA_ITEM_HTTP_HEADERS

Bundle extra: HTTP request headers.

String EXTRA_ITEM_ID

Bundle extra: Media item id.

String EXTRA_ITEM_METADATA

Bundle extra: Media item metadata.

String EXTRA_ITEM_STATUS

Bundle extra: Media item status.

String EXTRA_ITEM_STATUS_UPDATE_RECEIVER

Bundle extra: Media item status update receiver.

String EXTRA_MESSAGE

Bundle extra: Message.

String EXTRA_MESSAGE_RECEIVER

Bundle extra: Media message receiver.

String EXTRA_SESSION_ID

Bundle extra: Media session id.

String EXTRA_SESSION_STATUS

Bundle extra: Media session status.

String EXTRA_SESSION_STATUS_UPDATE_RECEIVER

Bundle extra: Media session status update receiver.

Inherited methods

From class java.lang.Object

Constants

ACTION_END_SESSION

added in version 22.1.0
String ACTION_END_SESSION

Remote playback media control action: End session.

Used with routes that support remote playback media control.

This action causes a remote playback route to end the specified session. The session becomes no longer valid and the route ceases to be under control of the session.

If successful, the status of the session is set to SESSION_STATE_ENDED and a status update is sent to the session's status update receiver.

Additionally, the status of all media items in the queue is set to canceled and a status update is sent to the appropriate status update receivers indicating the new status of each item.

Request parameters

Result data

Errors

This action returns an error if the session id is unknown or no longer valid. In other words, it is an error to attempt to end a session other than the current session.

Constant Value: "android.media.intent.action.END_SESSION"

ACTION_ENQUEUE

added in version 22.1.0
String ACTION_ENQUEUE

Remote playback media control action: Enqueue media item.

Used with routes that support remote playback media control.

This action works just like play except that it does not clear the queue or reset the pause state when it enqueues the new media item into the session's playback queue. This action only enqueues a media item with no other side-effects on the queue.

If the queue is currently empty and then the item will play immediately (assuming the queue is not paused). Otherwise, the item will play after all earlier items in the queue have finished or been removed.

The enqueue action can be used to create new sessions just like play. Its parameters and results are also the same. Only the queuing behavior is different.

See also:

Constant Value: "android.media.intent.action.ENQUEUE"

ACTION_GET_SESSION_STATUS

added in version 22.1.0
String ACTION_GET_SESSION_STATUS

Remote playback media control action: Get media session status information.

Used with routes that support