Media Playback Messages

Google Cast sender applications control the playback on the receiver device by sending messages in JSON format to the receiver application. Likewise, the receiver sends messages back to the sender, also in JSON. The messages may be commands from the sender that change the player state, responses to those commands from the receiver, or data structures that describe the media for the receiver application.

Following the Google Cast SDK Additional Developer Terms of Service, a Cast media application must use these messages as defined here to control media playback on the receiver. Doing so provides the media app with a consistent user experience across platforms and it ensures that a Cast application will support new and future use cases. These structures also support custom data, where appropriate, and an application may define its own messages for commands not supported by the SDK.

The namespace for the media playback messages is defined as urn:x-cast:com.google.cast.media.

Note: The messages and structures in this specification have an implicit maximum size determined by the maximum size of a transport message, there is no limit for individual fields. The transport message maximum size is currently 64 KBytes.

Common namespace data structures

A superset of data structures used by all media namespace artifacts is defined in a common namespace.

Image

This is the description of an image, including a small amount of metadata to allow the sender application a choice of images, depending on how it will render them.

The height and width are optional on only one item in an array of Images. For example, if there is a single item returned, then they are optional; if there are two items returned, one item must specify a height and width, but the sender may choose to go with the "default" option if it does not like the one passed with specific parameters.

Name Type Description
url URI URI for the image
height integer optional Height of the image
width integer optional Width of the image

Volume

The media stream volume. Used for fade-in/fade-out effects on the media stream. (Note: system volume is changed using the sender APIs.) Stream volume must not be used in conjunction with the volume slider or volume buttons to control the device volume. At least one of the following params must be passed to change the stream volume.

Name Type Description
level double optional Current stream volume level as a value between 0.0 and 1.0 where 1.0 is the maximum volume.
muted boolean optional Whether the Cast device is muted, independent of the volume level

Media namespace data structures

These messages describe the state of the media player. The namespace is urn:x-cast:com.google.cast.media.

MediaInformation

This data structure describes a media stream.

Name Type Description
contentId string Service-specific identifier of the content currently loaded by the media player. This is a free form string and is specific to the application. In most cases, this will be the URL to the media, but the sender can choose to pass a string that the receiver can interpret properly. Max length: 1k
streamType enum
(string)

Describes the type of media artifact as one of the following:

  • NONE
  • BUFFERED
  • LIVE
contentType string MIME content type of the media being played
metadata object

optional The media metadata object, one of the following:

duration double optional Duration of the currently playing stream in seconds
customData object optional Application-specific blob of data defined by either the sender application or the receiver application

GenericMediaMetadata

Describes a generic media artifact.

Name Type Description
metadataType integer 0  (the only value)
title string optional Descriptive title of the content. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
subtitle string optional Descriptive subtitle of the content. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
images Image[] optional Array of URL(s) to an image associated with the content. The initial value of the field can be provided by the sender in the Load message. Should provide recommended sizes
releaseDate string (ISO 8601) optional ISO 8601 date and time this content was released. Player can independently retrieve title using content_id or it can be given by the sender in the Load message

MovieMediaMetadata

Describes a movie media artifact.

Name Type Description
metadataType integer 1  (the only value)
title string optional Descriptive title of the content. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
subtitle string optional Descriptive subtitle of the content. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
studio string optional Studio which released the content. Player can independently retrieve studio using content_id or it can be given by the sender in the Load message
images Image[] optional Array of URL(s) to an image associated with the content. The initial value of the field can be provided by the sender in the Load message. Should provide recommended sizes
releaseDate string (ISO 8601) optional ISO 8601 date and time this content was released. Player can independently retrieve title using content_id or it can be given by the sender in the Load message

TvShowMediaMetadata

Describes a television show episode media artifact.

Name Type Description
metadataType integer 2  (the only value)
seriesTitle string optional Descriptive title of the t.v. series. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
subtitle string optional Descriptive subtitle of the t.v. episode. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
season integer optional Season number of the t.v. show
episode integer optional Episode number (in the season) of the t.v. show
images Image[] optional Array of URL(s) to an image associated with the content. The initial value of the field can be provided by the sender in the Load message. Should provide recommended sizes
originalAirDate string (ISO 8601) optional ISO 8601 date and time this episode was released. Player can independently retrieve originalAirDate using content_id or it can be given by the sender in the Load message

MusicTrackMediaMetadata

Describes a music track media artifact.

