智慧型住宅 CameraStream 特徵結構定義

action.devices.traits.CameraStream - 這個特徵涵蓋如何控制裝置的相機串流。

這類特徵包括能夠將影片動態消息串流至智慧螢幕、支援 Chromecast 的裝置或智慧型手機的裝置。主要為監視攝影機或嬰兒攝影機。不過，這種特徵也適用於配備攝影機的較複雜裝置 (例如視訊會議裝置或有攝影機的吸塵器)。

裝置特徵

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

屬性 類型 說明
cameraStreamSupportedProtocols 陣列

必要。

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

媒體類型。

支援的值：

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

必要。

是否將透過 cameraStreamAuthToken 提供驗證權杖，以供目標介面串流攝影機畫面。

範例

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

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

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

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

支援的串流通訊協定

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

將 hls、dash、smooth_stream 和 progressive_mp4 通訊協定串流至投放裝置 (Chromecast、智慧螢幕和支援 Chromecast 的智慧型電視) 時，系統會啟動投放網路接收器，以便處理串流並在裝置上顯示。建議開發人員建立自訂網路接收端，以便存取偵錯工具、自訂玩家行為、自訂 UI 品牌宣傳，並加入數據分析。如要啟用自訂接收器並選擇不採用預設接收器，請在 EXECUTE 回應的 cameraStreamReceiverAppId 欄位中，設定註冊投放應用程式時產生的接收器應用程式 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，且未提供這個值，系統就會使用使用者的 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 的 Session Traversal Utilities) 伺服器，該平台會預設為 Google 的公開 STUN 伺服器。只有在您無法保證所提供的 IP / ICE 可公開存取 (例如透過媒體伺服器、公用代管 ICE 候選項目、轉發 ICE 候選人等) 時，才需要使用 cent (使用 Relay 遍及 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 方法，其中包含 POST 主體和 JSON 格式的回應。

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

本節說明使用 WebRTC 串流通訊協定的需求條件。

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

標頭必須符合以下規定：

  • 驗證：驗證標頭應使用 GetCameraStream 傳回值的 cameraStreamAuthToken 驗證權杖 (權杖類型為 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 標頭，指示瀏覽器允許在一個來源執行的網頁應用程式存取不同來源的所選資源。代管 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
{}