Alexa.Media.Playback Interface

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

Understand how users initiate or reinitiate playback

When you use the Alexa.Media.Playback interface, the voice interaction model is already built for you. The following utterances are examples of what users might say to initiate playback.

User: Alexa, play "A Change Is Gonna Come," by Sam Cooke.

Alexa: Playing "A Change Is Gonna Come," by Sam Cooke, on Amazon Music.

User: Alexa, play the podcast Up First.

Alexa: Getting Up First, on Amazon Music. Playing the latest episode.

User: Alexa, resume the podcast Up First.

Alexa: Continuing Up First, on Amazon Music. Resuming the latest episode.

User: Alexa, move my music to the laundry room.

Alexa: Moving Amazon Music to the laundry room.

Configure your skill to receive requests

Before Alexa sends requests to the Alexa.Media.Playback API, you must configure your music skill to support it.

Support premium audio

When a provider supports premium audio, the Initiate or Reinitiate request includes a list of Endpoint objects, each of which corresponds to a playback device. Each Endpoint object contains a list of ContentFormat objects that identify the content types playable on the target device. The provider chooses one of these content types when it selects a playback stream.

Enable playback directives

When a user asks for audio content, Alexa responds with a directive. A directive is an actionable request Alexa sends to the device.

Initiate directive

If no audio is playing, Alexa invokes Initiate to retrieve the first track from the play queue. The following table shows which content types support this directive.

Content type Required

Music

Yes

Radio

Yes

Podcasts

Yes

Alexa sends an Initiate request when it receives a content identifier from a skill's GetPlayableContent response. The skill responds with the Stream URI, and playback begins.

Alexa calls this directive in three primary scenarios.

  1. The user asks Alexa to play music, radio, or a podcast content.
  2. A previously set music, radio, or podcast alarm is triggered. For example, the user sets an alarm to play a song at 7:00 AM, and Alexa sends an Initiate call to the skill at that time.
  3. The user selects content from the play history displayed on screen (for example, in the Alexa app or on an Alexa-enabled device with a screen).

Podcast skills are either serial or episodic (non-serial). In a serial program, users expect your skill to play the episodes in order, from oldest to latest (newest). In an episodic program, each episode is a stand-alone show, and users expect your skill to play episodes from latest to oldest by default. Therefore, in its response to the Initiate directive, your skill returns the oldest episode as the first item in the play queue for a serial program. For an episodic program, your skill starts the play queue with the latest episode.

Initiate directive payload details

Field Description Type

requestContext

Context information about the request.

RequestContext object

filters

Filters to apply during content resolution.

Filter object

contentId

Content to use in a playback queue.

String

currentItemReference

The item that's currently playing (active) on the target endpoint, if any. This property is absent when nothing is playing. Your skill uses this property to enforce concurrency limits. Specifically, it determines whether the playback session starts on an endpoint where no stream is playing, or whether it replaces an existing stream on an endpoint.

MediaReference object

playbackModes

The playback modes requested by the user. If the user doesn't request a looped queue, a shuffled queue, or a repeated track, this attribute defaults to false for all supported playback modes.

Object

playbackModes.shuffle

If the user starts a queue in shuffle mode, the value of playbackModes.shuffle is true. Otherwise, the value is false. This directive is ignored for podcast skills.

Boolean

playbackModes.loop

If the user starts a queue in loop mode, the value of playbackModes.loop is true. Otherwise, the value is false. This directive is ignored for podcast skills.

Boolean

playbackModes.repeat

An object that specifies whether the user requested item playback in repeat mode.

Object

playbackModes.repeat.status

If the user starts a particular track in repeat mode, the value of playbackModes.repeat.status is ON. Otherwise, the value is OFF.

ENUM

playbackPosition

(Podcasts only) The point at which playback begins, based on the user's requirements. The only supported value is RESUME. If the user doesn't indicate where to start playback, this attribute is absent.

String

endpoints

(Premium audio only) A list of Endpoint objects that identify the content types playable on the target device. This field is present only if the provider supports premium audio. See the Endpoint object for more information.

List of objects

Initiate directive examples (music)

Example of an Initiate directive with no current content.

Example of an Initiate directive that contains content.

Example that illustrates support for premium audio in the Initiate directive.

Initiate directive examples (podcast)

When a user says, "Alexa, play the podcast The Daily," the provider's response to the GetPlayableContent directive contains the ContentId for the requested content. To start playback, Alexa sends an Initiate request similar to the one in the following example. This request instructs the skill to create a play queue from the ContentId.

An Initiate request is generated when a user asks Alexa to resume playback. The user can say, for example, "Alexa, resume the podcast Up First." If the user is playing music but doesn't specify a different device, the skill begins playback on the same device.

Initiate response event

When a skill receives an Initiate directive, it responds with an Alexa.Response event. The time it takes for your skill to respond to an Initiate request directly affects the Alexa user experience. Music skills must comply with the following response latency limits.

Call percentage Latency limit

50%

100 ms

90%

250 ms

99%

400 ms

The skill's Initiate response includes a play queue based on the requested ContentId, the first playable track, and enough information for Alexa to manage the queue. To get the second track, Alexa calls GetNextItem after the first track begins. Subsequent tracks are also retrieved with GetNextItem. For details, see Alexa.Audio.PlayQueue Interface.

Initiate response event payload details

Field Description Type Required

playbackMethod

Information Alexa needs to initiate playback. This includes the play queue id, the ContentId of the first track, and the supported play queue controls, such as shuffle and repeat.

PlaybackMethod object

Yes

Initiate response event examples (music)

Response to the Initiate directive, in which the skill returns information about a playable item.

Initiate response that supports premium audio.

