媒体播放消息

Google Cast 发送器应用通过以 JSON 格式向接收器应用发送消息来控制接收器设备上的播放。同样，接收者也会以 JSON 格式将消息发送回发送者。这些消息可以是发件人发送的用于更改播放器状态的命令、接收者对这些命令的响应，也可以是用于向接收者应用描述媒体的数据结构。

根据 Google Cast SDK 附加开发者服务条款，Cast 媒体应用必须使用此处定义的这些消息来控制接收器上的媒体播放。这样做可为媒体应用提供跨平台的一致用户体验，并确保 Cast 应用支持新的和未来的使用情形。这些结构还支持自定义数据（如果适用），并且应用可以为 SDK 不支持的命令定义自己的消息。

媒体播放消息的命名空间定义为 urn:x-cast:com.google.cast.media。

注意：此规范中的消息和结构具有由传输消息的最大大小确定的隐式最大大小，但各个字段没有大小限制。传输消息的最大大小目前为 64 KB。

常见的命名空间数据结构

所有媒体命名空间制品所使用的数据结构的超集定义在一个通用命名空间中。

图片

这是图片的说明，其中包含少量元数据，以便发送方应用根据图片的呈现方式选择图片。

在图片数组中，只有一项的高度和宽度是可选的。例如，如果返回单个项，则它们是可选的；如果返回两个项，则其中一个项必须指定高度和宽度，但发送者可以选择“默认”选项，如果它不喜欢通过特定参数传递的项。

名称	类型	说明
网址	URI	图片的 URI
height	整数	可选 ：图片的高度
width	整数	可选 ：图片的宽度

音量

媒体音量。用于在媒体流上实现淡入/淡出效果。（注意：系统音量是通过发送方 API 更改的。）不得将媒体音量与音量滑块或音量按钮结合使用来控制设备音量。必须至少传递以下一个参数才能更改音频流音量。

名称	类型	说明
level	double	可选 ：当前音频流音量，以介于 0.0 和 1.0 之间的值表示，其中 1.0 为最大音量。
已设为静音	布尔值	可选 ：Cast 设备是否已设为静音，与音量无关

媒体命名空间数据结构

这些消息描述了媒体播放器的状态。命名空间为 urn:x-cast:com.google.cast.media。

MediaInformation

此数据结构用于描述媒体流。

名称	类型	说明
contentId	字符串	媒体播放器当前加载的内容的服务特定标识符。这是一个自由格式的字符串，特定于应用。在大多数情况下，这会是媒体的网址，但发送者可以选择传递接收者可以正确解读的字符串。长度上限：1,000
streamType	枚举 （字符串）	将媒体制品类型描述为以下类型之一： NONE BUFFERED 直播
contentType	字符串	正在播放的媒体的 MIME 内容类型
元数据	对象	可选 。媒体元数据对象，可以是以下对象之一： 0  GenericMediaMetadata 1  MovieMediaMetadata 2  TvShowMediaMetadata 3  MusicTrackMediaMetadata 4  PhotoMediaMetadata
duration	double	可选 ：当前播放的视频流的时长（以秒为单位）
customData	对象	可选 ：由发送方应用或接收方应用定义的特定于应用的数据 blob

GenericMediaMetadata

描述通用媒体制品。

名称	类型	说明
metadataType	整数	0（唯一值）
title	字符串	可选 ：内容的描述性标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
subtitle	字符串	可选 ：内容的描述性副标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
图片	图片[]	可选 ：与内容关联的图片的网址数组。字段的初始值可由发送方在 Load 消息中提供。应提供建议的尺寸
releaseDate	字符串 (ISO 8601)	可选 ：相应内容的发布日期和时间（采用 ISO 8601 格式）。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供

MovieMediaMetadata

描述电影媒体制品。

名称	类型	说明
metadataType	整数	1（唯一值）
title	字符串	可选 ：内容的描述性标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
subtitle	字符串	可选 ：内容的描述性副标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
studio	字符串	可选 ：发布相应内容的工作室。播放器可以使用 content_id 独立检索工作室，也可以由发送者在 Load 消息中提供
图片	图片[]	可选 ：与内容关联的图片的网址数组。字段的初始值可由发送方在 Load 消息中提供。应提供建议的尺寸
releaseDate	字符串 (ISO 8601)	可选 ：相应内容的发布日期和时间（采用 ISO 8601 格式）。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供

