Alexa.Media.Playback Interface

The Alexa.Media.Playback interface enables Alexa to start immediate playback of content on an Alexa device.

Understand ContentId

To build a high quality music skill, you must understand ContentId. ContentId identifies a music listening experience that a skill can return and play on a device. A ContentId can reference a track, an editorial playlist of popular songs, a custom (artist or genre seeded) station, or an album.

ContentId must be globally unique within your skill, long-lived, and always represent the same experience for all skill users. For example, imagine that Alice asks "Alexa, play the album Rainier Fog by Alice in Chains", and the skill returns a ContentId of "123" to represent the album. This same ContentId should represent this album for all users. When Bob asks "Alexa, play the album Rainier Fog by Alice in Chains", your skill should send the same ContentId of "123" in response to the GetPlayableContent request, even if the request happens one year after Alice's request.

Here is another example: Imagine that your music service has a "Top Weekly Songs" playlist, where the list of songs in the playlist changes from week to week to reflect the most popular songs on the charts. Alice asks "Alexa, play the top weekly songs playlist". Your skill responds with a ContentId of "321" which represents the "Top Weekly Songs" playlist. When Alexa sends this ContentId in an Initiate request, your skill returns the first track of the playlist, for example Shallow by Lady Gaga. One month later, Alice asks "Alexa, play the top weekly songs playlist". Your skill again responds with a ContentId of "321" because this ContentId always represents the "Top Weekly Songs" playlist. However, this time when Alexa sends this ContentId in an Initiate request, your skill returns, for example, the song Better Now by Post Malone, because the playlist contents change weekly.

When a user sets a music alarm (for example, "Alexa, wake me up to Can't Stop The Feeling by Justin Timberlake from skill name at 8 AM"), Alexa saves the ContentId returned in the GetPlayableContent response. Each time the alarm is triggered, which might be months later for a repeating alarm, Alexa sends an Initiate request to your skill with the saved ContentId, and the response should reflect the content the user requested when setting the alarm.

Similarly, when a user browses their history of music requests and selects an item to replay, Alexa calls Initiate with the saved ContentId. In the preceding example for "Top Weekly Songs", if the user sees "Top Weekly Songs" in their history and clicks to play it again, Alexa sends an Initiate request with a ContentId of "321". The resulting queue of songs might be different because the playlist changes weekly, but the user is still listening to the "Top Weekly Songs" playlist, so the result is correct.

Utterances

When you use the Alexa.Media.Playback interface, the voice interaction model is already built for you. The following example show a customer utterance:

• English

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:

• 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

Initiate directive

When Alexa receives a content identifier from a skill's GetPlayableContent response and is ready to start immediate playback of the content on an Alexa device, Alexa sends an Initiate request. The request includes the content identifier, and the skill responds with the stream URI for immediate playback of the content.

There are three primary scenarios that cause Alexa to call this API:

1. The user requested music to play, so playback is initiated immediately.
2. A previously set music alarm is triggered. For example, the user set an alarm to play a song at 7:00 AM, so at that time Alexa makes an Initiate call to the skill.
3. The user selects content from a play history UI that shows (for example in the Alexa app, or on an Alexa device with a screen) to hear the content again.

Initiate directive payload details

Initiate directive with no current content example

{
    "header": {
      "namespace": "Alexa.Media.Playback",
      "name": "Initiate",
      "messageId": "<message id, a 25-character random alphanumeric string>",
      "payloadVersion": "1.0"
    },
    "payload": {
      "requestContext": {
        "user": {
          "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
          "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
        },
        "location": {
          "originatingLocale": "en-US"
        }
      },
      "filters": {
        "explicitLanguageAllowed": true
      },
      "contentId": "1021012f-12bb-4938-9723-067a4338b6d0",
      "playbackModes": {
        "shuffle": false,
        "loop": false
      }
    }
}

Initiate directive with current content example

{
    "header": {
      "namespace": "Alexa.Media.Playback",
      "name": "Initiate",
      "messageId": "<message id, a 25-character random alphanumeric string>",
      "payloadVersion": "1.0"
    },
    "payload": {
        "requestContext": {
          "user": {
            "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
            "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
          },
          "location": {
            "originatingLocale": "en-US"
          }
        },
        "filters": {
          "explicitLanguageAllowed": true
        },
        "contentId": "1021012f-12bb-4938-9723-067a4338b6d0",
        "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"
          }
        },
        "playbackModes": {
          "shuffle": false,
          "loop": false
        }
    }
}

Initiate response event

If you handle a Initiate directive successfully, respond with an Alexa.Response event.

In response to the first of the preceding examples, the skill creates a queue for the user based on the requested ContentId and returns the queue identifier and the first audio item to Alexa. The Initiate response should contain enough information for Alexa to know how to manage the queue, and the first track to play for the user. To get the second track to play for the user, Alexa calls GetNextItem after beginning to play the first track. Subsequent tracks are also retrieved with GetNextItem after each track begins playback.

The time it takes your skill to respond to an Initiate request directly impacts the Alexa user experience. Music skills should adhere to the following response latency limits.

Initiate response event payload details

Initiate Response event example

{
    "header": {
        "namespace": "Alexa.Media.Playback",
        "name": "Initiate.Response",
        "messageId": "<message id, a 25-character random alphanumeric string>",
        "payloadVersion": "1.0"
    },
    "payload": {
      "playbackMethod": {
        "type": "ALEXA_AUDIO_PLAYER_QUEUE",
        "id": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
        "controls": [
          {
            "type": "TOGGLE",
            "name": "SHUFFLE",
            "enabled": true,
            "selected": false
          },
          {
            "type": "TOGGLE",
            "name": "LOOP",
            "enabled": true,
            "selected": false
          }
        ],
        "rules": {
          "feedback": {
            "type": "PREFERENCE",
            "enabled": true
          }
        },
        "firstItem": {
          "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
          "playbackInfo": {
            "type": "DEFAULT"
          },
          "metadata": {
            "type": "TRACK",
            "name": {
              "speech": {
                "type": "PLAIN_TEXT",
                "text": "jeremy"
              },
              "display": "Jeremy"
            },
            "art": {
              "sources": [
                {
                  "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
                  "size": "X_SMALL",
                  "widthPixels": 48,
                  "heightPixels": 48
                }
              ]
            }
          },
          "durationInMilliseconds": 318000,
          "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/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
            "offsetInMilliseconds": 0,
            "validUntil": "2018-05-10T19:11:35Z"
          },
          "feedback": {
            "type": "PREFERENCE",
            "value": "POSITIVE"
          }
        }
      }
    }
}

Initiate directive error handling

If your skill can't handle a Initiate 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.

Related topics

• Alexa.Audio.PlayQueue
• Alexa.Media.PlayQueue
• Alexa.Media.Search
• Alexa Music and Radio Skill API Components Reference
• Understand the Music and Radio Skill API