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 |
---|---|---|
|
Indicates whether a recording is in progress. |
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
.
{
"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.
{
"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.
{
"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
{
"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.