Developer Console
Thank you for your visit. This page is only available in English at this time.

Alexa.RemoteVideoPlayer Interface: SearchAndPlay (VSK Fire TV)

When users ask Alexa to play specific video content, such as "Play Bosch" or "Play the Warriors game," the Alexa.RemoteVideoPlayer interface sends SearchAndPlay directives to your Lambda.

Overview

The SearchAndPlay directive signals that the customer has asked Alexa to "play" an item. SearchAndPlay results in playback of the specifically requested title, or a title that best matches the requested entity. If there are no matched titles, search results are returned instead.

Here are some example utterances:

  • Alexa, watch title
  • Alexa, play title
  • Alexa, stream title
  • Alexa, start title

Utterances for SearchAndPlay Directives

Alexa sends a SearchAndPlay directive to your Lambda when users say the following utterances.

Feature Sample Utterances Expected Response Version
Play title

Watch breaking bad

ich möchte <VideoName> gucken

spiel <VideoName>

spiel watchlist ab von <VideoName>?

mets / joue / lance <VideoName> sur <AppName>

mets / joue / lance / pars <VideoName> sur <AppName>

metti / trasmetti / riproduci / fammi guardare / fammi vedere + VideoName (+ da/su DeviceName

pon interstellar

reproduce interstellar

ver interstellar

<VideoName>を再生して <VideoName>を<AppName>で再生して <AppName>で<VideoName><MediaType>を再生して

tocar/assistir/reproduzir <VideoName> no/na <AppName>

<VideoName> चलाओ/बजाओ/लगाओ/play/देखो <AppName> पे/पर/में <VideoName> चलाओ/बजाओ/लगाओ/play

The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.

1.0

Play by media type

Watch a movie

spiel einen <MediaType>

spiel <MediaType> aus der/meiner watchlist

streame den <MediaType> <VideoName> auf <AppName>/<Device> spiel trailer von <VideoName>

spiel die neueste folge von <VideoName>

regarde un film

mets un film

joue un film

regarde un film

mets un film

joue un film

pars un film

guarda un film

metti un fim

trasmetti un film

riproduci un film

pon la película*

reproduce la película*

Note: Not supported in es-ES or es-US

<VideoName>を再生して <VideoName>を<AppName>で再生して <AppName>で<VideoName><MediaType>を再生して

<MediaType>を再生して

<ActorNameName>が出ている<MediaType>を再生

<Anaphor><MediaType>を流して

<AppName>で<GenreNameName><MediaType>を再生

<AppName>で<VideoName><MediaType>を再生して

<ChannelName>の<MediaType>を再生

assistir um filme

colocar um filme

nós podemos assistir um filme

ver um filme

<VideoName> movies चलाओ/बजाओ/लगाओ/play/देखो

Either media matching the non-title request plays (through an algorithm that selects a recommended video for the user), or a list of results is presented to the user.

1.0

Play by actor

Watch sean connery

spiel <VideoName> (mit <ActorName>) auf <AppName>

streame einen film mit <ActorName> auf <AppName>

streame einen <ActorName> film auf <AppName>

streame eine serie mit <ActorName> auf <AppName>

streame eine <ActorName> serie auf <AppName>

regarde un film avec <actor>

mets un film avec <actor>

joue un film avec <actor>

regarde un film avec <actor>

mets un film avec <actor>

joue un film avec <actor>

pars un film avec <actor>

guarda un film con <ActorName>

metti un film con <ActorName>

pon salma hayek

reproduce salma hayek

<ActorNameName>が出ている<MediaType>を再生

assistir <ator>

colocar <ator>

coloque filmes com <ator>

encontre filmes com <ator>

me mostre filmes com <ator>

<ActorName> का/की/के movies को चलाओ/बजाओ/लगाओ/play/देखो <ActorName> का/की/के movies चलाओ/बजाओ/लगाओ/play/देखो <ActorName> का/की/के <GenreName> को चलाओ/बजाओ/लगाओ/play/देखो <ActorName> का/की/के <GenreName> चलाओ/बजाओ/लगाओ/play/देखो <ActorName> का/की/के <VideoName> को चलाओ/बजाओ/लगाओ/play/देखो <ActorName> का/की/के <VideoName> चलाओ/बजाओ/लगाओ/play/देखो

<ActorName> का/की/के/वाला <GenreName> की <VideoName> को चलाओ/बजाओ/लगाओ/play/देखो <ActorName> का/की/के/वाला <GenreName> की <VideoName> चलाओ/बजाओ/लगाओ/play/देखो

Either media with the actor plays (through an algorithm that selects the best match for the user), or a list of results is presented to the user.

1.0

Play <title> with season number

Watch breaking bad season two

spiel <VideoName> <Season> <Season_Numer>

spiel <VideoName> <Season> <Season_Numer> auf <AppName>

Regarde la saison <x> de <title>

Mets la saison <x> de <title>

Regarde <title> saison <x>

Mets <title> saison <x>

Joue <title> saison <x>

Joue la saison <x> de <title>

regarde la saison <x> de <title>

mets la saison <x> de <title>

joue la saison

<x> de <title>

pars la saison <x> de <title>

regarde <title> saison <x>

mets <title> saison <x>

joue <title> saison <x>

pars <title> saison <x>

joue la saison <x> de <title>

guarda <VideoName> stagione due

metti <VideoName> stagione due

riproduci <VideoName> stagione due

empieza la segunda temporada de los rompecorazones

comienza la segunda temporada de los rompecorazones

reproduce la segunda temporada de los rompecorazones

<VideoName>の<Season><Season_Number>の

assistir <title> temporada <x>

colocar <title> temporada <x>

reproduzir <title> temporada <x>

<VideoName> का/की/के <SeasonNumber> को चलाओ/बजाओ/लगाओ/play/देखो <VideoName> का/की/के <SeasonNumber> चलाओ/बजाओ/लगाओ/play/देखो <VideoName> का/की/के <SeasonNumber> को चलाओ/बजाओ/लगाओ/play/देखो <VideoName> का/की/के <SeasonNumber> <SeasonNumber> चलाओ/बजाओ/लगाओ/play/देखो

The last-watched episode in the series plays, if the episode wasn't completed. If the last-watched episode was completed, the next unwatched episode plays.

1.0

Play <title> with episode number

Watch breaking bad episode five

spiel die <Episode_Number> <Episode> von <VideoName>

spiel <VideoName> <Episode_Number>

spiel von <VideoName> <Episode> <Episode_Number>

Regarde l'épisode <x> de <title>

Mets l'épisode <x> de <title>

Joue l'épisode <x> de <title>

Joue <title> épisode <x>

regarde l'épisode <x> de <title>

mets l'épisode <x> de <title>

joue l'épisode <x> de <title>

pars l'épisode <x> de <title>

joue <title> épisode <x>

mets <title> épisode <x>

guarda <VideoName> episodio cinque

metti <VideoName> episodio cinque

riproduci <VideoName> episodio cinque

pon el capítulo final de los serrano

<Episode_Number><Episode>を再生

assistir <title> episódio <x>

colocar <title> episódio <x>

reproduzir <title> episódio <x>

reproduzir o <title> episódio <x>

<VideoName> का/की/के <EpisodeNumber> को चलाओ/बजाओ/लगाओ/play/देखो <VideoName> का/की/के <EpisodeNumber> चलाओ/बजाओ/लगाओ/play/देखो

The correct season is identified by the user's last-watched episode. The last-watched episode in the series plays, if the episode wasn't completed. If the last-watched episode was completed, the next unwatched episode plays.

1.0

Play <title> with season and episode number

Watch breaking bad season two episode five

spiel <Season> <Season_Numer> <Episode> <Episode_Number> von <VideoName>

spiel <VideoName> <Season> <Season_Numer> <Episode> <Episode_Number>

spiel die <VideoName> <Season> <Season_Numer> <Episode> <Episode_Number> auf <AppName> ab

Regarde l'épisode <x> de la saison <x> de <title>

Joue l'épisode <x> de la saison <x> de <title>

Mets l'épisode <x> de la saison <x> de <title>

Same as fr-FR

guarda <VideoName> stagione due episodio cinque

metti <VideoName> stagione due episodio cinque

riproduci <VideoName> stagione due episodio cinque

pon el segundo episodio de la primera temporada de anabel

reproduce el cuarto episodio de la temporada tres de águila roja

<Episode_Number><Episode>を再生

<VideoName>の<Season><Season_Number>の

assistir <title> temporada <x> episódio <x>

colocar <title> temporada <x> episódio <x>

reproduzir <title> temporada <x> episódio <x>

<VideoName> season one episode one चलाओ/बजाओ/लगाओ/play करो

<VideoName> season एक का episode एक चलाओ/बजाओ/लगाओ/play करो

The content corresponding to the requested season and episode plays.

1.0

Play by franchise <title>

Watch star trek

ich möchte <VideoName> gucken

spiel <VideoName>

spiel watchlist ab von <VideoName>?

Regarde <title>

Mets <title>

Joue <title>

regarde <title>

mets <title>

joue <title>

pars <title>

guarda star trek

fammi vedere star trek

mostra star trek

pon star wars

reproduce star wars

assitir jornada nas estrelas

colocar jornada nas estrelas

reproduzir jornada nas estrelas

você pode passsar jornada nas estrelas

por favor reproduzir jornada nas estrelas

star trek देखो/देखना/देखिए

Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.

1.0

Play by character name

Watch james bond

Not supported

Not supported

Not supported

guarda <CharacterName>

fammi vedere un film con james bond

mostrami un film di james bond

reproduce algo con james bond

Not Supported

<CharacterName> का/की/के/वाला movies चलाओ/बजाओ/लगाओ/play/देखो <CharacterName> का/की/के/वाला movies को चलाओ/बजाओ/लगाओ/play/देखो Watch <CharacterName> movie <VideoName>

Either media matching the character name plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of media results.

1.0

Play by genre name

Watch comedy

spiel eine <GenreName> <MediaType> auf <DeviceType> ab

spiel eine <GenreName> <MediaType> auf <AppName> ab

<GenreName> <MediaType> schauen

spiel einen <GenreName> <MediaType>

regarder un <GenreName>

regarder une <GenreName>

mets un <GenreName>

mets une <GenreName>

joue un <GenreName>

joue une <GenreName

regarder un <GenreName>

regarder une <GenreName>

mets un <GenreName>

mets une <GenreName>

joue un <GenreName>

joue une <GenreName

guarda una <GenreName>

fammi vedere una commedia

mostra mi una commedia

metti una commedia

pon comedia en netflix (Not supported without AppName)

<AppName>で<GenreNameName><MediaType>を再生<AppName>で<GenreNameName>を再生

assitir <GenreName>

assistir programas de <GenreName>

programas de <GenreName>

colocar <GenreName>

por favor reproduzir <GenreName>

reproduzir programas de <GenreName>

c

olocar um programa de <GenreName>

<GenreName> <VideoName> को चलाओ/बजाओ/लगाओ/play/देखो <GenreName> <VideoName> चलाओ/बजाओ/लगाओ/play/देखो

Either media from the requested genre plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of media results.

1.0

Play by sports team

Watch seahawks

spiel <SportsTeam> <Event> auf <AppName>

<SportsTeam> <Event> anschauen/ansehen

das <SportsTeam> <Event> auf <AppName> anschauen/ansehen

spiel das <SportsTeam> <Event> auf meinem <Device>

Regarde le <team>

Regarde le match de <team>

Regarde le <team>

Regarde le match de <team>

riproduci la partita del <SportsTeam>

ver el partido del real madrid

<SportsTeam>の<Event>を<AppName>で見せて

assisitr <SportTeam>

assitir o/a <SportTeam>

colocar no/na <SportTeam>

colocar o jogo do/da <SportTeam>

me mostre o jogo do/da <SportTeam>

mostre o jogo do/da <SportTeam>

<Sport/League/Seam> games चलाओ/बजाओ/लगाओ/play/देखो <Sport/League/Seam> के games को चलाओ/बजाओ/लगाओ/play/देखो

Either media matching the sports team plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of media results.

1.0

Play by sports type

Watch soccer

spiel das <Sport> <Event> auf meinem <Device>

das <Sport> <Event> ansehen

Not supported

Not supported

not supported

reproduce el partido de fútbol en mi televisor

ver el partido de fútbol en mi tele

ver el partido de fútbol

<SportsTeam>の<Event>を<AppName>で見せて

assistir <Sport>

<Sport/League/Seam> games चलाओ/बजाओ/लगाओ/play/देखो <Sport/League/Seam> के games को चलाओ/बजाओ/लगाओ/play/देखो

Either media matching the sports type plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of results.

1.0

Play by sports league

Watch n. b. a. league

spiel <SportsTeam> <Event> auf <AppName>

<SportsTeam> <Event> anschauen

Mets <league>

Joue <league>

Regarde <league>

Mets <league>

Joue <league>

Regarde <league>

trasmetti la partita della <League>

pon el partido de la a. c. b. en mi tele

ver el partido de la a. c. b. en mi televisor

<SportsTeam>の<Event>を<AppName>で見せて

assistir <League>

colocar <League>

<Sport/League/Seam> games चलाओ/बजाओ/लगाओ/play/देखो

<Sport/League/Seam> के games को चलाओ/बजाओ/लगाओ/play/देखो

Either media matching the sports league plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of results.

1.0

Play by sports event

Watch soccer game

spiel das <Sport> <Event> auf meinem <Device>

das <Sport> <Event> ansehen

Not supported

Not supported

not supported

ver el partido de fútbol

<SportsTeam>の<Event>を<AppName>で見せて

not supported

<Sport/League/Seam> games चलाओ/बजाओ/लगाओ/play/देखो <Sport/League/Seam> के games को चलाओ/बजाओ/लगाओ/play/देखो

Either media matching the sports event plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of results.

1.0

Handling SearchAndPlay Directives

SearchAndPlay directives contain instructions to play media. The directive contains the desired media object and URI obtained described as an entity. The directive contains an array of entities that specifies what to search and play.

(The SearchAndPlay directive is similar to GetPlayableItems in the video skills for multimodal implementations.)

SearchAndPlay Example

The following is an example SearchAndPlay directive. This is a directive that Alexa might send in response to a user's request to watch "Manchester by the Sea."

{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "e7f9c31f-cb90-4003-9795-c6fb9f487945",
            "name": "SearchAndPlay",
            "namespace": "Alexa.RemoteVideoPlayer",
            "payloadVersion": "3"
        },
        "payload": {
            "displayMode": "VUI",
            "entities": [
                {
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    },
                    "type": "Video",
                    "uri": "entity://provider/show/manchesterbythesea",
                    "value": "Manchester by the Sea"
                }
            ],
            "searchText": [
                {
                    "transcribed": "Manchester by the Sea"
                }
            ],
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}