TvShowMediaMetadata

描述电视节目剧集媒体制品。

名称	类型	说明
metadataType	整数	2（唯一值）
seriesTitle	字符串	可选 ：电视连续剧的描述性标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
subtitle	字符串	可选 电视节目的描述性副标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
season	整数	可选 ：电视节目的季号
集	整数	可选 ：电视节目的剧集编号（在剧季中）
图片	图片[]	可选 ：与内容关联的图片的网址数组。字段的初始值可由发送方在 Load 消息中提供。应提供建议的尺寸
originalAirDate	字符串 (ISO 8601)	可选 ：相应剧集的发布日期和时间（采用 ISO 8601 格式）。播放器可以使用 content_id 独立检索 originalAirDate，也可以由发送者在 Load 消息中提供

MusicTrackMediaMetadata

描述音乐轨道媒体制品。

名称	类型	说明
metadataType	整数	3（唯一值）
albumName	字符串	可选 ：相应轨道所属的专辑或合集。播放器可以使用 content_id 独立检索 albumName，也可以由发送者在 Load 消息中提供
title	字符串	可选 。轨道名称（例如歌曲标题）。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
albumArtist	字符串	可选 ：与包含相应曲目的专辑关联的音乐人名称。播放器可以使用 content_id 独立检索 albumArtist，也可以由发送方在 Load 消息中提供
音乐人	字符串	可选 ：与媒体轨道关联的音乐人名称。播放器可以使用 content_id 独立检索艺术家，也可以由发送者在 Load 消息中提供
composer	字符串	可选 ：与媒体轨道关联的作曲家的姓名。播放器可以使用 content_id 独立检索作曲家，也可以由发送者在 Load 消息中提供
trackNumber	整数	可选 ：专辑中曲目的编号
discNumber	整数	可选 ：专辑的卷（例如光盘）编号
图片	图片[]	可选 ：与内容关联的图片的网址数组。字段的初始值可由发送方在 Load 消息中提供。应提供建议的尺寸
releaseDate	字符串 (ISO 8601)	可选 ：相应内容的发布日期和时间（采用 ISO 8601 格式）。播放器可以使用 content_id 独立检索 releaseDate，也可以由发送者在 Load 消息中提供

PhotoMediaMetadata

描述摄影媒体制品。

名称	类型	说明
metadataType	整数	4（唯一值）
title	字符串	可选 照片的标题。播放器可以使用 content_id 独立检索标题，也可以由发送者在 Load 消息中提供
音乐人	字符串	可选 摄影师的姓名。播放器可以使用 content_id 独立检索艺术家，也可以由发送者在 Load 消息中提供
location	字符串	可选 ：照片的拍摄地点（以文字形式表示），例如“西班牙马德里”。播放器可以使用 content_id 独立检索位置，也可以由发送者在 Load 消息中提供
latitude	double	可选 ：照片拍摄地点的地理纬度值。播放器可以使用 content_id 独立检索纬度，也可以由发送者在 Load 消息中提供纬度
longitude	double	可选 ：照片拍摄地点的地理经度值。播放器可以使用 content_id 独立检索经度，也可以由发送者在 Load 消息中提供经度
width	整数	可选 ：照片的宽度（以像素为单位）。播放器可以使用 content_id 独立检索宽度，也可以由发送方在 Load 消息中提供宽度
height	整数	可选 ：照片的高度（以像素为单位）。播放器可以使用 content_id 独立检索高度，也可以由发送者在 Load 消息中提供高度
creationDateTime	字符串 (ISO 8601)	可选 ：拍摄相应照片的 ISO 8601 日期和时间。播放器可以使用 content_id 独立检索 creationDateTime，也可以由发送方在 Load 消息中提供

MediaStatus

描述媒体制品相对于会话的当前状态。

