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
andSTATION
.
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
- 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.
- 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 theselections
array, send a POST request to /v1/playback/sessions with the body includingplayParams
. 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 includeplayOptions
. 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 includesplayOptions
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
oruserPrev
. - 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
.
- Common errors:
Headers
The following headers must be sent with all requests:
Header | Type | Description |
---|---|---|
X-Amzn-Audio-DRMType | string | Value must be WIDEVINE. |
X-Amzn-Audio-Device-Capability | string | A comma separated list of supported playback qualities. |
X-Amzn-Device-Id | string | A unique ID for the device making the request. |
Table of API endpoints
The following table contains the API endpoints for Web Playback:
HTTP Method | Endpoint Path | Description |
---|---|---|
POST | /v1/playback/sessions | Initializes a new session with an associated playback queue. |
GET | /v1/playback/sessions/{sessionId}/current | Retrieves a playback object for the current track |
GET | /v1/playback/sessions/{sessionId}/next | Retrieves a playback object for the next track |
GET | /v1/playback/sessions/{sessionId}/previous | Retrieves a playback object for the previous track |
GET | /v1/playback/sessions/{sessionId}/queue | Retrieves an array of playback objects for the entire queue |
GET | /v1/playback/sessions/active | Retrieves all playback sessions across all devices |
GET | /v1/playback/sessions/entities/{entityReferenceId} | Retrieves an inactive playback session that has been active in the last 30 days |
POST | /v1/playback/sessions/{sessionId}/queue/next | Insert a track into the playback queue immediately after the current track. |
POST | /v1/playback/sessions/{sessionId}/queue/last | Add a track to the end of the playback queue. |
PUT | /v1/playback/sessions/{sessionId}/loop | Set playback mode to loop. |
PUT | /v1/playback/sessions/{sessionId}/shuffle | Set playback mode to shuffle. |
POST | /v1/playback/event | Report playback events to the Amazon Music service. |