The following sections provide guidance for handling SearchAndPlay directives with different requests.

Play by Title

When users say "Alexa, play Interstellar" or any other title to your Alexa-enabled device, you will receive a SearchAndPlay directive in your Lambda.

As part of the SearchAndPlay directive, you will see an externalIds section in the directive. Within this section, you should look for a field corresponding with your own catalog. This field will contain the same ID values you used in your catalog integration, allowing you to know precisely which show a user desires to play. You can then use that to fulfill the user's request by playing the media.

If you do not see your own catalog ID values in the externalIds field, and you've made sure that you're asking Alexa to play content that is in your app, contact your Fire TV Solution Architect for assistance.

Also note that you will see multiple entities in the directive you receive. This is because there are often multiple shows with the same name. After you incorporate the Alexa Client Library and complete the step to auto-pair and finalize your skill, we will narrow down the directives so that you receive only one entity from your own catalog (rather than receiving entries across all catalogs). Until the ID values are narrowed to your catalog only, you should iterate through the entities received by your Lambda code until you come across the entity with your own catalog ID. You should react to that entity in your code.

If within the same catalog you still see multiple ID values in the directive, this may be because Alexa identified multiple shows within your catalog that match the title the user asked for. You should select the best one to play for the user. Leverage any algorithms that help match the content to the user.