名称	类型	说明
mediaSessionId	整数	相应特定会话的播放的唯一 ID。此 ID 由接收方在加载时设置，可用于标识特定播放实例。例如，在同一会话中播放两次“Wish you were here”，每次播放都会有唯一的 mediaSessionId。
media	MediaInformation	可选（用于状态消息） 正在播放的内容的完整说明。仅在 MediaInformation 发生变化时才会在状态消息中返回。
playbackRate	float	指示媒体时间是否在推进，以及推进速度。这与播放器状态无关，因为媒体时间可以在任何状态下停止。1.0 为正常时间，0.5 为慢动作
playerState	枚举（字符串）	描述播放器的状态，可以是以下状态之一： 空闲  ：播放器尚未加载 正在播放  ：播放器正在主动播放内容 正在缓冲  ：播放器处于播放模式，但未主动播放内容（currentTime 未发生变化） PAUSED  ：播放器已暂停
idleReason	枚举（字符串）	可选 ：如果 playerState 为 IDLE 且变为 IDLE 的原因已知，则提供此属性。如果播放器因刚刚启动而处于 IDLE 状态，则不会提供此属性；如果播放器处于任何其他状态，则不应提供此属性。适用以下值： CANCELLED  发送者使用 STOP 命令请求停止播放 INTERRUPTED  发送者使用 LOAD 命令请求播放其他媒体 FINISHED  媒体播放已完成 ERROR  ：媒体因错误而中断；例如，播放器因网络问题而无法下载媒体
currentTime	double	媒体播放器自内容开始播放以来的当前位置（以秒为单位）。如果这是直播内容，则此字段表示播放器应知道的自活动开始以来的时间（以秒为单位）。
supportedMediaCommands	flags	用于描述媒体播放器支持哪些媒体命令的标志： 1 << 0  暂停 1 << 1  还原 1 << 2  音频流音量 1 << 3  数据流静音 1 << 4  快进（已弃用） 1 << 5  快退（已弃用） 1 << 6  将下一首歌曲添加到队列 1 << 7  将上一首歌曲加入队列 1 << 8  队列随机播放 1 << 9  跳过广告 1 << 10  队列重复播放全部 1 << 11  将单曲重复播放加入队列 1 << 12  编辑轨道 1 << 13  播放速率 1 << 14  赞 1 << 15  不喜欢 1 << 16  关注 1 << 17  取消关注 组合以求和形式描述；例如，Pause+Seek+StreamVolume+Mute == 15。
卷	Volume	视频流音量
customData	对象	可选 ：接收器应用定义的应用专用数据 blob

从发送者到接收者的命令

这些命令用于控制媒体播放器。以下消息中的所有 customData 对象都必须是可选的（即，如果未传递数据，接收方应正常降级）。这样，通用遥控器应用才能正常运行。

加载

将新内容加载到媒体播放器中。

名称	类型	说明
requestId	整数	请求的 ID，用于关联请求和响应
type	字符串	LOAD （唯一值）
media	MediaInformation	要加载的媒体的元数据（包括 contentId）
autoplay	布尔值	可选 （默认值为 true）如果指定了自动播放参数，媒体播放器会在加载内容后开始播放。即使未指定自动播放，媒体播放器实现也可以选择立即开始播放。如果开始播放，响应中的播放器状态应设置为 BUFFERING，否则应设置为 PAUSED
currentTime	double	可选 ：自内容开始以来经过的秒数。如果内容是直播内容，且未指定位置，则视频流将从直播位置开始
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
无	接收器状态变化	媒体状态更改消息	播放器状态无效 加载失败 加载已取消

暂停

暂停播放当前内容。向所有发送方应用触发 STATUS 事件通知。

名称	类型	说明
mediaSessionId	整数	要暂停的媒体会话的 ID
requestId	整数	请求的 ID，用于关联请求/响应
type	字符串	暂停 （唯一值）
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
无	接收器状态变化	媒体状态更改消息	播放器状态无效

搜索

设置视频流中的当前位置。向所有发送方应用触发 STATUS 事件通知。如果提供的位置超出当前内容的有效位置范围，播放器应选择尽可能接近所请求位置的有效位置。

名称	类型	说明
mediaSessionId	整数	设置了媒体流位置的媒体会话的 ID
requestId	整数	请求的 ID，用于关联请求和响应
type	字符串	SEEK （唯一值）
resumeState	枚举（字符串）	可选 。如果未设置此属性，播放状态将不会更改；以下值适用： PLAYBACK_START  强制媒体开始播放 PLAYBACK_PAUSE  强制媒体暂停
currentTime	double	可选 ：自内容开始以来经过的秒数。如果内容是直播内容，且未指定位置，则视频流将从直播位置开始
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
无	接收器状态变化	媒体状态更改消息	播放器状态无效

停止

