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.

Discovery
Directives
- InitializeCameraStreams
Properties and Events
Additional Sample Code

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",
          "endpointTypeId": "type id",
          "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 code for the stream. Possible values are “G711”, “AAC”, or “NONE”.	string	Yes

Directives

This control and query directives in this interface are supported in skills that target the following languages:

English (US)
English (UK)
German

See Develop Smart Home Skills in Multiple Languages for more information.

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": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "endpointId": "appliance-001",
       "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            },
      "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 code for the stream. Possible values are “G711”, “AAC”, or “NONE”.	string	Yes

Properties and Events

For this interface, you must reply:

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

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

Reportable 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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
       "endpointId": "appliance-001"
    },
    "payload": {
      "cameraStreams": [ {
        "uri": "rtsp://username:[email protected]: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:[email protected]/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`	A date in ISO 8601 format indicating the expiration time of the stream. Should be specified in UTC.	string	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 code 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 Error.Response for more details.

Additional Sample Code

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

CameraController