You might have seen our blog post and videos about an Alexa skill to play SoundCloud music (video and blog post). We were very excited to publish the Alexa SoundCloud skill so everybody could use it to listen to their music on SoundCloud. Sadly we didn’t anticipate one big blocker.

Last week we submitted a first version of the skill to Amazon for review. It had some minor technical bugs in the implementation that could be solved very fast. But there was also this:

Protecting intellectual property rights is important to us. Please provide documentation demonstrating that you have the right to use copyrighted material. The documentation must be either a confirmation letter from the intellectual property rights holder or a copy of the applicable license. Otherwise, please remove the copyrighted material within the skill’s responses.

That’s something I as a developer cannot solve. So we got into contact with SoundCloud to ask if they can provide such documentation. Mathis, a very nice moderator on the SoundCloud community recommended me to open a ticket with the copyrights team.

So I did that. This week the answer came and destroyed our hopes for publishing.

Unfortunately we are currently not accepting Alexa integration applications and do not proactively review any applications before they are shipped to the stores, as we don’t have the capacity to do so. This means we are unable to provide this documentation to Amazon.

I am not blaming SoundCloud here, I guess copyright issues with the music industry are not fun. Anyway this means we can’t publish the skill.

Since we are proud of what we’ve accomplished and still would like to see it being used we open-sourced the code. The rest of this blog post will be instructions on how to use it in developer mode, since this doesn’t require a certification.

Get the code here

Self-hosting the Skill to Run it in Developer Mode

The implementation of our Alexa skill is done in Kotlin. It is meant to be deployed in AWS Lambda, a serverless hosting service by Amazon that integrates well with Alexa skills.

You will need the following to run the Alexa SoundCloud skill:

  • A SoundCloud client id and secret. You can register an app here to get those. It can take some time for SoundCloud to approve a request. Don’t do this immediately, you need to first create the Alexa skill!
  • An AWS account. You can create one here. You will probably stay in the free tier with this skill.
  • An Amazon developer account, here. You should use the account that you already use for Alexa here!
  • A server where you can run Nginx which is needed to make the account linking work reliable with SSL enabled. Caution: I will not explain how to configure SSL in this blog post!

Preparing the Alexa SoundCloud Skill in the Amazon Developer Console

First log in to the Amazon Developer Console and choose Alexa from the top menu.

Amazon Developer Console

Click Get Started in the Alexa Skills Kit section. There you can choose the Add a New Skill button. There you have to enter a name and invocation name for the skill. Both can be „soundcloud“ as long as you don’t publish the skill. Be also sure to enable the audio player!

I will only show the examples for English (US) in this post, but it is very easy to use another language or even add multiple.

Create a New Alexa Skill

Now switch to the Interaction Model tab. You have to fill in the Intent Schema and Sample Utterances. You can find them here. The interaction model is the same for all languages, just open the IntentSchema_en_US.json file and paste its contents into the field. Choose the sample utterances file that matches your language and paste its contents, too!

The result will look similar to this:

Interaction Model

Now switch to the configuration tab. We need to do three things before we can finish configuring the skill.

  1. We first need to deploy our code. In the Skill Information tab you can find your application id which you will need, so note it somewhere (some-strange-number will be different for you – copy the whole id, including amzn1.ask.skill.) Application ID
  2. Request a SoundCloud client id with the correct redirect URI. For this you need to enable the account linking feature in your skill. This will give you two Redirect URLs. Write down the one that starts with https://layla.amazon.com. Account Linking
  3. Configure an OAuth proxy server

Requesting the SoundCloud Client ID

Go to the SoundCloud App Registration and fill it out. In the step for the Redirect URI use https://layla.amazon.com, the URL you noted before.

SoundCloud Application Registration

You might have to wait some time until your application gets approved. Afterwards you will find the client id and secret here.

Deploying the OAuth Proxy Server

Amazon provides two redirect URLs for OAuth, but SoundCloud can only work with one. To overcome this, we deploy an Nginx that transforms the request from Amazon to use always the same redirect URL.

You can find the necessary files here.

You need to

  • Configure SSL in the nginx.conf by setting ssl_certificate and ssl_certificate_key to your certificate and private key
  • Replace ENTER_YOUR_REDIRECT_URI_YOU_CONFIGURED_WITH_SOUNDCLOUD with the https://layla.amazon.com URL you wrote down earlier
  • Provide bootstrap.min.css (caution, CDNs will not work!) if you want the page to look a little bit more fancy

