歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。
透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

這個小眾所屬的裝置可用來將視訊畫面串流至智慧螢幕、支援 Chromecast 的裝置或智慧型手機。這些都是大型攝影機或嬰兒攝影機。不過,此特性同樣適用於較複雜的裝置 (例如視訊會議裝置,或是裝設攝影機的真空機器人)。

裝置屬性

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

屬性 類型 說明
cameraStreamSupportedProtocols 陣列

必填。

相機串流支援的媒體類型 (依偏好設定排序)。通常會要求在這個陣列中,與目標途徑相容的第一個通訊協定。

[item, ...] 字串

媒體類型。

支援的值:

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
}

支援的串流通訊協定

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

裝置狀態:STATE

無。

裝置指令

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

action.devices.commands.GetCameraStream

參數

參數 類型 說明
StreamToChromecast 布林

必填。

串流是否會透過 Chromecast 裝置播放。

SupportedStreamProtocols 陣列

必填。

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

[item, ...] 字串

媒體類型。

支援的值:

hls
HTTP 即時串流
dash
透過 HTTP 進行動態自動調整串流
smooth_stream
流暢的串流功能
progressive_mp4
漸進式 MP4 (主要用於剪輯片段)
webrtc
WebRTC

結果

結果 類型 說明
cameraStreamAuthToken 字串

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

cameraStreamProtocol 字串

必填。

串流網址指向的媒體格式。應為 SupportedStreamProtocols 指令參數中列出的其中一種通訊協定。

支援的值:

hls
HTTP 即時串流
dash
透過 HTTP 進行動態自動調整串流
smooth_stream
流暢的串流功能
progressive_mp4
漸進式 MP4 (主要用於剪輯片段)
webrtc
WebRTC

非 WebRTC 結果

結果 類型 說明
cameraStreamAccessUrl 字串

必填。

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

cameraStreamReceiverAppId 字串

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

WebRTC 搜尋結果

結果 類型 說明
cameraStreamSignalingUrl 字串

必填。

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

cameraStreamOffer 字串

提供工作階段說明通訊協定 (SDP)。

cameraStreamIceServers 字串

代表互動式連線 (建立) 伺服器,使用編碼 JSON 字串搭配 RTCIceServer 說明。如果您未指定 STUN (網路位址轉譯 (NAT) 工作階段週遊公用程式) 伺服器,平台會預設為 Google 的公開 STUN 伺服器。只有當您無法保證 IP / ICE 候選項目可公開存取 (例如透過媒體伺服器、公開主機 ICE 候選、轉發 ICE 候選等) 時,才需要 TURN (透過 NAT 使用轉發服務) 伺服器。

範例

顯示前門監視器畫面 (預設的投放接收器)。

{
  "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 智慧螢幕裝置支援 WebRTC。

本節說明使用 WebRTC 串流通訊協定的規定。

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

標頭應符合下列規定:

  • 驗證:驗證標頭應使用 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

支援的影片轉碼器:

  • V8
  • 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
{}