Steps to Build a Music, Radio, or Podcast Skill

Note: Submit your skill and see it come to life.

Important: Anyone can build a music skill for public distribution in the United States. However, radio and podcast skills are currently in developer preview. To register your radio or podcast skill for the preview, contact your Alexa Music, Radio, or Podcast representative.

To create a music, radio, or podcast skill for a content service, you provide information, configuration, and an endpoint for your skill code. Your skill code is an Amazon Web Services (AWS) Lambda function that handles requests from the Alexa Music, Radio, and Podcast Skill API and communicates with your content service cloud.

Music and podcast providers can create a new skill in the Alexa Skills Kit developer console or with the Alexa Skills Kit Command Line Interface (ASK CLI). For the detailed steps, see Create a new skill in the developer console or Create a new skill with the ASK CLI.

Radio providers can create a skill using the ASK CLI. For detailed steps, see Create a music, radio, or podcast skill with the ASK CLI. Alternatively, radio providers can follow a no-code process by providing the streaming URLs and metadata for their radio station. To get started, contact rsk-onboarding@amazon.com.

Complete the following steps to build a music, radio, or podcast skill.

Prerequisites

Before you build a music, radio, or podcast skill, make sure that you have the following items:

An Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.
An Amazon Web Services (AWS) account. The AWS account gives you access to resources as part of the free tier of services. You host your skill code on AWS Lambda.
An Alexa-enabled device, such as an Amazon Echo. Make sure that you sign in to the Echo with the same credentials as your Alexa developer account.
The Amazon Alexa app on your mobile device. For instructions about how to download the Alexa app, see Download the Alexa app on the Amazon website. Make sure that you sign in to the Alexa app on your mobile device with the same credentials as your Alexa developer account.

Steps to build a music, radio, or podcast skill

To build a music, radio, or podcast skill, complete the following steps:

Create a skill in the developer console.
Create a Lambda function.
Implement required features in your Lambda function.
Configure account linking (optional) (For music and podcast skills only).
Upload catalogs.
Enable the skill for testing.
Test the skill in the Alexa app.
Provide publishing information.
Submit the skill for certification.

Step 1: Create a skill in the developer console

You can create a new music or podcast skill by using the Alexa Skills Kit developer console. To create a music, radio, or podcast skill by using the Alexa Skills Kit (ASK) Command Line Interface (CLI), see Create a new skill by using the CLI.

To create a new skill in the developer console

Sign in to the Alexa developer console.
Click Create Skill.
Under Name, Locale, enter the skill name and default language, and then click Next.
- Skill name: This is the name customers will see when you publish the skill. You can edit this name later on the Distribution page.
- Primary locale: You can add additional languages to the skill later.
Under Experience, Model, Hosting service, choose the music model, then click Next.
Under Review, review your selections. If you want to make a change, click the prior step to make changes. Otherwise, click Create skill.
In the left pane, click Endpoint.
Copy the skill ID displayed near the top of the page. For example, amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6c036f905.
In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the Alexa Client Id and Alexa Client Secret values, and then save the file.
You need the skill ID to configure your AWS Lambda function.

To enter your skill name, prompt name, or invocation names

In the left pane, click Skill Names.
Enter your public skill name, prompt name, and invocation names.
In the top right corner of the page, click Save.

To select the interfaces that your skill supports

In the left pane, click Interfaces.
For each interface that your skill supports, select the check box.
In the top right corner of the page, click Save.

To select the features that your skill supports

In the left pane, click Features.
For each feature that your skill supports, select the check box.
For details about the explicit language filter (ELF), see ELF feature.
In the top right corner of the page, click Save.

Step 2: Create a Lambda function

You need an AWS Lambda function for your skill code. First create an IAM role for the Lambda function, then create the Lambda function.

Create an IAM role for Lambda

If you haven't worked with Lambda before, you need to create an Identity and Access Management (IAM) role that enables basic execution. If you already have a role that allows basic execution for Lambda, skip to the next section.

To create an IAM role

Sign in to the IAM console.
On the left side of the page, click Roles. Then click the Create role button.
Select AWS service. Then, for Choose the service that will use this role, click Lambda. Then click the Next: Permissions button.
In the search box next to Filter policies, enter "basic." Select the check box next to AWSLambdaBasicExecutionRole, then click the Next: Review button.
In the box next to Role name, enter a name for the role. For example, "LambdaRoleForAlexaSkill." Then click the Create role button.

Create the Lambda function

