Google Cast 发送器应用通过向接收设备应用发送 JSON 格式的消息来控制接收设备设备上的播放。同样,接收者还会以 JSON 格式将消息发回给发送者。这些消息可能是来自发送者的命令(用于更改播放器状态)、接收者对这些命令的响应,也可能是描述接收者应用媒体的数据结构。
根据 Google Cast SDK 附加开发者服务条款的规定,Cast 媒体应用必须使用此处定义的这些消息来控制接收端上的媒体播放。这样做可以为媒体应用提供跨平台一致的用户体验,并且可以确保 Cast 应用支持新的和未来的用例。这些结构还支持在适当的情况下自定义数据,并且应用可以针对 SDK 不支持的命令定义自己的消息。
媒体播放消息的命名空间定义为 urn:x-cast:com.google.cast.media。
注意:本规范中的消息和结构具有隐式大小上限,具体取决于传输消息的大小上限,单个字段没有限制。目前,传输消息的大小上限为 64 KB。
通用命名空间数据结构
在通用命名空间中定义所有媒体命名空间工件所使用的数据结构的超集。
图片
这是对图片的描述,包含少量的元数据,以便发送方应用根据其呈现方式来选择图片。
图片数组中只有一个项的高度和宽度是可选的。例如,如果仅返回单个项,则它们是可选的;如果返回了两个项,那么其中一个项必须指定高度和宽度,但如果发件人不喜欢传递特定参数的项,则可以选择“default”选项。
名称 | 类型 | 说明 |
---|---|---|
网址 | URI | 图片的 URI |
高度 | integer | 可选 :图片的高度 |
宽度 | integer | 可选 图片的宽度 |
音量
媒体流音量。用于媒体流的淡入/淡出效果。(注意:系统音量可通过发送方 API 更改。)声音流音量不得与音量滑块或音量按钮结合使用来控制设备音量。必须至少传递以下参数中的一个才能更改音频流音量。
名称 | 类型 | 说明 |
---|---|---|
级别 | 双精度 | 可选 :当前音频流的音量,以 0.0 到 1.0 之间的值表示,其中 1.0 是最大音量。 |
静音 | boolean | 可选 :是否将投射设备静音,与音量无关 |
媒体命名空间数据结构
这些消息说明了媒体播放器的状态。命名空间为 urn:x-cast:com.google.cast.media。
MediaInformation
此数据结构描述媒体流。
名称 | 类型 | 说明 |
---|---|---|
contentId | string | 媒体播放器当前加载的内容的服务特定标识符。这是一个自由格式的字符串,专用于应用。大多数情况下,这是媒体的网址,但发送者可选择传递接收者可正确解读的字符串。最大长度:1k |
streamType | 枚举 (字符串) |
将媒体工件的类型描述为以下任一项:
|
contentType | string | 正在播放的媒体的 MIME 内容类型 |
元数据 | 对象 | 可选 。媒体元数据对象,可以是以下对象之一: |
时长 | 双精度 | 可选 :当前正在播放的直播的时长(以秒为单位) |
customData | 对象 | 可选 发送方应用或接收方应用定义的应用专用数据 blob |
GenericMediaMetadata
描述通用媒体工件。
名称 | 类型 | 说明 |
---|---|---|
metadataType | integer | 0(唯一值) |
title | string | 可选 :内容的描述性标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
副标题 | string | 可选 :内容的描述性副标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
图片 | 图片[] | 可选 :指向与内容关联的图片的网址数组。该字段的初始值可以由发送者在 Load 消息中提供。应提供建议的尺寸 |
releaseDate | 字符串 (ISO 8601) | 可选 :此内容的发布日期和时间,采用 ISO 8601 格式。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
MovieMediaMetadata
描述影片媒体工件。
名称 | 类型 | 说明 |
---|---|---|
metadataType | integer | 1(唯一值) |
title | string | 可选 :内容的描述性标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
副标题 | string | 可选 :内容的描述性副标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
工作室 | string | 可选 :发布内容的工作室。播放器可以使用 content_id 独立检索 Studio,也可以由发送方在 Load 消息中提供 |
图片 | 图片[] | 可选 :指向与内容关联的图片的网址数组。该字段的初始值可以由发送者在 Load 消息中提供。应提供建议的尺寸 |
releaseDate | 字符串 (ISO 8601) | 可选 :此内容的发布日期和时间,采用 ISO 8601 格式。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
TvShowMediaMetadata
描述电视节目剧集媒体工件。
名称 | 类型 | 说明 |
---|---|---|
metadataType | integer | 2(唯一值) |
seriesTitle | string | (可选) 电视连续剧的描述性标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
副标题 | string | 可选 电视剧集的描述性副标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
季 | integer | 可选 电视节目的剧季编号 |
剧集 | integer | 选填节目的剧集编号(剧季) |
图片 | 图片[] | 可选 :指向与内容关联的图片的网址数组。该字段的初始值可以由发送者在 Load 消息中提供。应提供建议的尺寸 |
originalAirDate | 字符串 (ISO 8601) | 可选 :此剧集的发行日期和时间采用 ISO 8601 格式。播放器可以使用 content_id 独立检索 originalAirDate,也可以由发件人在 Load 消息中予以提供 |
MusicTrackMediaMetadata
描述音乐曲目媒体工件。
名称 | 类型 | 说明 |
---|---|---|
metadataType | integer | 3(唯一值) |
albumName | string | 可选 :用于生成此曲目的专辑或合集。播放器可以使用 content_id 独立检索 albumName,也可以由发送者在Load消息中给出此信息 |
title | string | 可选 :曲目的名称(例如歌曲名称)。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
albumArtist | string | 可选 :与使用此曲目的专辑关联的音乐人姓名。播放器可以使用 content_id 独立检索 albumArtist,也可以由发送者在Load消息中返回 |
音乐人 | string | 可选 :与媒体曲目关联的音乐人的姓名。播放器可以使用 content_id 独立检索音乐人,也可以在 Load 消息中由发送者提供该 ID |
composer | string | 可选 :与媒体轨道关联的作曲家的名称。播放器可以使用 content_id 独立检索合成器,也可以在 Load 消息中由发送者提供该 ID |
trackNumber | integer | (可选) 专辑中的曲目编号 |
discNumber | integer | 可选 :专辑的卷号(例如一张光盘) |
图片 | 图片[] | 可选 :指向与内容关联的图片的网址数组。该字段的初始值可以由发送者在 Load 消息中提供。应提供建议的尺寸 |
releaseDate | 字符串 (ISO 8601) | 可选 :此内容的发布日期和时间,采用 ISO 8601 格式。播放器可以使用 content_id 独立检索 releaseDate,也可以由发送者在 Load 消息中提供 |
PhotoMediaMetadata
描述摄影媒体工件。
名称 | 类型 | 说明 |
---|---|---|
metadataType | integer | 4(唯一值) |
title | string | 可选 :照片标题。播放器可以使用 content_id 独立检索标题,也可以由发送者在 Load 消息中提供 |
音乐人 | string | 可选 :摄影师的姓名。播放器可以使用 content_id 独立检索音乐人,也可以在 Load 消息中由发送者提供该 ID |
地理位置 | string | 可选 :照片的拍摄地点;例如“西班牙马德里”。播放器可以使用 content_id 独立检索位置,也可以由发送者在 Load 消息中提供 |
latitude | 双精度 | 可选 :照片拍摄地点的地理纬度值。播放器可以使用 content_id 独立检索纬度,也可以通过 Load 消息中的发送人提供纬度 |
longitude | 双精度 | 可选参数:照片拍摄地点的地理经度值。播放器可以使用 content_id 独立检索经度,也可以由发送者在 Load 消息中提供经度 |
宽度 | integer | 可选 照片的宽度(以像素为单位)。播放器可以使用 content_id 独立检索宽度,也可以由发送者在 Load 消息中给定检索宽度 |
高度 | integer | 可选 :照片的高度(以像素为单位)。播放器可以使用 content_id 独立检索高度,也可以由发送者在 Load 消息中给定检索高度 |
creationDateTime | 字符串 (ISO 8601) | 可选 :照片的拍摄日期和时间,采用 ISO 8601 格式。播放器可以使用 content_id 单独检索 createDateTime,也可以由发送者在 Load 消息中提供时间 |
MediaStatus
描述媒体工件相对于会话的当前状态。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 用于播放此特定会话的唯一 ID。此 ID 由接收方在 LOAD 进行设置,可用于识别播放的特定实例。例如,如果在同一会话中两次“Wish You are here”播放,每次播放都会拥有唯一的 mediaSessionId。 |
media | MediaInformation | 可选(适用于状态消息) 对正在播放的内容的完整说明。仅当 MediaInformation 发生更改时,状态消息中才会返回此字段。 |
playbackRate | float | 指示媒体时间是否正在播放,以及以何种速率播放。这与播放器状态无关,因为媒体时间在任何状态下都可能停止。1.0 表示常规时间,0.5 表示慢动作 |
playerState | 枚举(字符串) | 将播放器的状态描述为以下状态之一:
|
idleReason | 枚举(字符串) | 可选 如果 PlayerState 为 IDLE 且其变为 IDLE 的原因已知,则提供此属性。如果播放器因刚刚开始播放而处于 IDLE 状态,则系统不会提供此属性;如果播放器处于任何其他状态,则不应提供此属性。适用的值如下:
|
currentTime | 双精度 | 媒体播放器自内容开头以来的当前位置(以秒为单位)。如果这是直播内容,则此字段表示从活动开始算起,播放器应知晓的时间(以秒为单位)。 |
supportedMediaCommands | flags | 描述媒体播放器支持的媒体命令的标志:
组合以求和形式描述;例如,Pause+Seek+StreamVolume+Mute == 15。 |
卷 | Volume | 音频流音量 |
customData | 对象 | 可选 由接收器应用定义的应用专属数据 blob |
从发送者到接收者的命令
这些命令用于控制媒体播放器。以下消息中的所有 customData 对象都必须是可选的(即数据未传递时,接收器应适当降级)。这样一来,常规的遥控器应用将能够正常运行。
加载
在媒体播放器中加载新内容。
名称 | 类型 | 说明 |
---|---|---|
requestId | integer | 请求的 ID,用于将请求和响应关联起来 |
type | string | LOAD (仅限值) |
media | MediaInformation | 要加载的媒体的元数据(包括 contentId) |
自动播放 | boolean | 可选 (默认值为 true)如果指定了 autoplay 参数,媒体播放器将在内容加载后开始播放内容。即使未指定自动播放,媒体播放器实现也可能会选择立即开始播放。如果开始播放,响应中的播放器状态应设置为 BUFFERING,否则应设置为 PAUSED |
currentTime | 双精度 | 可选 :自内容开始播放以来的秒数。如果内容是直播内容,并且未指定位置,则直播将从直播位置开始 |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
无 | 接收器状态更改 | 媒体状态更改消息 | 播放器状态无效 加载失败 加载已取消 |
暂停
暂停播放当前内容。触发 STATUS 事件通知给所有发送器应用。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 要暂停的媒体会话的 ID |
requestId | integer | 请求的 ID,用于关联请求/响应 |
type | string | PAUSE (仅限值) |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
无 | 接收器状态更改 | 媒体状态更改消息 | 播放器状态无效 |
进度
设置信息流中的当前位置。触发 STATUS 事件通知给所有发送器应用。如果提供的位置超出当前内容的有效位置范围,则播放器应选择尽可能接近请求位置的有效位置。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 设置流位置的媒体会话的 ID |
requestId | integer | 请求的 ID,用于将请求和响应关联起来 |
type | string | SEEK (仅限值) |
resumeState | 枚举(字符串) | 可选 。如果未设置此属性,播放状态不会更改;系统会应用以下值:
|
currentTime | 双精度 | 可选 :自内容开始播放以来的秒数。如果内容是直播内容,并且未指定位置,则直播将从直播位置开始 |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
无 | 接收器状态更改 | 媒体状态更改消息 | 播放器状态无效 |
停止
停止播放当前内容。触发 STATUS 事件通知给所有发送器应用。在此命令之后,将不再加载内容,并且 mediaSessionId 会失效。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 要停止的内容的媒体会话的 ID |
requestId | integer | 请求的 ID,用于将请求和响应关联起来 |
type | string | STOP (仅限值) |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
无 | 接收器状态更改 | 媒体状态更改消息 | 播放器状态无效 |
播放
开始播放通过 load 调用加载的内容,然后从当前时间位置继续播放。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 要播放的内容的媒体会话 ID |
requestId | integer | 请求的 ID,用于将请求和响应关联起来 |
type | string | PLAY (仅限值) |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
无 | 接收器状态更改 | 媒体状态更改消息 | 播放器状态无效 |
获取状态
检索媒体状态。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 可选 :应返回其媒体状态的媒体的媒体会话 ID。如果未提供,系统将提供所有媒体会话 ID 的状态。 |
requestId | integer | 请求的 ID,用于将请求和响应关联起来 |
type | string | GET_STATUS (仅限值) |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
MediaStatus 消息发送给提出请求的发送者 | 无 | 无 | 无 |
SetVolume
设置媒体流音量。用于媒体流的淡入/淡出效果。(注意:接收器音量是使用网络发送器 setVolume 更改的。) 声音流音量不得与音量滑块或音量按钮结合使用来控制设备音量。音频流音量的变化不会触发接收器上的任何界面。
名称 | 类型 | 说明 |
---|---|---|
mediaSessionId | integer | 更改了流音量的媒体的媒体会话 ID |
requestId | integer | 请求的 ID,用于将请求和响应关联起来 |
type | string | VOLUME (仅限值) |
卷 | Volume | 音频流音量 |
customData | 对象 | 可选 发送方应用定义的应用专用数据 blob |
响应 | 触发器 | 广播 | 错误数 |
---|---|---|---|
无 | 接收器状态更改 | 媒体状态更改消息 | 播放器状态无效 |
从接收者到发送者的消息
接收者发送两种类型的消息:
- 错误:当发送者请求收到错误响应时发送的 Unicast 消息。
- 状态:广播消息。
- 发送者所发起操作的结果。将包含导致更改的请求的 requestId。
- 自发:例如,由于接收方应用触发的更改。RequestId 为 0。
错误:播放器状态无效
当因播放器未处于有效状态而无法实现发送者的请求时发送。例如,在应用尚未创建媒体元素时。
名称 | 类型 | 说明 |
---|---|---|
requestId | integer | 生成此错误的请求的 ID |
type | string | INVALID_PLAYER_STATE (仅限值) |
customData | 对象 | 可选 由接收器应用定义的应用专属数据 blob |
错误:加载失败
当加载请求失败时发送。播放器状态为“IDLE”。
名称 | 类型 | 说明 |
---|---|---|
requestId | integer | 生成此错误的请求的 ID |
type | string | LOAD_FAILED (仅限值) |
customData | 对象 | 可选 由接收器应用定义的应用专属数据 blob |
错误:加载已取消
当加载请求被取消(又收到第二个加载请求)时发送。
名称 | 类型 | 说明 |
---|---|---|
requestId | integer | 生成此错误的请求的 ID |
type | string | LOAD_CANCELLED (仅限值) |
customData | 对象 | 可选 由接收器应用定义的应用专属数据 blob |
错误:请求无效
当请求无效(例如未知请求类型)时发送。
名称 | 类型 | 说明 |
---|---|---|
requestId | integer | 生成此错误的请求的 ID |
type | string | INVALID_REQUEST (仅限值) |
原因 | 枚举(字符串) | 值:
|
customData | 对象 | 可选 由接收器应用定义的应用专属数据 blob |
媒体状态
在状态发生变化或收到媒体状态请求之后发送。只会发送已更改或请求的 MediaStatus 对象。
名称 | 类型 | 说明 |
---|---|---|
requestId | integer | 用于将此状态响应与发起它的请求相关联的 ID;如果状态消息是自发的(不是由发送者请求触发),则为 0。发送者应用通过选择一个随机数字并不断增大该 ID 来生成唯一的请求 ID(它们不会使用 0)。 |
type | string | MEDIA_STATUS (仅限值) |
状态 | MediaStatus[] | 媒体状态对象的数组。注意:仅当 MediaStatus 中的媒体元素发生更改时,系统才会返回该元素。 |
customData | 对象 | 可选 由接收器应用定义的应用专属数据 blob |