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 user says one of the following utterances, Alexa sends a corresponding directive to your skill.

The following examples show some user 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

isExtendedRecordingGUIShown

Indicates the type of graphical user interface shown to the user.
Set to true to indicate that your recording device displays an extended recording GUI. Otherwise, set to false.

Boolean

storageLevel

Indicates the percentage of storage used on the recording device.
Valid values: 0–100.

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.

Copied to clipboard.

{
    "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.1",
                        "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

entities

User-requested search terms.

Array of Entity objects

Yes

quantifier

Specifies the type of recording to create.

Object

No

quantifier.name

Recording type specified by the user. For details, see Quantifier name values.
Valid values: ALL, NEW, NEXT, WATCHED.

  • ALL – All content that matches the specified entity.
  • NEXT – Content that matches the specified entity and airs closest to the time specified or closest after the specified time.
  • NEW – Content that airs for the first time and matches the specified entity.
  • WATCHED – All watched content that matches the specified entity.

String

No

timeWindow

Specifies the span of time over which to search.

Object

No

timeWindow.start

The start time for the content search.
Formatted as a UTC string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

timeWindow.end

The end time for the content search.
Formatted as a UTC string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

Quantifier name values

The following table shows the possible quantifier names.

Name Description

ALL

All content that matches the specified entity.

NEXT

Content that matches the specified entity and airs closest to the time specified or closest after the specified time.

NEW

Content that airs for the first time and matches the specified entity.

WATCHED

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.

Copied to clipboard.

{
    "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

recordingStatus

Indicates the status of the recording.
Valid values: SCHEDULED, STARTED

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.

Copied to clipboard.

{
    "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.

Copied to clipboard.

{
    "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

Copied to clipboard.

{
  "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.


Was this page helpful?

Last updated: Jan 16, 2024