Add Premium Audio, Badging, and License Retrieval to a Music Skill

About premium audio and alternate audio quality streams

The Alexa premium audio feature allows music service providers to offer multiple levels of audio content stream quality in the same music skill.

Adding premium audio support to a music skill

If the music service provider supports premium audio in their skill, requests for GetItem, GetNextItem, GetPreviousItem, and JumpToItem contain an Endpoint object in the RequestContext containing information about what types of audio quality streams Alexa can play on the target device.

Using premium badging to indicate audio content stream quality

Premium badging enables music service providers who support premium audio to display content stream quality on a device screen or in the Alexa app.

During playback a customer whose music service subscription includes premium audio sees a badge on the Now Playing screen of their multimodal devices or the Alexa app (iOS and Android). The badge indicates the content stream quality, also known as the content format. Content formats are provided by the music service provider and may include general premium audio labels, such as Standard Definition (SD), High Definition (HD), Ultra High Definition UHD, or they may include branded content labels like 'HiFi', which is the HD format from Tidal. Providers may support either dynamic or static badging.

Dynamic badging requirements

Providers that support adaptive bitrate may also support dynamic badging. With dynamic badging, the badge changes throughout playback to reflect the current content format. Providers must hydrate adaptive representations in manifest file with badge identifiers. Alexa re-evaluates the badging state in 10- to 15-second intervals throughout playback. There is a limit on badge updates where rapid changes are required, in order to prevent distractions to the customer.

To support dynamic badging, providers must include all supported content formats during skill on-boarding. Each content format needs to be mapped to all badge identifiers that might be present in the MPEG-DASH manifest. For each badge identifier, the provider must indicate a customer-facing display label in all supported locales. Providers must give this mapping to their Alexa Music representative to onboard to dynamic badging.

Dynamic badging mapping example

The following table illustrates one possible mapping of content type IDs to badge identifiers and customer-facing display labels.

ContentTypeId Badge Identifier Customer-facing display label (en-US) Customer-facing display label (es-US)
CT-1233 Standard SD SD
CT-1234 Standard SD SD
CT-1234 HighDefinition HD HD
CT-1235 Standard SD SD
CT-1235 HighDefinition HD HD
CT-1235 UltraHighDefinition UHD UHD

Static badging requirements

Providers may or may not support adaptive bitrate to support static badging. With static badging, the badge will remain unchanged throughout playback, regardless of format fluctuations.

To support static badging, providers must include all supported content formats during skill on-boarding. Providers must indicate their supportedContentFormats by including a list of unique ContentTypeIDs in the MPEG-DASH manifest. See ContentFormat for more information. Providers must then map each ContentTypeID to a customer-facing display label for the badge for each locale supported by the provider. See Sample below. Providers must give this mapping to their Alexa Music representative to onboard to static badging.

Static badging mapping example

The following table illustrates one possible mapping of content type IDs to badge identifiers and customer-facing display labels.

ContentTypeId Badge Identifier Customer-facing display label (en-US) Customer-facing display label (es-US)
CT-1233 Standard SD SD
CT-1234 HighDefinition HD HD
CT-1235 UltraHighDefinition UHD UHD

Licensing retrieval for digital rights management (DRM)

Alexa users can request music content from a music service provider's skill. When a user requests music content from a skill, Alexa sends a GetPlayableContent request to the skill. In response to the request, if the Music Service Provider (MSP) has content that matches the search request, the skill returns a reference to the content. When digital rights management (DRM) is present, the following flow controls access to the music.

  1. The device indicates to Alexa that it's ready to play music.
  2. Alexa sends an Initiate request to the skill to create a play queue for the licensed content.
  3. As part of the Initiate response, the MSP includes a Stream object containing the requestHeaders and the stream uri for the first item in the play queue.
  4. Alexa sends this information to the device.
  5. If the stream URI is DRM-encrypted, the device sends the item's stream information to the MSP to request the headers for the content.
  6. The MSP returns the track manifest and DRM licensing endpoint.
  7. The device reads the MANIFEST, KEY, and AUDIOSEGMENT headers from the track manifest.
  8. The device uses the AUDIOSEGMENT header to request the audio segments for the content from the MSP.
  9. The MSP returns the audio segments to the device.
  10. The device creates a content decryption module (CDM) license challenge.
  11. The device sends the CDM license challenge and the DRM license token from the KEY header to the MSP's DRM license service. The DRM license token is an authentication token that the device must use to authenticate itself.
  12. The license service returns the license for the content.
  13. The device uses the license to decrypt the content and then plays the content.

