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







Alexa sends an Initiate request when it receives a content identifier from a skill's GetPlayableContent response or the customer chooses to play content Alexa received from a GetDisplayableContent response. The skill responds to this Initiate request 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


Context information about the request.

RequestContext object


Filters to apply during content resolution.

Filter object


Content to use in a playback queue.



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


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.



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.



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.



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



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



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



(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


100 ms


250 ms


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


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


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




Not applicable


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


Unique identifier used to track the request.




Message interface version. Defaults to 1.0.




Message interface category.



Message name. The value is Reinitiate.




Request context information, such as UserId and locale.




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.




Set of target playback endpoints.



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


Element that contains metadata about the type of response.




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




Unique identifier used for tracking purposes.




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



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




Response payload.




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



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.




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



Reinitiate action types

actionType Description Example


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.


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


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.

Was this page helpful?

Last updated: Dec 05, 2023