You can also change the index.html if it is too much text for you. Write down the domain of the server you deployed this Nginx on.

Preparing the DynamoDB Instance

The Alexa SoundCloud skill keeps the information about the current list of tracks that is being played in DynamoDB. In order to use the skill you have to create a table there.

Go to the DynamoDB console. There click the Create table button.

DynamoDB Dashboard

On the next page, name the table soundcloud-session and the primary key user. The type String needs to be selected.

DynamoDB Create Table

When the table is created you will need to find its ARN, an AWS-wide identifier. It will start with arn:aws:dynamodb. Write it down!

DynamoDB ARN

Deploying the Lambda

Download the release from GitHub (the file alexa-soundcloud-skill-fat-1.0.0-RELEASE.jar). If you rather want to build from source, clone the repository, checkout the tag 1.0.0 and run the Gradle build task.

Go to the AWS Lambda console and click Create a Lambda function.

Create a new Lambda

On the next page, don’t select a blueprint but go immediately to Configure triggers. There, add Alexa Skills Kit, so Alexa is able to invoke the lambda.

Configure triggers

Click Next. Choose a name such as „alexa-soundcloud“. Choose the Java 8 runtime. Choose to upload the file alexa-soundcloud-skill-fat-1.0.0-RELEASE.jar you downloaded before.

In the environment variables section you need to add the following:

  • SOUNDCLOUD_CLIENT_ID: the client id you got from SoundCloud. If you don’t have this yet leave it empty and add it later.
  • ALEXA_SKILL_ID: the id you copied before from your Alexa skill, should begin with amzn1.ask.skil.
  • DYNAMODB_REGION (optional): if you want to override the region of the DynamoDB table.
  • DYNAMODB_SESSIONS_TABLE (optional): if you want to override the name of the DynamoDB table.

Configure function

Now scroll down to Lambda function handler and role. We need to tell which function AWS Lambda should invoke in our skill and define a role so it can access DynamoDB and Cloud Watch.

In the handler field, enter de.techdev.alexa.soundcloud.SoundcloudSpeechletStreamHandler.

For the role, click Create a custom role. A new window will open. In this window:

  • Leave IAM Role at Create a new IAM role.
  • Name the role „soundcloud-lambda-execution“.
  • Edit the policy document and insert the following:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem"
      ],
      "Resource": [
        "arn:aws:dynamodb:$dynamodb-region:$dynamodb-number:table/soundcloud-session"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}

Be sure to replace $dynamodb-number and $dynamodb-region with the number you had in the ARN for your DynamoDB table. Or just replace the complete ARN! Now click Allow.

Now it should look like this (ignore the slightly wrong role name here):

Lambda function handler and role

Finally, click Next and on the next page Create function.

Now you need to find the ARN of your Lambda. On the overview page for the lambda function you can find it here:

Lambda ARN

Write it down! Now we can continue with the Alexa Skill.

Connecting the Alexa Skill With the Lambda

Go back to the Amazon Developer Console and your Alexa skill. In the Configuration tab, choose AWS Lambda ARN for Service Endpoint Type. Choose your AWS region and paste the Lambda ARN!

Skill Lambda Configuration

Now we have to configure account linking so the skill we be able to access your SoundClound account. In the Account Linking section, set the following:

  • Authorization URL: https://your.proxy.server/sc/connect where your.proxy.server is the domain of the proxy server you configured before.
  • Client Id: your SoundCloud client id. If you don’t have this yet you can add it later.
  • Domain List: Add the following domains - soundcloud.com, a1.sndcdn.com, a-v2.sndcdn.com
  • If you need Facebook login additionally add facebook.com, m.facebook.com, graph.facebook.com
  • Switch Authorization Grant Type to Auth Code Grant
  • Enter https://api.soundcloud.com/oauth2/token as the Access Token URI
  • Enter your SoundCloud client secret for Client Secret. If you don’t have this yet you can add this later.
  • Switch Client Authentication Scheme to Credentials in request body.

It will look like this:

Account Linking

Finally make sure testing is enabled for the skill so you can use it with your echo. Switch it on in the Test tab:

Enable Test

And that’s it! Your Alexa skill is now configured.

Enabling the Skill on Your Device

For this step it is important that you use the Amazon account that you used to create the skill for your Alexa device!

Now you can enable the skill in the companion app for your Echo device! Open the Skills section and click on Your Skills. Since testing was enabled it will be listed there. You can enable it and should be asked to link your account!

Stay in the Loop

If you would like to receive an email every now and then with new articles, just sign up below. We will never spam you!