停止播放当前内容。向所有发送方应用触发 STATUS 事件通知。执行此命令后，内容将不再加载，并且 mediaSessionId 会失效。

名称	类型	说明
mediaSessionId	整数	要停止的内容的媒体会话 ID
requestId	整数	请求的 ID，用于关联请求和响应
type	字符串	停止 （仅限值）
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
无	接收器状态变化	媒体状态更改消息	播放器状态无效

播放

开始播放通过 load 调用加载的内容，并从当前时间位置继续播放。

名称	类型	说明
mediaSessionId	整数	要播放的内容的媒体会话 ID
requestId	整数	请求的 ID，用于关联请求和响应
type	字符串	PLAY （唯一值）
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
无	接收器状态变化	媒体状态更改消息	播放器状态无效

获取状态

检索媒体状态。

名称	类型	说明
mediaSessionId	整数	可选 ：应返回媒体状态的媒体的媒体会话 ID。如果未提供任何 ID，则系统将提供所有媒体会话 ID 的状态。
requestId	整数	请求的 ID，用于关联请求和响应
type	字符串	GET_STATUS （唯一值）
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
向请求者发送 MediaStatus 消息	无	无	无

SetVolume

设置媒体流音量。用于在媒体流上实现淡入/淡出效果。（注意：接收器音量是通过 Web 发送器 setVolume 更改的。） 不得将媒体音量与音量滑块或音量按钮结合使用来控制设备音量。接收端不会因视频流音量发生变化而触发任何界面。

名称	类型	说明
mediaSessionId	整数	更改了音量的数据流所对应的媒体的媒体会话 ID
requestId	整数	请求的 ID，用于关联请求和响应
type	字符串	音量 （仅限值）
卷	Volume	视频流音量
customData	对象	可选 ：由发送方应用定义的特定于应用的数据 blob

响应	触发器	广播	错误
无	接收器状态变化	媒体状态更改消息	播放器状态无效

收件人发给发件人的消息

接收器会发送两种类型的消息：

• 错误：当对发送者的请求做出错误响应时发送的单播消息。
• 状态：广播消息。
  • 发件人发起的操作的后果。将包含导致更改的请求的 requestId。
  • 自发：例如，由于接收器应用触发的更改。RequestId 将为 0。

错误：播放器状态无效

当发送者的请求因播放器处于无效状态而无法完成时发送。例如，如果应用尚未创建媒体元素。

名称	类型	说明
requestId	整数	生成相应错误的请求的 ID
type	字符串	INVALID_PLAYER_STATE （唯一值）
customData	对象	可选 ：接收器应用定义的应用专用数据 blob

错误：加载失败

在加载请求失败时发送。播放器状态将为 IDLE。

名称	类型	说明
requestId	整数	生成相应错误的请求的 ID
type	字符串	LOAD_FAILED （唯一值）
customData	对象	可选 ：接收器应用定义的应用专用数据 blob

错误：加载已取消

在加载请求被取消（收到第二个加载请求）时发送。

名称	类型	说明
requestId	整数	生成相应错误的请求的 ID
type	字符串	LOAD_CANCELLED （唯一值）
customData	对象	可选 ：接收器应用定义的应用专用数据 blob

错误：请求无效

当请求无效（例如，请求类型未知）时发送。

名称	类型	说明
requestId	整数	生成相应错误的请求的 ID
type	字符串	INVALID_REQUEST （仅限值）
原因	枚举（字符串）	值： INVALID_COMMAND  不支持该命令 DUPLICATE_REQUESTID  ：请求 ID 不是唯一的（接收方正在处理具有相同 ID 的请求）
customData	对象	可选 ：接收器应用定义的应用专用数据 blob

媒体状态

在状态更改后或媒体状态请求后发送。系统只会发送已更改或被请求的 MediaStatus 对象。

名称	类型	说明
requestId	整数	用于将此状态响应与发起该响应的请求相关联的 ID；如果状态消息是自发的（不是由发送方请求触发的），则为 0。发送方应用将通过选择一个随机数并不断增加该随机数来生成唯一请求 ID（它们不会使用 0）。
type	字符串	MEDIA_STATUS （唯一值）
状态	MediaStatus[]	媒体状态对象数组。注意：只有当媒体元素发生变化时，系统才会返回 MediaStatus 中的媒体元素。
customData	对象	可选 ：接收器应用定义的应用专用数据 blob