Alexa.Media.PlayQueue Interface
Implement the Alexa.Media.PlayQueue
capability interface to enable users to view upcoming items in the play queue, advance in the queue, and turn shuffle or loop on or off.
Utterances
When you use the Alexa.Audio.PlayQueue
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, shuffle.
Alexa, shuffle the album Gemini by Macklemore.
Alexa, loop the album Gemini by Macklemore.
Alexa, shuffle songs by Lady Gaga.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Configure your skill to receive requests
You must configure your skill to support this API before Alexa will send requests to it. You can configure your skill in the following ways:
- If you build your skill by using the Alexa Skills Kit developer console, configure it on the Interfaces page.
- If you build your skill by using the ASK CLI, configure it in your skill manifest JSON.
Directives
GetItem directive
Support the GetItem
directive so that customers can pause and resume playing music when the item's stream URI has expired. The following table shows which content types use this directive:
Content type | Required? |
---|---|
Music | Optional |
Radio | Optional |
Podcast | Optional |
If an item's stream URI has expired, Alexa sends a GetItem
request to obtain a new (refreshed) URI to begin playback on an Alexa device. This directive is optional. Implement this directive only if the stream URIs returned by your music service cloud can expire.
The primary use case for this directive is when an item cached by Alexa is expired and needs to be refreshed. For example, a user is listening to music on their Alexa device, and then says, "Alexa, pause." One hour later, the user says, "Alexa, resume" but the stream URI for the item is now expired (based on the item's stream.validUntil
field). In this scenario, Alexa calls GetItem
to receive a new stream URI, and then sends the new stream URI to the device to resume playback.
If your skill doesn't expire stream URIs, or if the URI expiration period
(stream.validUntil
field) is always longer than 24 hours, your skill doesn't need to support the GetItem
API. When a user pauses for an extended period of time (many hours), Alexa eventually forgets about the paused stream. In these cases, when a user later asks "Alexa, resume," Alexa asks the user what she or he would like to hear and then sends new GetPlayableContent
and Initiate
requests to the skill.
GetItem directive payload details
Field | Description | Type |
---|---|---|
requestContext |
Context information about the request. | A RequestContext object. |
targetItemReference |
The item to get. | A MediaReference object. |
GetItem directive examples (music)
In the following example, Alexa is playing the first song from a skill's Initiate
response. The user pauses playback, then one hour later says "Alexa, resume." The stream URI is now expired, so Alexa sends a GetItem
request to obtain a new, non-expired stream URI.
If the provider supports premium audio (or audio quality streams in addition to the default), the request also contains an endpoint object which lists the provider's content type identifiers that are playable on the target device. The following GetItem
request example illustrates support for premium audio.
GetItem directive example (podcast)
In the following example, Alexa is playing the first program from a skill's Initiate
response. The user pauses playback, then one hour later says "Alexa, resume." The stream URI is now expired, so Alexa sends a GetItem
request to obtain a new, non-expired stream URI.
GetItem response event
If you handle a GetItem
directive successfully, respond with a GetItem.Response
event. The response header contains the common response header fields.
GetItem response event payload details
Field | Description | Type | Required |
---|---|---|---|
item |
The requested item in the play queue. | An Item object. | Yes |
GetItem response event examples (music)
In response to the preceding example request, the skill returns information about the item identified in the request, as shown in the following example.
If the provider supports premium audio, one of the content types in the request will have been selected as the most appropriate type of audio quality to provide to the customer. Whichever is the selected content format should be returned as part of the stream object in the response. Even if the provider selects the default Alexa audio quality for the response, a content format object for that quality should be returned 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 while playing music. For more information, see the background
field of the BaseMetadata object.
GetItem response event examples (podcast)
In response to the preceding example request, the skill returns information about the item identified in the request, as shown in the following example.
If the skill can't find the item identified in the request, it returns a media-specific error response as in the following example.
GetItem directive error handling
If your skill can't handle a GetItem
directive successfully, it should respond with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses. Use the ITEM_NOT_FOUND
error type if the item ID isn't recognized.
GetView directive
When music or a program is playing on an Alexa device and the user navigates to the "play queue" view in the Alexa app, Alexa sends a GetView
request to the skill. The skill responds with the item currently playing and (optionally) a list of up to ten upcoming items for display in the app or on a device screen. Alexa uses the response only for display so that users can see the items that are coming up next. The following table shows which content types use this directive:
Content type | Required? |
---|---|
Music | Optional but recommended |
Radio | Optional but recommended |
Podcast | Optional but recommended |
GetView directive payload details
Field | Description | Type |
---|---|---|
requestContext |
Context information about the request. | A RequestContext object. |
currentItemReference |
The currently playing item. Your skill should use the identifiers here to find the play queue for which Alexa is requesting items. | An ItemReference. |
GetView directive example (music)
When Alexa is playing music from a music skill and the user opens the "Now Playing" screen in the Alexa app or accesses the "Now Playing" display on an Alexa-enabled device with a screen, Alexa sends a GetView
request like the following example.
GetView directive example (podcast)
When Alexa is playing music from a music skill and the user opens the "Now Playing" screen in the Alexa app, Alexa sends a GetView request like the following example.
GetView response event
If you handle a GetView
directive successfully, respond with an Alexa.Response event. In the response, return a list of upcoming items.
GetView response event payload details
Field | Description | Type | Required |
---|---|---|---|
queueControls |
The controls to enable in the Alexa app. | A list of QueueControl objects. | Yes |
items |
A list of up to ten items. This list represents the active queue and should always include the currently playing item. Note: If the response contains more than ten items, Alexa discards the extra items. |
A list of Item objects. | Yes |
GetView response event example (music)
If the skill can return a list of upcoming items, it should respond with a GetView.Response
message, as shown in the following example.
GetView response event example (podcast)
If the skill can return a list of upcoming items, it should respond with a GetView.Response
message, as shown in the following example.
GetView directive error handling
If your skill can't handle a GetView
directive successfully, it should respond with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses.
SetLoop directive
SetLoop
isn't supported for podcast skills.Support the SetLoop
directive so that customers can turn loop mode on or off. The following table shows which content types use this directive:
Content type | Required? |
---|---|
Music | Optional |
Radio | Not applicable |
Podcast | Not applicable |
When music is playing on an Alexa device and the user makes a request to enable or disable loop mode, Alexa sends a SetLoop
request to the skill. This directive is optional. Implement this directive only if your music service supports loop mode.
Whenever a user asks for music to be looped, or to turn off loop, Alexa sends a SetLoop
request. The skill must persist the current loop state (on or off) and associate it to the currently playing queue of music.
For example, when a user is listening to the last track of an album with loop mode off, a GetNextItem
response should indicate that there are no more items in the queue ("isQueueFinished": true
). However, when a user turns on loop mode (Alexa sends a SetLoop
request with "enable": true
), a GetNextItem
response should return the first track of the album when the last track of the album is playing. Similarly, with loop mode on, a GetPreviousItem
response should return the last track of the album when the first track is playing.
The Alexa Music Skill API doesn't provide a way for a user to ask for music to start playing with loop mode on. When music is playing, however, the user can turn on or off loop mode through voice commands such as "Alexa, loop" or "Alexa, turn off loop".
The following example shows a customer utterance:
Alexa, loop.
SetLoop directive payload details
The following table describes the fields in the payload of a SetLoop
request.
Field | Description | Type |
---|---|---|
requestContext |
An object containing context information about the request. See the RequestContext object for more information. | object |
currentItemReference |
An object identifying the currently playing item. See the ItemReference object for more information. | object |
enable |
A flag that indicates whether to enable or disable loop mode. | Boolean |
SetLoop turn on loop mode directive example
When a user asks Alexa to turn on loop mode, Alexa sends a SetLoop
request as shown in the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "SetLoop",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
},
"enable": true
}
}
SetLoop turn off loop mode directive example
When a user asks Alexa to turn off loop mode, Alexa sends a SetLoop
request like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "SetLoop",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
},
"enable": false
}
}
SetLoop response event
If you handle a SetLoop
directive successfully, respond with a generic Alexa.Response event.
SetLoop directive error handling
If your skill can't handle a SetLoop
directive successfully, it should respond with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses.
SetShuffle directive
SetShuffle
isn't supported for podcast skills.When music is playing on an Alexa device and the user makes a request to enable or disable shuffle mode, Alexa sends a SetShuffle
request to the skill. This directive is optional. Implement this directive only if your music service supports shuffle mode. The following table shows which content types use this directive:
Content type | Required? |
---|---|
Music | Optional |
Radio | Not applicable |
Podcast | Not applicable |
Whenever a user asks for music to be shuffled, or to turn off shuffle, Alexa sends a SetShuffle
request. Example utterances include "Alexa, shuffle" and "Alexa, turn off shuffle". A SetShuffle
request likely changes the skill's response to the next GetNextItem
request. The skill must persist the current shuffle state (on or off) and associate it to the currently playing queue of music.
For example, when a user is listening to an album with shuffle mode off, a GetNextItem
response should return the next track in the album. If shuffle mode is turned on by the user (Alexa sends a SetShuffle
request with "enable": true
), the skill should shuffle the album queue and respond to the next GetNextItem
request with an out-of-order track. If shuffle mode is turned off by the user (Alexa sends a SetShuffle
request with "enable": false
), the skill should respond to the next GetNextItem
request with the following track in the album.
The Initiate request determines the initial shuffle mode for the queue. The Initiate
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 from the queue is playing.
After Alexa sends a SetShuffle
request, Alexa discards the next item in the queue because changing the shuffle mode likely changes which track should be played next. Therefore, immediately after a SetShuffle
request, Alexa sends a GetNextItem
request to prepare the correct next track to play.
The following example shows a customer utterance:
Alexa, shuffle.
SetShuffle directive payload details
The following table describes the fields in the payload of a SetShuffle
request.
Field | Description | Type |
---|---|---|
requestContext |
An object containing context information about the request. See the RequestContext object for more information. | object |
currentItemReference |
An object identifying the currently playing item. See the ItemReference object for more information. | object |
enable |
A flag that indicates whether to enable or disable shuffle mode. | Boolean |
SetShuffle directive turn on shuffle example
When a user asks Alexa to turn on shuffle mode, Alexa sends a SetShuffle
request like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "SetShuffle",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
},
"enable": true
}
}
SetShuffle directive turn off shuffle example
When a user asks Alexa to turn off shuffle mode, Alexa sends a SetShuffle
request like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "SetShuffle",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
},
"enable": false
}
}
SetShuffle response event
If you handle a SetShuffle
directive successfully, respond with an Alexa.Response event.
SetShuffle directive error handling
If your skill can't handle a SetShuffle
directive successfully, it should respond with an Alexa.Media.ErrorResponse
event or an Alexa.ErrorResponse
event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses.