Alexa.VideoRecorder Interface

The Alexa.VideoRecorder interface describes messages used to find and schedule a recording for a specified video item, to cancel a scheduled recording, or inquire about the recording space left on a DVR. To record the content that is currently playing, implement the Alexa.RecordController interface instead.

For the list of locales that are supported for the VideoRecorder interface, see List of Capability Interfaces and Supported Locales.

Directives

The directives for this interface each include an entity object that specifies the content to find and record. For more information, see Entity Types for Video Content.

SearchAndRecord

Request to find and record a specified video item, given a set of search criteria. When a SearchAndRecord directive is successfully handled, respond with a SearchAndRecord.Response event.

User: Alexa, record the new episode of the Grand Tour next week.

Example: Record the new episode of The Grand Tour next week

{
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
            "messageId": "708758c5-d1ca-4022-85ba-517f64b07a6c",
            "name": "SearchAndRecord",
            "namespace": "Alexa.VideoRecorder",
            "payloadVersion": "3"
        },
        "payload": {
            "entities": [
                {
                    "externalIds": {
                        "gracenote": "MV000000000001"
                    },
                    "type": "Video",
                    "value": "The Grand Tour"
                }
            ],
            "quantifier": {
                "name": "NEW"
            },
            "timeWindow": {
                "end": "2017-09-07T23:59:00.00Z",
                "start": "2017-09-01T00:00:00.00Z"
            }
        }
    }
}

Payload details

Field Description Type Required
entities An array of entity objects associated with this request Array of entity objects Yes
quantifier A quantifier for the type of recording; whether to create a new recording, or to record the next or all occurrences of the items with the specified title. Object No
quantifier.name The quantifier specified by the customer; possible values ALL, NEW, NEXT String, see Quantifier values No
timeWindow A time window object representing a time associated with this request Object No
timeWindow.start The start time for the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No
timeWindow.end The end time for the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No

Additional example: Record PBS at 5:00 PM

{
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
            "messageId": "1b391648-5346-4bf5-9444-6f14e749b4e3",
            "name": "SearchAndRecord",
            "namespace": "Alexa.VideoRecorder",
            "payloadVersion": "3"
        },
        "payload": {
            "entities": [
                {
                    "entityMetadata": {
                        "channelCallSign": "KBTC",
                        "channelNumber": 123
                    },
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    },
                    "type": "Channel",
                    "value": "PBS"
                }
            ],
            "timeWindow": {
                "start": "2016-09-01T00:17:00.00Z"
            }
        }
    }
}

CancelRecording

Request to cancel a scheduled recording for a specified title. This request should result in the cancellation of the specified recording, or a title that best matches the requested entity.

User: Alexa, stop recording title.

User: Alexa, cancel recording of next week's episode of The Grand Tour.

Example: Cancel recording of next week's episode of The Grand Tour


{
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
            "messageId": "d4a5a7a6-a45a-4e3f-b55a-f583c822384b",
            "name": "CancelRecording",
            "namespace": "Alexa.VideoRecorder",
            "payloadVersion": "3"
        },
        "payload": {
            "entities": [
                {
                    "externalIds": {
                        "gracenote": "MV000000000001"
                    },
                    "name": "The Grand Tour",
                    "type": "Video"
                }
            ],
            "timeWindow": {
                "end": "2017-09-07T23:59:00+00:00",
                "start": "2017-09-01T00:00:00+00:00"
            }
        }
    }
}

Payload details

Field Description Type Required
entities An array of entity objects associated with this request Array of entity objects Yes
quantifier A quantifier for the cancellation request; whether it's the next item or all items. Object No
quantifier.name Name of the quantifier such as the "next item" as specified by the customer. String, see Quantifier values No
timeWindow A time window object representing a time associated with this request Object No
timeWindow.start The start time for the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No
timeWindow.end The end time for the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No

DeleteRecording

Request to delete a recorded item. This request should result in the deletion of the specified title, or a title that best matches the requested entity.

User: Alexa, delete the recording of The Grand Tour.

Example: Delete the recording of The Grand Tour

{
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
            "messageId": "97b8ce2a-87f6-4c89-9b28-00d716e337ff",
            "name": "DeleteRecording",
            "namespace": "Alexa.VideoRecorder",
            "payloadVersion": "3"
        },
        "payload": {
            "entities": [
                {
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    },
                    "name": "The Grand Tour",
                    "type": "TV_Show"
                }
            ],
            "quantifier": {
                "name": "ALL"
            },
            "timeWindow": {
                "end": "2016-09-07T23:59:00.00Z",
                "start": "2016-09-01T00:00:00.00Z"
            }
        }
    }
}

Payload details

Field Description Type Required
entities An array of entity objects associated with this request array of entity objects objects Yes
quantifier A quantifier for the deletion request; whether all or just the watched items should be deleted for the specified title. Object No
quantifier.name Name of the quantifier specified by the customer. String enumeration value, see Quantifier values No
timeWindow A time window object representing a time associated with this request Object No
timeWindow.start The start time for the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No
timeWindow.end The end time for the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. No

Quantifier name values

The following table describes the possible quantifier name values.

Value Description
ALL All content matching the specified entity.
NEXT The content that matches the entity that airs closest to time specified, or the closest after the time specified.
NEW Any content airing for the first time that matched the specified entity.
WATCHED All content matching the entity that has already been watched.

Properties and Events

Reportable Properties

Property Name Type Description
isExtendedRecordingGUIShown boolean Indicates the type of graphical user interface shown to the user. true to indicate an extended recording GUI is shown, false if the extended recording GUI isn't shown.
storageLevel integer The storage used on the recording device as a percentage.

SearchAndRecord.Response

When a request to make a recording is successfully handled, you should respond with a SearchAndRecord.Response event. Specify the recording status in the payload of the message and the isExtendedRecordingGUIShown and storageLevel property values in the context of the message.

Example SearchAndRecord.Response

{
    "context": {
        "properties": [
            {
                "name": "isExtendedRecordingGUIShown",
                "namespace": "Alexa.VideoRecorder",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": false
            },
            {
                "name": "storageLevel",
                "namespace": "Alexa.VideoRecorder",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": 75
            }
        ]
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LdjCc8ptlAKulUj90jSqg==",
            "messageId": "aa6fd930-ce42-498d-a225-3fb94df83853",
            "name": "Alexa.SearchAndRecordResponse",
            "namespace": "Alexa.VideoRecorder",
            "payloadVersion": "3"
        },
        "payload": {
            "recordingStatus": "SCHEDULED"
        }
    }
}
Field Description Type Required
recordingStatus A string enumeration value that indicates the status of the recording. String. One of the following values: SCHEDULED, STARTED Yes

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason.

Interface Description
Alexa.RecordController Defines directives to start or stop recording content.