Alexa.VideoRecorder
The VideoRecorder interface describes messages used to find and schedule a recording for a specified video item, to cancel a recording, or inquire about the recording space left on a DVR. To support recording the currently playing content, see Alexa.RecordController.
Directives
The control and query directives in this interface are supported in skills that target the following languages:
- English (UK)
- English (US)
See Develop Smart Home Skills in Multiple Languages for more information.
The directives for this interface all include a entity that specifies the content to find and record.
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 specified in RFC 3399 variant of ISO 8601 | String | No |
timeWindow.end |
The end time for the time window specified in RFC 3399 variant of ISO 8601 | String | 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 specified in RFC 3399 variant of ISO 8601 | String | No |
timeWindow.end |
The end time for the time window specified in RFC 3399 variant of ISO 8601 | String | 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 specified in RFC 3399 variant of ISO 8601 | String | No |
timeWindow.end |
The end time for the time window specified in RFC 3399 variant of ISO 8601 | String | 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. |