Add Premium Audio, Badging, and License Retrieval to a Music Skill
The Alexa premium audio feature allows music service providers to offer multiple levels of audio content stream quality in the same music skill.
Add premium audio support to a music skill
If a music service provider 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 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 |
Request digital rights management (DRM) license retrieval
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.
- 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 therequestHeaders
and the streamuri
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 headers for the content.
- The MSP returns the track manifest and DRM licensing endpoint.
- The device reads the
MANIFEST
,KEY
, andAUDIOSEGMENT
headers from the track manifest. - The device uses the
AUDIOSEGMENT
header to request the audio segments for the content 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 an authentication token that the device must use to authenticate itself. - The license service returns the license for the content.
- 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 theKEY
headers.
- If the header is known to the player, i.e., it was sent earlier in the play directive in
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. |