Alexa.Media.PlayQueue Interface

Note: Sign in to the developer console to build or publish your skill.

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
`SetLoop`	Manages loop mode.	Queue control	Optional for music; not applicable to radio or podcast content
`SetRepeat`	Manages repeat mode.	Queue control and item control	Optional for music and podcasts; not applicable to radio content
`SetShuffle`	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
`requestContext`	Information about the audio quality streams supported on the target device.	`RequestContext` object	Yes
`targetItemReference`	The item to get.	`MediaReference` object	Yes

Music
Podcast

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
`Header`	Stores `namespace`, `messageId`, `payloadVersion`, and related properties.	Object	Yes
`item`	Item requested from the play queue.	`Item` object	Yes

Music
Podcast

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.

Copied to clipboard.

{
  "header": {
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetItem.Response",
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "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"
      }
    }
  }
}

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

Copied to clipboard.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetItem.Response",
    "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": []
        }
      },
      "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": "2018-05-10T19:11:35Z",
        "contentTypeId": "CT_EXAMPLE_DRM",
        "requestHeaders": [
          {
            "type": "KEY",
            "headers": [
              {
                "name": "X-AlexaMusic-ExampleMsp-LicenseToken",
                "value": "fbfd3378-a72d-45ef-9782-4edf140f5dd7"
              }
            ]
          },
          {
            "type": "MANIFEST",
            "headers": [
              {
                "name": "X-AlexaMusic-ExampleMsp-ManifestUrl",
                "value": "https://amazonMusic.com/manifest/track"
              }
            ]
          },
          {
            "type": "AUDIOSEGMENT",
            "headers": [
              {
                "name": "X-AlexaMusic-ExampleMsp-SegmentAsin",
                "value": "B07ZQ7Z83Y"
              }
            ]
          },
          {
            "type": "ALL",
            "headers": [
              {
                "name": "X-AlexaMusic-ExampleMsp-RequestId",
                "value": "0fe36d7f-6d67-4367-b5df-6a9505e5a5ef"
              }
            ]
          }
        ]
      },
      "feedback": {
        "type": "PREFERENCE",
        "value": "POSITIVE"
      }
    }
  }
}

The following example adds a background image for Alexa to display during playback. For more information, see the background field of the BaseMetadata object.

Copied to clipboard.

{
  "header": {
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetItem.Response",
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "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
            }
          ]
        },
        "background": {
          "type": "STATIC_IMAGES",
          "images": [
            {
              "art": {
                "contentDescription": "",
                "sources": [
                  {
                    "url": "url",
                    "size": "LARGE"
                  }
                ]
              }
            }
          ]
        }
      },
      "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 response examples (podcast)

As shown in the following example, the skill returns information about the item identified in the request.

Copied to clipboard.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetItem.Response",
    "payloadVersion": "1.0"
  },
  "payload": {
    "item": {
      "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
      "playbackInfo": {
        "type": "DEFAULT"
      },
      "metadata": {
        "type": "PROGRAM",
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "[PROGRAM_NAME]"
          },
          "display": "[PROGRAM_NAME]"
        },
        "series": {
          "name": {
            "speech": {
              "type": "PLAIN_TEXT",
              "text": "[PROGRAM_SERIES_NAME]"
            },
            "display": "[PROGRAM_SERIES_NAME]"
          }
        },
        "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": true
        },
        {
          "type": "ADJUST",
          "name": "SEEK_POSITION",
          "enabled": true
        }
      ],
      "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"
      }
    }
  }
}

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
`requestContext`	Information about the audio quality streams supported on the target device.	`RequestContext` object	Yes
`currentItemReference`	Object that identifies the current item in the play queue.	`ItemReference` object	Yes

Music
Podcast

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
`Header`	Stores `namespace`, `messageId`, `payloadVersion`, and related properties.	Object	Yes
`queueControls`	Controls used to manage the play queue in the Alexa app.	List of `queueControls` objects	Yes
`items`	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 `Item` objects	Yes

Music
Podcast

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.

Copied to clipboard.