Play by Title, Episode, and Season

When users say "Alexa, play Interstellar Season 2 Episode 2," you will receive a similar directive as when users say "Alexa, play Interstellar." However, the key difference is that this directive will also have the following JSON inside of it:

{
  "type": "Episode",
  "value": "2"
},
{
  "type": "Season",
  "value": "2"
}

This JSON indicates the season and episode number that the user requested. You must play the season/episode the customer requests. The catalog ID you receive will contain only the top-level show's catalog ID, not the season/episode ID. However, you should be able to use the season/episode number alongside the show's catalog ID to play the correct content.

You should also account for the fact that a user might choose to specify a season but not an episode, or an episode but not the season — you must still fulfill their request. Follow this guidance for identifying the right content:

  • If the user asks to play a title by season, (e.g., "Alexa, play Bosch, Season 3"), and it is unclear which episode of a TV series a user wants, show the last watched episode. If the last watched episode is completed, show the next unwatched episode after that. Alternatively, show an episode list for the season.
  • If the user asks to play a title by episode, (e.g., "Alexa, play Bosch, episode 5") that could belong to multiple seasons, identify the correct season by checking the user's last-watched episode. If the last-watched episode was within Season 2, then play episode 5 in Season 2. Alternatively, show an episode list for the season.

Play by Franchise