You use AWS Lambda to host the skill code for your skill. AWS Lambda is a web service that lets you run code in the cloud without managing servers. The Alexa Music, Radio, and Podcast Skill API sends requests to your skill code. Your code inspects the request, takes any necessary actions, and then sends back a response.

To create a Lambda function in the AWS Lambda console

Sign in to the AWS Lambda console.
Look in the top right corner of the page to make sure the US East (N. Virginia) region is selected.
Click the Create function button.
Select Author from scratch, then do the following:
1. For Name, enter a name for your Lambda function. For example, "MySkillLambda."
2. For Runtime, choose the programming language or environment that you prefer for your skill code.
3. For Role, select Choose an existing role. For Existing role, choose the role that you created previously.
4. Click the Create function button.
On the left side of the page, for Add triggers, choose Alexa Skills Kit.
At the bottom of the page, for Skill ID verification, select Enable (recommended). For Skill ID, paste the skill ID that you copied from the developer console.
At the bottom of the page, click the Add button. Then, at the top of the page, click the Save button.

After you create your Lambda function, copy the ARN displayed near the top of the page. For example, arn:aws:lambda:us-east-1:111122223333:function:MySkillLambda.

If you created your music, radio, or podcast skill in developer console, complete the following steps to add this ARN to the configuration of your skill. Otherwise, add this ARN to the skill manifest. For details, see Create a new skill by using the CLI.

To configure the endpoint in the Alexa developer console

Navigate back to your skill in the Alexa developer console.
Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
On the left pane, click Endpoint.
In the box next to Default endpoint, paste the ARN for the Lambda function, and then click SAVE.

Step 3: Implement required features

After you create the Lambda function and add it to your skill's configuration, you add your skill code to the Lambda function. You can do this in the AWS Lambda console. For more details, see creating functions using the AWS Lambda console editor in the AWS Lambda documentation.

Implement required features for a music skill

To build a music skill, you must implement the following directives:

For the best user experience, your skill should support other directives in addition to those in the preceding list. For example, GetPreviousItem allows users to replay the previous track. The API reference documentation contains additional details about the interfaces and the functionality they provide.

Implement required features for a radio skill

To build a radio skill, you must implement the following directives:

You can optionally implement the GetItem directive.

Implement required features for a podcast skill

To build a podcast skill, see Implement Podcast Skill Features.

Step 4: Configure account linking (optional)

Account linking connects the identity or data of the skill user with a user identity in your music service cloud. Account linking isn't required. To learn more about account linking, see understand account linking. For details about how to implement account linking in your skill, see Account Linking for Smart Home and Other Domains.

To implement account linking for your skill by using the ASK CLI, see the create-account-linking subcommand in the ASK CLI command reference. Account linking properties are maintained separately from the skill manifest. For more details, see account linking schemas.

Step 5: Upload catalogs

For music and radio skills, see Upload Music or Radio Catalogs.

For podcast skills, see Upload Podcast Catalogs.

Step 6: Enable the skill for testing

Complete the steps to enable your skill for testing in the developer console. Use the Test page in the developer console to test your skill with the Alexa simulator.

Step 7: Test the skill in the Alexa app

After your implementation is complete and you've tested your skill code in Lambda, you can functionally test your skill with an Alexa-enabled device.

To test your skill in the Alexa app

Find your skill in the Alexa app, then enable and account-link (if needed) your skill.
Give Alexa commands using the utterances that your skill supports. Make sure to test the skill with valid utterances and invalid ones, and in a variety of conditions, such as with the skill enabled, disabled, not account linked, etc.
When you're satisfied with your skill's performance, you can submit it for certification.

For more details about how to test your skill, see the testing guide.

Step 8 Provide publishing information

To distribute your skill to the Amazon Alexa Skills Store, you must fill out the required metadata for your skill on the Distribution tab in the developer console. For more details about publishing your skill, see Define Skill Store Details and Availability.

Step 9: Submit the skill for certification

When you're ready to publish your skill, submit for certification. For details about certifying a skill, see Test and Submit Your Skill for Certification. After your skill is certified and published, it appears in the Alexa Skills Store for Alexa users to discover.

Explicit language filter feature

The Explicit Language Filter (ELF) is a feature for music and radio skills that gives users more control over their listening experience. Users can let Alexa know that they prefer to listen to songs, playlists, and stations without explicit content. When the ELF feature is turned on, Alexa only plays content from skills that support the feature.

Note: ELF isn't supported for podcast skills.

To support ELF in a music skill, you need to:

Enable the ELF feature, which tells Alexa that the skill is capable of filtering explicit content. Do this by selecting the Explicit Language Filter check box on the Features page in the Alexa developer console, or by adding EXPLICIT_LANGUAGE_FILTER as a feature in your skill manifest.
Modify your skill code (Lambda function) to handle the ExplicitLanguageAllowed field in Initiate and GetPlayableContent requests by not returning identifiers for explicit content when ExplicitLanguageAllowed is set to false. The ExplicitLanguageAllowed field tells your skill whether the user wants explicit content blocked.

Your skill must filter and not return explicit content when ExplicitLanguageAllowed is false. If you can't guarantee that your skill can exclude explicit content, disable the Explicit Language Filter feature. When the Explicit Language Filter feature is disabled for a skill, the skill isn't available to users who have configured Alexa to block explicit content.

Create a new skill by using the CLI

Important: Skip this step if you created a music skill in the console in step 1.

You can use the ASK CLI to create and manage skills from the command line. If you want to create a skill in the developer console instead, see Step 1: Create a new skill.

To install the ASK CLI, complete steps 1 – 3 on the Quick Start ASK CLI page. To see a video that demonstrates how to use the CLI, see ASK CLI Setup on YouTube. Before you use the CLI, you should also familiarize yourself with ASK CLI commands not supported for music, radio, or podcast skills.

To create your skill using the ASK CLI, first create a Lambda function for your skill's code and know the ARN of the Lambda function. Then use the following command, replacing music-skill.json with the name of a file that contains a valid music, radio, or podcast skill manifest. For an example, see the Example music skill manifest.

ask api create-skill -f music-skill.json

See the following example:

C:\> ask api create-skill -f music-skill.json
Create skill request submitted.
Skill ID: amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4
Please use the following command to track the skill status:
    ask api get-skill-status -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4

C:\> ask api get-skill-status -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4
{
  "manifest": {
    "eTag": "fbcc6fe0491166550b11a819d55b106e",
    "lastUpdateRequest": {
      "status": "SUCCEEDED"
    }
  }
}

After you create a skill, copy the skill ID (for example, amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4). Then add a trigger for your Lambda function using this skill ID.

To create a trigger for your Lambda function:

Sign in to the AWS Lambda console.
Find the Lambda function for your skill, and then click the function.
On the left side of the page, for Add triggers, choose Alexa Skills Kit.
At the bottom of the page, for Skill ID verification, select Enable (recommended). For Skill ID, paste the skill ID.
At the bottom of the page, click the Add button. Then, at the top of the page, click the Save button.

Create your local project directory

After you create a skill with the preceding command, use the following ASK CLI command to create a local project directory for the skill. Before you use this command, make sure that your skill name is unique among your skills, because the name is used to create (or overwrite) the local project directory. In the following command, replace amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4 with your actual skill ID.

ask smapi export-package -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4

Configure your skill properties

To configure the properties of your skill, edit the skill.json file in your local project directory. For more details about skill properties, see the music, radio, and podcast skill property reference.

After you edit the skill.json file, update your skill with the ask deploy command. You must use this command from within your local project directory.

The ask deploy command updates your skill in the Alexa Skills Kit developer console, but doesn't update your live (published) skill. To promote changes from the skill in the developer console to your published skill, you must submit your skill for certification in one of the following ways:

Use the ask api submit command in the ASK CLI.
Test and submit your skill for certification in the developer console.

Example music skill manifest

The following example shows a valid music skill manifest. To use this example, change the skill name before creating your skill.

For a complete reference of all properties in a skill manifest, see the skill manifest documentation.

Copied to clipboard.

