智能家居 CameraStream trait 架构

action.devices.traits.CameraStream - 此 trait 介绍了如何控制设备的摄像头数据流。

此 trait 适用于能够将视频画面流式传输到智能显示屏、支持 Chromecast 的设备或智能手机的设备。这些设备通常是监控摄像头或婴儿摄像头。不过，此 trait 也适用于具有摄像头的更复杂设备（例如视频会议设备或带摄像头的吸尘器机器人）。

设备属性

具有此 trait 的设备可能会在 SYNC 操作中报告以下属性。如需详细了解如何处理 SYNC intent，请参阅intent 执行方式。

属性 类型 说明
cameraStreamSupportedProtocols 数组

必填。

相机画面支持的媒体类型，按首选顺序排列。通常，系统会请求此数组中与目标 Surface 兼容的第一个协议。
[item, ...] String

媒体类型。

支持的值：

hls
HTTP Live Streaming
dash
基于 HTTP 的动态自适应流式传输
smooth_stream
流畅的流式传输
progressive_mp4
渐进式 MP4（主要用于剪辑）
webrtc
WebRTC
cameraStreamNeedAuthToken 布尔值

必填。

指明是否需要身份验证令牌才能流式传输摄像头画面。

示例

支持多种协议的相机，无需身份验证令牌。

{
  "cameraStreamSupportedProtocols": [
    "webrtc",
    "hls",
    "dash",
    "smooth_stream",
    "progressive_mp4"
  ],
  "cameraStreamNeedAuthToken": false
}

支持单个协议且需要身份验证令牌的相机。

{
  "cameraStreamSupportedProtocols": [
    "hls"
  ],
  "cameraStreamNeedAuthToken": true
}

支持的流式传输协议

此 trait 支持以下流式传输协议：

将 hls、dash、smooth_stream 和 progressive_mp4 协议流式传输到 Cast 设备（Chromecast、智能显示屏和支持 Chromecast 的智能电视）时，系统会启动 Cast Web Receiver 来处理流式传输并在设备上呈现。建议开发者创建自定义 Web 接收器，以便访问调试工具、自定义玩家行为、自定义界面品牌，以及添加分析。如需启用自定义接收器并停用默认接收器，请在 EXECUTE 响应的 cameraStreamReceiverAppId 字段中设置您在注册 Cast 应用时生成的接收器应用 ID。

如需详细了解自定义 Web 接收器应用，请访问开发者网站的指南。

设备状态

无。

设备命令

具有此 trait 的设备可能会在 EXECUTE 操作期间响应以下命令。如需详细了解如何处理 EXECUTE intent，请参阅intent 执行方式。

action.devices.commands.GetCameraStream

参数

参数 类型 说明
StreamToChromecast 布尔值

必填。

流式传输内容是否会在 Chromecast 设备上播放。
SupportedStreamProtocols 数组

必填。

目标位置支持的媒体类型/格式。
[item, ...] String

媒体类型。

支持的值：

hls
HTTP Live Streaming
dash
基于 HTTP 的动态自适应流式传输
smooth_stream
流畅的流式传输
progressive_mp4
渐进式 MP4（主要用于剪辑）
webrtc
WebRTC

结果

结果 类型 说明
cameraStreamAuthToken String

用于授权特定接收器访问数据流的身份验证令牌。如果 cameraStreamNeedAuthToken 为 true，则 cameraStreamAuthToken 是必需的，并且令牌的范围仅限于目标设备。
cameraStreamProtocol String

必填。

串流网址指向的媒体格式。它应为 SupportedStreamProtocols 命令参数中列出的协议之一。

支持的值：

hls
HTTP Live Streaming
dash
基于 HTTP 的动态自适应流式传输
smooth_stream
流畅的流式传输
progressive_mp4
渐进式 MP4（主要用于剪辑）
webrtc
WebRTC

非 WebRTC 结果

结果 类型 说明
cameraStreamAccessUrl String

必填。

用于以 cameraStreamProtocol 指定的格式检索实时数据流的网址端点。
cameraStreamReceiverAppId String

当 StreamToChromecast 参数为 true 时，用于处理摄像头数据流的 Cast 接收器 ID；如果未提供，则使用默认接收器。

WebRTC 结果

结果 类型 说明
cameraStreamSignalingUrl String

必填。

用于检索和交换相机和客户端会话描述协议 (SDP) 的网址端点。客户端应返回在请求标头中使用 cameraStreamAuthToken 作为身份验证令牌的信号网址。
cameraStreamOffer String

提供会话描述协议 (SDP)。

如果 Offer SDP 包含在 Execution(WebRTC) 结果中，Google 将在信令端点提供 Answer SDP。

如果未包含在执行 intent 中，Google 将生成 Offer SDP 并将其发布到信令端点，并希望收到 Answer SDP 作为响应。另请参阅此处。
cameraStreamIceServers String

