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:

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.

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

{
    "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:00.00Z",
                "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.

{
    "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:00.00Z",
                "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:00.00Z",
                "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:00.00Z",
              "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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Reportable properties

Discovery

Discover response example

Proactive Discovery with AddOrUpdateReport

Directives

SearchAndRecord directive

SearchAndRecord directive example

SearchAndRecord directive payload

Quantifier name values

SearchAndRecord response

SearchAndRecord response payload

SearchAndRecord error handling

CancelRecording directive

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

​Utterances

​Reportable properties

​Discovery

​Discover response example

​Proactive Discovery with AddOrUpdateReport

​Directives

​SearchAndRecord directive

​SearchAndRecord directive example

​SearchAndRecord directive payload

Quantifier name values

​SearchAndRecord response

​SearchAndRecord response payload

​SearchAndRecord error handling

​CancelRecording directive

​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

Utterances

Reportable properties

Discovery

Discover response example

Proactive Discovery with AddOrUpdateReport

Directives

SearchAndRecord directive

SearchAndRecord directive example

SearchAndRecord directive payload

SearchAndRecord response

SearchAndRecord response payload

SearchAndRecord error handling

CancelRecording directive

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