public final class MediaItemStatus extends Object
This class is part of the remote playback protocol described by the
MediaControlIntent
class.
As a media item is played, it transitions through a sequence of states including:
pending
, buffering
,
playing
, paused
,
finished
, canceled
,
invalidated
, and
error
. Refer to the documentation of each state
for an explanation of its meaning.
While the item is playing, the playback status may also include progress information
about the content position
and
content duration
although not all route destinations
will report it.
To monitor playback status, the application should supply a PendingIntent
to use as the
item status update receiver
for a given playback request
. Note that
the status update receiver will only be invoked for major status changes such as a
transition from playing to finished.
The status update receiver will not be invoked for minor progress updates such as
changes to playback position or duration. If the application wants to monitor
playback progress, then it must use the
get status request
to poll for changes
periodically and estimate the playback position while playing. Note that there may
be a significant power impact to polling so the application is advised only
to poll when the screen is on and never more than about once every 5 seconds or so.
This object is immutable once created using a MediaItemStatus.Builder
instance.
Modifier and Type | Class and Description |
---|---|
static class |
MediaItemStatus.Builder
Builder for
media item status objects . |
Modifier and Type | Field and Description |
---|---|
static String |
EXTRA_HTTP_RESPONSE_HEADERS
Bundle extra: HTTP response headers.
|
static String |
EXTRA_HTTP_STATUS_CODE
Integer extra: HTTP status code.
|
static int |
PLAYBACK_STATE_BUFFERING
Playback state: Buffering or seeking to a new position.
|
static int |
PLAYBACK_STATE_CANCELED
Playback state: Canceled.
|
static int |
PLAYBACK_STATE_ERROR
Playback state: Playback halted or aborted due to an error.
|
static int |
PLAYBACK_STATE_FINISHED
Playback state: Finished.
|
static int |
PLAYBACK_STATE_INVALIDATED
Playback state: Invalidated.
|
static int |
PLAYBACK_STATE_PAUSED
Playback state: Paused.
|
static int |
PLAYBACK_STATE_PENDING
Playback state: Pending.
|
static int |
PLAYBACK_STATE_PLAYING
Playback state: Playing.
|
Modifier and Type | Method and Description |
---|---|
Bundle |
asBundle()
Converts this object to a bundle for serialization.
|
static MediaItemStatus |
fromBundle(Bundle bundle)
Creates an instance from a bundle.
|
long |
getContentDuration()
Gets the total duration of the content to be played as a long integer number of
milliseconds.
|
long |
getContentPosition()
Gets the content playback position as a long integer number of milliseconds
from the beginning of the content.
|
Bundle |
getExtras()
Gets a bundle of extras for this status object.
|
int |
getPlaybackState()
Gets the playback state of the media item.
|
long |
getTimestamp()
Gets the timestamp associated with the status information in
milliseconds since boot in the
SystemClock.elapsedRealtime() time base. |
String |
toString()
Returns a string representation of the object.
|
public static final int PLAYBACK_STATE_PENDING
Indicates that the media item has not yet started playback but will be played eventually.
public static final int PLAYBACK_STATE_PLAYING
Indicates that the media item is currently playing.
public static final int PLAYBACK_STATE_PAUSED
Indicates that playback of the media item has been paused. Playback can be
resumed using the resume
action.
public static final int PLAYBACK_STATE_BUFFERING
Indicates that the media item has been temporarily interrupted to fetch more content. Playback will continue automatically when enough content has been buffered.
public static final int PLAYBACK_STATE_FINISHED
Indicates that the media item played to the end of the content and finished normally.
A finished media item cannot be resumed. To play the content again, the application
must send a new play
or
enqueue
action.
public static final int PLAYBACK_STATE_CANCELED
Indicates that the media item was explicitly removed from the queue by the
application. Items may be canceled and removed from the queue using
the remove
or
stop
action or by issuing
another play
action that has the
side-effect of clearing the queue.
A canceled media item cannot be resumed. To play the content again, the
application must send a new play
or
enqueue
action.
public static final int PLAYBACK_STATE_INVALIDATED
Indicates that the media item was invalidated permanently and involuntarily. This state is used to indicate that the media item was invalidated and removed from the queue because the session to which it belongs was invalidated (typically by another application taking control of the route).
When invalidation occurs, the application should generally wait for the user to perform an explicit action, such as clicking on a play button in the UI, before creating a new media session to avoid unnecessarily interrupting another application that may have just started using the route.
An invalidated media item cannot be resumed. To play the content again, the application
must send a new play
or
enqueue
action.
public static final int PLAYBACK_STATE_ERROR
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.
A media item in the error state cannot be resumed. To play the content again,
the application must send a new play
or
enqueue
action.
public static final String EXTRA_HTTP_STATUS_CODE
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 was able to be played successfully; there is no need to report a 200 (OK) status code.
The value is an integer HTTP status code, such as 401 (Unauthorized), 404 (Not Found), or 500 (Server Error), or 0 if none.
public static final String EXTRA_HTTP_RESPONSE_HEADERS
Specifies the HTTP response headers that were returned when the content was requested from the network. The headers may include additional information about the content or any errors conditions that were encountered while trying to fetch the content.
The value is a Bundle
of string based key-value pairs
that describe the HTTP response headers.
public long getTimestamp()
SystemClock.elapsedRealtime()
time base.SystemClock.elapsedRealtime()
time base.public int getPlaybackState()
PLAYBACK_STATE_PENDING
,
PLAYBACK_STATE_PLAYING
, PLAYBACK_STATE_PAUSED
,
PLAYBACK_STATE_BUFFERING
, PLAYBACK_STATE_FINISHED
,
PLAYBACK_STATE_CANCELED
, PLAYBACK_STATE_INVALIDATED
,
or PLAYBACK_STATE_ERROR
.public long getContentPosition()
public long getContentDuration()
public Bundle getExtras()
public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
public Bundle asBundle()
public static MediaItemStatus fromBundle(Bundle bundle)
bundle
- The bundle, or null if none.