{
  "manifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "summary": "one sentence description of skill",
          "examplePhrases": [
            "play music on <skill name>"
            "<another example phrase>"
          ],
          "keywords": [],
          "name": "display name of skill",
          "description": "longer description of skill"
        }
      },
      "isAvailableWorldwide": false,
      "testingInstructions": "",
      "category": "STREAMING_SERVICE",
      "distributionCountries": [
        "US"
      ]
    },
    "events": {
      "subscriptions": [
        {
          "eventName": "SKILL_ENABLED"
        },
        {
          "eventName": "SKILL_DISABLED"
        },
        {
          "eventName": "SKILL_ACCOUNT_LINKED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_STARTED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_FINISHED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_STOPPED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_FAILED"
        }
      ],
      "endpoint": {
        "uri": "<your Lambda ARN>"
      },
      "regions": {
        "NA": {
          "endpoint": {
            "uri": ""
          }
        }
      }
    },
    "apis": {
      "music": {
        "endpoint": {
          "uri": "<your Lambda ARN>"
        },
        "locales": {
          "en-US": {
            "features": [
              {
                "name": "EXPLICIT_LANGUAGE_FILTER"
              }
            ],
            "aliases": [
              {
                "name": "<a name users speak to invoke my skill>"
              }
            ],
            "promptName": "<the name Alexa will speak when referring to my skill>"
          }
        },
        "interfaces": [
          {
            "namespace": "Alexa.Audio.PlayQueue",
            "requests": [
              {
                "name": "GetNextItem"
              },
              {
                "name": "GetPreviousItem"
              }
            ],
            "version": "1.0"
          },
          {
            "namespace": "Alexa.Media.Playback",
            "requests": [
              {
                "name": "Initiate"
              }
            ],
            "version": "1.0"
          },
          {
            "namespace": "Alexa.Media.PlayQueue",
            "requests": [
              {
                "name": "GetItem"
              },
              {
                "name": "SetShuffle"
              },
              {
                "name": "SetLoop"
              }
            ],
            "version": "1.0"
          },
          {
            "namespace": "Alexa.Media.Search",
            "requests": [
              {
                "name": "GetPlayableContent"
              }
            ],
            "version": "1.0"
          }
        ]
      }
    },
    "manifestVersion": "1.0",
    "permissions": [],
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "isExportCompliant": true,
      "containsAds": false,
      "isChildDirected": false,
      "usesPersonalInfo": false
    }
  }
}

Music, radio, and podcast skill property reference

This section describes the properties that are specific to music, radio, and podcast skills. These properties are specified in the apis.music section of the skill manifest, as shown in the previous example. For a complete reference of all properties in a skill manifest, see the skill manifest documentation.

Field	Description	Required	Type
`music.endpoint.uri`	Contains the Amazon Resource Name (ARN) for the AWS Lambda function that contains your skill code.	yes	string
`music.locales.aliases`	A list of one, two, or three names that a user can use to invoke your skill. This is similar to the skill invocation name for custom skills, but music, radio, and podcast skills allow up to three names. For example, if you set "awesome music" as an alias for your skill, users who want to hear top hits from your skill could say, "Alexa, play top hits from awesome music" to invoke your skill. Note that existing users of your skill must disable and then re-enable your skill for alias changes to take effect. For example, if you set your skill alias to "awesome music", any user who enables your skill can interact with your skill through utterances such as "Alexa, play Lady Gaga on awesome music." If you later replace the alias "awesome music" with "best music", current skill users must disable and then re-enable the skill for "Alexa, play Lady Gaga on best music" to work.	yes	list of strings
`music.locales.promptName`	The name that Alexa uses when speaking the name of your skill to users.	yes	string
`music.interfaces`	A list of skill interfaces that your skill supports. For more details, see the music, radio, and podcast skill API reference.	yes	list of strings
`music.locales.features`	Indicates whether your skill supports the `ELF` feature to filter explicit language. If it does, include this property with a value of `EXPLICIT_LANGUAGE_FILTER`. Otherwise, omit this property. Note: "`ELF` isn't supported for podcast skills."	no	string
`music.contentTypes`	(Podcast only) Add this field to use GetPlayableContent for state persistence.	no	object

CLI commands not supported for music, radio, or podcast skills

The following ASK CLI commands and features don't support music, radio, or podcast skills.

ask new

The ask new command can only create a custom skill. For the ASK CLI command to create a music, radio, or podcast skill, see Create a new skill by using the ASK CLI.

ask simulate

This feature isn't supported for music, radio, or podcast skills.

ask add and ask remove

These commands refer to in-skill products. In-skill products aren't supported for music, radio, or podcast skills.

ask api subcommands

The following API sub-commands don't support music, radio, or podcast skills.

get-model
head-model
update-model
simulate-skill
get-simulation
invoke-skill
create-isp
update-isp
associate-isp
disassociate-isp
get-isp
list-isp-for-skill
reset-isp-entitlement
delete-isp
intent-requests-history

Submit changes to a live skill

After your skill is live, any changes to the skill must be certified. For example, your skill must be recertified after changing the skill metadata. The certification review varies depending on the changes.

Note that updating your skill's catalog data doesn't require recertification. Skill catalogs are managed separately, with different workflows, compared to skill properties. For more details about catalogs, see upload catalogs.

For more details 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.