Alexa.VideoRecorder Interface

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

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:

title اليكسا، سجل
title اليكسا، سجل الحلقة التالية من
title اليكسا، تسجيل حلقات جديدة من
title اليكسا، ألغي تسجيل
title اليكسا، احذف تسجيل

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. Format as `int32`.	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.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": "Unique identifier, preferably a 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`	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

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 identifier, preferably a 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 identifier, preferably a 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.

Alexa.VideoRecorder Interface

Utterances

Reportable properties

Discovery

Discover response example

Proactive Discovery with AddOrUpdateReport

Directives

SearchAndRecord

SearchAndRecord directive example

SearchAndRecord directive payload

Quantifier name values

SearchAndRecord response

SearchAndRecord response payload

SearchAndRecord error handling

CancelRecording

CancelRecording directive example

CancelRecording directive payload

CancelRecording response

CancelRecording error handling

DeleteRecording directive

DeleteRecording directive example

DeleteRecording directive payload

DeleteRecording response

DeleteRecording error handling

State reporting

StateReport response example

Change reporting

Related topics