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.

Utterances for SearchAndPlay Directives

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

Feature Sample Utterances Expected Response
Play Title

Watch Breaking Bad

Spiele {title}

Öffne {title}

mets breaking bad

mets breaking bad

joue breaking bad

fai partire breaking bad

metti breaking bad

Pon la pelicula (title)

Pon breaking bad

Pon la pelicula (title)

Pon breaking bad

{title}を再生して

{title}を見せて

assistir {title}

ver {title}

{title} दिखाओ

{title} चलाओ

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

Play by media type

Watch a movie

Spiele Filme

Spiele einen Film

mets un film

je veux voir un film

mets un film

joue un film

fai partire un film

metti un film

pon una película

(quiero) ver una película

pon una película

pon una peli

{media type}を再生して

{media type}を見せて

assistir filmes

ver filmes

एक {media type} चलाओ

एक {media type} चलाओ

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.

Play by actor

Watch Sean Connery

Play a movie with Tom Hanks

spiele einen Film mit {actor} ab.

<Ann Blyth, Axel Deller, John Oliver>

mets un film de sean connery

je veux voir un film avec sean connery

mets un film de sean connery

mets un film avec sean connery

metti film con adriano celentano

fai partire un film con sean connery

pon (una película) de Sean Connery

(quiero) ver (una película) de Sean Connery

pon (una película) de Sean Connery

ponme (una película) de Sean Connery

{actor}を再生して

{actor}を見せて

assistir um filme com {actor/actress}

ver um filme com {actor/actress}

{actor}की movie चलाओ

{actor} की film लगा दो

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.

Play <title> with season number

Watch breaking bad season two

Spiele {title} Staffel {X}

Spiele die {X}. Staffel von {title}

mets la saison 2 de breaking bad

mets la deuxième saison de breaking bad

mets la deuxième saison de breaking bad

joue la deuxième saison de breaking bad

metti la seconda stagione di breaking bad

fai partire la seconda stagione di breaking bad

Pon la temporada 2 de breaking bad

pon la segunda temporada de breaking bad

pon la temporada 2 de breaking bad

pon la segunda temporada de breaking bad

{title} シーズン{season number}を再生して

{title} シーズン{season number}を見せて

assistir {title} temporada {cardinal number}

ver {title} temporada {cardinal number}

{title} season two चलाओ

{title} season two चला दो

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.

Play <title> with episode number

Watch breaking bad episode five

Spiele {title} Folge 5 ab.

<Breaking Bad>

mets l' épisode 5 de breaking bad

mets le cinquième épisode de breaking bad

mets le cinquième épisode de breaking bad

joue le cinquième épisode de breaking bad

metti il quinto episodio di breaking bad

fai partire il quinto episodio di breaking bad

pon el episodio 5 de breaking bad

pon el capítulo 5 de breaking bad

pon el episodio 5 de breaking bad

pon el capítulo 5 de breaking bad

{title} エピソード{episode number}を再生して

{title} エピソード{episode number}を見せて

assistir {title} episódio {cardinal number}

ver {title} number} episódio {cardinal number}

watch {title} episode five

play {title} episode five

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.

Play <title> with season and episode number

Watch breaking bad season two episode five

Spiele {title} Staffel 2 Folge 5 ab.

<Breaking Bad>

mets l' épisode 5 de la saison 2 de breaking bad

mets l' épisode 5 de la deuxième saison de breaking bad

mets l' épisode 5 de la saison 2 de breaking bad

mets l' épisode 5 de la deuxième saison de breaking bad

metti il quinto episodio della seconda stagione di breaking bad

fai partire il quinto episodio della seconda stagione di breaking bad

pon el episodio 5 de la temporada 2 de breaking bad

pon el episodio 5 de la segunda temporada de breaking bad

pon el episodio 5 de la temporada 2 de breaking bad

pon el episodio 5 de la segunda temporada de breaking bad

{title} シーズン{season number}エピソード{episode number}を再生して

{title} シーズン{season number}エピソード{episode number}を見せて

assistir {title} {ordinal number} temporada episódio {cardinal number}

ver {title} {ordinal number} temporada episódio {cardinal number}

play {title} season two episode five

{title} season two episode five लगाओ

The content corresponding to the requested season and episode plays.

Play by franchise <title>

Watch star trek

Spiele {franchise title}

Spiele {franchise title} Filme

mets star trek

je veux voir star trek

mets star trek

joue star trek

metti star trek

fai partire star trek

pon star trek

(quiero) ver star trek

pon star trek

pon una película de star trek

{franchise title}を再生して

{franchise title}を見せて

assistir {franchise title}

ver {franchise title}

{franchise title} चलाओ

watch {franchise title}

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

Play by character name

Watch james bond

spiele einen Film mit {actor} ab.

<James Bond>

mets james bond

je veux voir james bond

mets james bond

mets un film de james bond

metti james bond

metti un film di james bond

pon james bond

(quiero) ver james bond

pon james bond

pon una película de james bond

{character}を再生して

{character}を見せて

assistir filmes com {character name}

ver filmes com {character name}

{character name} की picture चलाओ

{character name} की movie चलाओ

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.

Play by genre name

Watch comedy

einen (title) (film/serie) ansehen

mets un film policier

mets une émission sportive

mets film d' comédie

mets une comédie

metti una commedia

fam mi vedere una commedia

pon una comedia

(quiero) ver una comedia

pon una comedia

pon una película de comedia

{genre}を再生して

{genre}を見せて

assistir uma/um {genre name}

ver uma/um {genre name}

watch {genre name}

play {genre name}

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.

Play by sports team

Watch seahawks

Zeig mir {sports team}

Zeig mir das Spiel von {sports team}

mets les bleus

je veux voir les bleus

mets les canadiens

mets le match des canadiens

fam mi vedere la Juventus

<Aberdeen, ac milan>

pon el Madrid

(quiero) ver el Madrid

pon el América

pon el partido del América

{sports team}を再生して

{sports team}を見せて

assistir {sports team}

ver {sports team}

{sports team} चलाओ

{sports team} की game चलाओ

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.

Play by sports type

Watch soccer

Zeig mir {sports type}

{sports type} anschauen

mets du foot

je veux voir du foot

mets du hockey

mets le hockey

fam mi vedere una partita di calcio

metti la/una partita

pon el fútbol

(quiero) ver el fútbol

pon fútbol

ponme fútbol

{sports type}を再生して

{sports type}を見せて

assistir {sports type}

ver {sports type}

watch {sports type}

{sports type} चलाओ

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.

Play by sports league

Watch n. b. a. league

Zeig mir die {sports league}

{sports league} anschauen

Mets la n.b.a.

Je veux voir la n.b.a.

mets la l. n. h.

je veux regarder la l. n. h.

fam mi vedere la n.b.a.

metti l'n.b.a.

pon la n. b. a.

(quiero) ver la n. b. a.

pon la n. b. a.

ponme la n. b. a.

{sports league}を再生して

{sports league}を見せて

assistir {sports league}

ver {sports league}

watch {sports league}

{sports league} चलाओ

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.

Play by sports event

Watch soccer game

Zeig mir das {sports event}

Zeig mir ein {sports event}

mets un match de foot/football

je veux voir un match de foot/football

mets une partie de hockey

je veux regarder une partie de hockey

metti una partita di calcio

fam mi vedere una/la partita

pon el partido de fútbol

(quiero) ver el partido de fútbol

pon el partido de fútbol

ponme el partido de fútbol

{sports event}を再生して

{sports event}を見せて

assistir {sports event}

ver {sports event}

watch {sports event}

play {sports event}

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.

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

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

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.

SearchAndPlay Example

The following is an example SearchAndPlay directive. This is a directive Alexa might send in response to a user's request to watch "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

The following table describes the payload fields in the GetBrowseNodeItems code sample.

Payload Descriptions
Field Description Data Type
entities
An array of entity objects to play, such as a Title, Franchise, Actor, Team or Media Type. See [entity types here](../video-skills-fire-tv-apps/entity-types-for-video-content.html). array
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 SearchAndPlay directive successfully completes, your Lambda should respond with an Alexa.Response message as follows:

{
    "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": {}
    }
}

No payload content is required.

Note that 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 multimodal devices. With multimodal devices, your response back to Alexa contains more detail to play the media, since multimodal devices are app-less.

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.