Initiate response that supports digital rights management (DRM).

Initiate response that includes a background image for Alexa to display during playback. For more information, see the background field of the BaseMetadata object.

Initiate response event examples (podcast)

In response to an Initiate directive, the skill creates a play queue based on the ContentId. Then it returns the queue identifier and the first audio item to Alexa. The Initiate response must contain enough information for Alexa to manage the queue. This information includes the first episode to play. To get the second episode, Alexa makes an additional call after the first program begins.

Users can pause and resume audio on the same device. In response to a resume request, your skill uses the offsetInMilliseconds field in the returned Stream object to indicate where to start playback. The following example shows the response to a RESUME request.

To disable fast-forward and rewind for a program series or episode, respond without the SEEK_ADJUST control, as shown in the following example.

Following is an example of a response that contains the latest program content. The isLatest flag is set to true when a program is the latest, or most recently released, program in a series. When the isLatest flag is true, the user receives a notification to confirm that the latest episode is about to play. When this flag is set to false, the user might be asked if they want to hear the latest episode. If the isLatest flag is unspecified, the user can receive incorrect prompts or unexpected playback behavior.

The following response example demonstrates support for subscription playback.

Initiate directive error handling

If your skill receives an Initiate directive it can't resolve, the skill responds with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For details, see Alexa Music, Radio, and Podcast Skill API Error Responses.

Reinitiate directive

If premium music is playing on an Alexa-enabled device and the user asks to move the stream to a different device, Alexa invokes the Reinitiate directive. The following table shows which content types support this directive.

Content type Required

Music

Optional

Radio

Not applicable

Podcasts

Not applicable

The device on which music is paused is called the origin device. The device to which the music stream is moved is the target device. When a music stream is moved, the Reinitiate interface captures specific information about the device, current play queue, and offset. This information, the playbackSnapshot, marks the point at which playback resumes on the target device.

Playback snapshot example

Reinitiate request event

A Reinitiate request pauses the music play queue on one device and resumes playback at the same point on another device. When you say, "Alexa, move my music to the car" or "Alexa, play my music in the kitchen," Alexa creates a playbackSnapshot to bookmark the music so you can pick up where you left off. A Reinitiate request instructs the skill to resume playback at the position captured by the playbackSnapshot.

Reinitiate request event details

Attribute Description Type Required

header.messageId

Unique identifier used to track the request.

String

Yes

header.payloadVersion

Message interface version. Defaults to 1.0.

String

Yes

header.namespace

Message interface category.

String

Yes

header.name

Message name. The value is Reinitiate.

String

Yes

payload.requestContext

Request context information, such as UserId and locale.

Object

Yes

payload.playbackSnapshot

Snapshot of the play queue on the source endpoint. This snapshot stores information related to the media to be moved, playback modes, offset, applied filters, and origin endpoint. See the preceding PlaybackSnapshot example for more information.

Object

Yes

payload.endpoints

Set of target playback endpoints.

List

Yes

Reinitiate request example

Reinitiate response event

The skill validates the eligibility of the play queue for the target endpoint and returns a Reinitiate.Response that indicates if the play queue needs to be modified. If the play queue requires no changes, its payload contains metadata for the relevant action type. If the play queue is not compatible with the target endpoint, the skill returns an error code.

To ensure a good user experience, a Reinitiate request must comply with the established latency limits for music skills. See the preceding latency limits table in the section Initiate response event.

Reinitiate response event details

Attribute Description Type Required

header

Element that contains metadata about the type of response.

Object

Yes

header.namespace

Notation that specifies the category of the response payload (in this case, Alexa.Media.Playback).

String

Yes

header.messageId

Unique identifier used for tracking purposes.

String

Yes

header.payloadVersion

Version of the message payload/interface. Defaults to 1.0.

String

Yes

header.name

Name of the response (in this case, Reinitiate.Response).

string

Yes

payload

Response payload.

Object

Yes

payload.actionType

Indicator showing if the original play queue must be modified and, if so, how. (See the following table, "Reinitiate action types," for possible values.)

String

Yes

payload.stream

Optional field that contains the stream object when the actionType = REPLACE_STREAM. The stream object contains the stream URI that Alexa sends to devices. For details, see the Stream object.

Object

No

payload.playbackMethod

Optional field that contains the PlaybackMethod object. The PlaybackMethod object contains AudioPlayer-based or ExternalMediaPlayer-based queue information to replace the original queue.

Object

No

Reinitiate action types

actionType Description Example

CONFIRM_QUEUE

Action type that allows the original queue to be moved as is, with no modification of the target endpoint.

The original play queue can be reinitiated as is when music is moved from an Echo device to another Echo device with eligible subscription rights.

REPLACE_STREAM

Action type in which the original play queue is replaced with another stream.

If music is moved from an Echo Dot, which doesn't support HD audio, to an Echo Show, which does support HD audio, the play stream must be replaced. The URL of the new play stream must be compatible with the supported HD content.

Reinitiate response example

Reinitiate directive error handling

If your skill receives a Reinitiate directive it can't resolve, the skill responds with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. Sometimes, for example, a user tries to move playback to another device, but the origin and target contexts are different, as in the following cases:

  • The target device is offline.
  • The user listens on Amazon's free music tier.
  • The account of the target device, such as a set of Alexa-enabled headphones, is not yet linked.

Mismatches like these generate a USER_CONTEXT_MISMATCH error. For details, see the following table and example.

User-context mismatch details

Value Description

USER_CONTEXT_MISMATCH

Error code that appears when the origin user context does not match the target user context.

Example of a user-context mismatch error

For more information about error responses, see Alexa Music, Radio, and Podcast Skill API Error Responses.

Last updated: Mar 22, 2023