Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
When users ask Alexa to play specific video content, such as “Watch Bosch” or “Watch the Warriors game,” the Alexa.RemoteVideoPlayer interface sends SearchAndPlay directives to your app or Lambda.

Overview

The SearchAndPlay directive signals that the customer has asked Alexa to “watch” 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 app (for app-only integrations) or to your Lambda (for cloudside integrations) when users say the following utterances.

SearchAndPlay Directive 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.”
payload contains the following:

Payload Definitions

FieldDescriptionData Type
entities
optional
An array of entity objects to play, such as a Title, Franchise, Actor, Team, or MediaType. See Entity Types for more details about entity types and values.array
experience
optional
An object that optimizes the display of search results. With the experience object, you can change the search results based on the device your customer used to search. See Experience Types for more details about the experience object and its values.Object containing mode
searchText
optional
Contains a transcribed version of the user’s search query as a string value in the transcribed field. See Viewing the Customer’s Actual Request for details.Object containing transcribe
transcribed
optional
Provides the transcribed version of the user’s utterance. See The searchText Object for details.Examples: h.d. popular comedy tv showsString
timeWindow
optional
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
optional
The end time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00ZA string in ISO 8601 format.
start
optional
The start time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00ZA string in ISO 8601 format.

Entity Types

The entities object consists of a list of objects, each of which contains a type and a value along with other possible data such as external IDs. The following values are possible for the type value: Actor, App, Channel, Character, Director, Episode, Event, Franchise, Genre, League, MediaType, ProductionCompany, Season, Sport, SportsTeam, Video, Popularity, Recency, and VideoResolution. Details about the payloads for each entity type are provided in the sections below.

Actor

Actor represents an actor credited in video media content; for example, Casey Affleck might contain the following:
Actor Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ ASINThe external ASIN of this entityStringB01LTHZVKG
└─ imdbThe IMDB identifier for the actor.Stringtt4034228
uriURI mapping to the actor/actressURIentity://provider/actor/caseyaffleck
valueThe name of the actorStringCasey Affleck

App

App represents the explicit app name specified by the user in utterance; for example, “Manchester by the Sea on Prime” might contain the following:

Channel

Channel represents the identifying data for a television channel; for example, “PBS” might contain the following:
Channel Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
entityMetadataA map of meta data associated with the channelObject—
└─ channelNumberThe channel numberInteger1234
└─ channelCallSignThe call sign for the channelStringKBTC
uriThe URI of the channelURIentity://provider/channel/1234
valueThe name of the channelStringPBS

Character

A Character represented in video media content.
Character Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ ASINThe Amazon Standard Identification Number (ASIN) for this entityStringB00DT55P3K
└─ imdbThe IMDB identifier for the character.Stringcharacter id
uriURI mapping to the characterURIentity://provider/character/snowwhite
valueThe name of the characterStringSnow White

Director

Director represents the director name for the video media content; for example, “Kenneth Lonergan” might contain the following:
Director Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
uriURI mapping to the directorURIentity://provider/director/kennethlonergan
valueThe name of the directorStringKenneth Lonergan

Episode

Episode represents the episode number for serial content like TV Shows; for example, the eighth episode of “Transparent” would have episode number 8.
Episode Payload FieldsDescriptionTypeExample
valueThe episode numberInteger8

Event

An Event is a reference to a type of event; examples would include sports, music, or other types of events. For example, searching for “Football games” would search for a game event entity and a football sport entity.
Event Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for the event.Stringtt4034228
uriURI mapping to the eventURIentity://amazon/events/games
valueThe name of the event typeStringGames

Franchise

A Franchise is a video entity which can represent a number of video entities, like movies or TV shows. For example, take the fictional franchise “Intergalactic Wars” which represents a collection of movie trilogies, as well as animated and live action TV shows. This entity type was introduced to account for requests by customers such as “Find Intergalactic Wars movies”, which would search for all “Intergalactic Wars” programs of the MOVIE value for MediaType, rather than attempting to match to a single title.
Franchise Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
uriURI mapping to the franchiseURI mapping to the evententity://amazon/franchise/intergalacticwars
valueThe name of the genreStringIntergalactic Wars

Genre

Genre represents the genre of video media content such as action, drama or comedy. For example, the Action genre might contain the following:
Genre Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
uriURI mapping to the genreURIentity://provider/genre/action
valueThe name of the genreStringAction

League

League represents the categorical information for a sporting league; for example, NCAA is a league that might contain the following:
League Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for the leagueStringtt4034228
uriURI mapping to the leagueURIentity://amazon/league/ncaa
valueThe name of the leagueStringNCAA

MediaType

MediaType represents the media type category of a particular piece of content; for example, the MediaType for “Manchester by the Sea” would be MOVIE.
MediaType Payload FieldsDescriptionTypeExample
valueThe media type; possible values are MOVIE, VIDEO, TV_SHOWEnumMOVIE

ProductionCompany

ProductionCompany represents the production company name for the video media content; for example, Marvels, Disney.
ProductionCompany Payload FieldsDescriptionTypeExample
valueProduction company nameStringMarvel

Season

Season represents the season number for serial content like TV Shows; for example, the season two of “Transparent” would have season number 2.
Season Payload FieldsDescriptionTypeExample
valueThe season numberInteger2

Sport

