Steps to Create a Music, Radio, or Podcast Skill

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 AWS Lambda function (an Amazon Web Services (AWS) offering) that handles requests from the Alexa Music, Radio, and Podcast Skill API and communicates with your content service cloud.

Before you create your skill, make sure that you've taken care of the prerequisites.

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 music or podcast skill in the developer console or Create a music, radio, or podcast 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.

Procedure overview

The following task list outlines the procedure that you must follow to create a music, radio, or podcast skill.

Step 1: Create a new skill by using the developer console (Skip this step if using the CLI to create your skill.)
Step 2: Create a Lambda function
Step 3: Implement required music, radio, or podcast features in your Lambda function
Step 4: Create a new skill by using the command-line interface (CLI) (Skip this step if you used the console to create your skill.)
Step 5: Configure account linking (Optional, music and podcast skills only)
Step 6: Upload catalogs
Step 7: Enable the skill
Step 8: Test the skill
Step 9: Submit the skill for certification

Step 1: Create a new skill by using the developer console

Important: Skip this step if you plan to create a new skill by using the CLI in step 4.

The Alexa Skills Kit developer console is a web application for creating and managing skills in a web browser.

To create a new skill in the developer console:

Sign in to the ASK developer console.
Click the Create Skill button.
On the Create a new skill page, do the following:
1. For Skill name, type a name for your skill. For example, "MyMusicSkill" or "MyPodcastSkill".
2. For Choose a model to add to your skill, select Music. If you don't see the Music option, see I can't create a music skill in the Alexa Skills Kit developer console on the Troubleshooting page.
  Note: The underlying skill type is music for both music and podcast skills.
3. In the top right corner of the page, click the Create skill button.
On the left side of the page, click Endpoint.
Copy the skill ID displayed near the top of the page. For example, amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6c036f905. You need the skill ID later to configure your AWS Lambda function.

To update your skill name, prompt name, or invocation names:

On the left side of the page, click Skill Names.
Type or update your skill name, prompt name, or invocation names. Then click the Save button in the top right corner of the page.

To select the interfaces that your skill supports:

On the left side of the page, click Interfaces.
Select the check boxes next to the interfaces that your music or podcast skill supports. Then click the Save button in the top right corner of the page.

To select the features that your skill supports:

On the left side of the page, click Features.
Select the check boxes next to the features that your music or podcast skill supports. Then click the Save button in the top right corner of the page.

Explicit Language Filter (ELF) feature

Note: ELF isn't supported for podcast skills.

The Explicit Language Filter (ELF) is a feature for music 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.

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

Enable the Explicit Language Filter 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 ASK 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.

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, type "basic". Select the check box next to AWSLambdaBasicExecutionRole, then click the Next: Review button.
In the box next to Role name, type 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:

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, type 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 already created your music or podcast skill using the ASK 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 music, radio, or podcast skill with the ASK CLI.

To add the Lambda ARN to your skill configuration:

Sign in to the ASK developer console.
Click on the name of your skill.
On the left side of the page, click Endpoint.
In the box next to Default endpoint, paste the Lambda ARN. Then click the Save button.

Step 3: Implement required music, radio, or podcast features in your Lambda function

After you create the Lambda function and add it to your skill's configuration, you need to add your skill code to the Lambda function. You can do this in the AWS Lambda console. For more information, 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 directive:

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

See Implement Podcast Skill Features.

Step 4: Create a new skill by using the ASK CLI

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

The Alexa Skills Kit Command Line Interface (ASK CLI) is a tool you can use to create and manage skills from the command line. The ASK CLI is a command line client for the Skill Management API (SMAPI).

To install the ASK CLI, complete steps 1 through 3 on the Quick Start ASK CLI page. To see a video demonstrating how to use the ASK CLI, see ASK CLI Setup on YouTube. Before you use the ASK CLI, you should also familiarize yourself with the ASK CLI commands that are 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, then click on it.
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 information 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.
Use the Alexa Skills Kit Developer Console:
1. Sign in to the developer console.
2. Click on the name of your skill.
3. At the top of the page, click the Certification tab.
4. On the left side of the page, click Submission. Then click the Submit for review button.

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.

{
  "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 information, 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

ASK CLI commands that are not supported for music, radio, or podcast skills

The following ASK CLI commands and features are not supported for 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 music, radio, or podcast skill 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 which are not supported for music, radio, or podcast skills.

ask api subcommands

The following API sub-commands are not supported for 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

Step 5: Configure account linking (optional, music and podcasts only)

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.

To configure account linking for your skill 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 information, see account linking schemas.

Step 6: Upload catalogs

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

For podcast skills, see Upload Podcast Catalogs.

Step 7: Enable the skill

While you're building your skill, you can enable (or disable) it in the Alexa Skills Kit developer console:

Sign in to the ASK developer console.
Click on the name of your skill.
At the top of the page, click Test.
On the test page, click the toggle next to Test is disabled for this skill.

To disable a skill, click the toggle next to Test is enabled for this skill.

You can use the Test page in the developer console to test your skill.

Step 8: Test your skill

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 do this:

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 are 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 9: Submit the skill for certification

The final step is submitting your skill for certification. You can submit your skill for certification on the Certification page in the ASK developer console. After your skill is certified and published, it appears in the Alexa Skills Store for Alexa users to discover.

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 re-certification. Skill catalogs are managed separately, with different workflows, compared to skill properties. For more information about catalogs, see upload catalogs.

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.