Name Type Description
metadataType integer 3  (the only value)
albumName string optional Album or collection from which this track is drawn. Player can independently retrieve albumName using content_id or it can be given by the sender in the Load message
title string optional Name of the track (for example, song title). Player can independently retrieve title using content_id or it can be given by the sender in the Load message
albumArtist string optional Name of the artist associated with the album featuring this track. Player can independently retrieve albumArtist using content_id or it can be given by the sender in the Load message
artist string optional Name of the artist associated with the media track. Player can independently retrieve artist using content_id or it can be given by the sender in the Load message
composer string optional Name of the composer associated with the media track. Player can independently retrieve composer using content_id or it can be given by the sender in the Load message
trackNumber integer optional Number of the track on the album
discNumber integer optional Number of the volume (for example, a disc) of the album
images Image[] optional Array of URL(s) to an image associated with the content. The initial value of the field can be provided by the sender in the Load message. Should provide recommended sizes
releaseDate string (ISO 8601) optional ISO 8601 date and time this content was released. Player can independently retrieve releaseDate using content_id or it can be given by the sender in the Load message

PhotoMediaMetadata

Describes a photographic media artifact.

Name Type Description
metadataType integer 4  (the only value)
title string optional Title of the photograph. Player can independently retrieve title using content_id or it can be given by the sender in the Load message
artist string optional Name of the photographer. Player can independently retrieve artist using content_id or it can be given by the sender in the Load message
location string optional Verbal location where the photograph was taken; for example, "Madrid, Spain." Player can independently retrieve location using content_id or it can be given by the sender in the Load message
latitude double optional Geographical latitude value for the location where the photograph was taken. Player can independently retrieve latitude using content_id or it can be given by the sender in the Load message
longitude double optional Geographical longitude value for the location where the photograph was taken. Player can independently retrieve longitude using content_id or it can be given by the sender in the Load message
width integer optional Width in pixels of the photograph. Player can independently retrieve width using content_id or it can be given by the sender in the Load message
height integer optional Height in pixels of the photograph. Player can independently retrieve height using content_id or it can be given by the sender in the Load message
creationDateTime string (ISO 8601) optional ISO 8601 date and time this photograph was taken. Player can independently retrieve creationDateTime using content_id or it can be given by the sender in the Load message

MediaStatus

Describes the current status of the media artifact with respect to the session.

Name Type Description
mediaSessionId integer Unique ID for the playback of this specific session. This ID is set by the receiver at LOAD and can be used to identify a specific instance of a playback. For example, two playbacks of "Wish you were here" within the same session would each have a unique mediaSessionId.
media MediaInformation optional (for status messages) Full description of the content that is being played back. Only be returned in a status messages if the MediaInformation has changed.
playbackRate float Indicates whether the media time is progressing, and at what rate. This is independent of the player state since the media time can stop in any state. 1.0 is regular time, 0.5 is slow motion
playerState enum (string)

Describes the state of the player as one of the following:

  • IDLE  Player has not been loaded yet
  • PLAYING  Player is actively playing content
  • BUFFERING  Player is in PLAY mode but not actively playing content (currentTime is not changing)
  • PAUSED  Player is paused
idleReason enum (string)

optional If the playerState is IDLE and the reason it became IDLE is known, this property is provided. If the player is IDLE because it just started, this property will not be provided; if the player is in any other state this property should not be provided. The following values apply:

  • CANCELLED  A sender requested to stop playback using the STOP command
  • INTERRUPTED  A sender requested playing a different media using the LOAD command
  • FINISHED  The media playback completed
  • ERROR  The media was interrupted due to an error; for example, if the player could not download the media due to network issues
currentTime double The current position of the media player since the beginning of the content, in seconds. If this a live stream content, then this field represents the time in seconds from the beginning of the event that should be known to the player.
supportedMediaCommands flags

Flags describing which media commands the media player supports:

  • 1  Pause
  • 2  Seek
  • 4  Stream volume
  • 8  Stream mute
  • 16  Skip forward
  • 32  Skip backward

Combinations are described as summations; for example, Pause+Seek+StreamVolume+Mute == 15.

volume Volume Stream volume
customData object optional Application-specific blob of data defined by the receiver application

Commands from sender to receiver

These commands control the media player. All customData objects in the messages below must be optional (i.e. the receiver should degrade properly if data is not passed). This will allow generic remote control apps to work properly.

Load

Loads new content into the media player.

Name Type Description
requestId integer ID of the request, to correlate request and response
type string LOAD (only value)
media MediaInformation Metadata (including contentId) of the media to load
autoplay boolean

optional (default is true) If the autoplay parameter is specified, the media player will begin playing the content when it is loaded. Even if autoplay is not specified, media player implementation may choose to begin playback immediately. If playback is started, the player state in the response should be set to BUFFERING, otherwise it should be set to PAUSED
currentTime double optional Seconds since beginning of content. If the content is live content, and position is not specifed, the stream will start at the live position
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
None Receiver state change A Media Status Change message Invalid Player State
Load Failed
Load Cancelled

Pause

