Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Alexa.CameraStreamController Interface

The Alexa.CameraStreamController interface describes the messages used retrieve camera streams from camera endpoints. For more information about skills that interact with cameras, see Build Smart Home Camera Skills.

For the list of locales that are supported for the CameraStreamController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.CameraStreamController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, show the front door camera.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Prerequisites and requirements

Your cameras must provide a video feed in the correct format and meet the security and performance requirements. Following are the technical and security requirements for cameras and video feeds.

Category Requirement
Streaming protocol(s) RTSP + RTP
Transport protocols Interleaved TCP on port 443 (for both RTP and RTSP)
Feed encryption TCP socket encryption on port 443 using TLS 1.2
RTSP Command support required DESCRIBE, SETUP, PLAY, and TEARDOWN commands are required although a full RFC compliant implementation is recommended.
Video format H.264
Audio format AAC/G711
Feed authentication methods HTTP Digest authentication within the returned camera stream.
RTSP URI responsiveness All responses must occur 6 seconds or less after request received.

Discovery

You describe endpoints that support Alexa.CameraStreamController using the standard discovery mechanism described in Alexa.Discovery. In addition, you describe the camera configurations in the response by including an array of cameraStreamConfiguration objects.

Use CAMERA for the display category. For the full list of display categories, see display categories.

Discover response example

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload":{
      "endpoints":[
        {
            "endpointId": "<unique ID of the endpoint>",
            "manufacturerName": "<the manufacturer name of the endpoint>",
            "modelName": "<the model name of the endpoint>",
            "description": "<a description that is shown in the Alexa app>",                      "friendlyName": "Front door camera",
            "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.PowerController",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Payload details

Field Description Type Required
cameraStreamConfigurations An array of cameraStream structures that provide information about the stream. object array Yes
cameraStream.protocols Protocols for the stream such as RTSP string Yes
cameraStream.resolutions An array of resolution objects, which describe the resolutions of the stream. Each resolution contains a width and height property. object Yes
cameraStream.resolution.width Describes the width of the video stream. integer Yes
cameraStream.resolution.height Describes the height of the video stream. integer Yes
cameraStream.authorizationType Describes the authorization type. Possible values are "BASIC", "DIGEST" or "NONE" string Yes
cameraStream.videoCodec The video codec for the stream. Possible values are "H264", "MPEG2", "MJPEG", or "JPG". string Yes
cameraStream.audioCodec The audio codec for the stream. Possible values are "G711", "AAC", or "NONE". string Yes

Directives

InitializeCameraStreams

Initializes camera streams for an endpoint.

"Alexa, show front door camera"

"Alexa, zeige die frontkamera"

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.CameraStreamController",
      "name": "InitializeCameraStreams",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "endpointId": "appliance-001",
       "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
      "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"
      }]
    }
  }
}

Payload details

Field Description Type Required
cameraStreams An array of cameraStream structures that provide information about the stream. object array Yes
cameraStream.protocol Protocol for the stream such as RTSP string Yes
cameraStream.resolution A resolution object that describes the the resolution of the stream. Contains width and height properties. object Yes
cameraStream.resolution.width Describes the width of the video stream. integer Yes
cameraStream.resolution.height Describes the height of the video stream. integer Yes
cameraStream.authorizationType Describes the authorization type. Possible values are "BASIC", DIGEST", or "NONE" string Yes
cameraStream.videoCodec The video codec for the stream. Possible values are "H264", "MPEG2", "MJPEG", or "JPG". string Yes
cameraStream.audioCodec The audio codec for the stream. Possible values are "G711", "AAC", or "NONE". string Yes

Properties and Events

For this capability, you must reply:

  • Synchronously, which means you send a Response to Alexa from the Lambda function.

When you send a Response, you should include the state of the interface properties in the context of the message.

Properties

There are no reportable properties currently defined for this interface.

Response

If the InitializeCameraStreams directive was successfully handled, you should respond with an Response event. The payload for this message contains the camera streams for the specified endpoint.

Example Response

{
  "event": {
    "header": {
      "namespace": "Alexa.CameraStreamController",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
       "endpointId": "appliance-001"
    },
    "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"
    }
  }
}

Payload details

Field Description Type Required
cameraStreams An array of cameraStream structures that provide information about the stream. object array Yes
cameraStream.uri The URI for the camera stream. This may be a temporary URI that expires at the time specified by expirationTime. If the URI expires, and an error occurs, Alexa will make a new call to InitializeCameraStreams to get a new, unexpired URI. string Yes
cameraStream.expirationTime The time that the stream expires, specified in UTC. A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No
cameraStream.idleTimeoutSeconds Indicates the timeout value for the stream. Integer No
cameraStream.protocol Protocol for the stream such as RTSP string Yes
cameraStream.resolution A resolution object that describes the the resolution of the stream. Contains width and height properties. object Yes
cameraStream.resolution.width Describes the width of the video stream such as 1920 or 1280. integer Yes
cameraStream.resolution.height Describes the height of the video stream such as 1080. integer Yes
cameraStream.authorizationType Describes the authorization type. Possible values are "BASIC", "DIGEST", or "NONE" string Yes
cameraStream.videoCodec The video codec for the stream. Possible values are "H264", "MPEG2", "MJPEG", or "JPG". string Yes
cameraStream.audioCodec The audio codec for the stream. Possible values are "G711", "AAC", or "NONE". string Yes
imageUri The URI to a static image from a previous feed of the camera specified in the request. string Yes

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

CameraController

Topic Description
Build Smart Home Camera Skills Describes concepts and details of building smart home skills for security cameras.
MediaMetadata Capability for notifying Alexa of new, updated, and deleted recordings.
Authenticate a Customer to Alexa Using Permissions Describes the process for obtaining a bearer token to identify users to Alexa.
Send Events to the Alexa Event Gateway Describes how to send events to Alexa regarding new, updated, or deleted media recordings.