Amazon Music Client Mac
Towanda Tuning
The Amazon Music Web Service API uses the OAuth 2.0 authorization framework to securely identify clients and end-users. With this open protocol, a client wishing to access a protected resource must contact an authorization server to obtain an access token. Clients can then transmit this access token when making subsequent protected resource requests.
Login with Amazon (LWA) provides the authorization server for the Amazon Music API. LWA is a separate service from the core Amazon Music Service, and so its API may have different formats, structure, and requirements from the Amazon Music API documented here.
The LWA documentation above will guide you through the authorization process that applies to your specific application. The Amazon Music-specific component of this process is scope. When you make a device authorization request to LWA you must specify a scope. You can request more than one scope at once: simply separate scopes with spaces. Which scope(s) you need depends on the API functionality you will need access to. While the Web API makes use of a number of different scopes, the Device API only requires one scope: amazon_music:access.
If you are implementing support for Alexa Voice Services (AVS) for the same devices/clients, you must use the same LWA Application ID for both, as both require LWA authorization. If the customer grants both AVS and Alexa Music permissions at the same time, the client should use the same LWA clientID for both. The Login With Amazon documentation on developer.amazon.com explains how to request scopes using the Web interface or the iOS or Android SDKs and provides sample code. It might be possible to maintain separate client IDs and have the customer grant permissions separately, but this is not tested or recommended and is not expected to work in most scenarios.
When a user taps PLAY on their device or app, the media they have requested should immediately begin playing. It should continue to play without interruption, even if bandwidth fluctuates. In addition, only authorized users should have access to the stream, and it should not be possible for the media to be downloaded or copied for use outside of Amazon Music.
In order to support varying network conditions, streaming files are broken into short segments (sometimes called 'chunks'). Multiple versions of each chunk are provided in several different levels of quality, bit-rates, and codecs. To keep the experience seamless, lower quality chunks can be requested for faster download. Once bandwidth improves, higher quality chunks can be requested once more. These are all packaged together in a Manifest file, which is an XML file defined by the MPEG-DASH format (.mpd). Amazon Music also offers media in a variety of high-definition and ultra-high-definition streaming formats. Segments in these higher-quality formats will be contained within the Manifest if requested by the client.
Additionally, all segments in the Manifest are encrypted by DRM technology to protect against unauthorized downloading and copying. The exception to this is that the first 30 seconds of a track are sent unencrypted, to allow playback to begin quickly and to provide an additional buffer to avoid latency. Segments after that are encrypted. A license is required to decrypt these segments. The license is obtained via a 'license challenge,' a special request sent to the Amazon Music license server.
Music playback from the Amazon Music catalog is only available for authorized consumer electronic devices. To be certified for Amazon Music playback implementation, device clients must meet the following requirements:
DRM stands for Digital Rights Management. DRM technology controls who has access to digital media content. Think of DRM as the digital equivalent of a lock on a secure box, ensuring that only those with the right key can open it. DRM protects Amazon Music's streaming audio and ensures that only authorized users have access to it. It also protects against unauthorized downloading or copying.
DRM primarily relies on encryption. Amazon Music's content streams are encrypted and cannot be played without being decrypted. To playback content, clients must send a license request to a license server. If the request is valid, the server will send back a license key. The license allows the client's media player to decrypt the content and play it.
Widevine is a DRM technology provided by Google. Amazon Music's streaming media files are compatible with Widevine. In order to receive decryption licenses from Widevine's license server, developers must enroll with Widevine as a licensee. Widevine has restricted access to its documentation and SDKs to licensees only. It is recommended that developers contact Widevine and work on acquiring a license before beginning engineering efforts.
Widevine allows for three different levels of security: L1, L2, and L3. L1 is the highest, most secure level of protection. L1 and L2 require the device to have a hardware-based Trusted Execution Environment (TEE). Devices certified for L3 do not have this requirement.
The Widevine License Server will respond with an error code if for some reason it is unable to validate the License Challenge. See License Response HTTP Error Codes for a list of error codes and the meaning of each.
Clients must specify the desired audio quality levels when making requests to the Amazon Music API. Use the X-Amzn-Audio-Device-Capability header for this purpose. The DRM type should also be specified using the X-Amzn-Audio-DrmType header. At this time the only available type is WIDEVINE.
The playback URL returned by the Amazon Music API will point to a XML manifest file with filtered content based on the highest quality audio requested by the client. A client requesting HD quality will not receive Ultra HD representations in the manifest.
The client should determine the audio quality that is best for the user's situation and request it. Factors to consider include the user's preferences, device capability, and current bandwidth. The manifest will include the requested audio quality as well as lower audio quality levels if available. Be aware that not all tracks in the Amazon Music catalog are available in all formats. The client should not make fixed assumptions that the manifest will contain the requested audio quality.
The client will receive information about the audio object from the Amazon Music Device API in a JSON response. The audio object will contain HTTP headers in three lists: key, manifestHeaders, and audioSegmentHeaders. The client will need these headers to make certain types of resource requests. Use the headers as follows:
Note that the streaming URI and headers of the audio object is non-persistent. Their expiration date (UTC format) is specified by the expires property. After that time, the client needs to retrieve a refreshed audio object by calling the API endpoint providing the parent track definition again.
Amazon Music offers a wide variety of music formats. In addition to standard audio, some songs in the Amazon Music catalog are available in high-definition lossless formats and even in spatial audio formats. Please note that not every audio track is available in all formats.
Playback URLs vended from the Amazon Music API point to an XML manifest that conforms to the MPEG-DASH specification. The manifest for standard definition and high-definition audio will contain multiple audio-quality versions of the track, ranging from 16-bit/44.1kHz up to the highest resolution Amazon Music has available for the particular track. For UHD and Spatial audio, the manifest only contains the highest-quality version of the track.
HD and UHD representations are encoded with the FLAC audio codec. The spatial audio codecs are Dolby Atmos and Sony 360 RA. The manifest containing HD, UHD, and spatial audio will also refer to standard quality representations using the OPUS codec to allow players to fall back to a lower bandwidth variant if current network conditions cannot sustain high-definition streams.
The file returned will be an XML manifest that conforms to the MPEG-DASH specification (DASH stands for Dynamic Adaptive Streaming over HTTP). When requesting the manifest, pass the headers under audio.headers.manifestHeaders from the audio object response described previously.
The important objects to note in this example are the object and the object. Each object describes one bitrate option using a particular codec. An object contains multiple objects. Each has a different bitrate, but generally all objects in an use the same codec.
To pull down the actual audio asset, identify the object in the manifest that you wish to request. The key attributes are codecs and qualityRanking, which is the bandwidth attribute of a object.For the codecs attribute, the following are possible values:
For a given codec type, an will contain one or more bitrate representations using that codec. Bitrates are ranked from lowest to highest in ascending order of qualityRanking. A higher quality ranking number means a lower bitrate. The bandwidth attribute can also be used to infer bitrate. The bandwidth value is a worst case (highest) bitrate needed to sustain the stream. In general, they correlate with the average stream bitrates but can in some cases spike much higher than expected.
The device must parse the pssh and LicenseUrl from the manifest to create a license challenge. This license challenge will be used to retrieve the key. An example of the function call the media player should make to the CDN is createLicenseChallenge(pssh).
The device must send a POST request to the license vending Url (LicenseUrl) with the license challenge. The LWA token and the User-Agent along with the headers described in audio.headers.key need to be passed through as header parameters.
To simulate license expiration for testing, the player will set the expiration header, x-amz-music-license-expiration-secs, when requesting the license. The value of this header would indicate the time in seconds after which the returned license will expire. When the license server receives a license request with this header, the license server will return a license that will expire after the duration set in the header.
d3342ee215