To fetch the next and previous items and refresh an item's uri, Alexa calls GetNextItem, GetPreviousItem, and GetItem respectively. If any of these directives return a DRM-encrypted URI, the stream is decrypted in the same manner as for Initiate.

HTTP headers used in DRM

MSPs can ask for HTTP headers to be sent along. The headers are sent to the MSP end point when fetching resources such as manifests, segments and licenses. MSPs can classify their headers into four header categories: KEY, MANIFEST, AUDIOSEGMENT, and ALL. Headers in the KEY and ALL categories are sent when fetching the LicenseToken.

KEY headers

MSPs can also add a new header or update the value of existing KEY headers using HTTP response headers when responding to a manifest request. This flexibility exists because some MSPs opt to generate the license authorization tokens only at the time of the manifest request.

  • KEY header additions and updates are allowed with manifest responses only.
  • When the manifest response has HTTP response headers (for example, in Step 7 in the above call flow).
    • If the header is known to the player, i.e., it was sent earlier in the play directive in KEY headers, it is updated with the new value received in the HTTP response headers. Otherwise, the new header is added in the KEY headers.

For example, if the KEY headers sent in the SPI response are:

{
    "type": "KEY",
    "headers": [
        {
            "name": "X-AlexaMusic-ExampleMsp-LicenseToken",
            "value": "fbfd3378-a72d-45ef-9782-4edf140f5dd7"
         }
     ]
}

And the HTTP response headers sent in Step 6 in the call flow above are:

{
    "type": "KEY",
    "headers": [
        {
            "name": "X-AlexaMusic-ExampleMsp-LicenseToken",
            "value": "bdb57ecc-80f4-4212-afbf-d4222d1d4482"
         }
     ]
}

Then the value of the KEY header "X-AlexaMusic-ExampleMsp-LicenseToken" would be updated to "bdb57ecc-80f4-4212-afbf-d4222d1d4482" from "fbfd3378-a72d-45ef-9782-4edf140f5dd7".

License URL

The MSP includes the URL to fetch the license in the manifest (MPD file), under the <ContentProtection><LicenseUrl> tag, under the following conditions:

  • The LicenseUrl must be URL-encoded.
  • Alexa invokes the license URL as-is along with the license challenge. See license request details below in the license request body description.
  • Alexa sends KEY headers with the license request.

Example manifest with license URL embedded

<ContentProtection schemeIdUri="urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
<cenc:pssh>AAAAXXBzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAAD0SEJWMtwtfbmN+SzO0Z/85SlEaC0FtYXpvbk11c2ljIhxjaWQ6bFl5M0MxOXVZMzVMTTdSbi96bEtVUT09</cenc:pssh>
<amz:LicenseUrl>https://example.com/license/KID=8f26d4a9-e4d9-4971-aeab-782659471d4a"</amz:LicenseUrl>
</ContentProtection>

License request

The license request is a POST request, in which the content-type is application/json. All headers in the KEY and in ALL categories are sent along with the request. The body of the request is a JSON object containing the following field:

Field Description Required
licenseChallenge The license challenge generated by the content decryption module (CDM), in Base64 format. yes

Example license request

POST {license-url} HTTP/1.1

Header of the request

Authorization: X-AlexaMusic-ExampleMsp-LicenseToken: fbfd3378-a72d-45ef-9782-4edf140f5dd7
X-AlexaMusic-ExampleMsp-RequestId: 0fe36d7f-6d67-4367-b5df-6a9505e5a5ef
content-type: application/json

Body of the request

{
    "licenseChallenge":"icWUsemVHvua9/FBtpbHgpbgwijFPjtQF9Ldb8Swf"
}

License response

The license response is in application/json form. The response should contain only the following field:

Field Description Required
license The license, in Base64 format. yes

Example license response

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "license": "ajWhpEgGhqGraJtFdUPgu6plJGy9ViaRn"
}

HTTP response codes for DRM

Following are the error codes that are specific to DRM license fetching:

Status Code Name Description
200 OK The CDM successfully generated the license.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized Unable to authorize, license token invalid. Retry might succeed.
403 Forbidden License denied (CDM revoked) or ineligible content or customer.
500 Internal Server Error The request couldn't be handled because of an internal service error.
503 Service Unavailable The service is currently unavailable to handle the request.
Amazon Alexa
Amazon business
Amazon Web Services
Amazon Dash Replenishment