Alexa.VideoRecorder Interface
The Alexa.VideoRecorder interface describes messages used to find and schedule a recording for a specified video item, to cancel a scheduled recording, or inquire about the recording space left on a DVR. To record the content that is currently playing, implement the Alexa.RecordController interface instead.
For the list of locales that are supported for the VideoRecorder interface, see List of Capability Interfaces and Supported Locales.
Directives
The directives for this interface each include an entity object that specifies the content to find and record. For more information, see Entity Types for Video Content.
SearchAndRecord
Request to find and record a specified video item, given a set of search criteria. When a SearchAndRecord directive is successfully handled, respond with a SearchAndRecord.Response event.
User: Alexa, record the new episode of the Grand Tour next week.
Example: Record the new episode of The Grand Tour next week
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "endpoint-001",
"cookie": {}
},
},
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
"messageId": "708758c5-d1ca-4022-85ba-517f64b07a6c",
"name": "SearchAndRecord",
"namespace": "Alexa.VideoRecorder",
"payloadVersion": "3"
},
"payload": {
"entities": [
{
"externalIds": {
"gracenote": "MV000000000001"
},
"type": "Video",
"value": "The Grand Tour"
}
],
"quantifier": {
"name": "NEW"
},
"timeWindow": {
"end": "2017-09-07T23:59:00.00Z",
"start": "2017-09-01T00:00:00.00Z"
}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
entities |
An array of entity objects associated with this request | Array of entity objects | Yes |
quantifier |
A quantifier for the type of recording; whether to create a new recording, or to record the next or all occurrences of the items with the specified title. | Object | No |
quantifier.name |
The quantifier specified by the customer; possible values ALL, NEW, NEXT |
String, see Quantifier values | No |
timeWindow |
A time window object representing a time associated with this request | Object | No |
timeWindow.start |
The start time for the time window. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
timeWindow.end |
The end time for the time window. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
Additional example: Record PBS at 5:00 PM
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "endpoint-001",
"cookie": {}
},
},
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
"messageId": "1b391648-5346-4bf5-9444-6f14e749b4e3",
"name": "SearchAndRecord",
"namespace": "Alexa.VideoRecorder",
"payloadVersion": "3"
},
"payload": {
"entities": [
{
"entityMetadata": {
"channelCallSign": "KBTC",
"channelNumber": 123
},
"externalIds": {
"gracenote": "MV000000099001"
},
"type": "Channel",
"value": "PBS"
}
],
"timeWindow": {
"start": "2016-09-01T00:17:00.00Z"
}
}
}
}
CancelRecording
Request to cancel a scheduled recording for a specified title. This request should result in the cancellation of the specified recording, or a title that best matches the requested entity.
User: Alexa, stop recording title.
User: Alexa, cancel recording of next week's episode of The Grand Tour.
Example: Cancel recording of next week's episode of The Grand Tour
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "endpoint-001",
"cookie": {}
},
},
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
"messageId": "d4a5a7a6-a45a-4e3f-b55a-f583c822384b",
"name": "CancelRecording",
"namespace": "Alexa.VideoRecorder",
"payloadVersion": "3"
},
"payload": {
"entities": [
{
"externalIds": {
"gracenote": "MV000000000001"
},
"name": "The Grand Tour",
"type": "Video"
}
],
"timeWindow": {
"end": "2017-09-07T23:59:00+00:00",
"start": "2017-09-01T00:00:00+00:00"
}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
entities |
An array of entity objects associated with this request | Array of entity objects | Yes |
quantifier |
A quantifier for the cancellation request; whether it's the next item or all items. | Object | No |
quantifier.name |
Name of the quantifier such as the "next item" as specified by the customer. | String, see Quantifier values | No |
timeWindow |
A time window object representing a time associated with this request | Object | No |
timeWindow.start |
The start time for the time window. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
timeWindow.end |
The end time for the time window. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
DeleteRecording
Request to delete a recorded item. This request should result in the deletion of the specified title, or a title that best matches the requested entity.
User: Alexa, delete the recording of The Grand Tour.
Example: Delete the recording of The Grand Tour
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "endpoint-001",
"cookie": {}
},
},
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
"messageId": "97b8ce2a-87f6-4c89-9b28-00d716e337ff",
"name": "DeleteRecording",
"namespace": "Alexa.VideoRecorder",
"payloadVersion": "3"
},
"payload": {
"entities": [
{
"externalIds": {
"gracenote": "MV000000099001"
},
"name": "The Grand Tour",
"type": "TV_Show"
}
],
"quantifier": {
"name": "ALL"
},
"timeWindow": {
"end": "2016-09-07T23:59:00.00Z",
"start": "2016-09-01T00:00:00.00Z"
}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
entities |
An array of entity objects associated with this request | array of entity objects objects | Yes |
quantifier |
A quantifier for the deletion request; whether all or just the watched items should be deleted for the specified title. | Object | No |
quantifier.name |
Name of the quantifier specified by the customer. | String enumeration value, see Quantifier values | No |
timeWindow |
A time window object representing a time associated with this request | Object | No |
timeWindow.start |
The start time for the time window. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
timeWindow.end |
The end time for the time window. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
Quantifier name values
The following table describes the possible quantifier name values.
| Value | Description |
|---|---|
ALL |
All content matching the specified entity. |
NEXT |
The content that matches the entity that airs closest to time specified, or the closest after the time specified. |
NEW |
Any content airing for the first time that matched the specified entity. |
WATCHED |
All content matching the entity that has already been watched. |
Properties and Events
Reportable Properties
| Property Name | Type | Description |
|---|---|---|
isExtendedRecordingGUIShown |
boolean | Indicates the type of graphical user interface shown to the user. true to indicate an extended recording GUI is shown, false if the extended recording GUI isn't shown. |
storageLevel |
integer | The storage used on the recording device as a percentage. |
SearchAndRecord.Response
When a request to make a recording is successfully handled, you should respond with a SearchAndRecord.Response event. Specify the recording status in the payload of the message and the isExtendedRecordingGUIShown and storageLevel property values in the context of the message.
Example SearchAndRecord.Response
{
"context": {
"properties": [
{
"name": "isExtendedRecordingGUIShown",
"namespace": "Alexa.VideoRecorder",
"timeOfSample": "2017-5-6T16:20:50.52Z",
"uncertaintyInMilliseconds": 0,
"value": false
},
{
"name": "storageLevel",
"namespace": "Alexa.VideoRecorder",
"timeOfSample": "2017-5-6T16:20:50.52Z",
"uncertaintyInMilliseconds": 0,
"value": 75
}
]
},
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
"messageId": "aa6fd930-ce42-498d-a225-3fb94df83853",
"name": "Alexa.SearchAndRecordResponse",
"namespace": "Alexa.VideoRecorder",
"payloadVersion": "3"
},
"payload": {
"recordingStatus": "SCHEDULED"
}
}
}
| Field | Description | Type | Required |
|---|---|---|---|
recordingStatus |
A string enumeration value that indicates the status of the recording. | String. One of the following values: SCHEDULED, STARTED | Yes |
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason.
- For video-specific errors, see Video.ErrorResponse
- For general errors, such as authentication and connection problems, see Error.Response.
Related Interfaces
| Interface | Description |
|---|---|
| Alexa.RecordController | Defines directives to start or stop recording content. |
