Alexa.CameraStreamControllerインターフェース



Alexa.CameraStreamControllerインターフェース

AlexaスキルにAlexa.CameraStreamControllerインターフェースを実装すると、ユーザーが防犯カメラからのフィードを確認できるようになります。リアルタイム通信（RTC）対応の防犯カメラの場合は、Alexa.RTCSessionControllerインターフェースを実装します。セキュリティスキルの詳細については、スマートホームセキュリティの概要を参照してください。

ユーザーが過去の録画を表示できるようにセキュリティカメラからのメディアを録画している場合は、MediaMetadataインターフェースを実装します。

CameraStreamControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

発話

Alexa.CameraStreamControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。以下に、ユーザーの発話の例を示します。

Alexa, show the front door camera.

Alexa, zeige die frontkamera.

アレクサ、玄関のカメラを見せて

ユーザーがこのような発話をすると、Alexaがそれに対応するディレクティブをスキルに送信します。

概要

ビデオやオーディオをストリーミングするクラウド対応カメラ用のAlexaスキルを構築するにはReal Time Streaming Protocol（RTSP）を使用します。

前提条件とSLA要件

最適なユーザーエクスペリエンスには待機時間が短いことが非常に重要です。CameraStreamController APIを使用するには、以下が必要です。

  • RTSP+RTPストリーミングプロトコル。

  • ポート443のインターリーブされたTCP（RTPとRTSPのどちらも）

  • TLS 1.2を用いたポート443でのTCPソケット暗号化

  • RTSPコマンドのDESCRIBE、SETUP、PLAY、TEARDOWNは必須ですが、RFCに完全に準拠した実装が推奨されています。

  • すべてのRTSP URI応答は、リクエストを受信してから6秒以内に完了する必要があります。

  • Lambdaは6秒以内にリクエストに応答する必要があります。最高のユーザーエクスペリエンスを提供するには、1秒以内に応答してください。ストリーミングを開始するためにカメラを起動する等の操作は、バックグラウンドのタスクとして非同期的に実行することをお勧めします。

  • ネットワーク状態によってフレームレートが決まります。ネットワーク状態が良好であれば、より高いフレームレートでストリーミングします。ネットワーク状態が悪い場合は、低いフレームレートでストリーミングします。フレームレートが低いと、モーションブラーが発生する可能性がありますが、ストリーミングは可能です。

  • 良好なネットワーク条件下では、TLSハンドシェイクが完了してから6秒以内に最初のフレームがデバイスにレンダリングされることが望ましいです。ストリームのキーフレームレートとバッファー時間を調節することで、起動の待機時間を最適化できます。

ローカルおよびリモート実行の推奨事項

デバイスと同じネットワーク上のローカルURIを返すことも、インターネット接続でどこからでもアクセスできるリモートURIを返すこともできます。各自のデバイス制御クラウドコンフィギュレーションに合うURIを返すようにします。ローカルURIとリモートURIのどちらを返す場合でも、TLS 1.2の使用を含むすべての要件を満たす必要があります。

一般的に、デフォルトではURIにはローカルでもリモートでもアクセスできません。ローカルおよびリモートでURIにアクセスできるようにするには、ドメインを購入するかポートを転送します。これらのソリューションは技術的に難しいため、ユーザーがローカルとリモートの両方でURIにアクセスする必要がある場合にのみ提供してください。

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

次のサポートされるプロトコル値を使用できます： RTSP、HLS。

サポートされる認可タイプ

次のサポートされる認可タイプ値を使用できます： BASIC、DIGEST、NONE。

サポートされるビデオコーデック

次のサポートされるビデオコーデック値を使用できます： H264、MPEG2、MJPEG、JPG。

サポートされるオーディオコーデック

次のサポートされるオーディオコーデック値を使用できます： G711、AAC、NONE。

サポートされている解像度

サポートされている解像度は480p~1080pです。

プロパティとオブジェクト

cameraStreamオブジェクト

Alexa.CameraStreamControllerインターフェースは、cameraStreamオブジェクトを使用してカメラストリームを表します。

CameraStreamオブジェクトの例

クリップボードにコピーされました。

{
  "uri": "rtsp://username:password@link.to.video:443/feed1.mp4",
  "expirationTime": "2017-02-03T16:20:50.52Z",
  "idleTimeoutSeconds": 30,
  "protocol": "RTSP",
  "resolution": {
    "width": 1920,
    "height": 1080
  },
  "authorizationType": "BASIC",
  "videoCodec": "H264",
  "audioCodec": "AAC"
  }

CameraStreamオブジェクトの詳細

フィールド 説明 型
uri カメラストリームのURIです。一時的なURIの場合、expirationTimeフィールドに有効期限を指定します。このURIが期限切れとなりエラーが発生すると、AlexaはInitializeCameraStreamsをもう一度呼び出して期限切れでない新しいURIを取得します。 文字列
expirationTime ストリームの有効期限です。UTCで指定します。 文字列はISO 8601形式で、YYYY-MM-DDThh:mm:ssZとなります。
idleTimeoutSeconds カメラストリームがタイムアウトするまでの非アクティブ状態の秒数です。 整数
protocol ストリームのプロトコルです。サポートされるプロトコルのいずれかの値を指定します。 文字列
resolution ストリームの解像度です。 resolutionオブジェクト
authorizationType ストリームにアクセスする際の認可タイプです。サポートされる認可タイプのいずれかの値を指定します。 文字列
videoCodec ストリームのビデオコーデックです。サポートされるビデオコーデックのいずれかの値を指定します。 文字列
audioCodec ストリームのオーディオコーデックです。サポートされるオーディオコーデックのいずれかの値を指定します。 文字列

