MediaControlIntent

Artifact: androidx.mediarouter:mediarouter

Added in 1.1.0

Kotlin |Java

public final class 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.

Start session: Starts a new session explicitly.
Get session status: Gets the status of a 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.

Summary

Constants
`static final String`	`ACTION_END_SESSION = "android.media.intent.action.END_SESSION"` Remote playback media control action: End session.
`static final String`	`ACTION_ENQUEUE = "android.media.intent.action.ENQUEUE"` Remote playback media control action: Enqueue media item.
`static final String`	`ACTION_GET_SESSION_STATUS = "android.media.intent.action.GET_SESSION_STATUS"` Remote playback media control action: Get media session status information.
`static final String`	`ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS"` Remote playback media control action: Get media item playback status and progress information.
`static final String`	`ACTION_PAUSE = "android.media.intent.action.PAUSE"` Remote playback media control action: Pause media playback.
`static final String`	`ACTION_PLAY = "android.media.intent.action.PLAY"` Remote playback media control action: Play media item.
`static final String`	`ACTION_REMOVE = "android.media.intent.action.REMOVE"` Remote playback media control action: Remove media item from session's queue.
`static final String`	`ACTION_RESUME = "android.media.intent.action.RESUME"` Remote playback media control action: Resume media playback (unpause).
`static final String`	`ACTION_SEEK = "android.media.intent.action.SEEK"` Remote playback media control action: Seek media item to a new playback position.
`static final String`	`ACTION_SEND_MESSAGE = "android.media.intent.action.SEND_MESSAGE"` Custom media control action: Send `EXTRA_MESSAGE`.
`static final String`	`ACTION_START_SESSION = "android.media.intent.action.START_SESSION"` Remote playback media control action: Start session.
`static final String`	`ACTION_STOP = "android.media.intent.action.STOP"` Remote playback media control action: Stop media playback (clear queue and unpause).
`static final String`	`CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"` Media control category: Live audio.
`static final String`	`CATEGORY_LIVE_VIDEO = "android.media.intent.category.LIVE_VIDEO"` Media control category: Live video.
`static final String`	`CATEGORY_REMOTE_PLAYBACK = "android.media.intent.category.REMOTE_PLAYBACK"` Media control category: Remote playback.
`static final int`	`ERROR_INVALID_ITEM_ID = 3` Error code: The item id specified in the request was invalid.
`static final int`	`ERROR_INVALID_SESSION_ID = 2` Error code: The session id specified in the request was invalid.
`static final int`	`ERROR_UNKNOWN = 0` Error code: An unknown error occurred.
`static final int`	`ERROR_UNSUPPORTED_OPERATION = 1` Error code: The operation is not supported.
`static final String`	`EXTRA_ERROR_CODE = "android.media.intent.extra.ERROR_CODE"` Integer extra: Error code.
`static final String`	`EXTRA_ITEM_CONTENT_POSITION = "android.media.intent.extra.ITEM_POSITION"` Long extra: Media item content position.
`static final String`	`EXTRA_ITEM_HTTP_HEADERS = "android.media.intent.extra.HTTP_HEADERS"` Bundle extra: HTTP request headers.
`static final String`	`EXTRA_ITEM_ID = "android.media.intent.extra.ITEM_ID"` Bundle extra: Media item id.
`static final String`	`EXTRA_ITEM_METADATA = "android.media.intent.extra.ITEM_METADATA"` Bundle extra: Media item metadata.
`static final String`	`EXTRA_ITEM_STATUS = "android.media.intent.extra.ITEM_STATUS"` Bundle extra: Media item status.
`static final String`	`EXTRA_ITEM_STATUS_UPDATE_RECEIVER = "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"` Bundle extra: Media item status update receiver.
`static final String`	`EXTRA_MESSAGE = "android.media.intent.extra.MESSAGE"` Bundle extra: Message.
`static final String`	`EXTRA_MESSAGE_RECEIVER = "android.media.intent.extra.MESSAGE_RECEIVER"` Bundle extra: Media message receiver.
`static final String`	`EXTRA_SESSION_ID = "android.media.intent.extra.SESSION_ID"` Bundle extra: Media session id.
`static final String`	`EXTRA_SESSION_STATUS = "android.media.intent.extra.SESSION_STATUS"` Bundle extra: Media session status.
`static final String`	`EXTRA_SESSION_STATUS_UPDATE_RECEIVER = "android.media.intent.extra.SESSION_STATUS_UPDATE_RECEIVER"` Bundle extra: Media session status update receiver.

Constants

ACTION_END_SESSION

Added in 1.1.0

public static final String ACTION_END_SESSION = "android.media.intent.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

EXTRA_SESSION_ID(required): Specifies the session id of the session to end.

Result data

EXTRA_SESSION_STATUS(always returned): Specifies the status of the media session.

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.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`

ACTION_ENQUEUE

Added in 1.1.0

public static final String ACTION_ENQUEUE = "android.media.intent.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
`ACTION_PLAY`

ACTION_GET_SESSION_STATUS

Added in 1.1.0

public static final String ACTION_GET_SESSION_STATUS = "android.media.intent.action.GET_SESSION_STATUS"

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

Used with routes that support remote playback media control.

This action asks a remote playback route to provide updated status information about the specified media session.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session whose status is to be retrieved.

Result data

EXTRA_SESSION_STATUS(always returned): Specifies the current status of the media session.

Errors

This action returns an error if the session id is unknown or no longer valid.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`
`EXTRA_SESSION_STATUS_UPDATE_RECEIVER`

ACTION_GET_STATUS

Added in 1.1.0

public static final String ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS"

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

Used with routes that support remote playback media control.

This action asks a remote playback route to provide updated playback status and progress information about the specified media item.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session to which the media item belongs.
EXTRA_ITEM_ID(required): Specifies the media item id of the media item to query.

Result data

EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.
EXTRA_ITEM_STATUS(always returned): Specifies the current status of the media item.

Errors

This action returns an error if the session id or media item id are unknown or no longer valid.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`
`EXTRA_ITEM_STATUS_UPDATE_RECEIVER`

ACTION_PAUSE

Added in 1.1.0

public static final String ACTION_PAUSE = "android.media.intent.action.PAUSE"

Remote playback media control action: Pause media playback.

Used with routes that support remote playback media control.

This action causes the playback queue of the specified session to be paused.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session whose playback queue is to be paused.

Result data

EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.

Errors

This action returns an error if the session id is unknown or no longer valid.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`
`ACTION_RESUME`

ACTION_PLAY

Added in 1.1.0

public static final String ACTION_PLAY = "android.media.intent.action.PLAY"

Remote playback media control action: Play media item.

Used with routes that support remote playback media control.

This action causes a remote playback route to start playing content with the Uri specified in the Intent's data uri. The action returns a media session id and media item id which can be used to control playback using other remote playback actions.

Once initiated, playback of the specified content will be managed independently by the destination. The application will receive status updates as the state of the media item changes.

If the data uri specifies an HTTP or HTTPS scheme, then the destination is responsible for following HTTP redirects to a reasonable depth of at least 3 levels as might typically be handled by a web browser. If an HTTP error occurs, then the destination should send a status update back to the client indicating the errorplayback state.

One item at a time

Each successful play action replaces the previous play action. If an item is already playing, then it is canceled, the session's playback queue is cleared and the new item begins playing immediately (regardless of whether the previously playing item had been paused).

Play is therefore equivalent to stop followed by an action to enqueue a new media item to be played immediately.

Sessions

This request has the effect of implicitly creating a media session whenever the application does not specify the session id parameter. Because there can only be at most one valid session at a time, creating a new session has the side-effect of invalidating any existing sessions and their media items, then handling the playback request with a new session.

If the application specifies an invalid session id, then an error is returned. When this happens, the application should assume that its session is no longer valid. To obtain a new session, the application may try again and omit the session id parameter. However, the application should only retry requests due to an explicit action performed by the user, such as the user clicking on a "play" button in the UI, since another application may be trying to take control of the route and the former application should try to stay out of its way.

For more information on sessions, queues and media items, please refer to the class documentation.

Request parameters

EXTRA_SESSION_ID(optional): Specifies the session id of the session to which the playback request belongs. If omitted, a new session is created implicitly.
EXTRA_ITEM_CONTENT_POSITION(optional): Specifies the initial content playback position as a long integer number of milliseconds from the beginning of the content.
EXTRA_ITEM_METADATA(optional): Specifies metadata associated with the content such as the title of a song.
EXTRA_ITEM_STATUS_UPDATE_RECEIVER(optional): Specifies a PendingIntent for a broadcast receiver that will receive status updates about the media item.

Result data

EXTRA_SESSION_ID(always returned): Specifies the session id of the session that was affected by the request. This will be a new session in the case where no session id was supplied as a parameter.
EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.
EXTRA_ITEM_ID(always returned): Specifies an opaque string identifier to use to refer to the media item in subsequent requests such as ACTION_GET_STATUS.
EXTRA_ITEM_STATUS(always returned): Specifies the initial status of the new media item.

Status updates

If the client supplies an item status update receiver then the media route provider is responsible for sending status updates to the receiver when significant media item state changes occur such as when playback starts or stops. The receiver will not be invoked for content playback position changes. The application may retrieve the current playback position when necessary using the ACTION_GET_STATUS request.

Refer to MediaItemStatus for details.

Errors

This action returns an error if a session id was provided but is unknown or no longer valid, if the item Uri or content type is not supported, or if any other arguments are invalid.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

Example

MediaRouter mediaRouter = MediaRouter.getInstance(context);
MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute();
Intent intent = new Intent(MediaControlIntent.ACTION_PLAY);
intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
intent.setDataAndType(Uri.parse("http://example.com/videos/movie.mp4"), "video/mp4");
if (route.supportsControlRequest(intent)) {
    MediaRouter.ControlRequestCallback callback = new MediaRouter.ControlRequestCallback() {
        public void onResult(Bundle data) {
            // The request succeeded.
            // Playback may be controlled using the returned session and item id.
            String sessionId = data.getString(MediaControlIntent.EXTRA_SESSION_ID);
            String itemId = data.getString(MediaControlIntent.EXTRA_ITEM_ID);
            MediaItemStatus status = MediaItemStatus.fromBundle(data.getBundle(
                    MediaControlIntent.EXTRA_ITEM_STATUS));
            // ...
        }

        public void onError(String message, Bundle data) {
            // An error occurred!
        }
    };
    route.sendControlRequest(intent, callback);
}

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`
`ACTION_SEEK`
`ACTION_GET_STATUS`
`ACTION_PAUSE`
`ACTION_RESUME`
`ACTION_STOP`

ACTION_REMOVE

Added in 1.1.0

public static final String ACTION_REMOVE = "android.media.intent.action.REMOVE"

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

Used with routes that support remote playback media control.

This action asks a remote playback route to remove the specified media item from the session's playback queue. If the current item is removed, then playback will proceed to the next media item (assuming the queue has not been paused).

This action does not affect the pause state of the queue. If the queue was paused then it remains paused (even if it is now empty) until a resume, stop or play action is issued that causes the pause state to be cleared.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session to which the media item belongs.
EXTRA_ITEM_ID(required): Specifies the media item id of the media item to remove.

Result data

EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.
EXTRA_ITEM_STATUS(always returned): Specifies the new status of the media item.

Errors

This action returns an error if the session id or media item id are unknown or no longer valid, or if the media item is in a terminal state (and therefore no longer in the queue).

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`

ACTION_RESUME

Added in 1.1.0

public static final String ACTION_RESUME = "android.media.intent.action.RESUME"

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

Used with routes that support remote playback media control.

This action causes the playback queue of the specified session to be resumed. Reverses the effects of ACTION_PAUSE.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session whose playback queue is to be resumed.

Result data

EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.

Errors

This action returns an error if the session id is unknown or no longer valid.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`
`ACTION_PAUSE`

ACTION_SEEK

Added in 1.1.0

public static final String ACTION_SEEK = "android.media.intent.action.SEEK"

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

Used with routes that support remote playback media control.

This action causes a remote playback route to modify the current playback position of the specified media item.

This action only affects the playback position of the media item; not its playback state. If the playback queue is paused, then seeking sets the position but the item remains paused. Likewise if the item is playing, then seeking will cause playback to jump to the new position and continue playing from that point. If the item has not yet started playing, then the new playback position is remembered by the queue and used as the item's initial content position when playback eventually begins.

If successful, the media item's playback position is changed.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session to which the media item belongs.
EXTRA_ITEM_ID(required): Specifies the media item id of the media item to seek.
EXTRA_ITEM_CONTENT_POSITION(required): Specifies the new content position for playback as a long integer number of milliseconds from the beginning of the content.

Result data

EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.
EXTRA_ITEM_STATUS(always returned): Specifies the new status of the media item.

Errors

This action returns an error if the session id or media item id are unknown or no longer valid, if the content position is invalid, or if the media item is in a terminal state.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`

ACTION_SEND_MESSAGE

Added in 1.1.0

public static final String ACTION_SEND_MESSAGE = "android.media.intent.action.SEND_MESSAGE"

Custom media control action: Send EXTRA_MESSAGE.

This action asks a route to handle a message described by EXTRA_MESSAGE.

Request parameters

EXTRA_SESSION_ID(required): Specifies the session id of the session to which will handle this message.
EXTRA_MESSAGE(required): Specifies the message to send.

Result data

Any messages defined by each media route provider.

Errors

Any error messages defined by each media route provider.

See also
`sendControlRequest`

ACTION_START_SESSION

Added in 1.1.0

public static final String ACTION_START_SESSION = "android.media.intent.action.START_SESSION"

Remote playback media control action: Start session.

Used with routes that support remote playback media control.

This action causes a remote playback route to invalidate the current session and start a new session. The new session initially has an empty queue.

If successful, the status of all media items in the previous session's queue is set to invalidated and a status update is sent to the appropriate status update receivers indicating the new status of each item. The previous session becomes no longer valid and the new session takes control of the route.

Request parameters

EXTRA_SESSION_STATUS_UPDATE_RECEIVER(optional): Specifies a PendingIntent for a broadcast receiver that will receive status updates about the media session.
EXTRA_MESSAGE_RECEIVER(optional): Specifies a PendingIntent for a broadcast receiver that will receive messages from the media session.

Result data

EXTRA_SESSION_ID(always returned): Specifies the session id of the session that was started by the request. This will always be a brand new session distinct from any other previously created sessions.
EXTRA_SESSION_STATUS(always returned): Specifies the status of the media session.

Status updates

If the client supplies a status update receiver then the media route provider is responsible for sending status updates to the receiver when significant media session state changes occur such as when the session's queue is paused or resumed or when the session is terminated or invalidated.

Refer to MediaSessionStatus for details.

Custom messages

If the client supplies a message receiver then the media route provider is responsible for sending messages to the receiver when the session has any messages to send.

Refer to EXTRA_MESSAGE for details.

Errors

