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
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: