媒体播放消息

Google Cast 发送者应用以 JSON 格式向接收设备应用发送消息，从而控制接收端设备上的播放。同样，接收者也使用 JSON 将消息发回给发送者。这些消息可能是来自发送器的命令（用于更改播放器状态）、对来自这些命令的响应（来自接收器），或用于描述接收器（应用）媒体的数据结构。

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

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

注意：本规范中的消息和结构都有隐含的大小上限，该大小由传输消息的大小上限决定。各个字段没有限制。传输消息的大小上限目前为 64 KB。

常见的命名空间数据结构

所有媒体命名空间工件使用的数据结构超集是在通用命名空间中定义的。

图片

这是图片的说明，包括少量元数据，以便发送者应用选择图片，具体取决于图片的呈现方式。

对于图片数组中的一项，高度和宽度是可选的。例如，如果返回了单个项，那么它们是可选的。如果返回了两个项，则一个项必须指定高度和宽度，但如果发送者不喜欢传递带有特定参数的项，则可以选择使用“默认”选项。

名称 类型 说明
网址 URI 图片的 URI
高度 integer 可选：图片的高度
宽度 integer 可选：图片的宽度

卷

媒体流音量。用于对媒体流进行淡入/淡出效果。（注意：系统会使用发送者 API 更改系统音量。）信息流音量不得与音量滑块或音量按钮结合使用，以控制设备音量。如需更改流音量，必须至少传递以下参数之一。

名称 类型 说明
级别 双精度 可选：当前音量音量值，介于 0.0 和 1.0 之间，其中 1.0 是最大音量。
静音 布尔值 可选：投射设备是否静音（不考虑音量级别）

媒体命名空间数据结构

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

媒体信息

此数据结构描述的是媒体流。

名称 类型 说明
内容 ID 字符串 媒体播放器当前所加载内容的服务标识符。这是一个自由格式字符串，且特定于应用。在大多数情况下，这将是媒体的网址，但发件人可以选择传递一个接收器可以正确解读的字符串。最大长度：1k
streamType 枚举
（字符串）

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

  • NONE
  • 已配对
  • 直播
内容类型 字符串 播放的媒体的 MIME 内容类型
元数据 对象

可选：媒体元数据对象，可以是以下几项之一：

时长 双精度 可选：当前播放的直播时长（以秒为单位）
自定义数据 对象 可选 - 由发送方应用或接收方应用定义的应用专属数据 blob

GenericMediaMetadata

描述通用媒体工件。

名称 类型 说明
metadataType integer 0（唯一值）
title 字符串 可选：内容的说明性标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
副标题 字符串 可选：内容的描述性副标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
图片 图片[] 可选字段。指向内容相关图片的网址数组。该字段的初始值可由发送者在加载消息中提供。应提供建议的尺寸
发布日期 字符串 (ISO 8601) 可选：ISO 8601 日期和时间。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。

电影媒体元数据

描述电影媒体工件。

名称 类型 说明
metadataType integer 1（唯一值）
title 字符串 可选：内容的说明性标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
副标题 字符串 可选：内容的描述性副标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
工作室 字符串 可选 - 发布内容的工作室。播放器可以使用 content_id 独立检索工作室，也可以由发送者通过 Load 消息提供
图片 图片[] 可选字段。指向内容相关图片的网址数组。该字段的初始值可由发送者在加载消息中提供。应提供建议的尺寸
发布日期 字符串 (ISO 8601) 可选：ISO 8601 日期和时间。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。

TvShowMediaMetadata

描述电视节目剧集媒体工件。

名称 类型 说明
metadataType integer 2（唯一值）
seriesTitle 字符串 可选：t.v. 系列的描述性标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
副标题 字符串 可选：电视剧集的副标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
剧季 integer 可选：电视节目的剧季编号
剧集 integer 可选：剧季的剧集编号（在剧季中）
图片 图片[] 可选字段。指向内容相关图片的网址数组。该字段的初始值可由发送者在加载消息中提供。应提供建议的尺寸
原始航空日期 字符串 (ISO 8601) 可选 ISO 8601 日期和时间值。播放器可以使用 content_id 独立检索原始 AirDate，或者可由发送者在加载消息中提供

MusicTrack 媒体元数据

描述音乐曲目媒体工件。

名称 类型 说明
metadataType integer 3（唯一值）
影集名称 字符串 可选：从中提取此曲目的专辑或作品集。播放器可以使用 content_id 独立检索 albumName，或者也可以由发送者在 Load 消息中提供此名称
title 字符串 可选曲目的名称（例如歌曲名称）。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
专辑音乐人 字符串 可选：与含有此曲目的专辑相关联的音乐人的名字。播放器可以使用 content_id 独立检索 albumArtist，也可以由发送者在加载消息中提供
音乐人 字符串 可选：与媒体曲目相关联的音乐人姓名。播放器可以使用 content_id 独立检索音乐人，也可以由发送者在加载消息中提供
composer 字符串 可选：与媒体轨道关联的 Composer 名称。播放器可以使用 content_id 单独检索 Composer，也可以由发送者在 Load 消息中提供
trackNumber integer 可选 专辑中的曲目编号
discNumber integer 可选：专辑的音量（例如光盘）数量
图片 图片[] 可选字段。指向内容相关图片的网址数组。该字段的初始值可由发送者在加载消息中提供。应提供建议的尺寸
发布日期 字符串 (ISO 8601) 可选：ISO 8601 日期和时间。玩家可以使用 content_id 独立检索 releaseDate，也可以由发送者在 Load 消息中提供

照片媒体元数据

描述照片媒体工件。

名称 类型 说明
metadataType integer 4（唯一值）
title 字符串 可选：照片的标题。玩家可以使用 content_id 独立检索影视内容，也可以由发送者在 Load 消息中提供。
音乐人 字符串 可选：摄影师的姓名。播放器可以使用 content_id 独立检索音乐人，也可以由发送者在加载消息中提供
地理位置 字符串 可选：所拍摄照片的口头位置，例如“西班牙马德里”。播放器可以使用 content_id 独立检索位置信息，也可以由发送者通过 Load 消息提供
latitude 双精度 可选：照片拍摄地理位置的纬度值。播放器可以使用 content_id 独立检索纬度，也可以由发送者在加载消息中指明。
longitude 双精度 可选：拍照地点的地理位置经度值。玩家可以使用 content_id 独立检索经度，也可以由发送者通过 Load 消息提供
宽度 integer 可选：照片的宽度（以像素为单位）。播放器可以使用 content_id 独立检索宽度，也可以由发送者在 Load 消息中提供
高度 integer 可选：照片的高度（以像素为单位）。播放器可以使用 content_id 独立检索高度，也可以由发送者通过 Load 消息提供
CreationDate 字符串 (ISO 8601) 可选 ISO 8601 照片拍摄日期和时间。播放器可以使用 content_id 独立检索创建日期时间，也可以由发送者通过加载消息提供

媒体状态

描述媒体工件相对于会话的当前状态。

名称 类型 说明
mediaSessionId integer 此特定会话的播放的唯一 ID。此 ID 由接收器在 LOAD 设置，可用于识别播放的特定实例。例如，如果同一次会话中有 2 个视频“Wish you there here”，则每个会话都有唯一的 mediaSessionId。
media MediaInformation 可选（适用于状态消息）正在播放的内容的完整说明。仅当 MediaInformation 发生变化时，才会在状态消息中返回。
playbackRate float 指示媒体时间是否正在播放以及播放速度如何。这与播放器状态无关，因为媒体时间可以在任何状态下停止。1.0 是正常时间，0.5 是慢动作
playerState 枚举（字符串）

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

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

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

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

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

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

组合被描述为求和；例如，Pause+Seek+StreamVolume+Mute == 15。

卷 Volume 直播音量
自定义数据 对象 可选 - 接收器应用定义的应用专属数据 blob

从发送者到接收者的命令

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

加载

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

名称 类型 说明
requestId integer 请求的 ID，用于将请求与响应关联
type 字符串 LOAD（仅限值）
media MediaInformation 要加载的媒体的元数据（包括 contentId）
自动播放 布尔值

可选（默认值为 true），如果指定了自动播放参数，媒体播放器将在内容加载后开始播放内容。即使未指定自动播放功能，媒体播放器实现也可能会选择立即开始播放。如果开始播放，则应将响应中的播放器状态设置为“BUFFERING”，否则应将其设置为“PAUSED”
currentTime 双精度 可选：内容开始后经过的秒数。如果内容是直播内容，且未指定位置，则视频流将从直播位置开始
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
无 接收器状态更改 媒体状态更改消息 玩家状态无效
加载失败
加载已取消