Sport represents the categorical information of a sport; for example, football is a sport that might contain the following:
Sport Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for the sportStringtt4034228
uriURI mapping to the sportsURIentity://amazon/sport/football
valueThe name of the sportStringFootball

SportsTeam

SportsTeam represents the categorical information of a professional sports team; for example, “University of Washington Huskies” is a sports team that might contain the following:
SportsTeam Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for this team.Stringtt4034228
uriURI mapping to the sports teamURIentity://amazon/sportsteam/huskies
valueThe name of the sports teamStringUniversity of Washington Huskies

Video

Video represents the identifying data for the piece of video content; for example, “Manchester by the Sea” might contain the following:
Video Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
ASINThe external ASIN of this entityStringB01LTHZVKG
└─ imdbThe IMDB identifierStringtt4034228
userConfirmationsObject containing information about user confirmations for the itemObject
└─ entitlementVoiceActivationFlag to inform partner if voice enablement of viewing period or entitlement is successful. Possible values - CONFIRMED (optional).Enum; Default policy - unrecognized values are ignoredCONFIRMED
uriURI mapping to the videoURIentity://provider/movie/manchesterbythesea
valueThe name of the videoStringManchester by the Sea

Popularity

Popularity indicates whether the user asks for popular content.
Popularity Payload FieldsDescriptionTypeExample
valueIndicates to provider that the user searches for popular contentStringTRUE
Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json “entities”: [..{ “value”: “TRUE”, “type”: “Popularity” } ..], ```

Recency

The resolved values for Recency indicate whether the user asks for new or old content.
Recency Payload FieldsDescriptionTypeExample
valueIndicates whether the user searches for new or old content; possible values are NEW, OLDEnumNEW
Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json “entities”: [..{ “value”: “NEW”, “type”: “Recency” } ..], ```

VideoResolution

VideoResolution represents the requested video resolution in one of the following standards:
  • SD (480p)
  • HD (720p-1080p)
  • 4k (2160p)
  • 8k (4320p)
VideoResolution Payload FieldsDescriptionTypeExample
valueVideo resolution; possible values are SD, HD, 4k, 8kEnumHD
Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json “entities”: [..{ “value”: “4k”, “type”: “VideoResolution” } ..], ```

Experience Types

Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote. The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.
  • VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.
  • DEFAULT: The default displays of all search results list format, regardless of the device used for the search.
To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

Handling SearchAndPlay Directives

SearchAndPlay directives contain instructions to watch or 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.

Watch by Title

When users say “Alexa, watch Interstellar” or any other title to your Alexa-enabled device, you will receive a SearchAndPlay directive in your app or 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 watch. You can then use that to fulfill the user’s request by playing the media. 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. 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 watch content that is in your app, contact your Amazon representative for assistance.

Watch by Title, Episode, and Season

When users say “Alexa, watch Interstellar Season 2 Episode 2,” you will receive a similar directive as when users say “Alexa, watch Interstellar.” However, the key difference is that this directive will also have the following JSON inside of it:
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 watch a title by season, (e.g., “Alexa, watch 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 watch a title by episode, (e.g., “Alexa, watch 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.

Watch 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 “Watch by Franchise.” When a user conducts a watch-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 shouldn’t simply ignore the directive. A list of franchises is available in Franchise List.

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

Alexa also supports phrases such as “Alexa, watch 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. You shouldn’t simply ignore the directive. A list of genres that might be received in directives is available in Genre List.

Handling Ambiguous 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, watch a popular comedy,” or “Alexa, watch a Billy Bob Thornton movie.” Despite the ambiguity, you can decide how to act on a request. For example, you can do the following:
  • 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 request if at all possible.

Viewing the Actual Customer’s Request

Recall that an Alexa service in the cloud does the work of interpreting the customer’s request, determining the intent, and then packaging it into a directive. What if you want to see the actual user’s request (rather than Alexa’s interpretation of it)? fortunately, a version of the user’s actual request is available. In the directive payload, the searchText object represents the customer search request. In the searchText object, the transcribed value is a string that represents the customer intent. This transcribed value is a stripped-down version of what the customer said. For example, here’s how the transcribed value might look like for the request, “Alexa, watch popular comedy tv shows in HD”:
As you can see, the transcribed property is a summarized/redacted version of the request that selects the main words of the request. 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”
  • Action verbs are omitted. The transcribed value will not show the action verbs used in the user’s request.
Note that searchText can include content provider names (if they were part of the customer’s request). Here are some examples:
  • The request, “Alexa, find <content provider> movies” will return the transcribed value “<content provider> movies”
  • The request, “Alexa, find comedies on <content provider>” will return the transcribed value “<content provider> comedies”
Use searchText if you want to focus on key word searches (for example, a full text search). Note that entities rely on resolved catalog values. Use these entities 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.

Response Example

If your app handled the directive successfully, your BroadcastReceiver class should send a success intent back with a success status, like this:
For more details, see Step 7: Add a BroadcastReceiver. Also see the AlexaDirectiveReceiver class in the sample app for a more specific code example.

Declaring Capability Support for this Interface

To receive SearchAndDisplayResults directives to your app from the RemoteVideoPlayer interface, you must indicate support for this interface when you declare your capabilities. See the following for more information on declaring capabilities with app-only integrations:
Last modified on June 9, 2021