Alexa.VideoRecorder Interface

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.

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 the new episode of title next week.
Alexa, record PBS at five o'clock pm.
Alexa, stop recording title.
Alexa, cancel recording of next week's episode of title.
Alexa, delete the recording of 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": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "the manufacturer name of the endpoint",
                "description": "a description that is shown in the Alexa app",
                "friendlyName": "Living Room TV",
                "displayCategories": ["TV"],
                "additionalAttributes": {
                    "manufacturer": "the manufacturer name of the endpoint",
                    "model": "the model of the device",
                    "serialNumber": "the serial number of the device",
                    "firmwareVersion": "the firmware version of the device",
                    "softwareVersion": "the 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": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an 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, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.

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": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an 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, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.

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": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an 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, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.

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": "a unique identifier, preferably a version 4 UUID",
      "correlationToken": "an 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.