Alexa.VideoRecorder Interface 3
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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
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 title/channel.
Alexa, record next episode of title.
Alexa, record new episode of title.
Alexa, cancel recording of title.
Alexa, delete the recording of title.
Alexa, titel aufnehmen.
Alexa, nimm die nächsten folgen von titel auf.
Alexa, nimm die nächsten folgen von titel auf.
Alexa, brich die titel aufnahme ab.
Alexa, lösch titel.
Alexa, graba titulo.
Alexa, graba el proximo capitulo del titulo.
Alexa, graba los capítulos nuevos del titulo.
Alexa, cancela la grabación del titulo.
Alexa, borra titulo.
Alexa, enregistre titre.
Alexa, enregistre le prochain épisode du titre.
Alexa, enregistre le nouvel épisode de titre.
Alexa, annule l'enregistrement de titre.
Alexa, supprime l'enregistrement de titre.
Alexa, title record करो/करना/कीजिए
Alexa, title का अगला episode record करो/करना/कीजिए
Alexa, record करो/करना/कीजिए title का नया episode
Alexa, title का recording रद्द करना/कीजिए/करो
Alexa, title का recording हटा दो/निकाल देना/delete कर देना
Alexa, registra titolo.
Alexa, registra il prossimo episodio del titolo.
Alexa, registra il nuovo episodio di titolo.
Alexa, annulla la registrazione di titolo.
Alexa, elimina la registrazione di titolo.
Alexa, gravar título.
Alexa, gravar próximo episódio do título.
Alexa, gravar novos episódios de título.
Alexa, cancelar gravação de título.
Alexa, deletar gravação de título.
アレクサ、title を録画して
アレクサ、title の次のエピソードを録画して
アレクサ、title の新しいエピソードを録画
アレクサ、北斗の拳の録画をキャンセル
アレクサ、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": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Living Room TV",
"displayCategories": ["TV"],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "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
Alexa sends the following Alexa.VideoRecorder interface directives to your skill.
The directives include an entity object that specifies the requested content. For details, see Entity Types for Video Content.
SearchAndRecord directive
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": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 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": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "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 and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic Alexa.ErrorResponse event.
CancelRecording directive
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": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 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": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "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 and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic Alexa.ErrorResponse event.
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": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 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": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "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 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": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "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.