For certain utterances, it's not actually clear which content the user wants. For example, a user might say "Alexa, watch Jurassic Park." In such a scenario, we don't know if the user meant Jurassic Park 1, Jurassic Park 2, or Jurassic Park 3. Media that has multiple variants like this is called a "franchise." Franchise scenarios, which don't fit neatly into the season/episode model, are handled by "Play by Franchise."

When a user conducts a play-by-franchise request, you will receive the franchise that the user requested (in this case, Jurassic Park) in the directive, but the directive will not contain a catalog ID. For these directives, the expectation is that you will conduct a search within your catalog for this content and then play the top result from your search. If that is not possible, you must at least take the user to search results within your app so that the user can use their remote to see the content they would like. You may not simply ignore the directive.

A list of franchises is available in Franchise List.

Play by Genre, Sport, Team, League, and Other Ambiguous Play Directives

Alexa also supports phrases such as "Alexa, play a comedy" or "Alexa, watch basketball." For generic scenarios like these, you have the option of either taking the user to search results, or taking the user to the detail page of that particular genre or appropriate entity.

For example, many apps have special pages dedicated to comedies, action movies, sitcoms, etc., which are different from simple search results. These genre pages curate media related to that topic. If desired, you can choose to take the user to these genre pages when the relevant ambiguous request is received by the user. The expectation is that, even in the worst case scenario, your app should at least take the user to search results. Do not simply ignore the directive.

