智能家居 CameraStream 特征架构

action.devices.traits.CameraStream - 此特征涵盖如何控制设备的摄像头数据流。

此特征属于能够将视频流式传输到智能显示屏、支持 Chromecast 的设备或智能手机的设备。总的来说,这些是监控摄像头或婴儿摄像头。但此特征也适用于装有摄像头的更复杂的设备(例如视频会议设备或装有摄像头的真空机器人)。

设备属性

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

属性 类型 说明
cameraStreamSupportedProtocols 数组

必填。

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

[item, ...] String

媒体类型。

支持的值:

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

必填。

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

示例

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

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

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

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

支持的流式传输协议

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

设备状态

无。

设备命令

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

action.devices.commands.GetCameraStream

参数

参数 类型 说明
StreamToChromecast Boolean

必填。

系统是否在 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 时,用于处理接收器数据流的投放接收器 ID;如果未提供,系统将使用默认接收器。

WebRTC 结果

成果 类型 说明
cameraStreamSignalingUrl String

必填。

用于检索和交换摄像头和客户端会话说明协议 (SDP) 的网址端点。客户端应返回在请求标头中使用 cameraStreamAuthToken 作为身份验证令牌的信令网址。

cameraStreamOffer String

优惠会话说明协议 (SDP)。

cameraStreamIceServers String

表示交互式连接机构 (ICE) 服务器,采用带有 RTCIceServer 说明的编码 JSON 字符串。如果您未指定 STUN (Session Traversal Utilities for NAT) 服务器,平台会默认使用 Google 的公共 STUN 服务器。只有无法保证能够公开提供的 IP / ICE 候选对象(例如通过媒体服务器、公共主机 ICE 候选对象、中继 ICE 候选对象等)时,TURN (穿越 NAT 的中继服务)服务器才是必需的。

示例

显示前门摄像头的默认投射接收器

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

显示前门摄像头的画面(自定义投放接收器)。

{
  "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 方法带有 POST 正文和 JSON 格式的响应。

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

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

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

标头应满足以下要求:

  • 身份验证:身份验证标头应使用令牌 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
{}