Alexa.RemoteVideoPlayer Interface
The Alexa.RemoteVideoPlayer
interface describes messages that are used to search and play video content.
For the list of locales that are supported for the RemoteVideoPlayer
interface, see List of Capability Interfaces and Supported Locales.
Directives
SearchAndPlay
Requests to play a specific piece of content. This message contains the desired media object and URI obtained described as an entity. This message contains an array of entities that specifies what to search and play.
User: Alexa, watch title
User: Alexa, titel anschauen
User: Alexa, play title
User: Alexa, titel abspielen
User: Alexa, stream title
User: Alexa, titel streamen
User: Alexa, start title
User: Alexa, titel starten
Example Request
This example shows a request for a specific piece of content, "Manchester by the Sea"
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "videoDevice-001",
"cookie": {
}
},
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"name": "SearchAndPlay",
"namespace": "Alexa.RemoteVideoPlayer",
"payloadVersion": "3"
},
"payload": {
"entities": [{
"externalIds": {
"gracenote": "MV000000099001"
},
"value": "Manchester by the Sea",
"type": "Video"
}],
"timeWindow": {
"end": "2016-09-07T23:59:00+00:00",
"start": "2016-09-01T00:00:00+00:00"
}
}
}
}
Payload description
Property | Description | Type | Required |
---|---|---|---|
entities |
An array of entity objects to play | array of Entity objects such as an App, Title, Franchise, Actor, Team or Media Type. For more information, see the entity type descriptions. | Yes |
timeWindow |
Provides the time window for the content the customer wants to play | list of end and start times | Yes |
timeWindow.end |
The end time for the content search. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
timeWindow.start |
The start time for the content search. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
SearchAndDisplayResults
Requests to search and then display the results of a search in a way that is appropriate for your application. This means that you could provide the user with a side-loaded search screen, send the results to a companion mobile app, or display them on a device. This message contains an array of entities that specifies what to search for and, optionally, the target app.
User: Alexa, show me the movie Manchester by the Sea on Prime Video
User: Alexa, zeige mir den Film Manchester by the Sea auf Prime Video
Example Request:
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001",
"cookie": {}
},
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"name": "SearchAndDisplayResults",
"namespace": "Alexa.RemoteVideoPlayer",
"payloadVersion": "3"
},
"payload": {
"entities": [
{
"externalIds": {
"gracenote": "ST0000000666661"
},
"name": "Manchester by the Sea",
"type": "Video"
},
{
"externalIds": {
"ENTITY_ID": "amzn1.alexa-ask-target.app.72095"
},
"name": "Prime Video",
"type": "App"
}
],
"timeWindow": {
"end": "2016-09-07T23:59:00+00:00",
"start": "2016-09-01T00:00:00+00:00"
}
}
}
}
Payload description
Property | Description | Type | Required |
---|---|---|---|
entities |
An array of entity objects to play | array of Entity objects such as an App, Title, Franchise, Actor, Team or Media Type. For more information, see the entity type descriptions. | Yes |
timeWindow |
Provides the time window for the content the customer wants to play. For example if a customer wants to play an episode from last week, time window would indicate the preceding week. | list of end time and a start times | No |
timeWindow.end |
The end time for the content search. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
timeWindow.start |
The start time for the content search. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | No |
Handling Ambiguous Play Requests
Similar to SearchAndDisplayResults
, SearchAndPlay
supports multiple entity types, including a content title, franchise name, actor, director, sports team, media type and more. This means one of these directives may contain an ambiguous entity request.
For example, a customer could request:
User: Alexa, play a popular comedy
User: Alexa, spiele eine beliebte Komödie ab
-or-
User: Alexa, play a Billy Bob Thornton movie
User: Alexa, spiele einen film mit Billy Bob Thornton
The Video Skill API is flexible in that, despite ambiguity, you can decide how to act on a request. For example, you can:
- Begin playing a popular comedy or Bob Thornton movie
- Generate a list of the top 10 comedies or Bob Thornton movies and randomly select one for the customer to avoid repetition
- Go straight to search results for that ambiguous entity
You can choose how to respond, however, it's recommended that you accommodate a customer's play request if at all possible.
The searchText
Object
Alexa video skill directives use the searchText
object to represent a transcribed version of the user’s search query as a string value in the transcribed
field. Here is how this might look like as part of a directive for search query "Alexa, play popular comedy tv shows in HD":
{
"searchText": {
"transcribed": "h.d. popular comedy tv shows"
}
}
Based on the user's utterance, searchText
can include content provider names. Here are some examples:
- Utterance "find content provider movies" returns
transcribed
value "content provider movies" - Utterance "find comedies on content provider" returns
transcribed
value "content provider comedies"
Using searchText
The searchText
object represents the customer search request. In the searchText
object, the transcribed
value is a string that represents the customer intent, for example a stripped-down version of what the customer said.
The searchText
object has the following limitations:
There is no word order guarantee.
For the same utterance, searchText
might return the transcribed
values with different order, such as:
- "h. d. korean war documentary movies"
- "korean war documentary h. d. movies"
The content of searchText
might change over time or by directive.
For the same utterance, searchText
might return different transcribed
values at different points in time, such as:
- "top ten comedies"
- "top 10 comedies"
searchText
only 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. Recommendations on Entities and searchText
Entities rely on resolved catalog values. Use them if you have specialized catalogs pertaining to specific values, such as Movie catalog, Genre catalog, and so on, or if you have some form of data model that facilitates structured queries.
Use searchText
if you want to focus on key word searches (for example, a full text search).
Alexa.Response Event
When a SearchAndPlay
or SearchAndDisplayResults
directive successfully completes, you should respond with an Alexa.Response
message.
Successful Response Example
{
"context": {
"properties": []
},
"event": {
"endpoint": {
"scope": {
"type": "DirectedUserId",
"directedUserId": "access-token-from-Amazon"
},
"endpointId": "videoDevice-001"
},
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"name": "Response",
"namespace": "Alexa",
"payloadVersion": "3"
},
"payload": {}
}
}
Payload description
No payload content required
Response Performance Requirements
The table describes the latency limits for search and play request responses by call percentage.
Call Percentage | Latency Limit (in milliseconds) |
---|---|
50% | 50 ms |
90% | 100 ms |
99% | 200 ms |
See the Testing Guide for more details.
Related Interfaces
Interface | Description |
---|---|
Alexa.PlaybackController | Provides directives for playing and moving around in a set of content; rewinding, fast forwarding and more. |