Alexa.RemoteVideoPlayer Interface 3.1

  • 3.1
  • 3

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.

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, 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 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 comedies or top 10 comedies.

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

operations

Identifies the directives that your skill supports. If you don't include this property, Alexa assumes that your skill supports all directives.
Valid values: SearchAndPlay, SearchAndDisplayResults.

Array of strings

No

entityTypes

Identifies the entity types that your skill supports. If you don't include this property, Alexa assumes that your skill supports all entity types.
For valid values, see Entity types.

Array of string

No

catalogs

Identifies the public and private catalogs that your skill supports. You can report different catalogs per endpoint and customer.
If you don't have a catalog, include one object in the array with sourceId = imdb and type = VIDEO_PUBLIC_CATALOG_IDENTIFIER.

Array of Catalog objects

Yes

catalogs.sourceId

Uniquely identifies the catalog.
For private catalogs, set to the partner ID that you used for catalog ingestion. For details, see Partner field in Catalog Data Format file.
For publicly accessible catalogs, such as IMDb, set to imdb and set type to VIDEO_PUBLIC_CATALOG_IDENTIFIER.

String

Yes

catalogs.type

Type of catalog.
Valid values: VIDEO_INGESTION_IDENTIFIER, VIDEO_PUBLIC_CATALOG_IDENTIFIER.

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.

Copied to clipboard.

{
    "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.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 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.

Copied to clipboard.

{
    "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.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

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": "Unique identifier, preferably a 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"
            }],
            "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

entities

User-requested search terms.

Array of Entity objects

Yes

searchText

Specifies the text version of the user's utterance after natural language understanding (NLU) processing.
The word order is non-deterministic and can change based on point in time and directive. Use searchText if you want to focus on keyword searches.

Object

No

searchText.transcribed

Transcribed version of the user's search query.

String

No

timeWindow

Specifies the span of time over which to search.

Object

No

timeWindow.start

The start time for the content search.
Formatted as a UTC string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

timeWindow.end

The end time for the content search.
Formatted as a UTC string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

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.

Copied to clipboard.

{
    "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: 20: 50Z",
                "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 identifier, preferably a 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"
                }
            ],
            "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.

Copied to clipboard.

{
    "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: 20: 50Z",
                "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.