暂停

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

名称 类型 说明
mediaSessionId integer 要暂停的媒体会话的 ID
requestId integer 请求的 ID，用于关联请求/响应
type 字符串 PAUSE（仅限值）
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
无 接收器状态更改 媒体状态更改消息 玩家状态无效

跳转

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

名称 类型 说明
mediaSessionId integer 已设置数据流位置的媒体会话的 ID
requestId integer 请求的 ID，用于将请求与响应关联
type 字符串 SEEK（仅限值）
sumstate 枚举（字符串）

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

  • PLAYBACK_START 强制启动媒体
  • PLAYBACK_PAUSE 强制暂停媒体
currentTime 双精度 可选：内容开始后经过的秒数。如果内容是直播内容，且未指定位置，则视频流将从直播位置开始
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
无 接收器状态更改 媒体状态更改消息 玩家状态无效

停止

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

名称 类型 说明
mediaSessionId integer 要停止的内容的媒体会话的 ID
requestId integer 请求的 ID，用于将请求与响应关联
type 字符串 STOP（仅限值）
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
无 接收器状态更改 媒体状态更改消息 玩家状态无效

播放

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

名称 类型 说明
mediaSessionId integer 要播放内容的媒体会话的 ID
requestId integer 请求的 ID，用于将请求与响应关联
type 字符串 PLAY（仅限值）
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
无 接收器状态更改 媒体状态更改消息 玩家状态无效

获取状态

用于检索媒体状态。

名称 类型 说明
mediaSessionId integer 可选：应返回其媒体状态的媒体的媒体会话 ID。如果未提供，则会提供所有媒体会话 ID 的状态。
requestId integer 请求的 ID，用于将请求与响应关联
type 字符串 GET_STATUS（仅限值）
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
MediaStatus 消息发送给发出请求的发送者 无 无 无

设置音量

设置媒体流音量。用于对媒体流进行淡入/淡出效果。（注意：接收者音量通过 Web 发送者 setVolume 更改）。 信息流音量不得与音量滑块或音量按钮结合使用来控制设备音量。更改音频流音量不会在接收器上触发任何界面。

名称 类型 说明
mediaSessionId integer 更改了流音量的媒体的媒体会话 ID
requestId integer 请求的 ID，用于将请求与响应关联
type 字符串 VOLUME（仅限值）
卷 Volume 直播音量
自定义数据 对象 可选 - 发件人应用定义的应用专属数据 blob
响应 触发器 广播 错误
无 接收器状态更改 媒体状态更改消息 玩家状态无效

从接收者发送至发送者的消息

接收者发送两种消息：

  • 错误：在发送者请求错误响应时发送的单播消息。
  • 状态：广播消息。
    • 由发送者发起的操作。将包含导致更改的请求的 requestId。
    • 自发性：例如，由于接收方应用触发了更改。RequestId 将是 0。

错误：播放器状态无效

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

名称 类型 说明
requestId integer 生成此错误的请求的 ID
type 字符串 INVALID_PLAYER_STATE（仅限值）
自定义数据 对象 可选 - 接收器应用定义的应用专属数据 blob

错误：加载失败

当加载请求失败时发送。播放器将处于空闲状态。

名称 类型 说明
requestId integer 生成此错误的请求的 ID
type 字符串 LOAD_FAILED（仅限值）
自定义数据 对象 可选 - 接收器应用定义的应用专属数据 blob

错误：加载已取消

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

名称 类型 说明
requestId integer 生成此错误的请求的 ID
type 字符串 LOAD_CANCELLED（仅限值）
自定义数据 对象 可选 - 接收器应用定义的应用专属数据 blob

错误：请求无效

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

名称 类型 说明
requestId integer 生成此错误的请求的 ID
type 字符串 INVALID_REQUEST（仅限值）
原因 枚举（字符串）

值：

  • INVALID_COMMAND 命令不受支持
  • DUPLICATE_REQUESTID 请求 ID 不具有唯一性（接收器正在处理具有相同 ID 的请求）
自定义数据 对象 可选 - 接收器应用定义的应用专属数据 blob

媒体状态

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

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