A list of genres that might be received in directives is available in Genre List.

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 might contain an ambiguous entity request.

For example, a customer could request, "Alexa, play a popular comedy," or "Alexa, play a Billy Bob Thornton movie." Despite the 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 ten comedies or Billy 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 VSK APIs 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"

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).

Handling Content Not Found

If the user asks for content that can't be found, you can send an error response with a CONTENT_NOT_FOUND error type. See Error Handling for more details.

Avoid user experiences that involve "voice cliffs." A voice cliff is a voice experience that leads to the user having to pick up the remote control.

Payload Descriptions

The following fields are supported.
Field Description Data Type
entities
An array of entity objects to play, such as a Title, Franchise, Actor, Team or MediaType. See Entity Types for Video Content for more details about entity types and values. array
displayMode
Identifies if the request is a far field (VUI) or a near field request (GUI). enum values "VUI" or "GUI"
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. Object containing start and end times.
end

The end time of the time window.

Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z

A string in ISO 8601 format.
start

The start time of the time window.

Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z

A string in ISO 8601 format.

Response Example

When a SearchAndPlayResults directive successfully completes, your Lambda should respond with an Alexa.Response message.

{
    "context": {
        "properties": []
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "1d8749ce-2805-4781-bb34-c5c59ce71f6a",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

No payload content is required. With video skills on Fire TV apps, the response back to Alexa is minimal, with an empty payload. This is because you send the needed instruction to your Fire TV app through ADM. This is not the case for VSK for Echo Show.

Declaring Capability Support for this Interface

To indicate that your video skill supports the Alexa.RemoteVideoPlayer 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.