Upload Music or Radio Catalogs
For the best user experience with your music or radio skill, you should upload your content catalogs to Alexa. The catalogs that you upload contain information about all the items in your entire music library. After you upload your catalogs, they are integrated with the models that are used to train Alexa.
The maximum number of entities in a catalog is 500,000. This limit is cumulative, so if you upload 250,000 entities to a catalog one day, then upload an additional 250,000 entities to the same catalog the next day, you have reached the limit for that catalog. If you require support for catalogs with more than 500,000 entities, contact Amazon to request an increase to this limit.
Why upload catalogs?
Alexa uses your catalogs for two primary purposes:
Help Alexa understand voice commands for your content
Your catalogs help train Alexa to recognize voice commands for your music content. For example, if you have a playlist called Exciting Hockey Songs, uploading a catalog that contains this playlist name helps Alexa understand that a user who says, "Alexa, play exciting hockey songs on your skill name" is asking for a playlist. Similarly, for radio providers, uploading a catalog of stations helps Alexa understand when customers are asking for a radio station using standard properties including station name, call sign, or frequency.
Help Alexa perform more accurate entity resolution
Your catalogs help Alexa with entity resolution, which is the process where Alexa determines which skills can provide the content that users request. For example, if a user says "Alexa, play music by Lady Gaga", Alexa understands that "Lady Gaga" is an artist. During the entity resolution step, Alexa searches the uploaded catalogs to see if "Lady Gaga" is an artist supported by your skill. If a match is found in your catalogs, your skill might be invoked to provide music to the user. If no match is found in your catalogs, your skill isn't invoked.
Catalog data is always live
After you publish your music skill, you can continue to work on the development version of your skill. Changes that you make to your development skill don't affect the live, published skill. You must submit your development skill for certification for the changes to be promoted to your live, published skill. For more information about the different skill statuses (Live, In Development, etc.) and how to continue working on a skill after it's published, see publication status and revise and update your skill after publication.
Music catalogs are different, and are always live. The music catalogs that you upload are shared by your development and published skills. When you upload new versions of your catalogs they affect your development skill and your published skill. Because of this, it's important to make sure that the catalogs you upload are correct and will not negatively impact your users. For example, when you upload a new catalog that removes items, these items are no longer available to your development skill and your published skill.
Create and manage your catalogs
You create and manage your catalogs separately from your skill. First you create a catalog, then you associate the catalog with your skill, then you upload the catalog data. You can do all of this with the ASK Command Line Interface (ASK CLI) or with the Alexa Catalog API, which is part of the Skill Management API (SMAPI).
Multiple skills can use the same catalog, but each skill can use only one catalog of each catalog type. That is, a skill can have a maximum of six associated catalogs.
For more information about the format that catalogs should take, see the catalog reference.
Steps to create and manage catalogs
Use the following steps to create a catalog, associate it with a skill, and then upload content to the catalog.
To create a catalog with ASK CLI, use the create-catalog command.
To create a catalog with SMAPI, send a POST /catalogs request.
In addition to a catalog title, you must provide a catalog type and a catalog usage. See catalog type and usage for the values to use.
Create a catalog for each kind of music item that your skill supports. For example, create a catalog for albums (MusicAlbum), songs (MusicRecording), artists (MusicGroup), playlists (MusicPlaylist), and so on.
To associate the catalog with a skill using ASK CLI, use the associate-catalog-with-skill command.
To associate the catalog with a skill using SMAPI, send a PUT /skills/skill ID/catalogs/catalogId request.
You can associate a skill with only one catalog of each catalog type.
To upload catalog data with ASK CLI, use the upload-catalog command.
To upload catalog data with SMAPI, send a POST /catalogs/catalog ID/uploads request.
Catalogs are JSON documents. For more information about catalog formats, see the catalog reference.
You can use this same command or API to upload additions or changes to a catalog. A typical workflow is to upload the entire catalog initially, and then subsequently upload only the additions or changes.
To delete entries from a catalog, you must explicitly specify
"deleted": true. For more information, see deleted entities on the catalog reference page.Important: When you upload a catalog with new, updated, or removed entries, make sure to update the corresponding
lastUpdatedTimefield. The Alexa service uses this field to help determine what's changed. If you upload a catalog with changed entries but an unchanged
lastUpdatedTimefield, the changes might be ignored.
To check the status of a catalog upload with ASK CLI, use the get-catalog-upload command.
To check the status of a catalog upload with SMAPI, send a GET /catalogs/catalog ID/uploads/upload ID request.
The response includes the processing status of the catalog. For information about the status values, see catalog upload status values.
Catalog type and usage
Use the following values for catalog type and catalog usage.
|Items in the catalog||Type value||Usage value|
|Artists, actors, composers, etc.||
|Playlists (collections of songs)||
|Artists and genre stations||
|Live radio stations||
Catalog upload status values
The following table explains the values for catalog upload status.
||The catalog has been uploaded and is ready for additional processing steps.|
||The catalog has passed schema validation for the specified catalog type.|
||The catalog was successfully ingested for entity resolution (ER). When the status changes to
||The catalog has passed initial validation for the Alexa speech and language understanding (SLU) process.|
||The catalog has been ingested and deployed in the Alexa SLU models. You can use your skill before this step completes. This step improves Alexa's accuracy in understanding requests for unique content in your catalog, and can take several weeks to complete.|
Last updated: Dec 29, 2020