Note:Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.
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
GetItem
Resumes playback of music content when the Stream URI expires.
Item control
Optional for music, radio, and podcast content
GetView
Shows the current item and the next few items in the play queue.
Item control
Optional but recommended for music, radio, and podcast content
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.
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
requestContext
Information about the audio quality streams supported on the target device.
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.
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.
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
Header
Stores namespace, messageId, payloadVersion, and related properties.
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.
Copied to clipboard.
{"header":{"namespace":"Alexa.Audio.PlayQueue","name":"GetItem.Response","messageId":"<message id, a 25-character random alphanumeric string>","payloadVersion":"1.0"},"payload":{"item":{"id":"e73befbe-8c27-4e4b-ab0c-9865ce8516f0","playbackInfo":{"type":"DEFAULT"},"metadata":{"type":"TRACK","name":{"speech":{"type":"PLAIN_TEXT","text":"Float On"},"display":"float on"},"art":{"sources":[{"url":"https://images.example.com/images/cover/album-art.jpg","size":"X_SMALL","widthPixels":48,"heightPixels":48},{"url":"https://images.example.com/images/cover/album-art.jpg","size":"SMALL","widthPixels":60,"heightPixels":60},{"url":"https://images.example.com/images/cover/album-art.jpg","size":"MEDIUM","widthPixels":110,"heightPixels":110},{"url":"https://images.example.com/images/cover/album-art.jpg","size":"LARGE","widthPixels":256,"heightPixels":256},{"url":"https://images.example.com/images/cover/album-art.jpg","size":"X_LARGE","widthPixels":600,"heightPixels":600}]}},"durationInMilliseconds":208000,"controls":[{"type":"COMMAND","name":"NEXT","enabled":true},{"type":"COMMAND","name":"PREVIOUS","enabled":false}],"rules":{"feedbackEnabled":true},"stream":{"id":"STREAMID_92_14629004","uri":"https://cdn.example.com/api/1/streaming-dash-manifest.mpd","offsetInMilliseconds":0,"validUntil":"2021-05-10T19:11:35Z","contentFormat":{"type":"AUDIO","contentTypeId":"CT-1236"}},"feedback":{"type":"PREFERENCE","value":"POSITIVE"}}}}
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.
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.
Copied to clipboard.
{"header":{"messageId":"2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b","namespace":"Alexa.Media","name":"ErrorResponse","payloadVersion":"1.0"},"payload":{"type":"ITEM_NOT_FOUND","message":"The item does not exist"}}
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
requestContext
Information about the audio quality streams supported on the target device.
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.
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
Header
Stores namespace, messageId, payloadVersion, and related properties.
Object
Yes
queueControls
Controls used to manage the play queue in the Alexa app.
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.
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.
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.
LOOP_QUEUE
User: Alexa, repeat this album/playlist.
LOOP_QUEUE
User: Alexa, repeat this track.
REPEAT_TRACK_INFINITELY
User: Alexa, shuffle this album/playlist.
SHUFFLE
Loop directive
Note: Loop mode is not supported for podcast skills.
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
Header
Stores namespace, messageId, payloadVersion, and related properties.
Object
Yes
requestContext
Information about the audio quality streams supported on the target device.
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.
ENUM (ON)
Yes
When a user turns on loop mode, Alexa sends a SetLoop request like the following example.
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.
ENUM (OFF)
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.
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.
Note: When a user turns on repeat mode, the selected content is repeated until repeat mode is ended or the music or podcast is turned off.
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
Header
Stores namespace, messageId, payloadVersion, and related properties.
Object
Yes
requestContext
Information about the audio quality streams supported on the target device.
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.
ENUM (ON)
Yes
When a user turns on repeat mode, Alexa sends a SetRepeat request like the following example.
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.
ENUM (OFF)
Yes
When a user turns off repeat mode, Alexa sends a SetRepeat request like the following example.
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
Note: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
Header
Stores namespace, messageId, payloadVersion, and related properties.
Object
Yes
requestContext
Information about the audio quality streams supported on the target device.
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.
ENUM (ON)
Yes
When a user turns on shuffle mode, Alexa sends a SetShuffle request like the following example.
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.
ENUM (OFF)
Yes
When shuffle mode is turned off, Alexa sends a SetShuffle request like the following example.