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:
|
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:
|
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:
|
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:
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:
|
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:
|
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 |