Amazon Music Web API

Playback V1.0 Overview

Web Playback API Overview

The Amazon Music Web API now provides full audio playback capabilities for users of all subscription tiers: Free, Prime, and Unlimited. Use the Web Playback APIs to create a playback queue of playable objects such as music tracks, podcast episodes, interludes, and ads.

Key concepts

Playback queue

In order to support the differing behavior of the various subscription tiers and ensure compliance, the Amazon Music service must maintain control of the playback queue. The client creates a queue and requests playables to add to it. The service controls what plays next. The client is required to conform to this model.

The playback queue is a dynamic list of playable objects to be played in order. The items in the queue might include the next tracks on an album or a playlist, the next episodes of a podcast, songs provided by a station, ads, interludes, etc. Amazon Music may at times inject items to play that have not been directly requested. Here are three examples of why this behavior may occur:

Example 1: The client has requested a station that is in DJ mode. In this example, the service may inject "interludes" which feature a DJ or artist introducing a track.

Example 2: The customer is subscribed to an ad-supported tier. In this example, the service may inject ads.

Example 3: The customer is subscribed to an 'augmented shuffle' tier. In this example, the service determines what to play next based on its recommendation algorithm.

To support this, the client creates a playback session seeding it with an initial set of playable entities. The client then uses the playback APIs to get the properly sequenced playable object. The playable object will contain a URL to the actual playable audio file or manifest, and include information on the media type and the allowed actions that can be performed with this playable entity. The client is obligated to report start and stop playback events to ensure continuity of control and compliance. Use the playback APIs to manage the queue, adding tracks, setting shuffle and loop, restoring and inspecting the queue.

Sessions

Every playback queue is associated with a unique sessionId. The sessionId ensures that every user interaction is tied to the correct playback queue. When making API calls, the sessionId ensures the server maintains context.

The playParams object

The playParams object is used to specify playable entities along with their context. It is acquired from APIs that return playable objects and is used when populating queues. A playParams object contains three primary attributes:

• id: The unique identifier of the item requested for play. It could be a specific music track or a podcast episode, among others.
• containerIds: An array of unique identifiers defining the container context of the current playback item. It can be a list of playable objects (tracks) or the ID of a single container. Potential containers include music albums, playlists, radio stations, and podcast shows. containerIds provides the Amazon Music service with a context that enables features like shuffling, looping, and auto play.
• selections: This is an array of the playback modes that are currently allowed. Options include PLAY, SHUFFLE and STATION. These can be used for CX to help customers understand what to expect when playing the item.

A playParams object must have either id or containerIds as one of its parameters.

Unique identifiers for both the id and the containerId are called MRNs (Music Resource Names). This format is proprietary and maintained by Amazon Music. Do not parse, introspect, or manipulate MRNs. Most playback use cases can be facilitated using a playParams object from the metadata API and passing it on to any of the playback endpoints as is.

Creating a new session

Create a new session with the Create New Session API. This API takes playParams and playbackOptions as input to initialize the queue. Examine the selections array from the playParams to determine what type of playback modes are allowed when populating the playbackOptions object.

Use a playParams object to create a new session and initiate a queue. Use the members of this object to initiate playback. The id and containerId should be passed as parameters. Additionally, pass playbackOptions and use the selections array to determine what type of playback modes are allowed for the particular play object. Options include PLAY, SHUFFLE, and STATION.

The following playback options are available and can be used if available in the selections:

• shuffleMode (SHUFFLE_ON/SHUFFLE_OFF): Can only be set to SHUFFLE_ON if the selections array contained SHUFFLE (for example, stations can't be shuffled)
• startAsStation (true/false) Indicates if a station should be started based on the requested 'playParams', can only be used if the selections array contained STATION (you can't start a station from a podcast)
• loopMode (LOOP_ON/LOOP_OFF) Determines if the container should be looped when it reaches the end
• playbackContinuationMode (AUTOPLAY_ON/AUTOPLAY_OFF) With AUTOPLAY_ON, the service will populate the queue with new similar content when the container reaches the end

yYou can also pass a limit to the Create New Session API. This will tell the service what size queue to initialize. Use a smaller number to reduce time to create a session, and larger numbers (up to 10) to have more visibility into the queue and reduce latency when skipping forward. This will also indicate how many tracks to return in the initial response.

The response of the Create New Session API contains a window of the playback queue that has been established on the Amazon Music server for this playback session. It will return a list of playable objects that are queued up to the specified limit. It also includes a list of allowed actions for each of the playables. Actions include things like Loop, skip, scrub, etc.

Once playback has commenced, use the Report Event APIs to send playback event reports (and any subsequent interruption or continuation) to the Amazon Music Service.

You can use the following endpoints to move through the queue. While the actual queue maintained on the Amazon Music server can be much longer, the API will only expose a limited sliding window. Based on the limit parameter, this window can be expanded up to 10 tracks preceding the current track, the current track, and the upcoming 10 tracks.

Once playback has commenced, use the Report Event APIs send a playback event reports (and any subsequent interruption or continuation) to to the Amazon Music Service.

You can use the following endpoints to move through the queue. While the actual queue maintained on the Amazon Music server can be much longer, the API will only expose a limited sliding window. Based on the limit parameter, this window can be expanded up to 10 tracks preceding the current track, the current track, and the upcoming 10 tracks.

• Current Track: /v1/playback/sessions/{sessionId}/current
  • Returns the current track of the queue, determined by the last 'start' event provided by the client.
• Next Tracks: /v1/playback/sessions/{sessionId}/next
  • This endoint supports fetching up to 10 tracks following the current track.
• Previous Track: /v1/playback/sessions/{sessionId}/previous
  • Provides up to 10 tracks preceding the current track in the queue.

The endoint /v1/playback/sessions/{sessionId}/queue can be called to inspect the current track and its upcoming tracks, but only provides a limited set of metadata for UI rendering purposes.

Handling user interactions

• Skipping tracks. If a user skips multiple tracks, the window adjusts to ensure that the current track and the next tracks from the playback queue are within the window and loaded.
• Revisiting tracks. If a user revisits a track that has just been played and is still within the sliding window, it can be instantly accessed without reloading. Otherwise, the track will need to be loaded and the sliding window adjusted.
• Shuffle and repeat. When shuffle or repeat is active, the sliding window automatically adapts to the new playback order, ensuring that the next track in the sequence is always ready.

Subscription tiers and allowed user interactions

The same APIs are used to request playback for users of all tiers. However, depending on tier, there may be differences in what actions are allowed. Also, some tiers inject ads for playback between the tracks.

For example, a free-tier listener may be limited in the number of tracks they can skip in a given time-frame. If the user tries to skip too many times, the service will return an error and the client may decide to show the user an up-sell popup message, encouraging them to upgrade to a premium tier such as Prime or Unlimited. A free tier listener's queue will also include some ads, while an Unlimited listener's queue will not.

Check out the playback APIs reference page for more details about where to find metadata on allowed actions and skip limits in the API response.

Event reporting

The reporting endpoint /v1/playback/event is used to relay playback status updates to the Amazon Music service. This includes starting playback, stopping playback, pausing playback, and skipping tracks.

Event reporting should take place even when there has been no recent interaction with the user. The client must update the service with the current position of playback within the track whenever playback of a track has been started or stopped, which includes pausing, resuming and transitioning to another track. Without reporting the device’s playback status, subsequent API calls related to the queue will fail. The Amazon Music service should always be kept up to date on the device’s current playback status and context in order to enable it to process future requests accurately.

The client must always report the following event types for each track played:

• Playback start
• Playback stop

Any time playback is started or resumed, the client must emit a start event. Any time playback is stopped, interrupted, paused, or scrubbed, the client must emit a stop event, together with a reason code. In cases of connectivity loss or the system shutting down, the client is required to cache these events and send them to the server once it is back online.

Concurrency Limits

Depending on the subscription tier, the customer might be limited in the number of devices that can actively stream content using the same account. The reporting endpoint can at any time inform the client through an error response, that the maximum permitted streams for that account has been reached. In such a situation, the client must choose to either take over playback (causing another device to stop) or stop playback on the current device.

For more details, please refer to the documentation page for the /v1/playback/event endpoint.

Headers

The following headers must be sent with all requests:

Table of API endpoints

The following table list the API endpoints for Playback:

Continue to the playback APIs reference page.