{
  "header": {
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetView.Response",
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "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 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.

Copied to clipboard.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetView.Response",
    "payloadVersion": "1.0"
  },
  "payload": {
    "queueControls": [
      {
        "type": "TOGGLE",
        "name": "SHUFFLE",
        "enabled": false,
        "selected": false
      },
      {
        "type": "TOGGLE",
        "name": "LOOP",
        "enabled": false,
        "selected": false
      },
      {
        "type": "ADJUST",
        "name": "SEEK_POSITION",
        "enabled": true
      }
    ],
    "items": [
      {
        "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
        "playbackInfo": {
          "type": "DEFAULT"
        },
        "metadata": {
          "type": "PROGRAM",
          "name": {
            "speech": {
              "type": "PLAIN_TEXT",
              "text": "[PROGRAM_NAME]"
            },
            "display": "[PROGRAM_NAME]"
          },
          "series": {
            "name": {
              "speech": {
                "type": "PLAIN_TEXT",
                "text": "[PROGRAM_SERIES_NAME]"
              },
              "display": "[PROGRAM_SERIES_NAME]"
            }
          },
          "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": 428000,
        "controls": [
          {
            "type": "COMMAND",
            "name": "NEXT",
            "enabled": true
          },
          {
            "type": "COMMAND",
            "name": "PREVIOUS",
            "enabled": true
          },
          {
            "type": "ADJUST",
            "name": "SEEK_POSITION",
            "enabled": true
          }
        ],
        "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": "PROGRAM",
          "name": {
            "speech": {
              "type": "PLAIN_TEXT",
              "text": "[PROGRAM_NAME]"
            },
            "display": "[PROGRAM_NAME]"
          },
          "series": {
            "name": {
              "speech": {
                "type": "PLAIN_TEXT",
                "text": "[PROGRAM_SERIES_NAME]"
              },
              "display": "[PROGRAM_SERIES_NAME]"
            }
          },
          "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": 449000,
        "controls": [
          {
            "type": "COMMAND",
            "name": "NEXT",
            "enabled": true
          },
          {
            "type": "COMMAND",
            "name": "PREVIOUS",
            "enabled": true
          },
          {
            "type": "ADJUST",
            "name": "SEEK_POSITION",
            "enabled": true
          }
        ],
        "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

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
`LOOP`	Flag to indicate if user asked for a looped queue.	Boolean	Yes
`REPEAT`	Indicator to show if user asked to repeat content.	Object	Yes
`SHUFFLE`	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.	`RequestContext` object	Yes
`currentItemReference`	Object that identifies the current item in the play queue.	`ItemReference` object	Yes
`enable`	Flag that indicates whether to enable or disable loop mode.	Boolean	Yes

SetLoop request examples

SetLoop on
SetLoop off

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.	`ENUM` (`ON`)	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.	`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.

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.

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.	`RequestContext` object	Yes
`currentItemReference`	Object that identifies the current item in the play queue.	`ItemReference` object	Yes
`mode`	Indicator to show if user asked to repeat content.	Object	Yes

SetRepeat request examples

SetRepeat on
SetRepeat off

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.	`ENUM` (`ON`)	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.	`ENUM` (`OFF`)	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

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.	`RequestContext` object	Yes
`currentItemReference`	Object that identifies the current item in the play queue.	`ItemReference` object	Yes
`enable`	Flag that indicates whether to enable or disable shuffle mode.	Boolean	Yes

SetShuffle request examples

SetShuffle on
SetShuffle off

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.	`ENUM` (`ON`)	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.	`ENUM` (`OFF`)	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.

Last updated: Mar 22, 2023

Alexa.Media.PlayQueue Interface

Components

Configuration

Item control directives

GetItem directive

GetItem response

GetItem directive error

GetView directive

GetView response

GetView directive error

Playback directives

Loop directive

SetLoop response

SetLoop directive error

Repeat directive

SetRepeat response

SetRepeat directive error

Shuffle directive

Shuffle mode request

SetShuffle response

SetShuffle directive error

Related topics