Alexa.RecordController Interface

Implement the Alexa.RecordController interface in your Alexa skill so that users can start and stop recording content immediately. To support scheduled recordings, see Alexa.VideoRecorder.

For the list of languages that the Alexa.RecordController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

The Alexa.RecordController interface uses the pre-built voice interaction model. After the customer says one of the following utterances, Alexa sends a corresponding directive to your skill.

The following examples show some customer utterances:

Alexa, start recording.
Alexa, stop recording.

Reportable properties

The Alexa.RecordController interface uses the recordingState as the primary property. You identify that you support the property in your discovery response.

The following example shows a recording in progress.

{
  "name": "recordingState",
  "value": "RECORDING"
}

The following table shows the definition of the recordingState property.

Property Description Type

recordingState

Indicates whether a recording is in progress.
Valid values: RECORDING, NOT_RECORDING

String

Discovery

You describe endpoints that support Alexa.RecordController by using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. For change reporting, set proactivelyReported to false for the Alexa.RecordController interface. Set proactivelyReported to true as appropriate for other interfaces that you implement in your skill.

Use TV, STREAMING_DEVICE, GAME_CONSOLE, or other appropriate display category. For the full list of display categories, see display categories.

Discover response example

The following example shows an Alexa.Discover.Response message for a device that supports the Alexa.RecordController.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "the manufacturer name of the endpoint",
                "description": "a description that is shown in the Alexa app",
                "friendlyName": "Living Room TV",
                "displayCategories": ["TV"],
                "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"
                },
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.RecordController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "recordingState"
                                }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Proactive Discovery with AddOrUpdateReport

When a user adds a new endpoint to their account or makes changes to an existing endpoint, you must proactively send an Alexa.Discovery.AddOrUpdateReport message to the Alexa event gateway. You can include all the endpoints associated with the user account, or only the new or updated endpoints. You can choose based on your skill implementation. For details, see AddOrUpdateReport.

Directives

StartRecording

Support the StartRecording directive so that users can request to start recording the content that is currently playing.

StartRecording directive example

The following example shows a request to start recording.

{
    "directive": {
        "header": {
            "namespace": "Alexa.RecordController",
            "name": "StartRecording",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {}
    }
}

StartRecording directive payload

The StartRecording directive doesn't define any payload parameters.

StartRecording response

If you handle a StartRecording directive successfully, respond with an Alexa.Response event. Include the recordingState and any other reportable properties in the context object.

The following example shows a StartRecording response.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.RecordController",
                "name": "recordingState",
                "value": "RECORDING",
                "timeOfSample": "2021-12-31T17:00:00.00Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

StartRecording error handling

If you can't handle a StartRecording directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic Alexa.ErrorResponse event.

StopRecording

Support the StopRecording directive so that users can request to stop the current recording.

StopRecording directive example

The following example shows a request to stop the recording.

{
    "directive": {
        "header": {
            "namespace": "Alexa.RecordController",
            "name": "StopRecording",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {}
    }
}

StopRecording directive payload

The StopRecording directive doesn't define any payload parameters.

StopRecording response

If you handle a StopRecording directive successfully, respond with an Alexa.Response event. Include the recordingState and any other reportable properties in the context object.

The following example shows a StopRecording response.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.RecordController",
                "name": "recordingState",
                "value": "NOT_RECORDING",
                "timeOfSample": "2021-12-31T18:30:00.00Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2021-12-31T18:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

StopRecording error handling

If you can't handle a StopRecording directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic Alexa.ErrorResponse event.

State reporting

Alexa sends an Alexa.ReportState directive to request information about the state of an endpoint. You send an Alexa.StateReport event in response. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see State Reporting for Video Skills.

StateReport response example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.RecordController",
                "name": "recordingState",
                "value": "NOT_RECORDING",
                "timeOfSample": "2021-12-31T18:30:00.00Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2021-12-31T18:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Change reporting

You send an Alexa.ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response.

The Alexa.RecordController interface doesn't define any proactively reportable properties. However, you send change reports for the other interfaces that you implement in your skill. For details about change reports, see State Reporting for Video Skills.