Alexa.VideoRecorder Interface (VSK Fire TV)

When users say utterances to manage recordings (e.g., "Alexa, record new episode"), the Alexa.VideoRecorder interface sends SearchAndRecord, CancelRecording, and DeleteRecording directives to your Lambda. These directives are used to record scheduled content and manage recordings. They should only be implemented if your app can schedule recordings.

For start-and-stop recording directives, see Alexa.RecordController Directives. Note that directives sent by the VideoRecorder interface are available only for Fire TV, not for multimodal devices.

Utterances for VideoRecorder Directives
SearchAndRecord Directives
CancelRecording Directive
- Quantifier Name Values
DeleteRecording Directive
Payload Details
- Quantifier Name Values
- Reportable Properties
SearchAndRecord Response
Declaring Capability Support for this Interface
Error Response

Utterances for VideoRecorder Directives

Alexa sends a directives from the VideoRecorder interface (SearchAndRecord, CancelRecording, and DeleteRecording) to your Lambda when users say the following utterances.

Feature	Sample Utterances	Expected Response
Record next episode of title	Record next episode of breaking bad Nimm die nächste Folge von <title> auf Nimm die nächste Episode von <title> auf enregistres le prochain épisode de breaking bad enregistres le prochain épisode de breaking bad enregistres la prochaine épisode de breaking bad registra il prossimo episodio di breaking bad <House, The Office, Sneaky Pete> graba el próximo episodio de breaking bad graba el próximo episodio de breaking bad {title}の次のエピソードを録画して {title}の次のエピソードを撮って gravar o próximo episódio de {title} grave o próximo episódio de {title} record {title} next episode record next episode of {title}	The next episode of requested media title is set to be recorded.
Record new episode of title	Record new episode of breaking bad Nimm die neue Episode von <title> auf Nimm die neue Folge von <title> auf enregistres le nouvel épisode de breaking bad enregistres le dernier épisode de breaking bad enregistres le nouvel épisode de breaking bad enregistres la nouvelle épisode de breaking bad registra il nuovo episodio di breaking bad <House, The Office, Sneaky Pete> graba el episodio nuevo de breaking bad graba el episodio nuevo de breaking bad {title}の新しいエピソードを録画して {title}の新しいエピソードを撮って gravar o novo episódio de {title} grave o novo episódio de {title} record {title} new episode record new episode of {title}	New episodes of the requested media title are set to be recorded.
Record network name	Record fox channel Nimm <network name> auf <Network name> aufnehmen enregistres fox enregistres la chaîne fox enregistres radio canada enregistres le poste de radio canada registra il canale Fox graba el canal fox graba el canal fox {network name}を録画して {network name}を撮って gravar {network name} grave {network name} record {network name} channel record {network name}	The network name is set to be recorded.
Record sports team	Record seattle seahawks Nimm das Spiel/die Partie von <sports team> auf Nimm <sports team> auf enregistres les bleus enregistres le match des bleus enregistres les canadiens enregistres le match des canadiens registra la juventus graba al Madrid graba a/al/a la/a las/a los {sports team} graba al América graba a/al/a la/a las/a los {sports team} {sports team}を録画して {sports team}を撮って gravar {sports team} grave {sports team} record {sports team} {sports team} record करो	Either currently playing or upcoming content for the requested sports team is set to be recorded.
Cancel recording of <title>	Cancel recording of breaking bad Brich die Aufnahme von <title> ab Aufnahme von <title> abbrechen Aannules l' enregistrement de breaking bad l' épisode has to always be transcribed as such with a space annules l' enregistrement de breaking bad cancelles l' enregistrement de breaking bad cancella la registrazione di breaking bad <House, The Office, Sneaky Pete> cancela la grabación de breaking bad cancela la grabación de breaking bad {title} の録画キャンセル {title} の録画をキャンセルして cancele a gravação de {title} cancelar a gravação de {title} {title} की recording cancel कर दो {title} वाली recording cancel कर दो	Recording for the title is canceled.
Delete recording of <title>	Delete recording of breaking bad Lösche die Aufnahme von <title> Aufnahme von <title> löschen supprimes l' enregistrement de breaking bad effaces l' enregistrement de breaking bad supprimes l' enregistrement de breaking bad effaces l' enregistrement de breaking bad elimina la registrazione di breaking bad <House, The Office, Sneaky Pete> borra la grabación de breaking bad borra la grabación de breaking bad {title} の録画を消して {title} の録画を削除して delete a gravação de {title} deletar a gravação de {title} {title} की recording delete कर दो {title} वाली recording delete कर दो	Recording for the title is deleted.

SearchAndRecord Directives

SearchAndRecord directives are used 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.

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 Directive

CancelRecording directives are used 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

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.

DeleteRecording Directive

DeleteRecording directives are sent to your Lambda when a user asks to delete a recorded item. This directive 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.

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-5-6T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": false
            },
            {
                "name": "storageLevel",
                "namespace": "Alexa.VideoRecorder",
                "timeOfSample": "2017-5-6T16: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

Declaring Capability Support for this Interface

To indicate that your video skill supports the Alexa.VideoRecorder interface, you must indicate support for it in your response to the Discover directive sent through the Alexa.Discovery interface. More details are provided in Alexa.Discovery.

Error Response

If you cannot complete the customer request for some reason, reply with an error. See Error Handling for more details.