Pauses playback of the current content. Triggers a STATUS event notification to all sender applications.

Name Type Description
mediaSessionId integer ID of the media session to be paused
requestId integer ID of the request, to use to correlate request/response
type string PAUSE (only value)
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
None Receiver state change A Media Status Change message Invalid Player State

Seek

Sets the current position in the stream. Triggers a STATUS event notification to all sender applications. If the position provided is outside the range of valid positions for the current content, then the player should pick a valid position as close to the requested position as possible.

Name Type Description
mediaSessionId integer ID of the media session where the position of the stream is set
requestId integer ID of the request, to correlate request and response
type string SEEK (only value)
resumeState enum (string)

optional If this is not set, playback status will not change; the following values apply:

  • PLAYBACK_START  Forces media to start
  • PLAYBACK_PAUSE  Forces media to pause
currentTime double optional Seconds since beginning of content. If the content is live content, and position is not specifed, the stream will start at the live position
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
None Receiver state change A Media Status Change message Invalid Player State

Stop

Stops playback of the current content. Triggers a STATUS event notification to all sender applications. After this command the content will no longer be loaded and the mediaSessionId is invalidated.

Name Type Description
mediaSessionId integer ID of the media session for the content to be stopped
requestId integer ID of the request, to correlate request and response
type string STOP (only value)
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
None Receiver state change A Media Status Change message Invalid Player State

Play

Begins playback of the content that was loaded with the load call, playback is continued from the current time position.

Name Type Description
mediaSessionId integer ID of the media session for the content to be played
requestId integer ID of the request, to correlate request and response
type string PLAY (only value)
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
None Receiver state change A Media Status Change message Invalid Player State

Get Status

Retrieves the media status.

Name Type Description
mediaSessionId integer optional Media session ID of the media for which the media status should be returned. If none is provided, then the status for all media session IDs will be provided.
requestId integer ID of the request, to correlate request and response
type string GET_STATUS (only value)
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
MediaStatus message to the sender that requested it None None None

SetVolume

Sets the media stream volume. Used for fade-in/fade-out effects on the media stream. (Note: receiver volume is changed using the Web sender setVolume.) Stream volume must not be used in conjunction with the volume slider or volume buttons to control the device volume. A change in stream volume will not trigger any UI on the receiver.

Name Type Description
mediaSessionId integer Media Session ID of the media for which the stream volume is changed
requestId integer ID of the request, to correlate request and response
type string VOLUME (only value)
volume Volume Stream volume
customData object optional Application-specific blob of data defined by the sender application
Response Triggers Broadcasts Errors
None Receiver state change A Media Status Change message Invalid Player State

Messages from receiver to sender

The receiver sends two types of messages:

  • Errors: Unicast messages sent when there is an error response to a sender request.
  • Status: Broadcast messages.
    • Consequence of a sender-initiated action. Will contain the requestId of the request that caused the change.
    • Spontaneous: For example, due to a change triggered by the receiver application. The RequestId will be 0.

Error: Invalid Player State

Sent when the request by the sender can not be fulfilled because the player is not in a valid state. For example, if the application has not created a media element yet.

Name Type Description
requestId integer ID of the request that generated this error
type string INVALID_PLAYER_STATE (only value)
customData object optional Application-specific blob of data defined by the receiver application

Error: Load Failed

Sent when the load request failed. The player state will be IDLE.

Name Type Description
requestId integer ID of the request that generated this error
type string LOAD_FAILED (only value)
customData object optional Application-specific blob of data defined by the receiver application

Error: Load Cancelled

Sent when the load request was cancelled (a second load request was received).

Name Type Description
requestId integer ID of the request that generated this error
type string LOAD_CANCELLED (only value)
customData object optional Application-specific blob of data defined by the receiver application

Error: Invalid Request

Sent when the request is invalid (an unknown request type, for example).

Name Type Description
requestId integer ID of the request that generated this error
type string INVALID_REQUEST (only value)
reason Enum (string)

Values:

  • INVALID_COMMAND  The command is not supported
  • DUPLICATE_REQUESTID  The request ID is not unique (the receiver is processing a request with the same ID)
customData object optional Application-specific blob of data defined by the receiver application

Media status

Sent after a state change or after a media status request. Only the MediaStatus objects that changed or were requested will be sent.

Name Type Description
requestId integer ID used to correlate this status response with the request that originated it or 0 if the status message is spontaneous (not triggered by a sender request). Sender applications will generate unique request IDs by selecting a random number and continuously increasing it (they will not use 0).
type string MEDIA_STATUS (only value)
status MediaStatus[] Array of Media Status objects. NOTE: the media element in MediaStatus will only be returned if it has changed.
customData object optional Application-specific blob of data defined by the receiver application