智慧型住宅攝影機串流特徵結構定義

action.devices.traits.CameraStream：這個特徵說明如何控制裝置的攝影機串流。

這項特徵屬於可將影片動態饋給串流至智慧螢幕、支援 Chromecast 的裝置或智慧型手機的裝置。這些裝置大多是監視攝影機或嬰兒監視器。不過，這個特徵也適用於內建攝影機的複雜裝置 (例如視訊會議裝置或內建攝影機的掃地機器人)。

裝置屬性

具有此特徵的裝置可能會在 SYNC 作業中回報下列屬性。如要進一步瞭解如何處理 SYNC 意圖，請參閱「意圖執行要求」。

屬性 類型 說明
cameraStreamSupportedProtocols 陣列

必要。

攝影機串流支援的媒體類型，依偏好順序排列。通常，系統會要求這個陣列中與目標途徑相容的第一個通訊協定。
[item, ...] String

媒體類型。

支援的值：

hls
HTTP 即時串流
dash
基於 HTTP 的動態自動調整串流
smooth_stream
流暢串流
progressive_mp4
漸進式 MP4 (主要用於短片)
webrtc
WebRTC
cameraStreamNeedAuthToken 布林值

必要。

指出是否需要權杖才能串流攝影機畫面。

範例

支援多種通訊協定的攝影機，不需驗證權杖。

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

相機支援單一通訊協定，需要授權權杖。

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

支援的串流通訊協定

這個特徵支援下列串流通訊協定：

將 hls、dash、smooth_stream 和 progressive_mp4 通訊協定串流至 Cast 裝置 (Chromecast、智慧型螢幕和支援 Chromecast 的智慧型電視) 時，系統會啟動 Cast Web Receiver，以便處理串流並在裝置上顯示。建議開發人員建立自訂網頁接收器，以便存取偵錯工具、自訂播放器行為、自訂 UI 品牌，以及納入數據分析。如要啟用自訂接收器並停用預設接收器，請在 EXECUTE 回應的 cameraStreamReceiverAppId 欄位中，設定您註冊 Cast 應用程式時產生的接收器應用程式 ID。

如要進一步瞭解自訂網頁接收器應用程式，請參閱開發人員網站的指南。

裝置狀態

無。

裝置指令

具備此特徵的裝置可能會在 EXECUTE 作業中回應下列指令。如要進一步瞭解如何處理 EXECUTE 意圖，請參閱「意圖執行要求」。

action.devices.commands.GetCameraStream

參數

參數 類型 說明
StreamToChromecast 布林值

必要。

串流內容是否會在 Chromecast 裝置上播放。
SupportedStreamProtocols 陣列

必要。

所需目的地支援的媒體類型/格式。
[item, ...] String

媒體類型。

支援的值：

hls
HTTP 即時串流
dash
基於 HTTP 的動態自動調整串流
smooth_stream
流暢串流
progressive_mp4
漸進式 MP4 (主要用於短片)
webrtc
WebRTC

結果

結果 類型 說明
cameraStreamAuthToken String

特定接收器的授權權杖，可授權存取串流。如果 cameraStreamNeedAuthToken 為 true，且權杖的範圍只需限定於目標裝置，則必須使用 cameraStreamAuthToken。
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)。

如果執行(WebRTC) 結果包含 Offer SDP，Google 就會在訊號端點提供 Answer SDP。

如果未納入執行意圖，Google 會產生 Offer SDP 並將其發送至信號端點，並預期收到 Answer SDP 做為回應。請參閱這篇文章。
cameraStreamIceServers String

代表使用已編碼 JSON 字串的互動連線建立 (ICE) 伺服器，其中包含 RTCIceServer 的說明。如果您未指定 STUN (Session Traversal Utilities for NAT) 伺服器，平台會預設使用 Google 的公開 STUN 伺服器。只有在您無法保證提供的 IP / ICE 候選項目可供大眾存取 (例如透過媒體伺服器、公開主機 ICE 候選項目、中繼 ICE 候選項目等) 時，才需要使用 TURN (Traversal Using Relays around 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 格式的回應。

WebRTC 目前支援 Google Nest 智慧螢幕和 Chromecast (支援 Google TV) 裝置。

本節說明使用 WebRTC 串流通訊協定時的必要條件。

資料類型 參數/定義
訊號要求標頭

標頭應符合下列規定：

  • 驗證：驗證標頭應使用 GetCameraStream 傳回值的權杖，該值適用於具有 Bearer 權杖類型的 cameraStreamAuthToken。
  • 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 標頭告知瀏覽器，允許在一個來源執行的網路應用程式存取不同來源的所選資源。代管 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
{}