媒体播放消息

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 枚举
（字符串）

将媒体工件的类型描述为以下任一项：

  • NONE
  • 已缓冲
  • 直播
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 枚举（字符串）

将播放器的状态描述为以下状态之一：

  • IDLE   播放器尚未加载
  • PLAYING   播放器正在播放内容
  • BUFFERING   玩家处于 PLAY 模式，但未主动播放内容（currentTime 未改变）
  • PAUSED  播放器已暂停
idleReason 枚举（字符串）

可选  如果 PlayerState 为 IDLE 且其变为 IDLE 的原因已知，则提供此属性。如果播放器因刚刚开始播放而处于 IDLE 状态，则系统不会提供此属性；如果播放器处于任何其他状态，则不应提供此属性。适用的值如下：

  • 已取消  ：发送者使用 STOP 命令请求停止播放
  • INTERRUPTED   某个发送者使用 LOAD 命令请求播放其他媒体
  • FINISHED   媒体播放完毕
  • ERROR   媒体因出错而中断；例如，如果播放器因网络问题而无法下载媒体
currentTime 双精度 媒体播放器自内容开头以来的当前位置（以秒为单位）。如果这是直播内容，则此字段表示从活动开始算起，播放器应知晓的时间（以秒为单位）。
supportedMediaCommands flags

描述媒体播放器支持的媒体命令的标志：

  • 1  暂停
  • 2  跳转
  • 4  直播音量
  • 8  直播静音
  • 16  快进
  • 32  快退

组合以求和形式描述；例如，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 枚举（字符串）

可选 。如果未设置此属性，播放状态不会更改；系统会应用以下值：

  • PLAYBACK_START   强制开始播放媒体
  • PLAYBACK_PAUSE   强制暂停媒体
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 （仅限值）
原因 枚举（字符串）

值：

  • INVALID_Command  不支持该命令
  • DUPLICATE_REQUESTID   请求 ID 不唯一（接收方正在处理具有相同 ID 的请求）
customData 对象 可选 由接收器应用定义的应用专属数据 blob

媒体状态

在状态发生变化或收到媒体状态请求之后发送。只会发送已更改或请求的 MediaStatus 对象。

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