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

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": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "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 can 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": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "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 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