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 music 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.

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 API 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 does not expire stream URIs, or if the URI expiration period (stream.validUntil field) is always longer than 24 hours, your skill does not 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 example

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.

{
    "header": {
      "namespace": "Alexa.Media.PlayQueue",
      "name": "GetItem",
      "messageId": "<message id, a 25-character random alphanumeric string>",
      "payloadVersion": "1.0"
    },
    "payload": {
      "requestContext": {
        "user": {
          "id": "amzn1.ask.account.AAAAABBBBBCCCCCDDDDDEEEEEFFFFFGGGGGHHHHH",
          "accessToken": "<an OAuth2 bearer token>"
        },
        "location": {
          "originatingLocale": "en-US"
        }
      },
      "targetItemReference": {
        "namespace": "Alexa.Audio.PlayQueue",
        "name": "item",
        "value": {
          "id": "<item GUID>",
          "queueId": "<queue GUID>",
          "contentId": "<content GUID>"
        }
      }
    }
}

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 example

In response to the preceding example request, the skill returns information about the item identified in the request, as shown in the following example.

{
    "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-file.mp3",
          "offsetInMilliseconds": 0,
          "validUntil": "2018-05-10T19:11:35Z"
        },
        "feedback": {
          "type": "PREFERENCE",
          "value": "POSITIVE"
        }
      }
    }
}

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 and Radio Skill API Error Responses. Use the ITEM_NOT_FOUND error type if the item ID is not recognized.

GetView directive

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.

When music 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.

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

{
    "header": {
      "namespace": "Alexa.Media.PlayQueue",
      "name": "GetView",
      "messageId": "<message id, a 25-character random alphanumeric string>",
      "payloadVersion": "1.0"
    },
    "payload": {
      "requestContext": {
        "user": {
          "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
          "accessToken": "e72e16c7e710c838347ae178b4a"
        },
        "location": {
          "originatingLocale": "en-US"
        }
      },
      "currentItemReference": {
        "namespace": "Alexa.Audio.PlayQueue",
        "name": "item",
        "value": {
          "id": "e73befbe-8c27-4e4b-9865ce8516f0",
          "queueId": "76f325d5-a648-87ad-6e53cf99e4c7",
          "contentId": "1021012f-12bb-9723-067a4338b6d0"
        }
      }
    }
}

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 The currently playing item and upcoming items in the active queue. The maximum number of items that Alexa reads is ten. A list of Item objects. Yes

GetView Response event example

If the skill can return a list of upcoming items, it should respond with a GetView.Response message like the following example.

{
    "header": {
        "namespace": "Alexa.Audio.PlayQueue",
        "name": "GetView.Response",
        "messageId": "<message id, a 25-character random alphanumeric string>",
        "payloadVersion": "1.0"
    },
    "payload": {
      "queueControls": [
        {
          "type": "TOGGLE",
          "name": "SHUFFLE",
          "enabled": true,
          "selected": false
        },
        {
          "type": "TOGGLE",
          "name": "LOOP",
          "enabled": true,
          "selected": false
        }
      ],
      "items": [
        {
          "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
          "playbackInfo": {
            "type": "DEFAULT"
          },
          "metadata": {
            "type": "TRACK",
            "name": {
              "speech": {
                "type": "PLAIN_TEXT",
                "text": "alive"
              },
              "display": "Alive"
            },
            "art": {
              "sources": [
                {
                  "url": "https://images.example.com/images/cover/album-art.jpg",
                  "size": "X_SMALL",
                  "widthPixels": 48,
                  "heightPixels": 48
                }
              ]
            }
          },
          "durationInMilliseconds": 428000,
          "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-file.mp3",
            "offsetInMilliseconds": 0,
            "validUntil": "2018-05-10T19:11:35Z"
          },
          "feedback": {
            "type": "PREFERENCE",
            "value": "POSITIVE"
          }
        },
        {
          "id": "533718fe-b22d-4f64-8b1c-49ffdb85f619",
          "playbackInfo": {
            "type": "DEFAULT"
          },
          "metadata": {
            "type": "TRACK",
            "name": {
              "speech": {
                "type": "PLAIN_TEXT",
                "text": "porch"
              },
              "display": "Porch"
            },
            "art": {
              "sources": [
                {
                  "url": "https://images.example.com/images/cover/album-art.jpg",
                  "size": "X_SMALL",
                  "widthPixels": 48,
                  "heightPixels": 48
                }
              ]
            }
          },
          "durationInMilliseconds": 449000,
          "controls": [
            {
              "type": "COMMAND",
              "name": "NEXT",
              "enabled": false
            },
            {
              "type": "COMMAND",
              "name": "PREVIOUS",
              "enabled": false
            }
          ],
          "rules": {
            "feedbackEnabled": true
          },
          "stream": {
            "id": "STREAMID_92_14629005",
            "uri": "https://cdn.example.com/api/1/streaming-file.mp3",
            "offsetInMilliseconds": 0,
            "validUntil": "2018-05-10T19:11:35Z"
          },
          "feedback": {
            "type": "PREFERENCE",
            "value": "POSITIVE"
          }
        }
      ]
    }
}

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 and Radio Skill API Error Responses.

SetLoop directive

Support the SetLoop directive so that customers can turn loop mode on or off.

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 does not 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 like the following example.

{
  "header": {
    "messageId": "<message id, a 25-character random alphanumeric string>",
    "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": "<message id, a 25-character random alphanumeric string>",
    "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 and Radio 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.

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": "<message id, a 25-character random alphanumeric string>",
    "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": "<message id, a 25-character random alphanumeric string>",
    "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 and Radio Skill API Error Responses.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment