MediaControlIntent

ACTION_END_SESSION

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

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

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

ACTION_ENQUEUE

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.

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

ACTION_GET_SESSION_STATUS

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

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

ACTION_GET_STATUS

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

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

ACTION_PAUSE

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

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

ACTION_PLAY

String 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 error playback 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("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);
 }

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

ACTION_REMOVE

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

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

ACTION_RESUME

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

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

ACTION_SEEK

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

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

ACTION_SEND_MESSAGE

String 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

Errors

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

ACTION_START_SESSION

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

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

ACTION_STOP

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

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

CATEGORY_LIVE_AUDIO

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

Constant Value: "android.media.intent.category.LIVE_AUDIO"

CATEGORY_LIVE_VIDEO

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

Constant Value: "android.media.intent.category.LIVE_VIDEO"

CATEGORY_REMOTE_PLAYBACK

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

Constant Value: "android.media.intent.category.REMOTE_PLAYBACK"

ERROR_INVALID_ITEM_ID

int ERROR_INVALID_ITEM_ID

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

Constant Value: 3 (0x00000003)

ERROR_INVALID_SESSION_ID

int ERROR_INVALID_SESSION_ID

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

Constant Value: 2 (0x00000002)

ERROR_UNKNOWN

int ERROR_UNKNOWN

Error code: An unknown error occurred.

Constant Value: 0 (0x00000000)

ERROR_UNSUPPORTED_OPERATION

int ERROR_UNSUPPORTED_OPERATION

Error code: The operation is not supported.

Constant Value: 1 (0x00000001)

EXTRA_ERROR_CODE

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

Constant Value: "android.media.intent.extra.ERROR_CODE"

EXTRA_ITEM_CONTENT_POSITION

String EXTRA_ITEM_CONTENT_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.

Constant Value: "android.media.intent.extra.ITEM_POSITION"

EXTRA_ITEM_HTTP_HEADERS

String EXTRA_ITEM_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 Bundle of string based key-value pairs that describe the HTTP request headers.

Constant Value: "android.media.intent.extra.HTTP_HEADERS"

EXTRA_ITEM_ID

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

Constant Value: "android.media.intent.extra.ITEM_ID"

EXTRA_ITEM_METADATA

String 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 Bundle of metadata key-value pairs as defined in MediaItemMetadata.

Constant Value: "android.media.intent.extra.ITEM_METADATA"

EXTRA_ITEM_STATUS

String 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 Bundle of data that can be converted into a MediaItemStatus object using MediaItemStatus.fromBundle.

Constant Value: "android.media.intent.extra.ITEM_STATUS"

EXTRA_ITEM_STATUS_UPDATE_RECEIVER

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

Constant Value: "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"

EXTRA_MESSAGE

String 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 Bundle.

Constant Value: "android.media.intent.extra.MESSAGE"

EXTRA_MESSAGE_RECEIVER

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

Constant Value: "android.media.intent.extra.MESSAGE_RECEIVER"

EXTRA_SESSION_ID

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

Constant Value: "android.media.intent.extra.SESSION_ID"

EXTRA_SESSION_STATUS

String 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 Bundle of data that can be converted into a MediaSessionStatus object using MediaSessionStatus.fromBundle.

Constant Value: "android.media.intent.extra.SESSION_STATUS"

EXTRA_SESSION_STATUS_UPDATE_RECEIVER

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

Constant Value: "android.media.intent.extra.SESSION_STATUS_UPDATE_RECEIVER"