スマートホームの 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
}

1 つのプロトコルをサポートするカメラで、認証トークンが必要です。

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

サポートされているストリーミング プロトコル

このトレイトは、次のストリーミング プロトコルをサポートしています。

デバイスのステータス

なし。

デバイスのコマンド

このトレイトを持つデバイスは、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

必須。

ストリーム URL が指しているメディア形式。SupportedStreamProtocols コマンド パラメータにリストされているプロトコルのいずれかを指定する必要があります。

サポートされる値:

hls
HTTP ライブ ストリーミング
dash
HTTP 経由の動的適応ストリーミング
smooth_stream
スムーズなストリーミング
progressive_mp4
プログレッシブ MP4（主にクリップに使用）
webrtc
WebRTC

WebRTC 以外の検索結果

結果 タイプ 説明
cameraStreamAccessUrl String

必須。

cameraStreamProtocol で指定された形式のリアルタイム ストリームを取得するための URL エンドポイントです。
cameraStreamReceiverAppId String

StreamToChromecast パラメータが true の場合にカメラ ストリームを処理するためのキャスト レシーバー ID。指定しない場合はデフォルトのレシーバーが使用されます。

WebRTC 結果

結果 タイプ 説明
cameraStreamSignalingUrl String

必須。

カメラとクライアントのセッション記述プロトコル（SDP）を取得および交換するための URL エンドポイント。クライアントは、リクエスト ヘッダーで認証トークンとして cameraStreamAuthToken を使用するシグナリング URL を返す必要があります。
cameraStreamOffer String

オファー セッション記述プロトコル（SDP）を提供します。
cameraStreamIceServers String

RTCIceServer の記述を含むエンコード済みの JSON 文字列を使用して、Interactive Connectivity Establishment（ICE）サーバーを表します。STUN（NAT セッションのセッション ユーティリティ）サーバーを指定しない場合、プラットフォームはデフォルトで Google のパブリック STUN サーバーになります。TURN（NAT を使用したトラバーサル）サーバーは、提供された IP / ICE 候補が（メディア サーバー、パブリック ホストの ICE 候補、リレー ICE 候補などによって）一般公開されることを保証できない場合にのみ必要です。

例

玄関のカメラを表示します（デフォルトのキャスト レシーバー）。

{
  "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 本文と JSON 形式のレスポンスを持つ POST メソッドを使用します。

WebRTC は現在、Google Nest スマートディスプレイと Chromecast with Google TV デバイスでサポートされています。

このセクションでは、WebRTC ストリーム プロトコルを使用する場合の要件について説明します。

データ型 パラメータ / 定義
信号リクエスト ヘッダー

ヘッダーは次の要件を満たしている必要があります。

  • 認証: 認証ヘッダーは、トークンタイプが Bearer である cameraStreamAuthToken の GetCameraStream 戻り値の認証トークンを使用する必要があります。
  • コンテンツ タイプ: application/json.
信号リクエスト パラメータ

リクエストには、次のパラメータを含めることが可能です。

  • action: 文字列。有効な値は次のとおりです。
    • offer: プロバイダからの SDP メッセージを提供します。
    • answer: プロバイダからの SDP メッセージに応答します。
    • end: 現在のセッションを閉じます。
  • deviceId: 文字列。SYNC または EXECUTE リクエストで報告されたデバイス ID。
  • sdp: 文字列。ピア接続の Session Description Protocol メッセージが含まれます。内容は action パラメータの値に基づいています。action が「end」の場合、このパラメータは空にできます。
信号レスポンス パラメータ

レスポンスには、次のパラメータを含めることが可能です。

  • action: 文字列。レスポンス値は、answer 型にする必要があります。
  • sdp: 文字列。回答に対する SDP メッセージ。

WebRTC の要件と推奨事項

  • Google は現在、一方向（半二重）通信をサポートしています。
  • バンドルと rtcp-mux をサポートする必要があります。
  • TLS 1.2 以降を使用する必要があります。
  • Trickle ICE はサポートされていません。SIP を送信する前に、ICE の候補をすべて集める必要があります。
  • 接続が成功する確率を高めるため、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
{}