智能家居 CameraStream 特征架构

action.devices.traits.CameraStream - 此特征介绍了如何控制设备的相机数据流。

此特征属于能够将视频 Feed 流式传输到智能显示屏、支持 Chromecast 的设备或智能手机的设备。大体上讲,监控摄像头或婴儿摄像头都是如此。但此特征也适用于带有摄像头的更复杂的设备(例如,视频会议设备或配有摄像头的吸尘器)。

设备特性

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

属性 类型 说明
cameraStreamSupportedProtocols 数组

必填。

相机数据流支持的媒体类型,按偏好设置排序。通常情况下,系统会请求此数组中与目标 Surface 兼容的第一个协议。

[item, ...] String

媒体类型。

支持的值:

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

必填。

是否通过 cameraStreamAuthToken 为目标 surface 提供身份验证令牌,以便流式传输相机画面。

示例

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

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

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

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

支持的流式传输协议

此特征支持以下流式传输协议:

在将 hlsdashsmooth_streamprogressive_mp4 协议流式传输到投放设备(Chromecast、智能显示屏和支持 Chromecast 的智能电视)时,系统会启动 Cast Web 接收器以处理流式传输并将其呈现在设备上。建议开发者创建自定义 Web 接收器,以便能够访问调试工具、自定义播放器行为、自定义界面品牌信息和包含分析数据。要启用自定义接收器并选择停用默认接收器,请在 EXECUTE 响应的 cameraStreamReceiverAppId 字段中设置注册 Cast 应用时生成的接收器应用 ID。

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

设备状态

无。

设备命令

具有此特征的设备可以在 EXECUTE 操作过程中响应以下命令。如需详细了解如何处理 EXECUTE intent,请参阅 intent 执行方式

action.devices.commands.GetCameraStream

参数

参数 类型 说明
StreamToChromecast 布尔值

必填。

视频流是否将在 Chromecast 设备上播放。

SupportedStreamProtocols 数组

必填。

所需目的地支持的媒体类型/格式。

[item, ...] String

媒体类型。

支持的值:

hls
HTTP 直播
dash
基于 HTTP 的动态自适应流式传输
smooth_stream
流畅的流式传输
progressive_mp4
渐进式 MP4(主要用于剪辑)
webrtc
WebRTC

成果

成果 类型 说明
cameraStreamAuthToken String

供特定接收器访问流的身份验证令牌。如果 cameraStreamNeedAuthToken 为 true,且未提供此值,则用户的 OAuth 凭据将用作身份验证令牌。

cameraStreamProtocol String

必填。

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

支持的值:

hls
HTTP 直播
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)。

cameraStreamIceServers String

使用编码的 JSON 字符串(包含 RTCIceServer 说明)表示交互式连接建立 (ICE) 服务器。如果您未指定 STUN (Session Traversal Utilities for 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"
}

设备 ERRORS

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

WebRTC 协议规范

使用 WebRTC 的优势在于低延迟和单向通话。WebRTC 使用 POST 方法,该方法的 POST 正文和响应采用 JSON 格式。

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

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

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

标头应满足以下要求:

  • Authentication:身份验证标头应使用 cameraStreamAuthTokenGetCameraStream 返回值中令牌类型为 Bearer 的身份验证令牌。
  • Content-Typeapplication/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 或更高版本。
  • 不支持 Trickle 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
{}