This action returns an error if the session could not be created.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`

ACTION_STOP

Added in 1.1.0

public static final String ACTION_STOP = "android.media.intent.action.STOP"

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

Used with routes that support remote playback media control.

This action causes a remote playback route to stop playback, cancel and remove all media items from the session's media item queue and, reset the queue's pause state.

If successful, 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

EXTRA_SESSION_ID(required): Specifies the session id of the session whose playback queue is to be stopped (cleared and unpaused).

Result data

EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.

Errors

This action returns an error if the session id is unknown or no longer valid.

EXTRA_ERROR_CODE(optional): Specifies the cause of the error.

See also
`sendControlRequest`
`CATEGORY_REMOTE_PLAYBACK`

CATEGORY_LIVE_AUDIO

Added in 1.1.0

public static final String CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"

Media control category: Live audio.

A route that supports live audio routing will allow the media audio stream to be sent to supported destinations. This can include internal speakers or audio jacks on the device itself, A2DP devices, and more.

When a live audio route is selected, audio routing is transparent to the application. All audio played on the media stream will be routed to the selected destination.

Refer to the class documentation for details about live audio routes.

CATEGORY_LIVE_VIDEO

Added in 1.1.0

public static final String CATEGORY_LIVE_VIDEO = "android.media.intent.category.LIVE_VIDEO"

Media control category: Live video.

A route that supports live video routing will allow a mirrored version of the device's primary display or a customized Presentation to be sent to supported destinations.

When a live video route is selected, audio and video routing is transparent to the application. By default, audio and video is routed to the selected destination. For certain live video routes, the application may also use a Presentation to replace the mirrored view on the external display with different content.

Refer to the class documentation for details about live video routes.

See also
`getPresentationDisplay`
`Presentation`

CATEGORY_REMOTE_PLAYBACK

Added in 1.1.0

public static final String CATEGORY_REMOTE_PLAYBACK = "android.media.intent.category.REMOTE_PLAYBACK"

Media control category: Remote playback.

A route that supports remote playback routing will allow an application to send requests to play content remotely to supported destinations.

Remote playback routes destinations operate independently of the local device. When a remote playback route is selected, the application can control the content playing on the destination by sending media control actions to the route. The application may also receive status updates from the route regarding remote playback.

Refer to the class documentation for details about remote playback routes.

See also
`sendControlRequest`

ERROR_INVALID_ITEM_ID

Added in 1.1.0

public static final int ERROR_INVALID_ITEM_ID = 3

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

See also
`EXTRA_ERROR_CODE`

ERROR_INVALID_SESSION_ID

Added in 1.1.0

public static final int ERROR_INVALID_SESSION_ID = 2

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

See also
`EXTRA_ERROR_CODE`

ERROR_UNKNOWN

Added in 1.1.0

public static final int ERROR_UNKNOWN = 0

Error code: An unknown error occurred.

See also
`EXTRA_ERROR_CODE`

ERROR_UNSUPPORTED_OPERATION

Added in 1.1.0

public static final int ERROR_UNSUPPORTED_OPERATION = 1

Error code: The operation is not supported.

See also
`EXTRA_ERROR_CODE`

EXTRA_ERROR_CODE

Added in 1.1.0

public static final String EXTRA_ERROR_CODE = "android.media.intent.extra.ERROR_CODE"

Integer extra: Error code.

Used with all media control requests to describe the cause of an error. This extra may be omitted when the error is unknown.

The value is one of: ERROR_UNKNOWN, ERROR_UNSUPPORTED_OPERATION, ERROR_INVALID_SESSION_ID, ERROR_INVALID_ITEM_ID.

EXTRA_ITEM_CONTENT_POSITION

Added in 1.1.0

public static final String EXTRA_ITEM_CONTENT_POSITION = "android.media.intent.extra.ITEM_POSITION"

Long extra: Media item content position.

Used with ACTION_PLAY or ACTION_ENQUEUE to specify the starting playback position.

Used with ACTION_SEEK to set a new playback position.

The value is a long integer number of milliseconds from the beginning of the content.

See also
`ACTION_PLAY`
`ACTION_ENQUEUE`
`ACTION_SEEK`

EXTRA_ITEM_HTTP_HEADERS

Added in 1.1.0

public static final String EXTRA_ITEM_HTTP_HEADERS = "android.media.intent.extra.HTTP_HEADERS"

Bundle extra: HTTP request headers.

Used with ACTION_PLAY or ACTION_ENQUEUE to specify HTTP request headers to be included when fetching to the content indicated by the media item's data Uri.

This extra may be used to provide authentication tokens and other parameters to the server separately from the media item's data Uri.

The value is a android.os.Bundle of string based key-value pairs that describe the HTTP request headers.

See also
`ACTION_PLAY`
`ACTION_ENQUEUE`

EXTRA_ITEM_ID

Added in 1.1.0

public static final String EXTRA_ITEM_ID = "android.media.intent.extra.ITEM_ID"

Bundle extra: Media item id.

An opaque unique identifier returned as a result from ACTION_PLAY or ACTION_ENQUEUE that represents the media item that was created by the playback request.

Used with various actions to specify the id of the media item to be controlled.

Included in broadcast intents sent to status update receivers to identify the item in question.

The value is a unique string value generated by the media route provider to represent one particular media item.

See also
`ACTION_PLAY`
`ACTION_ENQUEUE`
`ACTION_SEEK`
`ACTION_GET_STATUS`

EXTRA_ITEM_METADATA

Added in 1.1.0

public static final String EXTRA_ITEM_METADATA = "android.media.intent.extra.ITEM_METADATA"

Bundle extra: Media item metadata.

Used with ACTION_PLAY or ACTION_ENQUEUE to specify metadata associated with the content of a media item.

The value is a android.os.Bundle of metadata key-value pairs as defined in MediaItemMetadata.

See also
`ACTION_PLAY`
`ACTION_ENQUEUE`

EXTRA_ITEM_STATUS

Added in 1.1.0

public static final String EXTRA_ITEM_STATUS = "android.media.intent.extra.ITEM_STATUS"

Bundle extra: Media item status.

Returned as a result from media item actions such as ACTION_PLAY, ACTION_ENQUEUE, ACTION_SEEK, and ACTION_GET_STATUS to describe the status of the specified media item.

Included in broadcast intents sent to item status update receivers to provide updated status information.

The value is a android.os.Bundle of data that can be converted into a MediaItemStatus object using MediaItemStatus.fromBundle.

See also
`ACTION_PLAY`
`ACTION_ENQUEUE`
`ACTION_SEEK`
`ACTION_GET_STATUS`

EXTRA_ITEM_STATUS_UPDATE_RECEIVER

Added in 1.1.0

public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER = "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"

Bundle extra: Media item status update receiver.

Used with ACTION_PLAY or ACTION_ENQUEUE to specify a PendingIntent for a broadcast receiver that will receive status updates about a particular media item.

Whenever the status of the media item changes, the media route provider will send a broadcast to the pending intent with extras that identify the session to which the item belongs, the session status, the item's id and the item's updated status.

The same pending intent and broadcast receiver may be shared by any number of media items since the broadcast intent includes the media session id and media item id.

The value is a PendingIntent.

Broadcast extras

EXTRA_SESSION_ID(required): Specifies the session id of the session to which the item in question belongs.
EXTRA_SESSION_STATUS(optional, old implementations may omit this key): Specifies the status of the media session.
EXTRA_ITEM_ID(required): Specifies the media item id of the media item in question.
EXTRA_ITEM_STATUS(required): Specifies the status of the item as a bundle that can be decoded into a MediaItemStatus object.

See also
`ACTION_PLAY`
`ACTION_ENQUEUE`

EXTRA_MESSAGE

Added in 1.1.0

public static final String EXTRA_MESSAGE = "android.media.intent.extra.MESSAGE"

Bundle extra: Message.

Used with ACTION_SEND_MESSAGE, and included in broadcast intents sent to message receivers to describe a message between a session and a media route provider.

The value is a android.os.Bundle.

EXTRA_MESSAGE_RECEIVER

Added in 1.1.0

public static final String EXTRA_MESSAGE_RECEIVER = "android.media.intent.extra.MESSAGE_RECEIVER"

Bundle extra: Media message receiver.

Used with ACTION_START_SESSION to specify a PendingIntent for a broadcast receiver that will receive messages from the media session.

When the media session has a message to send, the media route provider will send a broadcast to the pending intent with extras that identify the session id and its message.

The value is a PendingIntent.

Broadcast extras

EXTRA_SESSION_ID(required): Specifies the session id of the session.
EXTRA_MESSAGE(required): Specifies the message from the session as a bundle object.

See also
`ACTION_START_SESSION`

EXTRA_SESSION_ID

Added in 1.1.0

public static final String EXTRA_SESSION_ID = "android.media.intent.extra.SESSION_ID"

Bundle extra: Media session id.

An opaque unique identifier that identifies the remote playback media session.

Used with various actions to specify the id of the media session to be controlled.

Included in broadcast intents sent to item status update receivers to identify the session to which the item in question belongs.

Included in broadcast intents sent to session status update receivers to identify the session.

The value is a unique string value generated by the media route provider to represent one particular media session.

See also
`ACTION_PLAY`
`ACTION_SEEK`
`ACTION_GET_STATUS`
`ACTION_PAUSE`
`ACTION_RESUME`
`ACTION_STOP`
`ACTION_START_SESSION`
`ACTION_GET_SESSION_STATUS`
`ACTION_END_SESSION`

EXTRA_SESSION_STATUS

Added in 1.1.0

public static final String EXTRA_SESSION_STATUS = "android.media.intent.extra.SESSION_STATUS"

Bundle extra: Media session status.

Returned as a result from media session actions such as ACTION_START_SESSION, ACTION_PAUSE, and ACTION_GET_SESSION_STATUS to describe the status of the specified media session.

Included in broadcast intents sent to session status update receivers to provide updated status information.

The value is a android.os.Bundle of data that can be converted into a MediaSessionStatus object using MediaSessionStatus.fromBundle.

See also
`ACTION_PLAY`
`ACTION_SEEK`
`ACTION_GET_STATUS`
`ACTION_PAUSE`
`ACTION_RESUME`
`ACTION_STOP`
`ACTION_START_SESSION`
`ACTION_GET_SESSION_STATUS`
`ACTION_END_SESSION`

EXTRA_SESSION_STATUS_UPDATE_RECEIVER

Added in 1.1.0

public static final String EXTRA_SESSION_STATUS_UPDATE_RECEIVER = "android.media.intent.extra.SESSION_STATUS_UPDATE_RECEIVER"

Bundle extra: Media session status update receiver.

Used with ACTION_START_SESSION to specify a PendingIntent for a broadcast receiver that will receive status updates about the media session.

Whenever the status of the media session changes, the media route provider will send a broadcast to the pending intent with extras that identify the session id and its updated status.

The value is a PendingIntent.

Broadcast extras

EXTRA_SESSION_ID(required): Specifies the session id of the session.
EXTRA_SESSION_STATUS(required): Specifies the status of the session as a bundle that can be decoded into a MediaSessionStatus object.

See also
`ACTION_START_SESSION`