Alexa.Media.PlayQueue Interface
The Alexa.Media.PlayQueue
interface helps users control playback of their music, radio, and podcast content. When you use this interface, the interaction model is built for you. User utterances prompt Alexa to send related directives to your skill. To see if this interface is supported in your locale, see the List of Capability Interfaces and Supported Locales.
Components
Music, radio, and podcast content is controlled by the Alexa.Media.PlayQueue
capability interface. This interface consists of queue controls, which apply to the play queue as a whole, and item controls, which apply to individual items like songs and episodes. These components let users initiate playback, view items on the screen, advance in the play queue, and shuffle, loop, or repeat content. The following table summarizes the components of the Alexa media play queue interface.
Component | Function | Type of playback control | Applicable content |
---|---|---|---|
|
Resumes playback of music content when the |
Item control |
Optional for music, radio, and podcast content |
|
Shows the current item and the next few items in the play queue. |
Item control |
Optional but recommended for music, radio, and podcast content |
|
Manages loop mode. |
Queue control |
Optional for music; not applicable to radio or podcast content |
|
Manages repeat mode. |
Queue control and item control |
Optional for music and podcasts; not applicable to radio content |
|
Manages shuffle mode. |
Queue control |
Optional for music; not applicable to radio or podcast content |
Configuration
Before Alexa uses the Alexa.Media.PlayQueue
interface, you must configure your skill to support it. You can use the developer console or the command line.
- If you build your skill in the Alexa Skills Kit (ASK) developer console, use the following instructions.
- On the Build tab, in the left navigation menu, click Interfaces.
- In the Audio player section, toggle the slider on.
- If you build your skill with the ASK Command Line Interface (CLI), configure the
Alexa.Media.PlayQueue
interface in the skill manifest JSON.
Item control directives
The item control directives in Alexa.Media.PlayQueue
are GetItem
and GetView
. These controls help users move around quickly and find what they want to hear.
GetItem directive
The Initiate
response includes a Stream
object that contains the request header and a uniform resource indicator (URI) for the first play queue item. You can support the GetItem
directive to let users resume playback of music, radio, or podcast content when the Stream
URI expires.
For example, a user listens to music on an Alexa-enabled device, and then says, "Alexa, pause." An hour later, the user says, "Alexa, resume my music." However, the Stream
URI for the item is now expired. To generate a new access token, Alexa calls GetItem
. Alexa then returns this fresh URI to the device, and playback resumes. If a user pauses for several hours, Alexa eventually forgets about the paused stream. If the user later asks Alexa to resume, Alexa asks what they want to hear, and then sends new GetPlayableContent
and Initiate
requests to the skill.
The GetItem
directive is optional. It's used primarily when a cached item expires and needs to be refreshed. If your skill's Stream
URIs don't expire, or if the URI expiration period (stream.validUntil
field) is always longer than 24 hours, your skill need not support the GetItem
API. If you're not sure, see Authorization code grant type for custom skills. The following table shows the information included in a GetItem
request.
Parameter | Description | Type | Required |
---|---|---|---|
|
Information about the audio quality streams supported on the target device. |
|
Yes |
|
The item to get. |
|
Yes |
GetItem request examples (music)
In the following example, a skill initiates playback of the first song. The user pauses the music, and the Stream
URI expires before playback resumes an hour later. Alexa sends a GetItem
request to obtain a new, valid Stream
URI.
If the provider supports premium audio (or audio quality streams in addition to the default), the request also contains an endpoint object that identifies the content types playable on the user's target device. The following GetItem
request example illustrates support for premium audio.
GetItem request example (podcast)
In the following example, a skill initiates playback of the first podcast episode in the skill's play queue. The user pauses the music, and the Stream
URI expires before playback resumes an hour later. Alexa sends a GetItem
request to obtain a new, valid Stream
URI.
GetItem response
A skill responds to a GetItem
directive with a GetItem.Response
event. As shown in the following table, the response header contains the typical response header fields.
Parameter | Description | Type | Required |
---|---|---|---|
|
Stores |
Object |
Yes |
|
Item requested from the play queue. |
|
Yes |
GetItem response examples (music)
In response to the preceding example request, the skill returns information about the item identified in the request. This information is shown in the following example.
If the provider supports premium audio, the preferred content type and quality is specified in the response as part of the Stream
object. Even if the provider accepts the default Alexa audio quality, a content format object that specifies the level of quality is returned in the response as part of the Stream
object. The following example illustrates support for premium audio.
The following example demonstrates support for digital rights management (DRM).
The following example adds a background image for Alexa to display during playback. For more information, see the background
field of the BaseMetadata
object.
GetItem response examples (podcast)
As shown in the following example, the skill returns information about the item identified in the request.
If the skill can't find the item identified in the request, it returns a media-specific error response. This error response is shown in the following example.
GetItem directive error
If the skill doesn't recognize a given content ID, it can't execute the GetItem
directive. It responds with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event that indicates ITEM_NOT_FOUND
. For details, see Alexa Music, Radio, and Podcast Skill API Error Response.
GetView directive
When a user navigates to the play queue view during playback on the Alexa app or on an Alexa-enabled multi-modal device, Alexa sends the skill a GetView
request. The skill response shows the current item and (optionally) a list of up to 10 items in the queue. The following table shows the information included in a GetView
request.
Parameter | Description | Type | Required |
---|---|---|---|
|
Information about the audio quality streams supported on the target device. |
|
Yes |
|
Object that identifies the current item in the play queue. |
|
Yes |
GetView directive example (music)
The following example shows the GetView
request Alexa sends when a user opens the "Now Playing" display during music playback.
GetView directive example (podcast)
When Alexa plays content from a podcast skill and the user opens the "Now Playing" screen in the Alexa app or accesses the "Now Playing" display on an Alexa-enabled multi-modal device, Alexa sends a GetView
request like the following example.
GetView response
When a skill handles a GetView
directive, it responds with an Alexa.Response
event. This event includes a list of other items in the play queue, as shown in the following table.
Parameter | Description | Type | Required |
---|---|---|---|
|
Stores |
Object |
Yes |
|
Controls used to manage the play queue in the Alexa app. |
List of |
Yes |
|
List that represents the active play queue. This list always includes the current item. If the response returns more than 10 items, Alexa discards the extra items. |
List of |
Yes |
GetView response example (music)
If the skill can return a list of other items in the music queue, it responds with a GetView.Response
message like the following example.
GetView response example (podcast)
If the skill can return a list of other items in the podcast queue, it responds with a GetView.Response
message like the following example.
GetView directive error
When a skill can't execute a GetView
directive, it responds with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Response.
Playback directives
The playback directives in the Alexa.Media.PlayQueue
are shown in the following table. They control playback modes and help users manage the playback of songs, albums, podcast episodes, and other content.
Parameter | Description | Type | Required |
---|---|---|---|
Flag to indicate if user asked for a looped queue. |
Boolean |
Yes | |
Indicator to show if user asked to repeat content. |
Object |
Yes | |
Flag to indicate if user asked for a shuffled queue. |
Boolean |
Yes |
The following table shows how Alexa interprets user utterances for each playback directive.
Utterance | Directive |
---|---|
User: Alexa, loop this album/artist/playlist. |
|
User: Alexa, repeat this album/playlist. |
|
User: Alexa, repeat this track. |
|
User: Alexa, shuffle this album/playlist. |
|
Loop directive
Loop mode repeats an album or playlist indefinitely. Support for the SetLoop
directive lets users turn loop mode on or off. Users can start music in loop mode with voice commands like those that follow.
User: Alexa, loop the album Diamonds, by Elton John.
User: Alexa, loop my yacht rock playlist.
When a user starts or stops loop mode during playback on an Alexa-enabled device, Alexa sends a SetLoop
request to the skill. This directive is optional. Implement it only if your music service supports loop mode. The following table describes the fields in a typical SetLoop
request.
Parameter | Description | Type | Required |
---|---|---|---|
|
Stores |
Object |
Yes |
|
Information about the audio quality streams supported on the target device. |
|
Yes |
|
Object that identifies the current item in the play queue. |
|
Yes |
|
Flag that indicates whether to enable or disable loop mode. |
Boolean |
Yes |
SetLoop request examples
Turn on loop mode
When a user asks Alexa to turn on loop mode, Alexa sends a SetLoop
request with loop mode enabled. The music skill responds with confirmation for the user that loop mode is now on.Users can request loop mode when playback is initiated, or they can switch to loop mode during playback.
User: Alexa, loop Santa Cumbia.
Alexa: Looping the album Santa Cumbia, by the Santa Fe Klan.
Parameter | Description | Type | Required |
---|---|---|---|
Status |
Specifies loop mode. |
|
Yes |
When a user turns on loop mode, Alexa sends a SetLoop
request like the following example.
Turn off loop mode
When a user turns off loop mode, Alexa sends a SetLoop
request with loop mode disabled. The music skill responds with confirmation for the user that loop mode is now off.
User: Alexa, stop looping this album.
Alexa: Loop mode off.
Parameter | Description | Type | Required |
---|---|---|---|
Status |
Specifies loop mode. |
|
Yes |
When a user turns off loop mode, Alexa sends a SetLoop
request like the following example.
When a user listens to the last track of an album with loop mode off, the GetNextItem
response indicates that there are no more items in the queue ("isQueueFinished": true
). However, when the last album track plays with loop mode enabled (that is, Alexa sends a SetLoop
request with "enable": true
), the GetNextItem
response returns the first track of the album. Similarly, with loop mode enabled and the first album track playing, a request for the previous item returns the last track of the album.
SetLoop response
When a skill handles a SetLoop
directive, the response is a generic Alexa.Response
event.
SetLoop directive error
When a skill can't execute a SetLoop
directive, it responds with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Response.
Repeat directive
Repeat mode supports the repetition of individual songs or podcast episodes. The function of repeat mode is to cycle through the specified playback content once, return to the beginning, and start playback again.
User: Alexa, play James Blunt's "Goodbye My Lover" on repeat.
User: Alexa, repeat "Shivers," by Ed Sheeran.
User: Alexa, repeat this Rammstein track.
When a user starts or stops repeat mode during playback on an Alexa-enabled device, Alexa sends a SetRepeat
request to the skill. This directive is optional. Implement it only if your music service supports repeat mode. The following table describes the fields in a typical SetRepeat
request.
Parameter | Description | Type | Required |
---|---|---|---|
|
Stores |
Object |
Yes |
|
Information about the audio quality streams supported on the target device. |
|
Yes |
|
Object that identifies the current item in the play queue. |
|
Yes |
|
Indicator to show if user asked to repeat content. |
Object |
Yes |
SetRepeat request examples
Turn on repeat mode
When a user asks Alexa to turn on repeat mode, Alexa sends a SetRepeat
request with repeat mode enabled. The music skill responds with confirmation for the user that repeat mode is now on. The track in progress continues until it reaches the end. Then the first repeat of the track begins. Users can enter repeat mode when they begin a new play queue or at any time after playback begins.
User: Alexa, turn on repeat.
Alexa: I will repeat this song.
Parameter | Description | Type | Required |
---|---|---|---|
Status |
Specifies the type of repeat mode. |
|
Yes |
When a user turns on repeat mode, Alexa sends a SetRepeat
request like the following example.
Turn off repeat mode
When a user turns off repeat mode, Alexa sends a SetRepeat
request with repeat mode disabled. The music skill responds with confirmation for the user that repeat mode is now off. The user can also turn off repeat mode by asking for new music.
User: Alexa, turn off repeat.
Alexa: Repeat mode off.
Parameter | Description | Type | Required |
---|---|---|---|
Status |
Specifies the type of repeat mode. |
|
Yes |
When a user turns off repeat mode, Alexa sends a SetRepeat
request like the following example.
SetRepeat response
When a skill handles a SetRepeat
directive, the response is a generic Alexa.Response event.
SetRepeat directive error
If a user does not have permission to repeat a track, or if your skill can't handle a SetRepeat
directive for another reason, it responds with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Response.
Shuffle directive
SetShuffle
is not supported for podcast skills.When a user asks for shuffle to be turned on or off, Alexa sends a SetShuffle
request to the skill. This directive is optional. Implement it only if your music service supports shuffle mode.
Shuffle mode request
When a user asks for music to be shuffled, or to turn off shuffle, Alexa sends the skill a SetShuffle
request. The Initiate request determines the initial shuffle mode for the queue. This request contains a playbackModes.shuffle
property that indicates whether to turn shuffle on or off for the queue. After a queue is created, SetShuffle
can change the shuffle mode while music is playing.
User: Alexa, shuffle songs by Elton John.
User: Alexa, shuffle this playlist.
User: Alexa, shuffle the album Diamonds, by Elton John.
User: Alexa, turn off shuffle.
A SetShuffle
request changes the skill's response to the next GetNextItem
request. The next item in the queue is discarded, because the switch to shuffle mode changes the track sequence. Therefore, immediately after a SetShuffle
request, Alexa sends a GetNextItem
request to prepare the correct next track to play. The skill must persist the current shuffle state (ON
or OFF
) and associate it with the play queue in progress.
For example, when a user listens to an album with shuffle mode off, a GetNextItem
response returns the next track in the album. If the user turns on shuffle mode (that is, Alexa sends a SetShuffle
request with "enable": true
), the skill shuffles the album queue and responds to the next GetNextItem
request with an out-of-order track. If the user turns off shuffle mode (that is, Alexa sends a SetShuffle
request with "enable": false
), the skill responds to the next GetNextItem
request with the next track in the album.
The following table describes the fields in a typical SetShuffle
request.
Parameter | Description | Type | Required |
---|---|---|---|
|
Stores |
Object |
Yes |
|
Information about the audio quality streams supported on the target device. |
|
Yes |
|
Object that identifies the current item in the play queue. |
|
Yes |
|
Flag that indicates whether to enable or disable shuffle mode. |
Boolean |
Yes |
SetShuffle request examples
Turn on shuffle mode
When a user asks to turn on shuffle mode, Alexa sends a SetShuffle
request with shuffle mode enabled. The music skill responds with confirmation for the user that shuffle mode is now on. Users can request shuffle when playback is initiated, or they can switch to shuffle mode during playback.
User: Alexa, shuffle this playlist.
Alexa: Shuffling your playlist.
Parameter | Description | Type | Required |
---|---|---|---|
Status |
Specifies shuffle mode. |
|
Yes |
When a user turns on shuffle mode, Alexa sends a SetShuffle
request like the following example.
Turn off shuffle mode
When a user asks Alexa to turn off shuffle mode, Alexa sends a SetShuffle
request with shuffle mode disabled. The music skill responds with confirmation for the user that shuffle mode is now off. Shuffle mode also ends if the user asks for new music.
User: Alexa, stop shuffling.
Alexa: Shuffle mode off.
Parameter | Description | Type | Required |
---|---|---|---|
Status |
Specifies shuffle mode. |
|
Yes |
When shuffle mode is turned off, Alexa sends a SetShuffle
request like the following example.
SetShuffle response
When a skill handles a SetShuffle
directive, the response is an Alexa.Response
event.
SetShuffle directive error
When a skill can't execute a SetShuffle
directive, it responds with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Response.
Related topics
- Alexa.Media.Search
- Alexa.Media.Playback
- Alexa.Audio.PlayQueue
- Understand the Music, Radio, and Podcast Skill API
- Alexa Music, Radio, and Podcast Skill API Components Reference
Last updated: Nov 27, 2023