Alexa.RemoteVideoPlayer Interface 3.1
Implement the Alexa.RemoteVideoPlayer
interface in your Alexa skill so that users can request Alexa to search and play video content. You can identify the public and private catalogs that your skill supports in the discovery response.
For the list of languages that the Alexa.RemoteVideoPlayer
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Alexa.RemoteVideoPlayer
version 3.1. If you build an Alexa skill, you can use Alexa.RemoteVideoPlayer
version 3 and identify your catalog in your skill manifest, or you can use Alexa.RemoteVideoPlayer
version 3.1.Utterances
The Alexa.RemoteVideoPlayer
interface uses the pre-built voice interaction model. After the user says one of the following utterances, Alexa sends a corresponding directive to your skill.
The following examples show some user utterances:
أليكسا، شغّلي لعبة نيوتن
أليكسا، أبي أشوف كوميديا
أليكسا، شغّلي أحمد حلمي
أليكسا، أبي أشوف فيلم
أليكسا، شغّلي خواطر الموسم التاني
أليكسا، حطّي الحلقة الخامسة من البحث عن علا
أليكسا، شغّلي حكايات بنات الموسم الثاني الحلقة الرابعة
أليكسا، شغّلي ستار وورز
أليكسا، ابحثي عن طاش ما طاش
أليكسا، ابحثي عن يسرا
أليكسا، دوري ديزني
أليكسا، ابحثي عن الدوري السعودي
أليكسا، ابحثي عن مباراة الهلال
أليكسا، ابحثي عن الدوري الإماراتي
أليكسا، ابحثي عن كرة الطائرة
Alexa, watch title.
Alexa, watch comedy.
Alexa, watch Sean Connery.
Alexa, watch a movie.
Alexa, watch title season two.
Alexa, watch title episode five.
Alexa, watch title season two episode five.
Alexa, watch Star Wars.
Alexa, search for James Bond.
Alexa, search for Quentin Tarantino.
Alexa, search for Disney.
Alexa, search Seahawks.
Alexa, search for soccer.
Alexa, search for N B A league.
Alexa, search for the soccer.
Alexa, spiel titel.
Alexa, spiel komödien.
Alexa, spiel einen film mit Tom Cruise.
Alexa, spiel einen film.
Alexa, spiel titel staffel zwei.
Alexa, spiel titel folge zwei.
Alexa, spiel titel staffel zwei folge zwei.
Alexa, such nach Quentin Tarantino filmen.
Alexa, such nach Pixar filmen.
Alexa, such nach bayern münchen.
Alexa, such nach fußball.
Alexa, such fußball spiele.
Alexa, pon titulo.
Alexa, pon comedias.
Alexa, pon Julia Roberts.
Alexa, pon la película.
Alexa, empieza la segunda temporada de los rompecorazones.
Alexa, pon paquita salas episodio dos.
Alexa, pon el segundo episodio de la primera temporada de anabel.
Alexa, busca las películas de Alejandro Lozano.
Alexa, busca películas de Disney.
Alexa, busca real Madrid.
Alexa, enséña nos un vídeo de fútbol.
Alexa, busca el partido de la N B A.
Alexa, busca el partido de fútbol.
Alexa, pars/mets titre.
Alexa, mets un dessin animé.
Alexa, mets un film avec Tom Cruise.
Alexa, pars/mets un film.
Alexa, pars/mets titre saison deux.
Alexa, pars/mets l'épisode deux de titre.
Alexa, mets l'épisode deux de la saison de titre.
Alexa, cherche un film de Quentin Tarantino.
Alexa, cherche des films de Disney.
Alexa, cherche la premier league.
Alexa, title चलाओ
Alexa, comedy movie चलाओ
Alexa, सलमान खान के movies को चलाओ
Alexa, movies चलाओ
Alexa, title का season one चलाओ
Alexa, title का episode one चलाओ
Alexa, title का season one का episode one चलाओ
Alexa, Disney search करना
Alexa, Chelsea खोजो
Alexa, football खोजो
Alexa, metti titolo.
Alexa, metti cartoni.
Alexa, metti un film con Tom Cruise.
Alexa, metti un fim.
Alexa, metti titolo stagione due.
Alexa, metti titolo episodio cinque.
Alexa, metti titolo stagione due episodio cinque.
Alexa, cerca Quentin Tarantino.
Alexa, cerca dei film della Disney.
Alexa, cerca juventus.
Alexa, cerca calcio.
Alexa, assistir título.
Alexa, assistir comédias.
Alexa, coloque filmes com Brad Pitt.
Alexa, assistir um filme.
Alexa, assistir título temporada dois.
Alexa, assistir título episódio um.
Alexa, assistir titulo episódio um temporada um.
Alexa, procurar Disney.
Alexa, procurar Toronto Raptors.
Alexa, procurar por basquetebol.
Alexa, procurar por N B A.
アレクサ、キルラキルを見せて
アレクサ、お笑いを見せて
アレクサ、三池崇史の映画を見せて
アレクサ、映画を再生して
アレクサ、家政婦は見たのシーズン二を流して
アレクサ、家政婦は見たの第二話を再生
アレクサ、家政婦は見たの第二シーズン第二話を流して
アレクサ、三谷幸喜を検索して
アレクサ、ディズニーを検索
アレクサ、セレッソ大阪のプレーオフを探して
アレクサ、サッカーの試合を見つけて
アレクサ、ナデシコリーグトーナメントを探して
Handle search criteria
When a user requests Alexa to search and display or search and play video content, Alexa sends the search criteria to your skill. The Alexa.RemoteVideoPlayer
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 might 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 (
SearchAndPlay
directive) - Generate a list of the top 10 comedies and randomly select one for the customer (
SearchAndPlay
directive) - Display search results for the ambiguous entity (
SearchAndDisplayResults
directive)
You choose how to respond. However, Amazon recommends that you accommodate a customer's 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 comedies
ortop 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.
Configurations object
In addition to the usual discovery response fields, for Alexa.RemoteVideoPlayer
, include a configurations
object that contains the following fields. The configurations
object is required.
Property | Description | Type | Required |
---|---|---|---|
|
Identifies the directives that your skill supports. If you don't include this property, Alexa assumes that your skill supports all directives. |
Array of strings |
No |
|
Identifies the entity types that your skill supports. If you don't include this property, Alexa assumes that your skill supports all entity types. |
Array of string |
No |
|
Identifies the public and private catalogs that your skill supports. You can report different catalogs per endpoint and customer. |
Array of Catalog objects |
Yes |
|
Type of catalog. |
String |
Yes |
|
Uniquely identifies the catalog. |
String |
Yes |
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. In this example, the endpoint supports searching for content with MediaType
, League
, Sport
, and SportsTeam
entity types in the IMDb public catalog and the ABCDE private catalog.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Living Room TV",
"displayCategories": ["TV"],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "Software version of the device"
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.RemoteVideoPlayer",
"version": "3.1",
"properties": {},
"configurations": {
"operations": ["SearchAndPlay"],
"entityTypes": ["MediaType", "League", "Sport", "SportsTeam"],
"catalogs": [{
"type": "VIDEO_INGESTION_IDENTIFIER",
"sourceId": "ABCDE"
},
{
"type": "VIDEO_PUBLIC_CATALOG_IDENTIFIER",
"sourceId": "imdb"
}
]
}
},
{
"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.1",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Proactive Discovery
When a user adds a new endpoint to their account or makes changes to an existing endpoint, you must send an Alexa.Discovery.AddOrUpdateReport
message proactively 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": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the new endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Living Room TV",
"displayCategories": ["TV"],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "Software version of the device"
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.RemoteVideoPlayer",
"version": "3.1",
"properties": {},
"configurations": {
"operations": ["SearchAndPlay"],
"entityTypes": ["MediaType", "League", "Sport", "SportsTeam"],
"catalogs": [{
"type": "VIDEO_PUBLIC_CATALOG_IDENTIFIER",
"sourceId": "imdb"
}
]
}
},
{
"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.1",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
Alexa sends the following Alexa.RemoteVideoPlayer
interface directives to your skill.
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": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {
"entities": [{
"externalIds": {
"imdb": "tt4574334"
},
"value": "Title of series",
"type": "Video"
}],
"searchText": [{
"transcribed": "Manchester by the Sea"
}],
"experience": {
"mode": "VOICE_OPTIMIZED"
},
"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 |
|
Suggests how to display the results to give the best user experience. |
Object |
No |
|
Suggests the mode to display the requested results. |
String |
Yes |
|
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": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "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:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SearchAndPlay error handling
If you can't handle a SearchAndPlay
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
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": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {
"entities": [{
"externalIds": {
"imdb": "tt4574334"
},
"value": "Title of series",
"type": "Video"
},
{
"externalIds": {
"ENTITY_ID": "amzn1.alexa-ask-target.app.72095"
},
"name": "Prime Video",
"type": "App"
}
],
"experience": {
"mode": "VOICE_OPTIMIZED"
},
"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 SearchAndPlay
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": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "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:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SearchAndDisplayResults error handling
If you can't handle a SearchAndDisplayResults
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
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.
Related topics
Last updated: Aug 23, 2024