Alexa.Camera.LiveViewController Interface 1.7
Implement the Alexa.Camera.LiveViewController
interface so that users can use your viewing device to start and stop the live feed video stream from their security cameras. The camera streams audio and video to your viewer by using Web Real-Time Communication (WebRTC) and the Alexa.RTCSessionController interface.
The Alexa.Camera.LiveViewController
interface supports en-US (English, United States) only.
Utterances
When you use the Alexa.Camera.LiveViewController
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, talk to the front door camera.
Alexa, show the front door camera.
Alexa, stop the front door camera feed.
Alexa, go home.
Alexa, stop.
After the user says one of these utterances, the Alexa service sends the corresponding directive to the viewing device.
Communication between your device and the camera
With the Alexa.Camera.LiveViewController
interface, you can control live video streaming to your Alexa-enabled viewing device. To stream video, you use the Alexa.RTCSessionController interface.
The following diagram shows the message flow to enable live viewing to your viewing device from a customer's camera. The flow starts when the user asks Alexa to start the live stream.

- The Alexa service sends the
Alexa.StartLiveView
directive to the viewing device. - The Alexa service sets up the real time communication (RTC) session between the camera and the viewing device.
- The viewing device sends a
Alexa.LiveViewStartedEvent
to notify the Alexa service that streaming started.
The viewing device begins showing the streaming video to the user. - Later, the user asks Alexa to close the live view.
The Alexa service sendsAlexa.StopLiveView
to viewing device - The Alexa service tears down the RTC session.
- The viewing device sends
Alexa.LiveViewStopped
.
Dependencies
If your endpoint supports Alexa.Camera.LiveViewController
, the endpoint must also support Alexa
3.0 and Alexa.Discovery
3.0 or higher.
Capability assertion
You describe endpoints that support Alexa.Camera.LiveViewController
using the standard discovery mechanism described in Alexa.Discovery. You include the Alexa.Camera.LiveViewController
in the capabilities
list for each endpoint.
Use ALEXA_VOICE_ENABLED
for the display category. For the full list of display categories, see display categories.
Configurations array
In addition to the usual discovery response fields, for the Alexa.Camera.LiveViewController
entry in the configurations array, include the following fields.
Field | Description | Type |
---|---|---|
supportedDisplayModes |
Display modes that the viewing device supports. Default value: FULL_SCREEN. |
Array of DisplayMode values |
supportedOverlayTypes |
Overlay types that the viewing device supports. Default value: NONE. |
Array of OverlayType values |
supportedOverlayPositions |
Overlay position that the viewing device supports. Default value: TOP_RIGHT. |
Array of OverlayPosition values |
Discover response example
The following example shows a Discover.Response
message for a viewing device that supports the Alexa.Camera.LiveViewController
and EndpointHealth interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "message id"
},
"payload": {
"endpoints": [{
"endpointId": "uniqueIdOfCameraEndpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "a description that is shown in the Alexa app",
"friendlyName": "the friendly name of the device set by the customer",
"displayCategories": ["ALEXA_VOICE_ENABLED"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.Camera.LiveViewController",
"version": "1.7",
"configuration": {
"supportedDisplayModes": ["FULL_SCREEN", "OVERLAY"],
"supportedOverlayTypes": ["PICTURE_IN_PICTURE"],
"supportedOverlayPositions": ["TOP_RIGHT", "TOP_LEFT", "BOTTOM_RIGHT"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
AddOrUpdateReport example
The following example shows an AddOrUpdateReport
event for a device that supports the Alexa.Camera.LiveViewController
and EndpointHealth interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 bearer token"
},
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"registration": {
"productId": "productID-001",
"deviceSerialNumber": "serial-001"
},
"manufacturerName": "Manufacturer name of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Living Room TV",
"displayCategories": ["TV"],
"additionalAttributes": {
"manufacturer": "Manufacturer name of the endpoint",
"model": "Model of the device",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "Software version of the device",
"customIdentifier": "Optional custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.Camera.LiveViewController",
"version": "1.7",
"configuration": {
"supportedDisplayModes": ["FULL_SCREEN", "OVERLAY"],
"supportedOverlayTypes": ["PICTURE_IN_PICTURE"],
"supportedOverlayPositions": ["TOP_RIGHT", "TOP_LEFT", "BOTTOM_RIGHT"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
The Alexa.Camera.LiveViewController
interface includes the following directives sent from Alexa to the viewer.
StartLiveView directive
After the user says, "Alexa, show the front door camera" or "Alexa, talk to the front door camera," Alexa sends the Alexa.StartLiveView
directive to instruct the viewer to start streaming.
If you handle a Alexa.StartLiveView
directive successfully, send the LiveViewStarted event in response. The DeferredResponse event isn't supported. If you can't start the live view, respond with a LiveViewStopped event.
StartLiveView directive example
The following example illustrates a Alexa.StartLiveView
directive that Alexa sends to your device.
{
"directive": {
"header": {
"namespace": "Alexa.Camera.LiveViewController",
"name": "StartLiveView",
"messageId": "message id",
"correlationToken": "an opaque correlation token from the directive",
"payloadVersion": "1.7"
},
"payload": {
"sessionId": "session_id",
"target": {
"type": "ALEXA_ENDPOINT",
"endpointId": "endpoint_id of the viewing device"
},
"role": "VIEWER",
"participants": {
"viewers": [{
"name": "name of the viewing device",
"hasCameraControl": true,
"state": "CONNECTED"
}],
"camera": {
"name": "name of camera streaming the live feed",
"make": "camera make name",
"model": "camera model name"
}
},
"viewerExperience": {
"suggestedDisplay": {
"displayMode": "FULL_SCREEN",
"overlayType": "NONE"
},
"audioProperties": {
"talkMode": "TAP",
"concurrentTwoWayTalk": "ENABLED",
"microphoneState": "MUTED",
"speakerState": "MUTED"
},
"liveViewTrigger": "USER_ACTION",
"idleTimeoutInMilliseconds": 15000
}
}
}
}
StartLiveView directive payload details
Field | Description | Type |
---|---|---|
sessionId |
Live streaming session identifier. | String |
target |
Identifies the viewing device. | Target object |
role |
Specifies the role of the device for the streaming session. | Role value |
participants |
Camera source and a list of viewing devices in the requested streaming session. | Participants object |
viewerExperience |
Defines the display and audio properties of the streaming session. | ViewerExperience object |
StopLiveView directive
Alexa sends the Alexa.StopLiveView
directive to instruct the viewing device to stop streaming or inform the viewer of streaming errors.
If you handle a Alexa.StopLiveView
directive successfully, send the LiveViewStopped event in response. The DeferredResponse event isn't supported. If you can't stop the live view, respond with an Alexa.ErrorResponse.
StopLiveView directive example
The following example illustrates a Alexa.StopLiveView
directive that Alexa sends to your device.
{
"directive": {
"header": {
"namespace": "Alexa.Camera.LiveViewController",
"name": "StopLiveView",
"messageId": "message id",
"correlationToken": "an opaque correlation token from the directive",
"payloadVersion": "1.7"
},
"payload": {
"sessionId": "session_id",
"target": {
"type": "ALEXA_ENDPOINT",
"endpointId": "endpoint_id of the viewing device"
},
"status": "MEDIA_SOURCE_NOT_FOUND",
"description": "The media source could not be found."
}
}
}
StopLiveView directive payload details
Field | Description | Type |
---|---|---|
sessionId |
Live streaming session identifier. | String |
target |
Identifies the viewing device. | Target object |
status |
Indicates the reason that Alexa stopped the session. | Status value |
description |
Human-readable message that describes why Alexa sent the Alexa.StopLiveView directive. |
String |
Events
The Alexa.Camera.LiveViewController
interface includes the following events sent from the viewer.
LiveViewStarted
Send the Alexa.LiveViewStarted
event in response to Alexa.StartLiveView
to indicate that the viewing session started. Set the target property to the endpoint ID of the viewing device.
LiveViewStarted event example
{
"event": {
"header": {
"namespace": "Alexa.Camera.LiveViewController",
"name": "LiveViewStarted",
"messageId": "message id",
"payloadVersion": "1.7"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"target": {
"type": "ALEXA_ENDPOINT",
"endpointId": "endpoint ID of viewer"
}
}
}
}
LiveViewStarted event payload details
Field | Description | Type |
---|---|---|
sessionId |
Identifier of the session that wants to connect to the camera. Use the streaming session ID in the RTCSessionController interface. |
String |
target |
Identifies the viewing device. | Target object |
LiveViewStopped
Send the Alexa.LiveViewStopped
event in response to Alexa.StopLiveView
when the live stream stops, or in response to Alexa.StartLiveView
to indicate that the live stream failed to start. Set the target property to the endpoint ID of the viewing device.
LiveViewStopped example
{
"event": {
"header": {
"namespace": "Alexa.Camera.LiveViewController",
"name": "LiveViewStopped",
"messageId": "message id",
"payloadVersion": "1.7"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"target": {
"type": "ALEXA_ENDPOINT",
"endpointId": "endpoint ID of the viewing device"
}
}
}
}
LiveViewStopped event payload details
Field | Description | Type |
---|---|---|
sessionId |
Identifier of the session that wants to connect to the camera. Use the streaming session ID in the RTCSessionController interface. |
String |
target |
Identifies the viewing device. | Target object |
status |
(Optional) Indicates the reason the viewer stopped the session. | Status value |
description |
(Optional) Human-readable message that describes why the viewer sent the Alexa.LiveViewStopped event. |
String |
Properties and objects
The Alexa.Camera.LiveViewController
interface uses the following properties and objects.
The AudioState property
Defines the state of the microphone and speaker when the streaming session starts. You can use the following values for AudioState
.
Value | Description |
---|---|
UNMUTED |
For microphone state, this value opens the microphone on the viewing device. For speaker state, this value enables audio from the camera to the viewing device. For example, when the user says, "Alexa, talk to the front door camera." |
MUTED |
For microphone state, this value mutes the microphone on the viewing device. For speaker state, this value disables audio from the camera to the viewing device. For example, when the user says, "Alexa, show the front door camera." |
DISABLED |
This value indicates that the camera doesn't support audio communication. In this state, the viewing device doesn't display the microphone and speaker. |
The Capability property
Defines the motion capabilities of the camera.
The following table shows the values for Capability
.
Value | Description |
---|---|
PHYSICAL_PAN |
The camera supports physical panning. To pan, the camera rotates on the horizontal axis. |
PHYSICAL_TILT |
The camera can tilt on the vertical axis. |
PHYSICAL_ZOOM |
The camera supports optical zoom. |
The ConcurrentTwoWayTalkState property
Indicates whether the camera supports two-way communication with the viewing device. You can use the following values for ConcurrentTwoWayTalkState
.
Value | Description |
---|---|
ENABLED |
Indicates the camera supports two-way audio communication with the viewing device. |
DISABLED |
Indicates the camera doesn't support two-way audio communication with the viewing device. |
The DisplayMode property
Defines the supported modes to render the stream. You can use the following values for DisplayMode
.
Value | Description |
---|---|
FULL_SCREEN |
The camera live feed stream displays on the entire screen. |
OVERLAY |
The camera live feed stream displays on top of other streams. |
The LiveViewTrigger property
Defines the reason that the live view session started. You can use the following values for LiveViewTrigger
.
Value | Description |
---|---|
USER_ACTION |
The user started the live view streaming session. |
AUTOMATED_EVENT |
An automated event, such as a doorbell press, triggered the streaming session. |
The OverlayPosition property
Defines the position on the screen to display the overlay. You can use the following values for OverlayPosition
.
Value | Description |
---|---|
TOP_RIGHT |
Directs the viewing device to display the overlay on the top right of the screen. |
TOP_LEFT |
Directs the viewing device to display the overlay on the top left of the screen. |
BOTTOM_RIGHT |
Directs the viewing device to display the overlay on the bottom right of the screen. |
BOTTOM_LEFT |
Directs the viewing device to display the overlay on the bottom left of the screen. |
The OverlayType property
Defines the type of overlay supported by the viewing device. You can use the following values for OverlayType
.
Value | Description |
---|---|
PICTURE_IN_PICTURE |
The viewing device supports picture-in-picture display mode. |
NONE |
The viewing device doesn't support overlay mode. |
The Role property
The device can act as a security camera or a viewer of a security camera stream. Use the Role
property to specify the role of the device for the streaming session. You can use the following values for Role
.
Value | Description |
---|---|
CAMERA |
The device acts as a camera. There can be one camera per streaming session. |
VIEWER |
The device acts as a viewer of the security camera streaming session. There can be multiple viewing devices in a streaming session. |
The Status property
Indicates the reason for the Alexa.StopLiveView
directive and the Alexa.LiveViewStopped
event. You can use the following values for Status
.
Value | Description |
---|---|
STOP_LIVE_VIEW_REQUESTED |
The user requested to stop the live view session. |
MEDIA_SOURCE_NOT_FOUND |
Alexa can't find the media source. |
UNAUTHORIZED |
The device isn't authorized to access the live view feature. |
BATTERY_LEVEL_TOO_LOW |
The device battery is too low is support the live stream. |
MEDIA_SOURCE_ASLEEP |
The media source is asleep. |
MEDIA_SOURCE_TURNED_OFF |
The media source is off. |
The TalkMode property
Defines the audio communication supported by the camera. You can use the following values for TalkMode
.
Value | Description |
---|---|
NO_SUPPORT |
The camera doesn't support audio communication. |
PRESS_AND_HOLD |
The camera supports two-way communication in the style of a walkie-talkie. The user pushes the microphone on the viewing device to talk, and then releases to listen. |
TAP |
The camera supports two-way audio communication. The user taps the microphone on the viewing device to unmute and talk, and then taps to mute the microphone. |
The AudioProperties object
Defines audio details of the streaming session.
AudioProperties object example
{
"audioProperties": {
"talkMode": "PRESS_AND_HOLD",
"concurrentTwoWayTalk": "ENABLED",
"microphoneState": "MUTED",
}
}
AudioProperties object details
Field | Description | Type |
---|---|---|
talkMode |
Audio communication capability of the camera. | TalkMode value |
concurrentTwoWayTalk |
Defines whether the camera supports concurrent two-way communication. | ConcurrentTwoWayTalk value |
microphoneState |
State of the microphone at the start of the streaming session. | AudioState value |
speakerState |
State of the speaker at the start of the streaming session. | AudioState value |
The Camera object
Defines details of the camera, such as name, manufacturer, and camera capabilities.
Camera object example
{
"camera": {
"name": "Front Door camera",
"make": "camera make",
"model": "camera model",
"capabilities": ["PHYSICAL_PAN, PHYSICAL_TILT, PHYSICAL_ZOOM"]
}
}
Camera object details
Field | Description | Type |
---|---|---|
name |
Friendly name of the camera, such as "front door." Maximum length is 512 characters. |
String |
make |
Name of the manufacturer of the camera. Maximum length is 512 characters. |
String |
model |
(Optional) Model name of the camera. Maximum length is 512 characters. |
String |
capabilities |
(Optional) Motion capabilities of the camera. | Array of Capability values |
The DisplayProperties object
Defines details of the requested display experience on the viewing device.
DisplayProperties object example
{
"suggestedDisplay": {
"displayMode": "FULL_SCREEN",
"overlayType": "PICTURE_IN_PICTURE",
"overlayPosition": "TOP_RIGHT"
}
}
DisplayProperties object details
Field | Description | Type |
---|---|---|
displayMode |
Display mode in which to render the live stream. | DisplayMode value |
overlayType |
(Optional) If displayMode=OVERLAY, the type of overlay to use to render the live stream. If set to NONE , the displayMode defaults to FULL_SCREEN . |
OverlayType value |
overlayPosition |
(Optional) If displayMode = OVERLAY , overlayPosition indicates the position on the screen to display the overlay. |
OverlayPosition value |
The Participants objects
Contains the camera source and a list of viewing devices in the current streaming session.
Participants object example
{
"participants": {
"viewers": [
{
"name": "Kitchen Echo Show",
"hasCameraControl": true,
"state": "CONNECTED"
},
{
"name": "Mom's Alexa App",
"hasCameraControl": false,
"state": "CONNECTING"
}
],
"camera": {
"name": "Front Door camera"
}
}
}
Participants object details
Field | Description | Type |
---|---|---|
viewers |
List of the viewing devices. You must specify at least one viewing device. |
Array of Viewer objects |
camera |
Camera source of the live feed. | Camera object |
The Target object
Identifies the endpoint of the viewing device.
Target object example
{
"type": "ALEXA_ENDPOINT",
"endpointId": "56dc9dea-e1ce-4c36-a6c5-72ed12ef2c0c"
}
Target object details
Field | Description | Type |
---|---|---|
endpointId |
Identifier of the device. | String |
type |
(Optional) Type of endpoint. Valid value: ALEXA_ENDPOINT . |
String |
The Viewer object
Defines details of the Alexa device used to view the streaming session.
Viewer object example
{
"viewer": {
"name": "Livingroom TV",
"hasCameraControl": true,
"state": "CONNECTED ",
}
}
Viewer object details
Field | Description | Type |
---|---|---|
name |
Friendly name of the viewing device, such as "Kitchen Echo Show." Maximum length is 512 characters. |
String |
hasCameraControl |
Indicates whether the viewing device has control over the camera. In a list of viewing devices, one device can control the camera at any one time. | Boolean |
state |
Connection state of the viewing device. In the connected state, the user can see the camera feed. Valid Values: CONNECTED , CONNECTING . |
String |
The ViewerExperience object
Defines the display and audio properties of the streaming session.
ViewerExperience object example
{
"viewerExperience": {
"suggestedDisplay": {
"displayMode": "FULL_SCREEN",
"overlayType": "PICTURE_IN_PICTURE",
"overlayPosition": "TOP_RIGHT"
},
"audioProperties": {
"talkMode": "PRESS_AND_HOLD",
"concurrentTwoWayTalk": "ENABLED",
"microphoneState": "MUTED",
},
"liveViewTrigger": "USER_ACTION",
"idleTimeoutInMilliseconds": 6000
}
}
ViewerExperience object details
Field | Description | Type |
---|---|---|
suggestedDisplay |
Display properties of the live view streaming session. | DisplayProperties object |
audioProperties |
Audio communication properties of the live view streaming session. | AudioProperties object |
liveViewTrigger |
Reason the live view streaming session started. | LiveViewTrigger value |
idleTimeoutInMilliseconds |
Timeout value in milliseconds. Any user interaction with the viewing device cancels the timer. For example, the user enables the microphone, performs pan, tilt, zoom gestures, or switches between full screen and picture-in-picture. A negative value or zero disables the timer. The default is 15000 milliseconds. |
Integer |
Related topics
Last updated: Nov 27, 2023