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

Note: Sign in to the developer console to build or publish your skill.

The Alexa premium audio feature lets music service providers (MSPs) offer multiple levels of audio content stream quality within the same music skill.

Support premium audio

If an MSP supports premium audio in its skill, requests for GetItem, GetNextItem, GetPreviousItem, and JumpToItem contain an Endpoint object in the RequestContext. This object specifies which types of audio quality streams Alexa can play on the target device.

Use premium badging

Premium badging enables MSPs that support premium audio to display content stream quality on the device screen or in the Alexa app.

During playback of premium music content, a badge appears on the Now Playing screen in the Alexa app (iOS and Android) and on any multimodal device. This badge indicates the content stream quality, also known as the content format. The MSP provides these content formats. They can include general premium audio labels, such as standard definition (SD), high definition (HD), and ultra-high definition (UHD), or branded content labels like 'HiFi', which is the HD format from Tidal. Providers can support either dynamic or static badging.

Dynamic badging requirements

Providers that support adaptive bitrate can also support dynamic badging. With dynamic badging, the badge changes throughout playback to reflect the current content format. The provider must supply adaptive representations in a manifest file with badge identifiers. During playback, Alexa reevaluates the badging state every 10 to 15 seconds. To prevent user distraction, MSPs should limit badge updates that require more rapid changes.

To support dynamic badging, providers must include all supported content formats during skill onboarding. Each content format must be mapped to badge identifiers in the MPEG-DASH manifest. For each badge identifier, the MSP must identify a user-facing display label in all supported locales. To onboard to dynamic badging, the provider supplies this mapping to its Alexa Music representative.

Dynamic badging mapping example

The following table illustrates one possible mapping of the ContentTypeID to the badge identifier and user-facing display label.

ContentTypeId	Badge identifier	User-facing display label (en-US)	User-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

With static badging, the badge remains unchanged throughout playback, regardless of format fluctuations. Adaptive bitrate support is optional.

In static badging, the MSP includes all supported content formats during skill onboarding. The MSP identifies its supportedContentFormats by including a list of unique ContentTypeID labels in the MPEG-DASH manifest. (For details, see ContentFormat). The MSP then maps each ContentTypeID to a user-facing display label for the badge in each supported locale (see the following example). The provider gives this mapping to its Alexa Music representative.

Static badging mapping example

The following table illustrates one possible mapping of the ContentTypeID to the badge identifier and the user-facing display label.

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

Use DRM to control content access

When a user requests music content, Alexa sends a GetPlayableContent request to the skill. In response, if the MSP has content that matches the search request, the skill returns a content reference. When digital rights management (DRM) is applicable, the following flow controls access to the music.

The device indicates to Alexa that it's ready to play music.
Alexa sends an Initiate request to the skill to create a play queue for the licensed content.
As part of the Initiate response, the MSP includes a Stream object containing the requestHeaders and the uniform resource identifier (URI) for the first item in the play queue.
Alexa sends this information to the device.
If the stream URI is DRM encrypted, the device sends the item's stream information to the MSP to request the content headers.
The MSP returns the track manifest and DRM licensing endpoint.
The device reads the MANIFEST, KEY, and AUDIOSEGMENT headers from the track manifest.
The device uses the AUDIOSEGMENT header to request the audio segments from the MSP.
The MSP returns the audio segments to the device.
The device creates a content decryption module (CDM) license challenge.
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 a device authentication token.
The license service returns the content license.
The device uses the license to decrypt the content, and then it 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 returns a DRM-encrypted URI, the stream is decrypted in the same manner as for Initiate.

HTTP headers used in DRM

When fetching resources such as manifests, segments, and licenses, MSPs can request that HTTP headers be sent to the MSP endpoint. MSPs classify their headers into four categories: KEY, MANIFEST, AUDIOSEGMENT, and ALL. When fetching the LicenseToken, headers in the KEY and ALL categories are sent.

KEY headers

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

KEY header additions and updates are allowed with manifest responses only under specified circumstances.
- When the manifest response includes HTTP response headers (for example, in Step 7 of the preceding call flow).
- When the header is known to the player (for example, if the header was sent in KEY headers earlier in the play directive). In this case, the header is updated with the new value received in the HTTP response header. Otherwise, the new header is added in the KEY headers.

For example, suppose that the following KEY headers are sent in the service provider interface (SPI) response.

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

In this example, the following HTTP response headers are sent in Step 6 of the preceding call flow.

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

As a result, the value of the KEY header "X-AlexaMusic-ExampleMsp-LicenseToken" is updated from "fbfd3378-a72d-45ef-9782-4edf140f5dd7"to "bdb57ecc-80f4-4212-afbf-d4222d1d4482".

License URL

Under the following conditions, the MSP includes the URL to fetch the license in the manifest (music presentation description [MPD] file), under the <ContentProtection><LicenseUrl> tag.

The LicenseUrl must be URL encoded.
Alexa invokes the license URL as is, along with the license challenge. See the following license request details.
Alexa sends KEY headers with the license request.

Example manifest with embedded license URL

<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 that includes all headers in the KEY and ALL categories. 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

Request header

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

Request body

{
    "licenseChallenge":"icWUsemVHvua9/FBtpbHgpbgwijFPjtQF9Ldb8Swf"
}

Response

The license response contains only the following field.

Field	Description	Required
`license`	The license, in Base64 format.	Yes

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

{ 
    "license": "ajWhpEgGhqGraJtFdUPgu6plJGy9ViaRn"
}

DRM error codes

When fetching a DRM license, the following HTTP error codes can be returned.

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 user.
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.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023