-
Notifications
You must be signed in to change notification settings - Fork 174
RAMP protocol
Archived from Google Cache https://developers.google.com/cast/cast_messages?hl=en
Media tracks in the current content are described using the following data structure.
TRACKS: [
{
"id": , // unique identifier of track
"type": "subtitles"|"captions"|"audio"<wbr>|"video",
"name": , // optional, human readable description
"lang": , // optional
"selected": // optional, true if track is in use, default false
}, {..} ]
}
An ID that is unique within the scope of a single content. ID cannot change during the lifetime of a playback session.
Identity the type of track. Currently supported types are subtitles, closed captions, audio, and video. If content contains only 1 track or types video and audio, ie. if there are no user selections possible, then these tracks should not be returned.
Human readable description of the track. e.g description audio track, vs. alternate audio track. The name field will be assumed to be in the language specified in the lang field.
The language of the track given in ISO-639 code.
Indicates if the track is currently being used for playback. This field will be modified by the SELECT_TRACKS command.
Player status is represented by the following JSON object which is used by various other messages:
{
"event_sequence": ,
"state": ,
"content_id": "", // src in LOAD
"title": , // optional, descriptive title of content
"time_progress": , // indicate if media time is progressing
"current_time": , // sec since beginning of content
"duration": , // sec for duration of content
"volume": , // 0.0-1.0
"muted": , // mute state, set by VOLUME command
"content_info": {...}, // optional
"tracks": , // optional array of tracks
"error":
{
"domain": , // Error domain
"code": // Error code
},
"image_url": // optional url for content specific image url
}
The sequence number is used to identity the relative position of status events received from response to operations (LOAD, PLAY... etc.), and those received from unsolicited status updates. When a status event is received from the response of an operation, any status event received with sequence number less than that of the response should be ignored.
There is an assumption that player status message may be delivered on a separate channel than the one used to send commands. Thus event_sequence can become out of order. Currently implementations do not use separate channels and therefore will always deliver status messages in order.
0= IDLE
1= STOPPED
2= PLAYING
If player state is IDLE, then all fields except sequence and error should be ignored.
This is the service-specific identifier of the content currently loaded by the media player. This is a free form string and is specific to the application.
A descriptive title of the content. Player can independently retrieve title using content_id or it can be given by controller in LOAD message.
Indicates whether the media time is progressing. If the value is false, controller should stop extrapolating the media time. This is independent of the player state since the media time can stop in any state.
The current position of the media player since the beginning of the content, in seconds. If this a live stream content, identified with null duration, then this field represent the time in seconds from the beginning of the event that should be known to the player.
This field represent the duration of the currently playing stream in seconds. If the stream is a live stream then this field must be null.
This field indicate the current volume level as a value between 0.0 and 1.0
This field contains a service specific object which can be used to provide more in depth information about the current content. The initial value of the field can be provided by the controller in LOAD message. Players are free to modify the content of the object to provide information obtained from player logic.
The error object returns the last error encountered by the media player since the last control operation. If no error has been encountered, it should be set to null.
Error Domain: Error domain to segregate errors, so that applications can return their own errors
Error Code: error code specific to the domain
This field represents [ TO DO ].
This command requests the status of the content currently playing in the media player.
{
"cmd_id": ,
"type": "INFO",
}
{
"cmd_id": ,
"type": "RESPONSE",
"status": , // See Player Status
}
This command is used to load new content into the media player. The field contains an identity of the media that needs to be loaded. The format of this field is defined by the application and media player.
{
"cmd_id": ,
"type": "LOAD",
"src": "", // optional
"title": , // optional
"autoplay": true|false, // optional, default false
"content_info": {...} // optional
}
{
"cmd_id": ,
"type": "RESPONSE",
"status": , // See Player Status
}
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 PLAYING, otherwise it should be set to STOPPED.
The title field optionally provides a user readable descriptive string for the content being loaded. If provided, the string will be used by the player as initial value for the title field of each STATUS object sent from the player. Whether or not the title is provided in the LOAD message, a player can modify the title at any point based on local player logic.
The content_info field can contain a JSON object which give more in depth information about the content being loaded, e.g. id of a TV service, episode number etc. If provided, the content_info object will be used as the initial value of the content_info field of each STATUS message. Players however free to modify the content_info at any point.
This begins playback of the content that was loaded with the load call or change the playback position of a currently loaded content. If the position field is not specified, then playback is continued from the current position. If position provided is outside the range of valid position of the current content, then the player should pick a valid position as closed to the requested position as possible.
{
"cmd_id": ,
"type": "PLAY",
"position": , // optional, seconds since beginning of content
}
{
"cmd_id": ,
"type": "RESPONSE",
"status": , // See Player Status
}
This halt playback of the current content. There is no distinction between stopping and pausing content.
{
"cmd_id": 0,
"type": "STOP",
}
Stopping the content will trigger a STATUS event notification to all controllers.
Set the volume at the output of the device.
{
"cmd_id": 0,
"type": "VOLUME",
"volume": , // 0.0-1.0
"muted": // True to mute audio
}
Volume level can be changed even if mute is enabled. The new volume level will apply when mute is disabled.g4
Change in volume will trigger a STATUS event notification to all controllers.
Selects the media tracks that the player should use.
{
"cmd_id": ,
"type": "SELECT_TRACKS",
"enabled": [ // optional list of tracks to enable
, ,...
],
"disabled": [ // optional list of tracks to disable
, ,...
]
}
{
"cmd_id": ,
"type": "RESPONSE",
"status": , // See Player Status
}
The SELECT_TRACKS command is used to enable or disable media tracks. The tracks are identified by trackID obtained from the TRACKS data object. The controller must check the response from the player to determine if the requested tracks are actually enabled or disabled. A player may be unable to enable a requested track because of local conditions e.g. if it cannot support more than 1 audio stream.
Modifying selected tracks will trigger a STATUS event notification to all controllers.
The data of this event contains a play status event structure with the following data fields:
{
"cmd_id": 0,
"type": "STATUS",
"status": , // See Player Status
}
Player implementations must immediately send out a STATUS message whenever there is a state transition in the player. In addition players should send out periodic updates to synchronize state with 2nd screen applications.
Media time should be extrapolated by the controller from the last STATUS update based on a local clock. If the current_time reported by a STATUS message does not match what is locally extrapolated, the local media time is updated to the value in the STATUS message.
Recommendation for player implementation: player implementations should locally compare the media time reported by the AV system with a local system clock. If the local time drifts too far from the reported media time, a new STATUS event should be generated.
In order to implement the license delegation protocol described in [ TO DO ] Google Play on Chromecast we need a way to forward key requests coming from the CDM to the controller to get a valid token.
The token is returned to the Chromecast device (via the controller) and should be passed when the license is requested.
One optimization could have been to return the license directly instead of the token but we did not go down that route to be consistent with the model used in Nexus Q (patent pending.) On top of that, the link between the Chromecast device and the controller is not secure and the Google security team recommended against passing the license.
In the current solution, the YT player will have some extra hooks we can use to register a callback when the key request is issued. We need an extension to RAMP to forward that key request and the associated reply (token).
{
"cmd_id": ,
"type": "KEY_REQUEST",
"method": ,
"requests": [ 1*,],
}
The cmd_id is an identified generated by the player and should be unique for each player session that can be used to match KEY_RESPONSE messages to the request.
The requests array contains one or more key requests. Typically during a playback there will be 2 requests from the CDM, one for the video and one for the audio stream. The player can either sends one KEY_REQUEST message per CDM request or wait and batch them into one.
The method field defines how the requests and tokensfields should be interpreted. Current valid values are "WV-token".
The response is a KEY_REPLY which contains the token(s) matching the request.
{
"cmd_id": ,
"type": "KEY_RESPONSE",
"tokens": [ 1*,],
}
The tokens are treated as opaque blobs, passed to the license server as URL parameters. The process by which tokens are used to exchange for licenses are specific to the KEY_REQUEST method.
Also check [ TO DO ] to see how the token is generated, passed and used in license server.
This command is used to load new content into the media player. The field contains an identity of the media that needs to be loaded. The format of this field is defined by the application and media player.
{
"cmd_id": ,
"type": "LOAD",
"src": "", // optional
"title": , // optional
"autoplay": true|false, // optional, default false
"content_info": {...} , // optional
... // other html5 video/audio attributes and values
}
{
"cmd_id": ,
"type": "RESPONSE",
"status": , // See Player Status
}
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 "PLAYING", otherwise it should be set to "STOPPED".
The title field optionally provides a user readable descriptive string for the content being loaded. If provided, the string will be used by the player as initial value for the title field of each STATUS object sent from the player. Whether or not the title is provided in the LOAD message, a player can modify the title at any point based on local player logic.
The content_info field can contain a JSON object which give more in depth information about the content being loaded, e.g. id of a TV service, episode number etc. If provided, the content_info object will be used as the initial value of the content_info field of each STATUS message. Players however free to modify the content_info at any point.
This begins playback of the content that was loaded with the load call or change the playback position of a currently loaded content. If the position field is not specified, then playback is continued from the current position. If position provided is outside the range of valid position of the current content, then the player should pick a valid position as closed to the requested position as possible.
{
"cmd_id": ,
"type": "PLAY",
"position": , // optional, seconds since beginning of content
}
{
"cmd_id": ,
"type": "RESPONSE",
"status": , // See Player Status
}
Halt playback of the current content.
{
"cmd_id": 0,
"type": "STOP",
}
Stopping the content will trigger a STATUS event notification.
Set the volume for the output of the device.
Request:
{
"cmd_id": 0,
"type": "VOLUME",
"volume": , // 0.0-1.0
}
The data of this event contains a play status event structure with the following data fields:
{
"cmd_id": 0,
"type": "STATUS",
"status": , // See Player Status
}
Player implementations must immediately send out a STATUS message whenever there is a state transition in the player. In addition players should send out periodic updates to synchronize state with controller applications. For short form content an update rate of approx once per second is recommended.
Media time should be extrapolated by the controller from the last STATUS update based on a local clock. If the current_time reported by a STATUS message does not match what is locally extrapolated, the local media time is updated to the value in the STATUS message.
Recommendation for player implementation: player implementations should locally compare the media time reported by the AV system with a local system clock. If the local time drifts too far from the reported media time, a new STATUS event should be generated.
Player status is represented by the following JSON object which is used by various other messages:
{
"event_sequence": ,
"state": ,
"active_input": , // true if device is active input
"content_id": "", // src in LOAD
"title": , // descriptive title of content
"time_progress": , // indicate if media time is progressing
"current_time": , // sec since beginning of content
"duration": , // sec for duration of content
"volume": , // 0.0-1.0
"content_info": {...}, // optional rich description of content
"error":
{
"domain": , // Error domain
"code": // Error code
}
}
The sequence number is used to identity the relative position of status events received from response to operations (LOAD, PLAY... etc.), and those received from unsolicited status updates. When a status event is received from the response of an operation, any status event received with sequence number less than that of the response should be ignored.
(NOTE: There is assumption that player status message may be delivered on a separate channel than the one used to send commands. Thus event_sequence can become out of order. Currently implementations do not use separate channels and therefore will always deliver status messages in order).
0= IDLE
1= STOPPED
2= PLAYING
If player state is IDLE, then all fields except sequence and error should be ignored.
This is the service-specific identifier of the content currently loaded by the media player. This is a free form string and is specific to the application.
A descriptive title of the content. Player can independently retrieve title using content_id or it can be given by controller in LOAD message.
Indicates whether the media time is progressing. If the value is false, controller should stop extrapolating the media time. This is independent of the player state since the media time can stop in any state.
The current position of the media player since the beginning of the content, in seconds. If this a live stream content, identified with null duration, then this field represent the time in seconds from the beginning of the event that should be known to the player.
This field represent the duration of the currently playing stream in seconds. If the stream is a live stream then this field must be null.
This field indicate the current volume level as a value between 0.0 and 1.0
This field contains a service specific object which can be used to provide more in depth information about the current content. The initial value of the field can be provided by the controller in LOAD message. Players are free to modify the content of the object to provide information obtained from player logic.
This is an opaque blob that is optionally send with each command to define the identity under which the command should execute. Note that this is not a system or OS identity but rather an authentication token that the media player should use when communicating with external entities, such as service provider CDN or DRM license servers.
The error object returns the last error encountered by the media player since the last control operation. If no error has been encountered, it should be set to null.
Error domain to segregate errors, so that applications can return their own errors.
Error code specific to the domain.