Alexa.Media.Search Interface
Use the Alexa.Media.Search
interface to enable your skill to search for content. In the following utterance, for example, a user asks to play audio content.
User: Alexa, play "Alive," from the album Ten, on Amazon Music.
Alexa sends your skill a GetPlayableContent
request that contains information about the user and the requested content. If the content is available, the skill responds with a unique identifier.
Sometimes, as in the following example, a user asks to play content that's also displayable on devices with screens.
User: Alexa, show me songs by Adele.
When the content includes a visual component, Alexa sends your skill a GetDisplayableContent
request. If the content is available, the skill returns a unique identifier.
In either type of request, GetPlayableContent
or GetDisplayableContent
, the response returns content items, if available, to satisfy the request. If the customer decides to play one of the returned items, the service sends an Initiate
request to the skill. If the skill can't satisfy a given request, it returns an error code.
Utterances
When you use the Alexa.Media.Search
interface, the voice interaction model is already built for you. The following examples represent typical user queries.
Alexa, play music on <skill name>.
Alexa, play top rock on <skill name>.
Alexa, I want to listen to Soundgarden on <skill name>.
Alexa, play "Alive," by Pearl Jam, on <skill name>.
Alexa, play the album Nevermind, by Nirvana, on <skill name>.
Alexa, I want to hear the Party Hits playlist on <skill name>.
Alexa, let me hear some jazz classics on <skill name>.
Alexa, play the Summertime station on <skill name>.
Alexa, wake me up to yacht rock on <skill name> at seven-thirty AM.
Alexa, set an alarm to <program series name> for <time> on <provider>.
Alexa, play the program <program series name>.
Alexa, play the Stuff You Should Know podcast.
Alexa, resume the podcast <program series name>.
Alexa, resume my podcast.
Alexa, play the latest <program in the current series>.
Alexa, play the oldest <program in the current series>.
Alexa, turn on <program series name> from <time>.
Alexa, play <program series name> about <topic>.
Alexa, play episode <program number> of <series name>.
When the user says one of these utterances, Alexa sends a corresponding GetPlayableContent
directive to your skill.
Configure your skill to receive requests
You must configure your music skill to support the GetPlayableContent
API before Alexa sends requests to it. The following table shows where to configure your skill.
Build method | Configuration |
---|---|
Interfaces page in the console | |
ASK command line interface (ASK CLI) |
Directives
GetPlayableContent directive
Support the GetPlayableContent
directive so that users can request content. The following table shows the content types that use this directive.
Content type | Required |
---|---|
Music |
Yes |
Radio |
Yes |
Podcast |
Yes |
The following table shows the GetPlayableContent
directive payload.
Field | Description | Type | Required |
---|---|---|---|
|
Context information about the request. |
RequestContext object |
Yes |
|
Filters to apply during content resolution. |
Filter object |
Yes |
|
Attributes that your skill resolves to a content object to play for the user. |
ResolvedSelectionCriteria object |
Yes |
For music skills, the following table shows the entity types in the selectionCriteria
property and the music catalog associated with each type. These entity types apply only to selected play requests and search requests.
Entity | Catalog type |
---|---|
TRACK |
AMAZON.MusicRecording |
ALBUM |
AMAZON.MusicAlbum |
ARTIST |
AMAZON.MusicGroup |
PLAYLIST |
AMAZON.MusicPlaylist |
GENRE |
AMAZON.Genre |
STATION |
AMAZON.BroadcastChannel |
For podcast skills, the following table shows that the entity types in the selectionCriteria
property correspond to podcast catalogs associated with the skill.
Entity | Catalog type |
---|---|
PROGRAM_SERIES |
AMAZON.ProgramSeries |
GetPlayableContent directive example (music)
The following example demonstrates the user request "Alexa, play 'Teach Your Children,' by Crosby, Stills, Nash & Young."
GetPlayableContent directive examples (podcast)
The following example demonstrates the user request "Alexa, play the podcast/program <program series name>."
The following example demonstrates the user request "Alexa, resume my podcast."
When a user says "Alexa, play the latest," the skill responds only if a program series is currently playing. This kind of request is made, for example, when the user wants to pause and then resume a program. Your skill must retrieve the current playing (last played) program series from the user's history and initiate playback of the latest—that is, the most recent—program the user has heard.
When a user says "Alexa, play the oldest season", the skill responds only if a program series is currently playing. This kind of request is made, for example, when the user wants to listen to a program series from the beginning. Your skill must retrieve the currently playing (last played) program series from the user's history and initiate playback of the program's earliest available season.
The following example demonstrates the user request "Alexa, play <provider name>." The skill receives this type of request with an empty selectionCriteria
attributes list. Your skill must respond with the user's most recently played media. For skills that support multiple media types, the most recently played media need not be a podcast.
The following example demonstrates the user request "Alexa, play <program series name> from a week ago."
The following example demonstrates the user request "Alexa, play <program series name> about/with <topic name>."
The following example demonstrates support for subscription playback.
GetPlayableContent response
To handle a GetPlayableContent
directive, respond with an Alexa.Response event.
If your skill receives a GetPlayableContent
request and finds playable content to satisfy the request, it responds with a GetPlayableContent.Response
. The following table shows payload details for GetPlayableContent.Response
.
Field | Description | Type | Required |
---|---|---|---|
|
Content that satisfies the request. For details, see the Content object. |
Object |
Yes |
|
(Podcasts only) User-specific information related to the returned content. For details, see the userContentProperties object. |
Object |
Yes |
GetPlayableContent response example (music)
The following example response satisfies a user request like "Alexa, play the song Poker Face, by Lady Gaga."
GetPlayableContent response event examples (podcast)
The following example response satisfies the user request "Alexa, play <program series> on <skill name>."
The following example response satisfies the user request "Alexa, play <program series> on <skill name>". This response assumes that the user has listened to the program series before.
The following example shows the error response that the skill returns when it can't find playable content to satisfy the user's request.
Your skill must provide subscription playback support for commands like "Alexa, play my followed podcasts." If the user has episodes to play in their subscription queue, the response must include a PLAYLIST
content object that includes a MediaMetadata object. Note that PLAYLIST
metadata has the same structure as BaseMetadata. In the response payload, the <Subscription_Playlist_Name>
, such as "My followed podcasts," is provider specific. The Alexa companion app or multimodal device displays this name in the Most recently played section.
GetPlayableContent directive error handling
Sometimes a skill can't handle a given GetPlayableContent
directive. For example, the customer's subscription tier might not allow access to the requested content, or geographic restrictions might prohibit streaming to the user's location. In such cases, your skill must respond with a media-specific CONTENT_NOT_FOUND message. This message is associated with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For details, see Alexa Music, Radio, and Podcast Skill API Error Responses.
GetDisplayableContent
You can support the GetDisplayableContent
directive so that your skill can return content items with displayable attributes, such as images and other metadata. In response to requests from Alexa or from users, these content items are returned in the Alexa app and on multimodal devices like Fire TV and Echo Show. The following table lists the content types that can use the GetDisplayableContent
directive.
GetDisplayableContent
, reach out to alexa-audio-getdisplayablecontent-spi-onboarding@amazon.com
. In your message, include your skillId
and a list of the experiences you'd like to support.Content type | Required |
---|---|
Music |
No |
Radio |
No |
Podcast |
No |
GetDisplayableContent request
When your skill receives a GetDisplayableContent
request, the request contains information about the user and the resolved selection criteria. When a media provider receives a request for music or other audio content, the provider responds with corresponding content identifiers. To satisfy a request to find music similar to the current song, the provider responds with identifiers for appropriate content recommendations.
The tabbed panels in the following tables show GetDisplayableContent
requests for various attributes.
Search, find, and browse
When users want to find a particular song or artist, or when they browse for new music that suits their preferences or mood, they use the Search, find, browse experience. Following are example utterances for this experience.
Alexa, show me songs by The Scorpions.
Alexa, show me hard rock songs.
Library content
A user can request displayable content by touch action from the Play tab of the Alexa mobile app. Content displayed in response to a touch-action request is called library content.
"Now Playing" recommendations
When an Alexa multimodal device, such as Echo Show or Fire TV, starts to play a new item, Alexa fetches contextual recommendations. The new item might be a song, a podcast episode, or a radio station. Alexa retrieves content identifiers for these contextual recommendations, and the items appear on the Now Playing screen. This experience is known as "Now Playing" recommendations.
End-of-queue recommendations
When all play queue items on an Alexa multimodal device finish playing, Alexa fetches contextual suggestions called end-of-queue recommendations. The end-of-queue recommendations experience is the same as the "Now playing" experience except that Alexa also shares the last item played in the queue. The following code example shows a typical request for the end-of-queue experience.
Non-contextual recommendations
On multimodal devices, recommendations from the user’s default music provider appear periodically on the Home Cards. These cards rotate on and off the screen when the device is not in use. Recommendations also appear in widgets. These experiences are known as non-contextual recommendations. Recommendations and widgets are enabled by default on multimodal devices, but users can opt out of them in Settings.
Editorial widgets
On multimodal devices, editorial widgets let content creators feature special content, such as "Top 10 Podcast Episodes" or "Best Songs of the '80s." Alexa initiates the widget experience with a GetDisplayableContent
request.
The following table shows payload details for the GetDisplayableContent
directive.
Field | Description | Type | Required |
---|---|---|---|
|
Unique identifier used to track a single request. |
String |
Yes |
|
Message payload version. Value is 2.0. |
String |
Yes |
|
Message category. Value is |
String |
Yes |
|
Message name. Value is |
String |
Yes |
|
Context information about the request. |
RequestContext object |
Yes |
|
Filters to apply during content resolution. |
Filters object |
Yes |
|
A list of target playback endpoints. For details, see the Endpoint object. |
Array of Endpoints objects |
No |
|
Maximum number of results returned |
Integer |
Yes |
|
A list of |
Array of |
Yes |
|
An object that specifies the number of items to be sent to the play queue for the preview during the playback initiation. This object accepts |
Object |
No |
GetDisplayableContent response
If your skill receives a GetDisplayableContent
request and finds displayable content to satisfy the request, it responds with GetDisplayableContent.Response
. The following table shows payload details for GetDisplayableContent.Response
.
Field | Description | Type | Required |
---|---|---|---|
|
Unique identifier used to track a single request. |
String |
Yes |
|
Version of the message payload. Value is |
String |
Yes |
|
Message category. Value is |
String |
Yes |
|
Message name. Value is |
String |
Yes |
|
List of objects, each of which describes a content item and associated metadata. |
Array of |
Yes |
ContentGroup object
The following table shows the ContentGroup
object. It contains a list of content to be rendered on a visual interface, and the metadata associated with that content.
Field | Description | Type | Required |
---|---|---|---|
|
Metadata associated with the |
Object |
Yes |
|
List of content in the |
Array of objects |
Yes |
ContentGroupMetadata object
The following table shows the ContentGroupMetadata
object. It contains a list of metadata for the items in the ContentGroup
.
Field | Description | Type | Yes |
---|---|---|---|
|
Localized name that describes an item in |
Object |
Yes |
GetDisplayableContent response structure
The following code example shows the response structure for a voice or touch-action GetDisplayableContent
request. The structure is the same for all GetDisplayableContent
experiences.
GetDisplayableContent directive error handling
If your skill can't handle a given GetDisplayableContent
directive, the skill must respond with a media-specific CONTENT_NOT_FOUND message. This message is associated with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For details, see Alexa Music, Radio, and Podcast Skill API Error Responses.
Related topics
- Alexa.Audio.PlayQueue
- Alexa.Media.PlayQueue
- Alexa.Media.Playback
- Alexa Music, Radio, and Podcast Skill API Components Reference
- Understand the Music, Radio, and Podcast Skill API
Last updated: Feb 09, 2024