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, and then you upload the catalog data. You can do create and upload your catalog with the ASK Command Line Interface (ASK CLI) or with the Catalog Management REST API.

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 details about the format that catalogs should take, see the catalog reference.

Steps to create and manage catalogs

Complete the following steps to create a catalog, associate it with a skill, and then upload content to the catalog.

  1. To create a catalog with ASK CLI, use the create-catalog command.

    To create a catalog with REST, send a Create catalog API request.

    In addition to a catalog title, you must provide a catalog type and a catalog usage. For more details about the values to use, see catalog type and usage.

    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.

  2. To associate the catalog with a skill using ASK CLI, use the associate-catalog-with-skill command.

    To associate the catalog with a skill with REST, send Associate catalog.

    You can associate a skill with only one catalog of each catalog type.

  3. To upload catalog data with ASK CLI, use the upload-catalog command.

    To upload catalog data to Amazon S3 with REST, send Create S3 upload URL, and then send an HTTP PUT {presignedUploadUrl} request to each presigned URL with the catalog or catalog part in the body of the request. For more details, see Create catalog and upload content to Amazon S3.

    Catalogs are JSON documents. For more details 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 details, see deleted entities on the catalog reference page.

  4. 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 REST, send Get upload status v0.

    The response includes the processing status of the catalog. For details 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. AMAZON.MusicGroup AlexaMusic.Catalog.MusicGroup
Songs, tracks AMAZON.MusicRecording AlexaMusic.Catalog.MusicRecording
Albums AMAZON.MusicAlbum AlexaMusic.Catalog.MusicAlbum
Playlists (collections of songs) AMAZON.MusicPlaylist AlexaMusic.Catalog.MusicPlaylist
Genres AMAZON.Genre AlexaMusic.Catalog.Genre
Artists and genre stations AMAZON.BroadcastChannel AlexaMusic.Catalog.BroadcastChannel
Live radio stations AMAZON.TerrestrialRadioChannel AlexaMusic.Catalog.TerrestrialRadioChannel

Catalog upload status values

The following table explains the values for catalog upload status.

Status Description
UPLOAD The catalog has been uploaded and is ready for additional processing steps.
SCHEMA_VALIDATION The catalog has passed schema validation for the specified catalog type.
ER_INGESTION The catalog was successfully ingested for entity resolution (ER). When the status changes to SUCCEEDED, you can test voice requests for your catalog data with your skill. The ER_INGESTION step typically takes less than 30 minutes to complete.
SLU_MODELING_VALIDATION The catalog has passed initial validation for the Alexa speech and language understanding (SLU) process.
SLU_MODELING 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.
Was this page helpful?

Last updated: Nov 27, 2023