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.

Start a live video stream to an Alexa-enabled viewing device with a screen.
  1. The Alexa service sends the Alexa.StartLiveView directive to the viewing device.
  2. The Alexa service sets up the real time communication (RTC) session between the camera and the viewing device.
  3. 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.
  4. Later, the user asks Alexa to close the live view.
    The Alexa service sends Alexa.StopLiveView to viewing device
  5. The Alexa service tears down the RTC session.
  6. 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.

Copied to clipboard.

{
    "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.

Copied to clipboard.

{
    "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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

Was this page helpful?

Last updated: Nov 27, 2023