Alexa.RemoteVideoPlayer Interface
Implement the Alexa.RemoteVideoPlayer interface in your Alexa skill so that users can request Alexa to search and play video content.
For the list of languages that the Alexa.RemoteVideoPlayer interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
The Alexa.RemoteVideoPlayer 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, watch title.
Alexa, play title.
Alexa, stream title.
Alexa, start title.
Alexa, show me the movie Star Wars: Return of the Jedi on Prime Video.
Alexa, titel anschauen.
Alexa, titel abspielen.
Alexa, titel streamen.
Alexa, titel starten.
Alexa, zeige mir den Film Star Wars: Return of the Jedi auf Prime Video.
Handle search requests
The Alexa.RemoteVideoPlayer interface includes directives to search for video content. The directives might include multiple entity types. For example, the customer might say, "Alexa, play title by director." and the resulting directive includes the content title in the Video entity object and the director's name in the Director entity object.
Entities rely on resolved catalog values. You might have specialized catalogs about specific entity types, such as movie catalog or genre catalog, or a data model that facilitates structured queries.
Even with the included entities, the request could be ambiguous. For example, the customer might say, "Alexa, play a popular comedy" and the resulting directive contains only the Genre entity object. Despite ambiguity, you decide how to act on a request. For example, you might:
- Play a popular comedy
- Generate a list of the top 10 comedies and randomly select one for the customer
- Display search results for the ambiguous entity
You choose how to respond. However, Amazon recommends that you accommodate a customer's play request if possible.
Along with entity types, the search directive might contain searchText to represent a transcribed version of the user’s search query. This version doesn't contain action verbs. For example, the utterance, "Alexa, find content provider movies," returns the search text, content provider movies. The utterance, "Alexa, find comedies on content provider," returns the search text, content provider comedies. Use searchText if you want to focus on keyword searches.
The transcribed searchText has the following limitations:
- There's no word order guarantee in the transcribed text.
- The content of transcribed text might change over time or by directive. For example, the same request might return
top ten comediesortop 10 comedies.
searchText as a fallback for other values in the search payload. The searchText field is optional, and might not appear in the directive you receive. Your implementation must return a response even if the directive contains no searchText value. Performance requirements for search
The following table shows the latency limits for search responses by call percentage.
| Call percentage | Latency limit in milliseconds (ms) |
|---|---|
|
50 percent |
50 ms |
|
90 percent |
100 ms |
|
99 percent |
200 ms |
Reportable properties
The Alexa.RemoteVideoPlayer interface doesn't have any reportable properties.
Discovery
You describe endpoints that support Alexa.RemoteVideoPlayer by using the standard discovery mechanism described in Alexa.Discovery.
The Alexa.RemoteVideoPlayer interface doesn't have any reportable properties. Set retrievable and 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 television that supports the Alexa.RemoteVideoPlayer, Alexa.PlaybackStateReporter, Alexa.PowerController, and Alexa.EndpointHealth interfaces
{
"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.RemoteVideoPlayer",
"version": "3",
"properties": {}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackStateReporter",
"version": "1.0",
"properties": {
"supported": [{
"name": "playbackState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [{
"name": "powerState"
}],
"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.
AddOrUpdateReport example
The following example shows a AddOrUpdateReport message for a new endpoint.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the new 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.RemoteVideoPlayer",
"version": "3",
"properties": {}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackStateReporter",
"version": "1.0",
"properties": {
"supported": [{
"name": "playbackState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [{
"name": "powerState"
}],
"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"
}
]
}],
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
}
}
}
}
Directives
SearchAndPlay directive
Support the SearchAndPlay directive so that users can request to play specific video content. The payload contains an array of entities that specifies what to search for.
SearchAndPlay directive example
The following example shows a request for specific video content from 2017-2018.
{
"directive": {
"header": {
"namespace": "Alexa.RemoteVideoPlayer",
"name": "SearchAndPlay",
"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": {
"gracenote": "MV000000099001"
},
"value": "Title of movie",
"type": "Video"
}],
"timeWindow": {
"end": "2018-09-01T16:20:50.52Z",
"start": "2017-09-01T16:20:50.52Z"
}
}
}
}
SearchAndPlay directive payload
The following table shows the payload details for the SearchAndPlay directive.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
User-requested search terms. |
Array of |
Yes |
|
|
Specifies the text version of the user's utterance after natural language understanding (NLU) processing. |
Object |
No |
|
|
Transcribed version of the user's search query. |
String |
No |
|
|
Specifies the span of time over which to search. |
Object |
No |
|
|
The start time for the content search. |
String |
No |
|
|
The end time for the content search. |
String |
No |
SearchAndPlay response
If you handle a SearchAndPlay directive successfully, respond with an Alexa.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 SearchAndPlay response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "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.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PLAYING"
},
"timeOfSample": "2021-12-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2021-12-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-26T16: 20: 50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SearchAndPlay error handling
If you can't handle a SearchAndPlay 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.
SearchAndDisplayResults directive
Support the SearchAndDisplayResults directive so that users can search for video content. The payload contains an array of entities that specifies what to search for.
You display the results in a way that's appropriate for your skill. For example, you might provide the user with a side-loaded search screen, send the results to a companion mobile app, or display the search results on a device.
SearchAndDisplayResults directive example
The following example shows a request for specific video content from 2017-2018.
{
"directive": {
"header": {
"namespace": "Alexa.RemoteVideoPlayer",
"name": "SearchAndDisplayResults",
"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": {
"gracenote": "MV000000099001"
},
"value": "Title of movie",
"type": "Video"
},
{
"externalIds": {
"ENTITY_ID": "amzn1.alexa-ask-target.app.72095"
},
"name": "Prime Video",
"type": "App"
}
],
"timeWindow": {
"end": "2018-09-01T16:00:00.00Z",
"start": "2017-09-01T16:00:00.00Z"
}
}
}
}
SearchAndDisplayResults directive payload
The SearchAndDisplayResults directive contains the same payload parameters as the SearchAndPlayResults directive.
SearchAndDisplayResults response
If you handle a SearchAndDisplayResults directive successfully, respond with an Alexa.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 SearchAndDisplayResults response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "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.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "STOPPED"
},
"timeOfSample": "2021-12-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2021-12-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-26T16: 20: 50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SearchAndDisplayResults error handling
If you can't handle a SearchAndDisplayResults 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.
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.RemoteVideoPlayer 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.