智慧型住宅 CameraStream 訓練結構定義

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

裝置具有這種特性,能夠將視訊串流串流播放至智慧螢幕、支援 Chromecast 的裝置或智慧型手機。簡單來說,這些相機是監視攝影機或嬰兒相機。不過,這個特性也適用於裝有攝影機的較複雜裝置 (例如視訊會議裝置或配備攝影機的吸塵器)。

裝置屬性

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

屬性 類型 說明
cameraStreamSupportedProtocols 陣列

必要。

相機串流支援的媒體類型 (按照偏好順序排列)。通常,系統會要求此陣列中的第一個與目標介面相容的通訊協定。

[item, ...] String

媒體類型。

支援的值:

hls
HTTP 即時串流
dash
透過 HTTP 動態自動調整串流
smooth_stream
流暢串流
progressive_mp4
Progressive MP4 (通常用於短片)
webrtc
WebRTC
cameraStreamNeedAuthToken 布林

必要。

是否透過 cameraStreamAuthToken 提供驗證權杖,讓目標途徑串流串流攝影機畫面。

範例

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

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

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

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

支援的串流通訊協定

此特性支援下列串流通訊協定:

裝置狀態

無。

裝置指令

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

action.devices.commands.GetCameraStream

參數

參數 類型 說明
StreamToChromecast 布林

必要。

串流是否會在 Chromecast 裝置上播放。

SupportedStreamProtocols 陣列

必要。

所需目的地支援的媒體類型/格式。

[item, ...] String

媒體類型。

支援的值:

hls
HTTP 即時串流
dash
透過 HTTP 動態自動調整串流
smooth_stream
流暢串流
progressive_mp4
Progressive MP4 (通常用於短片)
webrtc
WebRTC

成果

成果 類型 說明
cameraStreamAuthToken String

特定接收器的驗證權杖,用於授權存取串流。如果 cameraStreamNeedAuthToken 為 true,且未提供這個值,則會使用使用者的 OAuth 憑證做為驗證權杖。

cameraStreamProtocol String

必要。

串流網址指向的媒體格式。必須是 SupportedStreamProtocols 指令參數中列出的其中一個通訊協定。

支援的值:

hls
HTTP 即時串流
dash
透過 HTTP 進行動態自動調整串流
smooth_stream
流暢串流
progressive_mp4
Progressive MP4 (通常用於短片)
webrtc
WebRTC

非 WebRTC 結果

成果 類型 說明
cameraStreamAccessUrl String

必要。

網址端點,用於擷取 cameraStreamProtocol 指定的格式的即時串流。

cameraStreamReceiverAppId String

StreamToChromecast 參數為 true 時,投放接收端 ID 來處理相機串流;如未提供預設接收器,系統會使用預設接收器。

WebRTC 結果

成果 類型 說明
cameraStreamSignalingUrl String

必要。

用於擷取及交換相機和用戶端工作階段說明通訊協定 (SDP) 的網址端點。用戶端應傳回信號網址,並在要求標頭中使用 cameraStreamAuthToken 做為驗證權杖。

cameraStreamOffer String

優惠工作階段說明通訊協定 (SDP)。

cameraStreamIceServers String

代表使用 RTCIceServer 說明的編碼 JSON 字串代表互動式連線能力 (ICE) 伺服器。如未指定 STUN (網路位址轉譯 (NAT) 伺服器公用公用程式) 伺服器,平台會預設為 Google 的公開 STUN 伺服器。只有在您無法保證所提供的 IP / ICE 候選人可公開存取時 (例如透過媒體伺服器、公開主機 ICE 候選人、轉發 ICE 候選人等) 時,才需要啟用 GO (在 ReNA 中使用轉送功能)。

範例

顯示前門攝影機 (預設的 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 串流通訊協定的需求條件。

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

標題應符合下列規定:

  • 驗證:驗證標頭應使用 cameraStreamAuthToken 回傳 GetCameraStream 傳回驗證權杖,且權杖類型為 Bearer
  • Content-Typeapplication/json
信號要求參數

要求可包含以下參數:

  • action:字串。有效值如下:
    • offer:提供供應商的 SDP 訊息。
    • answer:接聽供應商的 SDP 訊息。
    • end:關閉目前的工作階段。
  • deviceId:字串。同步或 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

支援的影片轉碼器:

  • 副總裁 8
  • H.264

支援的音訊轉碼器:

  • Opus (偏好的轉碼器)
  • G.711/PCMU
  • G722

跨源資源共享

跨源資源共享 (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
{}