Update media router API.
Use the nomenclature "media item" rather than "media stream"
to refer to playback requests to avoid confusion.
Add a STOP action.
Document that the status broadcasts should include the item id.
Bug: 8175766
Change-Id: Ideb5c674d48b4a5ba2cb276c19beaafda83900b5
diff --git a/v7/mediarouter/src/android/support/v7/media/MediaControlIntent.java b/v7/mediarouter/src/android/support/v7/media/MediaControlIntent.java
index 626ceef..5d2711c 100644
--- a/v7/mediarouter/src/android/support/v7/media/MediaControlIntent.java
+++ b/v7/mediarouter/src/android/support/v7/media/MediaControlIntent.java
@@ -33,6 +33,73 @@
* the media route's destination to control media playback. Media control
* actions may only apply to routes that support certain media control categories.
* </ul>
+ *
+ * <h3>Route Categories</h3>
+ * <p>
+ * Routes are classified by the categories of actions that they support. The following
+ * standard categories are defined.
+ * </p><ul>
+ * <li>{@link #CATEGORY_LIVE_AUDIO Live audio}: The route supports streaming live audio
+ * from the device to the destination. Live audio routes include local speakers
+ * and Bluetooth headsets.
+ * <li>{@link #CATEGORY_LIVE_VIDEO Live video}: The route supports streaming live video
+ * from the device to the destination. Live video routes include local displays
+ * and wireless displays that support mirroring and
+ * {@link android.app.Presentation presentations}.
+ * <li>{@link #CATEGORY_REMOTE_PLAYBACK Remote playback}: The route supports sending
+ * remote playback requests for media content to the destination. The content to be
+ * played is identified by a Uri and mime-type.
+ * </ul>
+ *
+ * <h3>Remote Playback</h3>
+ * <p>
+ * Media control intents are frequently used to start remote playback of media
+ * on a destination using remote playback actions from the
+ * {@link #CATEGORY_REMOTE_PLAYBACK remote playback category}.
+ * </p><p>
+ * The {@link #ACTION_PLAY} action enqueues the Uri of content to be played and obtains
+ * a media item id that can be used to control playback.
+ * </p>
+ *
+ * <h4>Media Items</h4>
+ * <p>
+ * A media item id is an opaque token that represents the playback request.
+ * The application must supply the media item id when sending control requests to
+ * {@link #ACTION_PAUSE pause}, {@link #ACTION_RESUME resume}, {@link #ACTION_SEEK seek},
+ * {@link #ACTION_GET_STATUS get status}, {@link #ACTION_GET_PROGRESS get progress},
+ * or perform other actions to affect playback.
+ * </p><p>
+ * Each remote playback action is bound to a specific media item. If a
+ * media item has finished, been canceled or encountered an error, then most
+ * actions other than status requests will fail. In particular, actions such as
+ * {@link #ACTION_PAUSE} always control playback of a specific media item rather
+ * than acting globally upon whatever happens to be playing at the moment.
+ * </p>
+ *
+ * <h4>Queue Behavior</h4>
+ * <p>
+ * To provide a seamless media experience, the application can enqueue a limited number
+ * of items to play in succession. The destination can take advantage of its
+ * queue to optimize continuous playback, starting the next media item automatically
+ * as soon as the previous one finishes.
+ * </p><p>
+ * By default, the {@link #ACTION_PLAY play action} causes the destination to stop
+ * whatever is currently playing, clear the queue of pending items, then begin playing
+ * the newly requested content. By supplying a
+ * {@link #EXTRA_ITEM_QUEUE_BEHAVIOR queue behavior} parameter as part of the playback
+ * request, the application can specify whether the media item should
+ * {@link #ITEM_QUEUE_BEHAVIOR_PLAY_NOW play now},
+ * {@link #ITEM_QUEUE_BEHAVIOR_PLAY_NOW play next},
+ * or {@link #ITEM_QUEUE_BEHAVIOR_PLAY_NOW play later},
+ * </p><p>
+ * Typically the application will start by queuing two media items at once: one item to
+ * play now and one item to play later. When the first item finishes, the next item
+ * will begin playing immediately. The application can then enqueue another media item to
+ * play next (without interrupting current playback), and so on.
+ * </p><p>
+ * The application can also enqueue additional items to play later although queuing
+ * just two items at a time is usually sufficient for continuous playback.
+ * </p>
*/
public final class MediaControlIntent {
/**
@@ -87,13 +154,15 @@
"android.media.intent.category.REMOTE_PLAYBACK";
/**
- * Media control action: Play.
+ * Media control action: Play media item.
* <p>
* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
* media control.
* </p><p>
* This action causes a remote playback route to start playing content with
* the {@link Uri} specified in the {@link Intent}'s {@link Intent#getData() data uri}.
+ * The action returns a media item id which can be used to control playback
+ * using other remote playback actions.
* </p><p>
* Once initiated, playback of the specified content will be queued and managed
* independently by the destination. The application will receive status
@@ -103,35 +172,34 @@
* 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 {@link MediaStreamStatus#PLAYBACK_STATE_ERROR error}
- * {@link MediaStreamStatus#KEY_PLAYBACK_STATE state}
- * and include the {@link MediaStreamStatus#KEY_HTTP_STATUS_CODE HTTP status code}.
+ * indicating the {@link MediaItemStatus#PLAYBACK_STATE_ERROR error}
+ * {@link MediaItemStatus#KEY_PLAYBACK_STATE state}
+ * and include the {@link MediaItemStatus#KEY_HTTP_STATUS_CODE HTTP status code}.
* </p>
*
* <h3>Request parameters</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_QUEUE_BEHAVIOR}: specifies when the content should be played.
- * <li>{@link #EXTRA_STREAM_POSITION}: specifies the initial start position of the
- * content stream.
- * <li>{@link #EXTRA_STREAM_METADATA}: specifies metadata associated with the
- * content stream such as the title of a song.
- * <li>{@link #EXTRA_STREAM_STATUS_UPDATE_RECEIVER}: specifies a {@link PendingIntent}
- * for a broadcast receiver that will receive status updates.
- * <li>{@link #EXTRA_STREAM_HTTP_HEADERS}: specifies HTTP headers to supply to the
- * server when requesting the content stream.
+ * <li>{@link #EXTRA_ITEM_QUEUE_BEHAVIOR}: specifies when the content should be played.
+ * <li>{@link #EXTRA_ITEM_POSITION}: specifies the initial start position of the content.
+ * <li>{@link #EXTRA_ITEM_METADATA}: specifies metadata associated with the
+ * content such as the title of a song.
+ * <li>{@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER}: specifies a {@link PendingIntent}
+ * for a broadcast receiver that will receive status updates about the media item.
+ * <li>{@link #EXTRA_ITEM_HTTP_HEADERS}: specifies HTTP headers to supply to the
+ * server when fetching the content.
* </ul>
*
* <h3>Result data</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_ID}: specifies a string identifier to use to refer
- * to the media stream in subsequent requests such as {@link #ACTION_SEEK}.
+ * <li>{@link #EXTRA_ITEM_ID}: specifies an opaque string identifier to use to refer
+ * to the media item in subsequent requests such as {@link #ACTION_PAUSE}.
* </ul>
*
* <h3>Status updates</h3>
* <p>
- * If the client supplies a {@link #EXTRA_STREAM_STATUS_UPDATE_RECEIVER status update receiver}
+ * If the client supplies a {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receiver}
* then the media route provider is responsible for sending status updates to the receiver
- * when significant state changes occur.
+ * when significant media item state changes occur.
* </p>
*
* <h3>Example</h3>
@@ -141,15 +209,15 @@
* Intent intent = new Intent(MediaControlIntent.ACTION_PLAY);
* intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
* intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4");
- * intent.putExtra(MediaControlIntent.EXTRA_QUEUE_BEHAVIOR,
- * MediaControlIntent.QUEUE_BEHAVIOR_PLAY_NEXT);
+ * intent.putExtra(MediaControlIntent.EXTRA_ITEM_QUEUE_BEHAVIOR,
+ * MediaControlIntent.ITEM_QUEUE_BEHAVIOR_PLAY_NEXT);
* if (route.supportsControlRequest(intent)) {
* MediaRouter.ControlRequestCallback callback = new MediaRouter.ControlRequestCallback() {
* public void onResult(int result, Bundle data) {
* if (result == REQUEST_SUCCEEDED) {
* // The request succeeded.
- * // The content stream may be controlled using the returned stream id...
- * String id = data.getStringExtra(MediaControlIntent.EXTRA_STREAM_ID);
+ * // Playback may be controlled using the returned item id...
+ * String id = data.getStringExtra(MediaControlIntent.EXTRA_ITEM_ID);
* }
* }
* };
@@ -158,33 +226,38 @@
*
* @see MediaRouter.RouteInfo#sendControlRequest
* @see #CATEGORY_REMOTE_PLAYBACK
+ * @see #ACTION_SEEK
+ * @see #ACTION_STOP
+ * @see #ACTION_PAUSE
+ * @see #ACTION_RESUME
+ * @see #ACTION_GET_PROGRESS
+ * @see #ACTION_GET_STATUS
*/
public static final String ACTION_PLAY = "android.media.intent.action.PLAY";
/**
- * Media control action: Seek to a new playback position.
+ * Media control action: Seek media item to a new playback position.
* <p>
* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
* media control.
* </p><p>
* This action causes a remote playback route to modify the current playback
- * position of the specified media stream.
+ * position of the specified media item.
* </p><p>
- * This action should generally not affect the current playback state of the media stream.
- * If the stream is paused, then seeking should set the position but leave
- * the stream paused. Likewise if the stream is playing, then seeking should
- * continue playing from the new position. If the stream has not yet started
+ * This action should generally not affect the current playback state of the media item.
+ * If the item is paused, then seeking should set the position but leave
+ * the item paused. Likewise if the item is playing, then seeking should
+ * continue playing from the new position. If the item has not yet started
* playing, then the new playback position should be remembered and used as the
- * initial position for the stream.
+ * initial position for the item.
* </p>
*
* <h3>Request parameters</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_ID}: specifies the stream id of the stream to be
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
* controlled. This value was returned as a result from the
* {@link #ACTION_PLAY play} action.
- * <li>{@link #EXTRA_STREAM_POSITION}: specifies the new position of the
- * content stream.
+ * <li>{@link #EXTRA_ITEM_POSITION}: specifies the new position of the content.
* </ul>
*
* <h3>Result data</h3>
@@ -198,21 +271,52 @@
public static final String ACTION_SEEK = "android.media.intent.action.SEEK";
/**
- * Media control action: Pause playback.
+ * Media control action: Stop media item playback.
+ * <p>
+ * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
+ * media control.
+ * </p><p>
+ * This action causes a remote playback route to stop playback of the
+ * specified media item.
+ * </p><p>
+ * If the media item has not started playing yet, then the media item should
+ * be stopped and removed from the queue.
+ * </p>
+ *
+ * <h3>Request parameters</h3>
+ * <ul>
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
+ * controlled. This value was returned as a result from the
+ * {@link #ACTION_PLAY play} action.
+ * </ul>
+ *
+ * <h3>Result data</h3>
+ * <ul>
+ * <li>(none)
+ * </ul>
+ *
+ * @see MediaRouter.RouteInfo#sendControlRequest
+ * @see #CATEGORY_REMOTE_PLAYBACK
+ */
+ public static final String ACTION_STOP = "android.media.intent.action.STOP";
+
+
+ /**
+ * Media control action: Pause media item playback.
* <p>
* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
* media control.
* </p><p>
* This action causes a remote playback route to pause playback of the
- * specified stream.
+ * specified media item.
* </p><p>
- * If the stream has not started playing yet, then the request to pause should
- * be remembered such that the stream will initially start in a paused state.
+ * If the media item has not started playing yet, then the request to pause should
+ * be remembered such that the item will initially start in a paused state.
* </p>
*
* <h3>Request parameters</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_ID}: specifies the stream id of the stream to be
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
* controlled. This value was returned as a result from the
* {@link #ACTION_PLAY play} action.
* </ul>
@@ -224,22 +328,23 @@
*
* @see MediaRouter.RouteInfo#sendControlRequest
* @see #CATEGORY_REMOTE_PLAYBACK
+ * @see #ACTION_RESUME
*/
public static final String ACTION_PAUSE = "android.media.intent.action.PAUSE";
/**
- * Media control action: Resume playback (unpause).
+ * Media control action: Resume media item playback (unpause).
* <p>
* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
* media control.
* </p><p>
* This action causes a remote playback route to resume playback of the
- * specified stream. Reverses the effects of {@link #ACTION_PAUSE}.
+ * specified media item. Reverses the effects of {@link #ACTION_PAUSE}.
* </p>
*
* <h3>Request parameters</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_ID}: specifies the stream id of the stream to be
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
* controlled. This value was returned as a result from the
* {@link #ACTION_PLAY play} action.
* </ul>
@@ -251,58 +356,60 @@
*
* @see MediaRouter.RouteInfo#sendControlRequest
* @see #CATEGORY_REMOTE_PLAYBACK
+ * @see #ACTION_PAUSE
*/
public static final String ACTION_RESUME = "android.media.intent.action.RESUME";
/**
- * Media control action: Get status.
+ * Media control action: Get media item status.
* <p>
* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
* media control.
* </p><p>
* This action asks a remote playback route to provide updated status information
- * about playback of the specified stream.
+ * about playback of the specified media item.
* </p>
*
* <h3>Request parameters</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_ID}: specifies the stream id of the stream to be
- * queried. This value was returned as a result from the
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
+ * controlled. This value was returned as a result from the
* {@link #ACTION_PLAY play} action.
* </ul>
*
* <h3>Result data</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_STATUS}: specifies the status of the stream.
+ * <li>{@link #EXTRA_ITEM_STATUS}: specifies the status of the stream.
* </ul>
*
* @see MediaRouter.RouteInfo#sendControlRequest
* @see #CATEGORY_REMOTE_PLAYBACK
+ * @see #EXTRA_ITEM_STATUS_UPDATE_RECEIVER
*/
public static final String ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS";
/**
- * Media control action: Get progress.
+ * Media control action: Get media item progress.
* <p>
* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback}
* media control.
* </p><p>
- * This action asks a remote playback route to provide the stream playback
+ * This action asks a remote playback route to provide media item playback
* progress information. The client may use this information to provide feedback
* to the user about the current playback position and overall duration.
* </p>
*
* <h3>Request parameters</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_ID}: specifies the stream id of the stream to be
- * queried. This value was returned as a result from the
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
+ * controlled. This value was returned as a result from the
* {@link #ACTION_PLAY play} action.
* </ul>
*
* <h3>Result data</h3>
* <ul>
- * <li>{@link #EXTRA_STREAM_POSITION}: specifies the stream playback position.
- * <li>{@link #EXTRA_STREAM_DURATION}: specifies the stream overall duration.
+ * <li>{@link #EXTRA_ITEM_POSITION}: specifies the content playback position.
+ * <li>{@link #EXTRA_ITEM_DURATION}: specifies the overall duration of the content.
* </ul>
*
* @see MediaRouter.RouteInfo#sendControlRequest
@@ -311,62 +418,62 @@
public static final String ACTION_GET_PROGRESS = "android.media.intent.action.GET_PROGRESS";
/**
- * Integer extra: Queue behavior.
+ * Integer extra: Media item queue behavior.
* <p>
- * Used with {@link #ACTION_PLAY} to specify when the requested content should be
+ * Used with {@link #ACTION_PLAY} to specify when the requested should be
* played. The default is to play the content immediately.
* </p><p>
- * The value must be one of {@link #STREAM_QUEUE_BEHAVIOR_PLAY_NOW},
- * {@link #STREAM_QUEUE_BEHAVIOR_PLAY_NEXT}, or {@link #STREAM_QUEUE_BEHAVIOR_PLAY_LATER}.
+ * The value must be one of {@link #ITEM_QUEUE_BEHAVIOR_PLAY_NOW},
+ * {@link #ITEM_QUEUE_BEHAVIOR_PLAY_NEXT}, or {@link #ITEM_QUEUE_BEHAVIOR_PLAY_LATER}.
* </p>
*
* @see #ACTION_PLAY
*/
- public static final String EXTRA_STREAM_QUEUE_BEHAVIOR =
+ public static final String EXTRA_ITEM_QUEUE_BEHAVIOR =
"android.media.intent.extra.QUEUE_BEHAVIOR";
/**
- * Value for {@link #EXTRA_STREAM_QUEUE_BEHAVIOR}: Play now.
+ * Value for {@link #EXTRA_ITEM_QUEUE_BEHAVIOR}: Play now.
* <p>
* This is the default queue behavior.
* </p><p>
- * Requests that the new content stream play immediately, canceling the currently playing
- * stream and all subsequent items in the queue. When this control request returns, the
- * queue will contain exactly one item consisting of the newly requested content.
+ * Requests that the new content be played immediately, canceling the currently playing
+ * media item and all subsequent items in the queue. When this control request returns,
+ * the queue will contain exactly one item consisting of the newly requested content.
* </p>
*
- * @see #EXTRA_STREAM_QUEUE_BEHAVIOR
+ * @see #EXTRA_ITEM_QUEUE_BEHAVIOR
*/
- public static final int STREAM_QUEUE_BEHAVIOR_PLAY_NOW = 0;
+ public static final int ITEM_QUEUE_BEHAVIOR_PLAY_NOW = 0;
/**
- * Value for {@link #EXTRA_STREAM_QUEUE_BEHAVIOR}: Play next.
+ * Value for {@link #EXTRA_ITEM_QUEUE_BEHAVIOR}: Play next.
* <p>
- * Requests that the new content stream be enqueued to play next after the currently playing
- * stream, canceling all subsequent items in the queue. When this control request returns,
- * the queue will contain either one or two items consisting of the currently playing
- * content, if any, followed by the newly requested content.
+ * Requests that the new content be enqueued to play next after the currently playing
+ * media item, canceling all subsequent items in the queue. When this control request
+ * returns, the queue will contain either one or two items consisting of the currently
+ * playing content, if any, followed by the newly requested content.
* </p>
*
- * @see #EXTRA_STREAM_QUEUE_BEHAVIOR
+ * @see #EXTRA_ITEM_QUEUE_BEHAVIOR
*/
- public static final int STREAM_QUEUE_BEHAVIOR_PLAY_NEXT = 1;
+ public static final int ITEM_QUEUE_BEHAVIOR_PLAY_NEXT = 1;
/**
- * Value for {@link #EXTRA_STREAM_QUEUE_BEHAVIOR}: Play later.
+ * Value for {@link #EXTRA_ITEM_QUEUE_BEHAVIOR}: Play later.
* <p>
- * Requests that the new content stream be enqueued to play later after all other items
+ * Requests that the new content be enqueued to play later after all other media items
* currently in the queue. When this control request returns, the queue will contain at
* least one item consisting of the currently playing content and all previously
* enqueued items followed by the newly requested content.
* </p>
*
- * @see #EXTRA_STREAM_QUEUE_BEHAVIOR
+ * @see #EXTRA_ITEM_QUEUE_BEHAVIOR
*/
- public static final int STREAM_QUEUE_BEHAVIOR_PLAY_LATER = 2;
+ public static final int ITEM_QUEUE_BEHAVIOR_PLAY_LATER = 2;
/**
- * Integer extra: Stream position.
+ * Integer extra: Media item content position.
* <p>
* Used with {@link #ACTION_PLAY} to specify the starting playback position.
* </p><p>
@@ -374,114 +481,119 @@
* </p><p>
* Used with {@link #ACTION_GET_PROGRESS} to report the current playback position.
* </p><p>
- * The value is an integer number of seconds from the beginning of the
- * content stream.
+ * The value is an integer number of seconds from the beginning of the content.
* <p>
*
* @see #ACTION_PLAY
* @see #ACTION_SEEK
* @see #ACTION_GET_PROGRESS
*/
- public static final String EXTRA_STREAM_POSITION =
- "android.media.intent.extra.STREAM_POSITION";
+ public static final String EXTRA_ITEM_POSITION =
+ "android.media.intent.extra.ITEM_POSITION";
/**
- * Integer extra: Stream duration.
+ * Integer extra: Media item content duration.
* <p>
- * Used with {@link #ACTION_GET_PROGRESS} to report the overall duration of the stream.
+ * Used with {@link #ACTION_GET_PROGRESS} to report the overall duration of the
+ * media item content.
* </p><p>
- * The value is an integer number of seconds from the beginning of the
- * content stream.
+ * The value is an integer number of seconds from the beginning of the content.
* <p>
*
* @see #ACTION_GET_PROGRESS
*/
- public static final String EXTRA_STREAM_DURATION =
- "android.media.intent.extra.STREAM_DURATION";
+ public static final String EXTRA_ITEM_DURATION =
+ "android.media.intent.extra.ITEM_DURATION";
/**
- * Bundle extra: Stream metadata.
+ * Bundle extra: Media item metadata.
* <p>
- * Used with {@link #ACTION_PLAY} to specify metadata associated with a
- * content stream.
+ * Used with {@link #ACTION_PLAY} to specify metadata associated with the content
+ * of a media item.
* </p><p>
* The value is a {@link android.os.Bundle} of metadata keys and values as defined
- * in {@link MediaStreamMetadata}.
+ * in {@link MediaItemMetadata}.
* </p>
*
* @see #ACTION_PLAY
*/
- public static final String EXTRA_STREAM_METADATA =
- "android.media.intent.extra.STREAM_METADATA";
+ public static final String EXTRA_ITEM_METADATA =
+ "android.media.intent.extra.ITEM_METADATA";
/**
- * Bundle extra: Stream id.
+ * Bundle extra: Media item id.
* <p>
- * Returned as a result from {@link #ACTION_PLAY} to provide a unique id
- * for the requested content stream which may then be used to issue subsequent
- * requests to control that content stream.
+ * Returned as a result from {@link #ACTION_PLAY} to provide an opaque unique id
+ * for the requested media item which may then be used to issue subsequent
+ * requests to control the content.
* </p><p>
- * Used with various actions to specify the id of the stream to be controlled.
+ * Used with various actions to specify the id of the media item to be controlled.
* </p><p>
* The value is a unique string value generated by the media route provider
- * to represent one particular content stream.
+ * to represent one particular media item.
* </p>
*
* @see #ACTION_PLAY
+ * @see #ACTION_STOP
* @see #ACTION_SEEK
* @see #ACTION_PAUSE
* @see #ACTION_RESUME
* @see #ACTION_GET_STATUS
*/
- public static final String EXTRA_STREAM_ID =
- "android.media.intent.extra.STREAM_ID";
+ public static final String EXTRA_ITEM_ID =
+ "android.media.intent.extra.ITEM_ID";
/**
- * Bundle extra: Stream status.
+ * Bundle extra: Media item status.
* <p>
* Returned as a result from {@link #ACTION_GET_STATUS} and in broadcasts
- * sent to a {@link #EXTRA_STREAM_STATUS_UPDATE_RECEIVER status update receiver}
- * to describe the status of the stream.
+ * sent to a {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receiver}
+ * to describe the status of the media item.
* </p><p>
* The value is a {@link android.os.Bundle} of status keys and values as defined
- * in {@link MediaStreamStatus}.
+ * in {@link MediaItemStatus}.
* </p>
*
* @see #ACTION_PLAY
- * @see #ACTION_SEEK
- * @see #ACTION_PAUSE
- * @see #ACTION_RESUME
* @see #ACTION_GET_STATUS
*/
- public static final String EXTRA_STREAM_STATUS =
- "android.media.intent.extra.STREAM_STATUS";
+ public static final String EXTRA_ITEM_STATUS =
+ "android.media.intent.extra.ITEM_STATUS";
/**
- * Bundle extra: Stream status update receiver.
+ * Bundle extra: Media item status update receiver.
* <p>
* Used with {@link #ACTION_PLAY} to specify a {@link PendingIntent} for a
- * broadcast receiver that will receive status updates.
+ * broadcast receiver that will receive status updates about a media item.
* </p><p>
- * Whenever the status of the stream changes, the media route provider will
- * send a broadcast to the pending intent which includes the {@link #EXTRA_STREAM_STATUS}
- * that describes the new status.
+ * Whenever the status of the media item changes, the media route provider will
+ * send a broadcast to the pending intent with extras that describe
+ * the status of the media item.
* </p><p>
* The value is a {@link PendingIntent}.
* </p>
*
+ * <h3>Broadcast extras</h3>
+ * <ul>
+ * <li>{@link #EXTRA_ITEM_ID}: specifies the media item id of the playback to be
+ * controlled. This value was returned as a result from the
+ * {@link #ACTION_PLAY play} action.
+ * <li>{@link #EXTRA_ITEM_STATUS}: specifies the status of the stream.
+ * </ul>
+ *
* @see #ACTION_PLAY
*/
- public static final String EXTRA_STREAM_STATUS_UPDATE_RECEIVER =
- "android.media.intent.extra.STREAM_STATUS_UPDATE_RECEIVER";
+ public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER =
+ "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER";
/**
* Bundle extra: HTTP headers.
* <p>
* Used with {@link #ACTION_PLAY} to specify HTTP headers to be included when
- * connecting to the media stream indicated by the data Uri.
+ * fetching to the content indicated by the media item's data Uri.
* </p><p>
* This extra may be used to provide authentication tokens and other
- * parameters to the server separately from the media stream's data Uri.
+ * parameters to the server separately from the media item's data Uri.
* </p><p>
* The value is a {@link android.os.Bundle} of string based key value pairs
* that describe the HTTP headers.
@@ -489,7 +601,7 @@
*
* @see #ACTION_PLAY
*/
- public static final String EXTRA_STREAM_HTTP_HEADERS =
+ public static final String EXTRA_ITEM_HTTP_HEADERS =
"android.media.intent.extra.HTTP_HEADERS";
private MediaControlIntent() {
diff --git a/v7/mediarouter/src/android/support/v7/media/MediaItemMetadata.java b/v7/mediarouter/src/android/support/v7/media/MediaItemMetadata.java
new file mode 100644
index 0000000..1836f91
--- /dev/null
+++ b/v7/mediarouter/src/android/support/v7/media/MediaItemMetadata.java
@@ -0,0 +1,130 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.support.v7.media;
+
+import android.os.Bundle;
+
+/**
+ * Constants for specifying metadata about a media item as a {@link Bundle}.
+ */
+public final class MediaItemMetadata {
+ /*
+ * Note: MediaMetadataRetriever also defines a collection of metadata keys that can be
+ * retrieved from a content stream although the representation is somewhat different here
+ * since we are sending the data to a remote endpoint.
+ */
+
+ private MediaItemMetadata() {
+ }
+
+ /**
+ * Metadata key: Album artist name.
+ * <p>
+ * The value is a string suitable for display.
+ * </p>
+ */
+ public static final String KEY_ALBUM_ARTIST = "ALBUM_ARTIST";
+
+ /**
+ * Metadata key: Album title.
+ * <p>
+ * The value is a string suitable for display.
+ * </p>
+ */
+ public static final String KEY_ALBUM_TITLE = "ALBUM_TITLE";
+
+ /**
+ * Metadata key: Artwork Uri.
+ * <p>
+ * The value is a string URI for an image file associated with the media item,
+ * such as album or cover art.
+ * </p>
+ *
+ * @see #KEY_ARTWORK_BITMAP
+ */
+ public static final String KEY_ARTWORK_URI = "ARTWORK_URI";
+
+ /**
+ * Metadata key: Artwork Bitmap.
+ * <p>
+ * The value is a {@link Bitmap} for an image file associated with the media item,
+ * such as album or cover art.
+ * </p><p>
+ * Because bitmaps can be large, use {@link #KEY_ARTWORK_URI} instead if the artwork can
+ * be downloaded from the network.
+ * </p>
+ *
+ * @see #KEY_ARTWORK_URI
+ */
+ public static final String KEY_ARTWORK_BITMAP = "ARTWORK_BITMAP";
+
+ /**
+ * Metadata key: Artist name.
+ * <p>
+ * The value is a string suitable for display.
+ * </p>
+ */
+ public static final String KEY_ARTIST = "ARTIST";
+
+ /**
+ * Metadata key: Author name.
+ * <p>
+ * The value is a string suitable for display.
+ * </p>
+ */
+ public static final String KEY_AUTHOR = "AUTHOR";
+
+ /**
+ * Metadata key: Composer name.
+ * <p>
+ * The value is a string suitable for display.
+ * </p>
+ */
+ public static final String KEY_COMPOSER = "COMPOSER";
+
+ /**
+ * Metadata key: Track title.
+ * <p>
+ * The value is a string suitable for display.
+ * </p>
+ */
+ public static final String KEY_TITLE = "TITLE";
+
+ /**
+ * Metadata key: Year of publication.
+ * <p>
+ * The value is an integer year number.
+ * </p>
+ */
+ public static final String KEY_YEAR = "YEAR";
+
+ /**
+ * Metadata key: Track number (such as a track on a CD).
+ * <p>
+ * The value is a one-based integer track number.
+ * </p>
+ */
+ public static final String KEY_TRACK_NUMBER = "TRACK_NUMBER";
+
+ /**
+ * Metadata key: Disc number within a collection.
+ * <p>
+ * The value is a one-based integer disc number.
+ * </p>
+ */
+ public static final String KEY_DISC_NUMBER = "DISC_NUMBER";
+}
diff --git a/v7/mediarouter/src/android/support/v7/media/MediaStreamStatus.java b/v7/mediarouter/src/android/support/v7/media/MediaItemStatus.java
similarity index 67%
rename from v7/mediarouter/src/android/support/v7/media/MediaStreamStatus.java
rename to v7/mediarouter/src/android/support/v7/media/MediaItemStatus.java
index dd37e2d..4a53113 100644
--- a/v7/mediarouter/src/android/support/v7/media/MediaStreamStatus.java
+++ b/v7/mediarouter/src/android/support/v7/media/MediaItemStatus.java
@@ -19,16 +19,16 @@
import android.os.Bundle;
/**
- * Constants for specifying status about a media stream as a {@link Bundle}.
+ * Constants for specifying status about a media item as a {@link Bundle}.
*/
-public final class MediaStreamStatus {
- private MediaStreamStatus() {
+public final class MediaItemStatus {
+ private MediaItemStatus() {
}
/**
* Status key: Playback state.
* <p>
- * Specifies the playback state of a content stream in the queue.
+ * Specifies the playback state of a media item.
* </p><p>
* Value is one of {@link #PLAYBACK_STATE_QUEUED}, {@link #PLAYBACK_STATE_PLAYING},
* {@link #PLAYBACK_STATE_PAUSED}, {@link #PLAYBACK_STATE_BUFFERING},
@@ -40,7 +40,7 @@
/**
* Playback state: Queued.
* <p>
- * Indicates that the stream is in the queue to be played eventually.
+ * Indicates that the media item is in the queue to be played eventually.
* </p>
*/
public static final int PLAYBACK_STATE_QUEUED = 0;
@@ -48,7 +48,7 @@
/**
* Playback state: Playing.
* <p>
- * Indicates that the stream is currently playing.
+ * Indicates that the media item is currently playing.
* </p>
*/
public static final int PLAYBACK_STATE_PLAYING = 1;
@@ -56,7 +56,7 @@
/**
* Playback state: Paused.
* <p>
- * Indicates that the stream has been paused. Playback can be
+ * Indicates that the media item has been paused. Playback can be
* resumed playback by sending {@link MediaControlIntent#ACTION_RESUME}.
* </p>
*/
@@ -65,7 +65,7 @@
/**
* Playback state: Buffering or seeking to a new position.
* <p>
- * Indicates that the stream has been temporarily interrupted
+ * Indicates that the media item has been temporarily interrupted
* to fetch more content. Playback will resume automatically
* when enough content has been buffered.
* </p>
@@ -75,12 +75,12 @@
/**
* Playback state: Stopped.
* <p>
- * Indicates that the stream has been stopped permanently either because
+ * Indicates that the media item has been stopped permanently either because
* it reached the end of the content or because the user ended playback.
* </p><p>
- * A stopped stream cannot be resumed. To play the content again, the application
+ * A stopped media item cannot be resumed. To play the content again, the application
* must send a new {@link MediaControlIntent#ACTION_PLAY} action to enqueue
- * a new playback request and obtain a new stream id from that request.
+ * a new playback request and obtain a new media item id from that request.
* </p>
*/
public static final int PLAYBACK_STATE_STOPPED = 4;
@@ -88,13 +88,13 @@
/**
* Playback state: Canceled.
* <p>
- * Indicates that the stream was canceled permanently. This may
- * happen because a new item was queued which caused this stream
+ * Indicates that the media item was canceled permanently. This may
+ * happen because a new media item was queued which caused this media item
* to be stopped and removed from the queue.
* </p><p>
- * A canceled stream cannot be resumed. To play the content again, the application
+ * A canceled media item cannot be resumed. To play the content again, the application
* must send a new {@link MediaControlIntent#ACTION_PLAY} action to enqueue
- * a new playback request and obtain a new stream id from that request.
+ * a new playback request and obtain a new media item id from that request.
* </p>
*/
public static final int PLAYBACK_STATE_CANCELED = 5;
@@ -102,12 +102,13 @@
/**
* Playback state: Playback halted or aborted due to an error.
* <p>
- * Examples of errors are no network connectivity when attempting to stream data from a
- * server, or expired user credentials when trying to play subscription-based content.
+ * Examples of errors are no network connectivity when attempting to retrieve content
+ * from a server, or expired user credentials when trying to play subscription-based
+ * content.
* </p><p>
- * An errored stream cannot be resumed. To play the content again, the application
- * must send a new {@link MediaControlIntent#ACTION_PLAY} action to enqueue
- * a new playback request and obtain a new stream id from that request.
+ * A media item in the error state cannot be resumed. To play the content again,
+ * the application must send a new {@link MediaControlIntent#ACTION_PLAY} action to enqueue
+ * a new playback request and obtain a new media item id from that request.
* </p>
*/
public static final int PLAYBACK_STATE_ERROR = 6;
@@ -115,10 +116,10 @@
/**
* Status key: HTTP status code.
* <p>
- * Specifies the HTTP status code that was encountered when the content stream
+ * Specifies the HTTP status code that was encountered when the content
* was requested after all redirects were followed. This key only needs to
* specified when the content uri uses the HTTP or HTTPS scheme and an error
- * occurred. This key may be omitted if the content stream was able to be played
+ * occurred. This key may be omitted if the content was able to be played
* successfully; there is no need to report a 200 (OK) status code.
* </p><p>
* Value is an integer HTTP status code such as 401 (Unauthorized), 404 (Not Found),
diff --git a/v7/mediarouter/src/android/support/v7/media/MediaRouter.java b/v7/mediarouter/src/android/support/v7/media/MediaRouter.java
index 1579100..09122e1 100644
--- a/v7/mediarouter/src/android/support/v7/media/MediaRouter.java
+++ b/v7/mediarouter/src/android/support/v7/media/MediaRouter.java
@@ -472,7 +472,7 @@
* {@link MediaControlIntent media control} request.
* <p>
* Media control requests are used to request the route to perform
- * actions such as starting remote playback of a content stream.
+ * actions such as starting remote playback of a media item.
* </p>
*
* @param intent A {@link MediaControlIntent media control intent}.
@@ -502,7 +502,7 @@
* asynchronously by the route's destination.
* <p>
* Media control requests are used to request the route to perform
- * actions such as starting remote playback of a content stream.
+ * actions such as starting remote playback of a media item.
* </p><p>
* This function may only be called on a selected route. Control requests
* sent to unselected routes will fail.
diff --git a/v7/mediarouter/src/android/support/v7/media/MediaStreamMetadata.java b/v7/mediarouter/src/android/support/v7/media/MediaStreamMetadata.java
deleted file mode 100644
index 501b8df..0000000
--- a/v7/mediarouter/src/android/support/v7/media/MediaStreamMetadata.java
+++ /dev/null
@@ -1,84 +0,0 @@
-/*
- * Copyright (C) 2013 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package android.support.v7.media;
-
-import android.graphics.Bitmap;
-import android.os.Bundle;
-
-/**
- * Constants for specifying metadata about a media stream as a {@link Bundle}.
- */
-public final class MediaStreamMetadata {
- private MediaStreamMetadata() {
- }
-
- /**
- * Metadata key: Album art.
- * <p>
- * The value is a {@link Bitmap}.
- * </p>
- */
- public static final String KEY_ALBUM_ART = "ALBUM_ART";
-
- /**
- * Metadata key: Album artist.
- * <p>
- * The value is a string suitable for display.
- * </p>
- */
- public static final String KEY_ALBUM_ARTIST = "ALBUM_ARTIST";
-
- /**
- * Metadata key: Album title.
- * <p>
- * The value is a string suitable for display.
- * </p>
- */
- public static final String KEY_ALBUM_TITLE = "ALBUM_TITLE";
-
- /**
- * Metadata key: Track artist.
- * <p>
- * The value is a string suitable for display.
- * </p>
- */
- public static final String KEY_TRACK_ARTIST = "TRACK_ARTIST";
-
- /**
- * Metadata key: Track number.
- * <p>
- * The value is an integer track number.
- * </p>
- */
- public static final String KEY_TRACK_NUMBER = "TRACK_NUMBER";
-
- /**
- * Metadata key: Track title.
- * <p>
- * The value is a string suitable for display.
- * </p>
- */
- public static final String KEY_TRACK_TITLE = "TRACK_TITLE";
-
- /**
- * Metadata key: Year of publication.
- * <p>
- * The value is an integer year number.
- * </p>
- */
- public static final String KEY_YEAR = "YEAR";
-}
