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
- 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
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:
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. |