欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 Action 的新平台。注意:你将继续在 Actions 控制台中构建操作。
使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

智能家居 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 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

使用 JSON 编码字符串与 RTCIceServer 的说明表示交互式连接设施 (ICE) 服务器。如果您不指定 STUN(NAT 会话遍历实用程序)服务器,则平台会默认使用 Google 的公共 STUN 服务器。仅当您无法保证所提供的 IP / ICE 候选项可被公开访问时(例如,通过媒体服务器、公共主机 ICE 候选对象、中继 ICE 候选对象等),服务器才需要使用 TURN(遍历资源在 NAT 中使用中继)

示例

显示前门摄像头(默认的 Cast 接收器)

{
  "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 流协议的要求。

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

标头应满足以下要求:

  • Authentication:身份验证标头应使用 GetCameraStream 返回值的 cameraStreamAuthToken 身份验证令牌(类型为 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
{}