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"