cameraStreamConfigurationオブジェクト

cameraStreamConfigurationオブジェクトは、カメラがサポートするコンフィギュレーションを表します。カメラがサポートするコンフィギュレーションを検出応答で指定します。

CameraStreamConfigurationオブジェクトの例

クリップボードにコピーされました。

{
  "protocols": ["RTSP"],
  "resolutions": [{"width":1920, "height":1080}, {"width":1280, "height":720}],
  "authorizationTypes": ["BASIC"],
  "videoCodecs": ["H264", "MPEG2"],
  "audioCodecs": ["G711"]
},

CameraStreamConfigurationオブジェクトの詳細

フィールド 説明 型
protocols サポートするプロトコルです。サポートされるプロトコル値の配列です。 配列
resolutions サポートする解像度です。resolutionオブジェクトの配列です。 配列
authorizationTypes サポートする認可タイプです。サポートされる認可タイプ値の配列です。 配列
videoCodecs サポートするビデオコーデックです。サポートされるビデオコーデック値の配列です。 配列
audioCodecs サポートするオーディオコーデックです。サポートされるオーディオコーデック値の配列です。 配列

resolutionオブジェクト

resolutionオブジェクトは、カメラストリームの高さと幅を表します。

Resolutionオブジェクトの例

クリップボードにコピーされました。

{
  "height": 720,
  "width": 1280
}

検出

Alexa.CameraStreamControllerをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

表示カテゴリーにはCAMERAを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

機能配列のCameraStreamControllerエントリには、通常の検出応答フィールドのほかに、次のフィールドを含めます。

フィールド 説明 型
cameraStreamConfigurations カメラがサポートするコンフィギュレーションです。 cameraStreamConfigurationオブジェクトの配列です。

検出応答の例

以下は、Alexa.CameraStreamControllerインターフェース、MediaMetadataインターフェース、EndpointHealthインターフェースをサポートするセキュリティカメラのDiscover.Responseメッセージ例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "玄関のカメラ",
          "displayCategories": ["CAMERA"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.CameraStreamController",
              "version": "3",
              "cameraStreamConfigurations" : [
                  {
                    "protocols": ["RTSP"],
                    "resolutions": [{"width":1920, "height":1080}, {"width":1280, "height":720}],
                    "authorizationTypes": ["BASIC"],
                    "videoCodecs": ["H264", "MPEG2"],
                    "audioCodecs": ["G711"]
                  },
                  {
                    "protocols": ["RTSP"],
                    "resolutions": [{"width":1920, "height":1080}, {"width":1280, "height":720}],
                    "authorizationTypes": ["NONE"],
                    "videoCodecs": ["H264"],
                    "audioCodecs": ["AAC"]
                 }
              ]
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.MediaMetadata",
              "version": "3",
              "proactivelyReported": true
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name":"connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

InitializeCameraStreamsディレクティブ

ユーザーが防犯カメラからのフィードを確認できるようにInitializeCameraStreamsディレクティブをサポートします。

以下に、ユーザーの発話の例を示します。

Alexa, show the front door camera.

Alexa, zeige die frontkamera.

アレクサ、玄関のカメラを見せて

InitializeCameraStreamsディレクティブペイロードの詳細

フィールド 説明 型
cameraStreams ストリームに関する情報を提供するcameraStreamオブジェクトの配列です。 配列

InitializeCameraStreamsディレクティブの例

次の例は、Alexaがスキルに送信するInitializeCameraStreamsディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.CameraStreamController",
      "name": "InitializeCameraStreams",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "cameraStreams": [
        {
          "protocol": "RTSP",
          "resolution": {"width": 1920, "height": 1080},
          "authorizationType": "BASIC",
          "videoCodec": "H264",
          "audioCodec": "AAC"
        },
        {
          "protocol": "RTSP",
          "resolution": {"width": 1280, "height": 720},
          "authorizationType": "NONE",
          "videoCodec": "MPEG2",
          "audioCodec": "G711"
        }
      ]
    }
  }
}

InitializeCameraStreams応答イベント

InitializeCameraStreamsを正常に処理したら、Alexa.CameraStreamController.Responseイベントで応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。

Alexa.CameraStreamController.Responseイベントペイロードの詳細

フィールド 説明 型 必須
cameraStreams ストリームに関する情報を提供するcameraStreamオブジェクトの配列です。 配列 ◯
imageUri リクエストに指定されたカメラの以前のフィードの静止画像のURIです。 文字列 ◯

Alexa.CameraStreamController.Responseイベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.CameraStreamController",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "cameraStreams": [
        {
          "uri": "rtsp://username:password@link.to.video:443/feed1.mp4",
          "expirationTime": "2017-02-03T16:20:50.52Z",
          "idleTimeoutSeconds": 30,
          "protocol": "RTSP",
          "resolution": {"width": 1920, "height": 1080},
          "authorizationType": "BASIC",
          "videoCodec": "H264",
          "audioCodec": "AAC"
        }
      ],
      "imageUri": "https://username:password@link.to.image/image.jpg"
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

InitializeCameraStreamsディレクティブのエラー処理

InitializeCameraStreamsディレクティブを正常に処理できなかった場合、Alexa.ErrorResponseイベントを使用して応答します。ユーザーがカメラを設定する必要がある場合、NOT_SUPPORTED_IN_CURRENT_MODEエラーを返し、currentDeviceModeフィールドにはNOT_PROVISIONEDの値が含まれます。

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするために、ReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

StateReport応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

ChangeReportイベントの例

クリップボードにコピーされました。

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "UNREACHABLE"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
    ]
  }
}