Alexa.VideoRecorder Interface
Implement the Alexa.VideoRecorder
interface in your Alexa skill so that users can find and schedule a recording for a specified video item. Also implement this interface to cancel a scheduled recording or inquire about the recording space left on a digital video recorder (DVR). To record video content that's currently playing, implement the Alexa.RecordController interface instead.
For the list of languages that the Alexa.VideoRecorder
interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
The Alexa.VideoRecorder
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, record the new episode of title next week.
Alexa, record PBS at five o'clock pm.
Alexa, stop recording title.
Alexa, cancel recording of next week's episode of title.
Alexa, delete the recording of title.
Reportable properties
The Alexa.VideoRecorder
interface uses the following properties. You identify that you support the properties in your discovery response.
Property | Description | Type |
---|---|---|
|
Indicates the type of graphical user interface shown to the user. |
Boolean |
|
Indicates the percentage of storage used on the recording device. |
Integer |
Discovery
You describe endpoints that support Alexa.VideoRecorder
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.VideoRecorder
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.VideoRecorder
.
{
"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.VideoRecorder",
"version": "3",
"properties": {
"supported": [{
"name": "isExtendedRecordingGUIShown"
},
{
"name": "storageLevel"
}
],
"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
The directives for the Alexa.VideoRecorder
interface include an entity object that specifies the requested content. For details, see Entity Types for Video Content.
SearchAndRecord
Support the SearchAndRecord
directive so that users can request to find and record specific video content. The payload contains an array of entities
that specifies what to search for and the time window in which to search.
SearchAndRecord directive example
The following example shows a request to record PBS at 5:00 PM.
{
"directive": {
"header": {
"namespace": "Alexa.VideoRecorder",
"name": "SearchAndRecord",
"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": {
"entities": [{
"externalIds": {
"imdb": "co0668124"
},
"entityMetadata": {
"channelNumber": 123,
"channelCallSign": "PBS"
},
"type": "Channel",
"value": "PBS"
}],
"quantifier": {
"name": "NEW"
},
"timeWindow": {
"start": "2021-12-31T17:00:00.00Z"
}
}
}
}
SearchAndRecord directive payload
The following table shows the payload details for the SearchAndRecord
directive.
Property | Description | Type | Required |
---|---|---|---|
|
User-requested search terms. |
Array of |
Yes |
|
Specifies the type of recording to create. |
Object |
No |
|
Recording type specified by the user. For details, see Quantifier name values. |
String |
No |
|
Specifies the span of time over which to search. |
Object |
No |
|
The start time for the content search. |
String |
No |
|
The end time for the content search. |
String |
No |
Quantifier name values
The following table shows the possible quantifier names.
Name | Description |
---|---|
|
All content that matches the specified entity. |
|
Content that matches the specified entity and airs closest to the time specified or closest after the specified time. |
|
Content that airs for the first time and matches the specified entity. |
|
All watched content that matches the specified entity. |
SearchAndRecord response
If you handle a SearchAndRecord
directive successfully, respond with an SearchAndRecord.Response
event. Include the status of the record request in the payload
object and the value of the reportable properties in the context
object.
The following example shows a SearchAndRecord
response.
{
"event": {
"header": {
"namespace": "Alexa.VideoRecorder",
"name": "SearchAndRecord.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": {
"recordingStatus": "SCHEDULED"
}
},
"context": {
"properties": [{
"namespace": "Alexa.VideoRecorder",
"name": "isExtendedRecordingGUIShown",
"value": false,
"timeOfSample": "2021-12-31T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.VideoRecorder",
"name": "storageLevel",
"value": 75,
"timeOfSample": "2021-12-31T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-31T17:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SearchAndRecord response payload
The following table shows the payload
details for the SearchAndRecord
response.
Also, include the values of all other reportable properties in the context
object.
Property | Description | Type | Required |
---|---|---|---|
|
Indicates the status of the recording. |
String |
Yes |
SearchAndRecord error handling
If you can't handle a SearchAndRecord
directive successfully, respond with an Alexa.Video.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to video.
CancelRecording
Support the CancelRecording
directive so that users can request to cancel a scheduled recording of the specified title or a title that best matches the requested entity.
CancelRecording directive example
The following example shows a request to cancel the recording of next week's episode of the specified video content.
{
"directive": {
"header": {
"namespace": "Alexa.VideoRecorder",
"name": "CancelRecording",
"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": {
"entities": [{
"externalIds": {
"imdb": "tt0086190"
},
"type": "Video",
"value": "Movie Title"
}],
"timeWindow": {
"start": "2021-12-30T17:00:00.00Z",
"end": "2021-12-31T17:00:00.00Z"
}
}
}
}
CancelRecording directive payload
The CancelRecording
directive contains the same payload parameters as the SearchAndRecord
directive.
CancelRecording response
If you handle a CancelRecording
directive successfully, respond with an SearchAndRecord.Response
event. The response doesn't require a payload, but include the values of all other reportable properties in the context
object.
The following example shows a CancelRecording
response.
{
"event": {
"header": {
"namespace": "Alexa.VideoRecorder",
"name": "SearchAndRecord.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.VideoRecorder",
"name": "isExtendedRecordingGUIShown",
"value": false,
"timeOfSample": "2021-12-31T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.VideoRecorder",
"name": "storageLevel",
"value": 75,
"timeOfSample": "2021-12-31T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-31T17:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
CancelRecording error handling
If you can't handle a CancelRecording
directive successfully, respond with an Alexa.Video.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to video.
DeleteRecording directive
Support the DeleteRecording
directive so that users can request to delete a scheduled recording for a specified title or a title that best matches the requested entity.
DeleteRecording directive example
The following example shows a request to delete the recording of next week's episode of the specified video content.
{
"directive": {
"header": {
"namespace": "Alexa.VideoRecorder",
"name": "DeleteRecording",
"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": {
"entities": [{
"externalIds": {
"imdb": "tt0086190"
},
"type": "Video",
"value": "Movie Title"
}],
"quantifier": {
"name": "ALL"
},
"timeWindow": {
"start": "2021-12-30T17:00:00.00Z",
"end": "2021-12-31T17:00:00.00Z"
}
}
}
}
DeleteRecording directive payload
The DeleteRecording
directive contains the same payload parameters as the SearchAndRecord
directive.
DeleteRecording response
If you handle a DeleteRecording
directive successfully, respond with an SearchAndRecord.Response
event. The response doesn't require a payload, but include the values of all other reportable properties in the context
object.
The following example shows a DeleteRecording
response.
{
"event": {
"header": {
"namespace": "Alexa.VideoRecorder",
"name": "SearchAndRecord.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.VideoRecorder",
"name": "isExtendedRecordingGUIShown",
"value": false,
"timeOfSample": "2021-12-31T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.VideoRecorder",
"name": "storageLevel",
"value": 75,
"timeOfSample": "2021-12-31T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-31T17:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
DeleteRecording error handling
If you can't handle a DeleteRecording
directive successfully, respond with an Alexa.Video.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to video.
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": [
{
"name": "isExtendedRecordingGUIShown",
"namespace": "Alexa.VideoRecorder",
"timeOfSample": "2021-12-31T17:00:00.00Z",
"uncertaintyInMilliseconds": 0,
"value": false
},
{
"name": "storageLevel",
"namespace": "Alexa.VideoRecorder",
"timeOfSample": "2021-12-31T17:00:00.00Z",
"uncertaintyInMilliseconds": 0,
"value": 75
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-31T17: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.VideoRecorder
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.