スマートホームの CameraStream トレイトのスキーマ

action.devices.traits.CameraStream - このトレイトは、デバイスのカメラストリームを制御する方法を扱います。

このトレイトは、スマート ディスプレイ、Chromecast 対応デバイス、スマートフォンに動画フィードをストリーミングする機能を搭載したデバイスに使用します。該当するデバイスのほとんどはセキュリティ カメラやベビーモニターですが、このトレイトは、カメラを搭載したもっと複雑なデバイス（ビデオ会議用のデバイス、カメラ付きの掃除ロボットなど）にも適用されます。

デバイスの属性

このトレイトを持つデバイスは、SYNC オペレーションの一部として次の属性を報告できます。SYNC インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。

属性 タイプ 説明
cameraStreamSupportedProtocols 配列

必須。

カメラ ストリームでサポートされているメディアタイプ（優先度順）。通常、この配列内のターゲット サーフェスと互換性のある最初のプロトコルがリクエストされます。
[item, ...] String

メディアタイプ。

サポートされている値:

hls
HTTP Live Streaming
dash
Dynamic Adaptive Streaming over HTTP
smooth_stream
スムーズ ストリーミング
progressive_mp4
プログレッシブ MP4（クリップでよく使用されます）
webrtc
WebRTC
cameraStreamNeedAuthToken ブール値

必須。

カメラフィードをストリーミングするために Auth トークンが必要かどうかを示します。

例

複数のプロトコルをサポートするカメラで、認証トークンは不要。

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

単一のプロトコルをサポートし、認証トークンを必要とするカメラ。

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

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

このトレイトは、次のストリーミング プロトコルに対応します。

hls、dash、smooth_stream、progressive_mp4 プロトコルを Cast デバイス（Chromecast、スマートディスプレイ、Chromecast 対応スマートテレビ）にストリーミングする場合、Cast ウェブ レシーバーが起動してストリーミングを処理し、デバイスにレンダリングします。デベロッパーは、カスタム ウェブ レシーバーを作成して、デバッグ ツールへのアクセスを有効にし、プレーヤーの動作をカスタマイズし、UI のブランディングをカスタマイズし、分析情報を含めることをおすすめします。カスタム レシーバーの使用を有効にしてデフォルト レシーバーの使用をオプトアウトするには、Cast アプリを登録したときに生成されたレシーバー アプリ ID を EXECUTE レスポンスの cameraStreamReceiverAppId フィールドに設定します。

カスタム ウェブ レシーバー アプリケーションについて詳しくは、デベロッパー サイトのガイドをご覧ください。

デバイスのステータス

なし。

デバイスのコマンド

このトレイトを持つデバイスは、EXECUTE オペレーションの一部として次のコマンドに応答する場合があります。EXECUTE インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。

action.devices.commands.GetCameraStream

パラメータ

パラメータ タイプ 説明
StreamToChromecast ブール値

必須。

ストリームを Chromecast デバイスで再生するかどうか。
SupportedStreamProtocols 配列

必須。

目的の宛先でサポートされているメディアのタイプ/形式。
[item, ...] String

メディアタイプ。

サポートされている値:

hls
HTTP Live Streaming
dash
Dynamic Adaptive Streaming over HTTP
smooth_stream
スムーズ ストリーミング
progressive_mp4
プログレッシブ MP4（クリップでよく使用されます）
webrtc
WebRTC

結果

結果 タイプ 説明
cameraStreamAuthToken String

特定の受信者がストリームへのアクセスを承認するための認証トークン。cameraStreamNeedAuthToken が true の場合、cameraStreamAuthToken は必須であり、トークンのスコープはターゲット デバイスのみにする必要があります。
cameraStreamProtocol String

必須。

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

サポートされている値:

hls
HTTP Live Streaming
dash
Dynamic Adaptive Streaming over 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）を指定します。

Offer SDP が Execution（WebRTC）の結果の一部として含まれている場合、Google はシグナリング エンドポイントで Answer SDP を提供します。

実行インテントに含まれていない場合、Google は Offer SDP を生成し、シグナリング エンドポイントに投稿します。レスポンスとして Answer SDP を想定しています。こちらもご覧ください。
cameraStreamIceServers String

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

例

玄関のカメラを見せて（デフォルトの 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 を使用するメリットは、低レイテンシと 1 方向の通信です。WebRTC では、JSON 形式の POST 本文とレスポンスがある POST メソッドが使用されます。

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

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

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

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

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

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

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

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

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

WebRTC の要件と推奨事項

  • 現在、Google は 1 方向（半二重）通信をサポートしています。
  • バンドルと rtcp-mux をサポートする必要があります。
  • （D）TLS 1.2 以降を使用する必要があります。
  • Trickle ICE はサポートされていません。SDP を送信する前に、すべての 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
{}