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
Prerequisites and requirements
Discovery
Directives
- InitializeCameraStreams
Properties and Events
Additional Sample Code

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

When you respond to a discovery request for a skill that controls a camera, you describe the camera configuration(s) in the response with an array of cameraStreamConfiguration objects.

DiscoveryResponse example containing Alexa.CameraStreamController

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "uniqueIdOfCameraEndpoint",
          "manufacturerName": "the manufacturer name of the endpoint",
          "modelName": "the model name of the endpoint",
          "friendlyName": "Camera",
          "description": "a description that is shown to the customer",
          "displayCategories": [ "CAMERA" ],
          "cookie": {
              "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
              "key2": "There can be multiple entries",
              "key3": "but they should only be used for reference purposes.",
              "key4": "This is not a suitable place to maintain current endpoint state."
          },
          "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.