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

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

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

hlsdashsmooth_streamprogressive_mp4 プロトコルをキャスト デバイス(Chromecast、スマートディスプレイ、Chromecast 対応スマートテレビ)にストリーミングする場合、キャスト ウェブ レシーバーが起動し、ストリームを処理してデバイス上でレンダリングします。カスタム ウェブ レシーバーを作成して、デバッグツールへのアクセスの有効化、プレーヤーの動作のカスタマイズ、UI のブランディングのカスタマイズ、分析の実行を行うことをおすすめします。カスタム レシーバーの使用を有効にして、デフォルトのレシーバーをオプトアウトするには、キャストアプリの登録時に生成されるレシーバー アプリ ID を EXECUTE レスポンスの cameraStreamReceiverAppId フィールドに設定します。

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

デバイスのステータス

なし。

デバイスのコマンド

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

必須

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

サポートされている値:

hls
HTTP ライブ ストリーミング
dash
Dynamic Adaptive Streaming over HTTP
smooth_stream
スムーズなストリーミング
progressive_mp4
プログレッシブ MP4(主にクリップに使用)
webrtc
WebRTC

WebRTC 以外の結果

結果 種類 説明
cameraStreamAccessUrl 文字列

必須

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

cameraStreamReceiverAppId 文字列

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

WebRTC の結果

結果 種類 説明
cameraStreamSignalingUrl 文字列

必須

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

cameraStreamOffer 文字列

オファー セッション記述プロトコル(SDP)。

cameraStreamIceServers 文字列

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

正面玄関のカメラ(デフォルトのキャスト レシーバー)を見せてください。

{
  "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 ストリーム プロトコルを使用する場合の要件について説明します。

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

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

  • Authentication: 認証ヘッダーでは、トークンタイプが BearercameraStreamAuthToken に対する 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 をサポートする必要があります。
  • (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
{}