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:

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

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

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.