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

A playback queue is a dynamic list of playable objects to be played in order (unless the user intervenes with a new command). 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.

In order to support the differing behavior of the various subscription tiers, the Amazon Music service must control 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.

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.

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 helps the server maintain context.

The playParams object

The playParams objects are acquired from the Browse or Web Metadata APIs. 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 strings of MVN IDs defining the container context of the current playback item. It can be a list of playable objects 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 and looping.
• selections: This is an array of the playback modes that are currently allowed. Options include PLAY, SHUFFLE and STATION.

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

Unique identifiers for both the id and the containerId are formatted as MRNs (Music Resource Name). Here is an example of an MRN:

mrn:1.0:key:catalog:Asjh4

It is not necessary to parse the MRN.

Sliding windows

In the context of a playback queue, a sliding window refers to a subset of tracks or items that changes dynamically as playback moves from one track to the next. Tracks within the sliding window are loaded and ready for immediate playback. Once a track has finished playing, that track leaves the sliding window and is unloaded. Then a new track from the queue is loaded.

To ensure that skipping and playback is a fast and responsive experience, the next few tracks the user is likely to play are pre-loaded. However, the playback queue can consists of hundreds or even thousands of tracks. Loading the entire queue at once is therefore undesirable. Using a sliding window reduces initial load time while insuring immediate playback.

How it works

1. Initialization. When playback starts, the system loads a set number of tracks from the queue into the sliding window. This might be, for example, the current track followed by the next two tracks.
2. Playback. As tracks play and the user progresses through the queue, older tracks that have already been played are moved out of the window and upcoming tracks slide in. All of this is done via updates to the report-event API.

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.

Tiers

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.

Creating a new session with a queue from playParams

Playable objects include a playParams object. Use the members of this object to initiate playback. The id and containerId should be passed as parameters to /v1/playback/sessions. In addition, use the selections array to determine what type of playback modes are allowed. Options include PLAY, SHUFFLE, and STATION.

Based on user input and the allowed selections, determine what type of playback session to initiate.

• Standard Playback (PLAY): If PLAY is available in the selections array, send a POST request to /v1/playback/sessions with the body including playParams. This initiates a standard playback session for the specified item.
• Shuffle Mode (SHUFFLE): If SHUFFLE is available, the POST request to /v1/playback/sessions should also include playOptions. In playOptions, set { shuffleMode: SHUFFLE_ON }. This starts a playback session in shuffle mode, playing items in a randomized order.
• Station Mode (STATION): When STATION is an option, the POST request is similar but includes playOptions with { startAsStation: true }. This initiates a station-based playback session, creating a dynamic playlist based on the genre, artist, or other attributes of the initial item.

Once playback has commenced, use the following endpoints to move through the queue:

• Current Track: /v1/playback/sessions/{sessionId}/current
• Next Tracks: /v1/playback/sessions/{sessionId}/next
  • This API supports fetching up to 10 tracks in advance for gapless playback
• Previous Track: /v1/playback/sessions/{sessionId}/previous

Event reporting

The report-event API 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 should regularly update the service with the current position of playback within the track. If the user should decide to resume playback on a different device, the service then knows where to resume from. 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 events 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.

Example start event

await this.reportEvent({
  type: "start",
  clientTimestampInMilliseconds,
  initialPlaybackDelayMilliseconds: this.#localTimers.initialPlaybackDelay,
  deviceTimezone,
  playbackCurrentSpeed,
  playbackStartAbsoluteOffsetMilliseconds: event.currentMediaTime,
});

Example stop event

await this.reportEvent({
  type: "stop",
  clientTimestampInMilliseconds,
  initialPlaybackDelayMilliseconds: this.#localTimers.initialPlaybackDelay,
  deviceTimezone,
  terminationReason,
  playbackCurrentSpeed,
  durationSeconds: Math.trunc((Date.now() - this.#localTimers.playing) / 1000),
  entityProgressSeconds: event.currentMediaTimer ?? this.#playerManager.getCurrentTimeSec(),
  rebufferCount: 0,
});

Event fields

• clientTimestampInMilliseconds: The current time from the client perspective.
• initialPlaybackDelayMilliseconds: How long it takes the client to load the request for playback.
• deviceTimezone: The timezone, measured in offset hours. For example, "-08:00" is the timezone of California.
• playbackCurrentSpeed: The speed of playback. For example, 1.
• playbackStartAbsoluteOffsetMilliseconds: Where in the track to start playback, specified in thousandths of a second.
• durationSeconds: How long does the user play this track for?
• entityProgressSeconds: The current progress of this track.
• terminationReason: Reason for playback termination.
  • Common errors: systemStop, userStop, userNext, userPrev, trackFinished, trackScrub
  • If the user skips next or previous, the client should emit a stop event for the current track with an appropriate reason such as userNext or userPrev.
  • If the user scrubs, emit a stop event with trackScrub.
  • If the current track is paused, emit userStop.
  • If the current track finishes playing, emit trackFinished.
  • For any other reason for interruption, emit systemStop.

Headers

The following headers must be sent with all requests:

Table of API endpoints

The following table contains the API endpoints for Web Playback:

Continue to the playback APIs page.