使用包含 RTCIceServer 说明的编码 JSON 字符串表示 Interactive Connectivity Establishment (ICE) 服务器。如果您未指定 STUN（适用于 NAT 的会话穿越实用程序）服务器，平台将默认使用 Google 的公共 STUN 服务器。只有在您无法保证提供的 IP 地址 / ICE 候选将可供公众访问（例如通过媒体服务器、公共主机 ICE 候选、中继 ICE 候选等）时，才需要 TURN（Traversal Using Relays around NAT）服务器。

示例

显示前门摄像头（默认的 Cast 接收器）。

{
  "cameraStreamAccessUrl": "https://fluffysheep.com/baaaaa.mp4",
  "cameraStreamProtocol": "progressive_mp4"
}

显示前门摄像头（自定义 Cast 接收器）。

{
  "cameraStreamAccessUrl": "https://fluffysheep.com/baaaaa.mp4",
  "cameraStreamReceiverAppId": "1g2f89213hg",
  "cameraStreamAuthToken": "12657342190192783",
  "cameraStreamProtocol": "progressive_mp4"
}

显示前门摄像头（WebRTC 流式传输）。

{
  "cameraStreamIceServers": "[{\"urls\": \"stun:stun.l.partner.com:19302\"},{\"urls\":\"turn:192.158.29.39:3478?transport=udp\",\"credential\": \"JZEOEt2V3Qb0y27GRntt2u2PAYA=\",\"username\": \"28224511:1379330808\"},{\"urls\": \"turn:192.158.29.39:3478?transport=tcp\",\"credential\": \"JZEOEt2V3Qb0y27GRntt2u2PAYA=\",\"username\": \"28224511:1379330808\"}]",
  "cameraStreamSignalingUrl": "https://example.com/signaling/answer",
  "cameraStreamOffer": "o=- 4611731400430051336 2 IN IP4 127.0.0.1...",
  "cameraStreamProtocol": "webrtc"
}

设备错误

查看错误和异常的完整列表。

WebRTC 协议规范

使用 WebRTC 的好处是低延迟和单向通话。WebRTC 使用 POST 方法，其中包含 JSON 格式的 POST 正文和响应。

Google Nest 智能显示屏和 Chromecast（支持 Google TV）设备目前支持 WebRTC。

本部分介绍了使用 WebRTC 流协议时的要求。

数据类型 参数/定义
信号请求标头

标头应满足以下要求：

  • 身份验证：身份验证标头应使用 cameraStreamAuthToken 的 GetCameraStream 返回值中的身份验证令牌，令牌类型为 Bearer。
  • Content-Type：application/json。
信号请求参数

请求可以包含以下参数：

  • action：字符串。有效值包括：
    • offer：提供方提供的 SDP 消息。
    • answer：回复来自提供方的 SDP 消息。
    • end：关闭当前会话。
  • deviceId：字符串。SYNC 或 EXECUTE 请求中报告的设备 ID。
  • sdp：字符串。包含对等连接的会话描述协议消息。内容取决于 action 参数的值。如果 action 为“end”，此参数可以为空。
信号响应参数

响应可以包含以下参数：

  • action：字符串。响应值必须为 answer 类型。
  • sdp：字符串。响应答案的 SDP 消息。

WebRTC 要求和建议

  • Google 目前支持单向（半双工）通信。
  • 您必须支持捆绑和 rtcp-mux。
  • 您必须使用 (D)TLS 1.2 或更高版本。
  • 不支持涓流 ICE。 必须先收集所有 ICE 候选，然后才能发送 SDP。
  • 强烈建议您添加 UDP/IPv4、TCP/IPv4、UDP/IPv6 和 TCP/IPv6 ICE 候选项，以提高连接成功的几率。

支持的视频分辨率：

  • 最低：480p
  • 上限：1080p

支持的视频编解码器：

  • VP8
  • H.264

支持的音频编解码器：

  • Opus（首选编解码器）
  • G.711/PCMU
  • G.722

跨源资源共享

跨源资源共享 (CORS) 是一种机制，它使用额外的 HTTP 标头告知浏览器允许在一个源上运行的 Web 应用访问来自其他源的选定资源。托管 cameraStreamSignalingUrl 的服务器应返回以下标头：

Access-Control-Allow-Origin: https://www.gstatic.com

示例信号请求和响应

以下示例展示了 Google 向您的信令服务发送的请求以及 Google 收到的相应响应。

请求
Header:

Authentication: Bearer <cameraStreamAuthToken>
Content-Type: application/json

POST body:

// When camera offer SDP is provided in the execution response, Google provides an answer SDP.
{
  "action": "answer",
  "deviceId": "123",
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// When camera offer SDP is not provided in execution response, Google generates and provides an offer SDP.
{
  "action": "offer",
  "deviceId": "123",
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// Close the current stream session.
{
  "action": "end"
  "deviceId": "123"
}
响应
// Response to accept the answer SDP in the request.
Response Code : 200
{}

// Response to provide the answer SDP from the service provider.
Response Code : 200
{
  // When the camera offer SDP is not provided in the execution response,
  // Google provides the answer SDP via the signaling response.
  "action": "answer"
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// Response to close current session.
Response Code : 200
{}