Amazon Alexa Skill for Streaming Radio: Code Generator
A guide by Andy Moore First published June 2019, revised August 2020
How to stream your radio station on Alexa
A tool to help you stream your radio station to Amazon's Alexa devices!
Used by Internet Radio Stations, Hopsital Radio Stations, Local, Regional, National, State and Pirate Broadcasters
Since it's been online it's helped Internet; AM, FM and DAB stations around the world get on Alexa
If you can cut and paste you have this covered.
One to one help available to blind / partially sighted / charitable stations.
Hello user of assistive screen reading technology.
Sorry to say the Amazon Developer Console doesn't work that well on screen readers.
I've had two blind organisations say the console wouldn't let them submit their skill.
Don't worry. We can still get your stream live as I'm happy to host it for you under my developer account.
Please fill in the form below, and click the link in your email to generate the code, then email firstname.lastname@example.org tell me you've read this (only screen readers will see it) and we'll get the ball rolling.
It will take a little email ping-pong, and a couple of days to get it approved with the team at Amazon but we'll get you sorted.
If you're interested in those I've helped get live, ask Alexa to play H.H.C.R. or THE BLIND HAMS NETWORK.
I'll sort this for you for free, I don't want your cash. I'd rather have the good karma.
I look forward to hearing from you soon.
- 10th September 2020: Added support for playlists / HLS (HTTP Live Streaming)
- 17th August 2020: Added Screen Reader only section for our blind friends
- August 2020: Relaunched site
- July 9th 2020: Kept up with a change at Amazon
- July 1st 2020:
- Totally revised front and back end
- Added Email validation
- Enhanced the stream validation and analysis
- Added optional Intro support: "You're listening to"
- Added optional Outro support: "Thanks for listening to"
- June 17th 2020: Added extra tips
- June 16th 2020: Extended the validation on the back end form processor:
- Checks stream address resolves and returns a HTTP status code of 200
- Checks stream is actually playing audio, and is not silent
- June 13th 2020: Updated Frequently Asked Questions
- January 5th 2020: Steps updated to reflect changes at Amazon
- August 29th 2019: FAQs at the bottom of the page.
- Station Logo on displays
- Alexa, what's playing?
- Alexa, what song is this?
- Alexa, who sings this song?
- Alexa, what's this song called?
Step 1: Your Radio Station's Details
Some things you need to know:
- The "Alexa, play" value will be used as the invocation, examaple: Alexa, play Your Station Name.
- The web address will be read to users asking Alexa for help, example: You can say Play, Stop or Resume. For more information please visit...
- The stream address can be Icecast or Shoutcast, the big requirement is that the stream must run on a HTTPS secure connection.
- The (optional) intro text will be read to the user before the stream starts.
- The (optional) outro text will be read to the user after they've asked the stream to stop; pause, or quit.
- The email address is needed to tell you about updates to this code: I promise I'm 100% spam free.
- The email is only for me, it doesn't go to Amazon and isn't linked with the skill in any other way.
Step 2: Check the data and generate the code
- If your station name includes initials like FM or ABC, enter them with dots / periods, like F. M. or A. B. C.
- Check how Alexa responds to your invocation before you start this process:
- Does Alexa understand the invocation?
- Does the invocation respond, has it already been used?
- Does the invocation launch another Skill, like TuneIn?
- Amazon require a secure stream. If your stream is not secure, go and fix that, then come back.
- Check the Security Certificate on your stream here (you need a screen of green ticks to satisfy Amazon)
- Amazon require you to pay music royalties: make sure you have some certification to hand for the submission process.
- Enter a valid email address; you will need to confirm it before this page generates any code
Stream Analysis Results:
Amazon Skill JSON:
Step 3: Create a free Amazon Developer Account
Go to https://developer.amazon.com/ and either login to, or create you Amazon Developer Account.
Step 4: Create an Alexa Skill
Go to https://developer.amazon.com/alexa/console/ask and click the Create Skill button.
Then enter Your Station Name in the Skill Name form field, and select the Default Language of your skill.
Next you need to Choose a model to add to your skill, select the Custom option.
Now Choose a method to host your skill's backend resources, and select the Alexa-Hosted (Node.js) option.
The Alexa-Hosted (Node.js) option comes with a rather generous helping of free computational power and storage space.
The following limits apply to each account. AWS Lambda: 1 million free AWS Lambda requests and 3.2 million seconds of compute time per month. Amazon S3: 5 GB of Amazon S3 storage, 20,000 get requests, 2,000 put requests, and 15 GB of data transfer out per month.
Scroll towards the top of that page, click the Create Skill button up there.
January 2020 Update: An extra step!
The new step of Choose a template to add to your skill, has caused confusion for several people who emailed me recently; just select the Hello World Skill option and click Choose: don't worry about us not actually wanting a Hello World Skill, we're going to overwrite everything it does next.
It may take Amazon a couple of minutes to create your skill.
Once this is done you'll get several annoying alerts on the right hand side of your screen.
Based on feedback and questions from users I can tell it's round about here where people's attention starts to slip off a little and things get overlooked. Now is a good time to take a break for five minutes to make sure your brain is refreshed for the next few steps!
Step 5: Enable the AudioPlayer Interface
This is an essential, yet commonly overlooked step: you need your skill to be able to play audio!
Because playing a stream requires what Amazon calls the AudioPlayer Interface, we'll need to enable it.
On the left hand side of the screen, there should be a menu, click Interfaces, then enable the Audio Player.
Now click the Save Interfaces, button near the top of the screen.
Step 6: Paste the JSON
Now click the Interaction Model link from the menu on the left, followed by JSON Editor.
Select all of the code in the textarea, then delete it.
Copy the JSON code from this page, paste it into the textarea.
Click the Save Model button at the top of the screen, followed by the Build Model button.
Next click the Save, button, followed by the Deploy button.
Step 8: Enable Testing
Before you can test this on your Alexa device, you need to click the Testing link from the menu at the top of the screen.
Switch on Testing.
Step 9: Device Testing
Whilst Amazon provide an excellent browser based tool for testing your skill, it doesn't play any audio so you're better off testing it with a real gadget; that is after all what you're listeners will be tuning in on!
If your Alexa device is registered to the same account as your Amazon Developer account, you will now have access to your radio station on your Alexa.
"Alexa, play Your Station Name"
You should now be listening to your streaming radio station!
Step 10: Distribution
Consider these final few steps the paperwork you need to complete to get your new skill listed, and available for the public to tune into.
This defines how your skill will appear to customers on the Amazon site.
Amazon need you to complete the following for your skill's public page.
- Public Name
- One Sentence Description
- Detailed Description
- What's New
- Example Phrases
- Small and Large Skill Icons
Privacy and Compliance
- Does this skill allow users to make purchases or spend real money?
- Does this Alexa skill collect users' personal information?
- Is this skill directed to or does it target children under the age of 13?
- Does this skill contain advertising?
- Export Compliance
- Testing Instructions
Advertising: Amazon allow advertising, as long as the ads meet the criteria below; this forbids giving Alexa a dedicated stream, and serving different ad output than you do on your website, or app: some might find this a little restricting, as a former Group Traffic Manager, I used to send different ad breaks to different transmitters, and it makes sense for a station to utilise different media for different campaigns, but that's more advanced than your average streaming setup!
"Streaming music, streaming radio, podcast, and flash briefing skills may include audio advertisements as long as (1) the advertisements do not use Alexa's voice, Amazon Polly voices, or a similar voice, refer to Alexa, or imitate Alexa interactions and (2) the skill does not include more or materially different advertising than is included when the same or similar content is made available outside of Alexa."
Testing Instructions and Sample Phrases:
In order to pass Amazon Certification you need to test the following voice commands, then once satisfied your stream behaves as it should, paste these details into the form, someone at Amazon will check they work:
- Alexa, Play Your Radio Station
- Alexa, Pause
- Alexa, Resume
- Alexa, Start Your Radio Station
- Alexa, Stop
- Alexa, Ask Your Radio Station to play
- Alexa, Cancel
- Alexa, Ask Your Radio Station to play Your Radio Station
Tip: Paste a link to an online copy of your music licences in the testing field
Whilst Amazon are thorough, and will ask you to provide copies of your music licences, I find it interesting knowing the TuneIn app, and skill, are in no way as conscientious as Amazon with regards to royalties: there are over 100,000 stations on TuneIn, where is the same concern for rights with each of them?
"If your skill makes legitimate use of trademarks, intellectual property, or brands, you must clearly indicate that you have permission to use these, and provide proof, when you submit your skill for certification. In the developer console, go to Distribution > Privacy & Compliance and use the Testing Instructions form to provide this information, including external links to documentation evidencing your right to use the intellectual property (such as proof of trademark registration or a license agreement with the rights owner) and contact information, if needed. With this information, the certification team will be able to determine if your skill has the necessary permissions."
See 'Policy Testing for an Alexa Skill'
This is where you can set who has access to this skill, and which countries it'll be available in.
This is where you can geo-lock your stream on Alexa, to meet your music licencing requirements.
Step 11: Certification and Submission
You need to click the Certification link from the menu at the top of your screen.
These final certification steps, each launched via the menu on the left, ensure that quality criterea are met before your skill can be launched to the public, it automates a series of tests like checking for complete information; broken code and bad syntax:
If you skipped any of the questions in the Distribution section the validation report will pick them up and tell you what needs correcting. If only every online tool was as thoroughly validated, and as well explained as this:
This is the screen you want to be looking at now:
So close now, hit that Run button!
The final step: Submission!
If you've followed every step of this guide you should now be ready to submit your Alexa Skill.
Go on, do it: hit that blue button that you've been working towards!
Has this helped? Why not treat me to an Amazon Gift Card?
Frequently Asked Questions
Can this manage streams for more than one station?
Yes, but you'd need to hack around with the code.
You might just find it a lot easier to create a skill for each station you manage; this will involve having to put each different skill through Amazon's certification, it requires a little more admin, but it does negate the need for more complex code.
Is there a quick hack to getting Icecast running on HTTPS?
Sorry, no. As for why Amazon insist on SSL streams, I'm too am perplexed about their reasoning.
How do I get Icecast to run on SSL?
CertBot is pretty cool, it creates free SSL Certificates, the Icecast website has a guide to follow, though I may create a blog post about automating the whole process.
Hot question! My stream is silent / Amazon say my stream needs to run on port 443, what do I do?
It seems there was an Amazon back end update some time in May 2020 which has caused some station's streams to return silence.
The Amazon console says the stream needs to run on port 443, this isn't technically accurate as Alexa can actually play any stream hosted in a https environemnt, where the certificates are valid.
Several stations have been in touch asking about this, through checking the Security Certificate setup on streams which have been silent, I was able to see it's an issue with Server and Chain certificates in most cases that is causing the issue.
If your stream is silent, check it at https://www.sslshopper.com/ssl-checker.html
If you manage your own SSL Certificates regenerating them will most likely fix the issue, if you're using a streaming provider you might want to drop them a line, include a link to your stream's SSL report.
New Will you do it for us?
No, sorry, unless there are exceptional circumstances: for example, you're a radio station run by blind volunteers, and your screen reader can't render the developer console. Those kind of exceptional circumstances. If you've not had a screen reader tell you about it already, it doesn't apply to you.
New Will you do it for us, if we offer you cash?
No, sorry: there's no reason why you can't get your radio skill published on Alexa yourself. I don't want to feel obligated to you, I don't need your technical headaches, and frankly, if you can't follow a guide you'd probably frustrate the hell out of me.
New What to do if it doesn't work
If you're struggling to get this working re-read the guide; sorry but you've most likely overlooked something and it might be best to start from scratch, and make sure you follow each step as directed.
The most commonly overlooked steps are now highlighted in red making them much harder to miss, but they are:
- Not enabling the Audio Player
- Not clicking Save Interfaces after enabling the Audio Player
- Not clicking Save Modal or Built Modal after adding the JSON
- Your stream's SSL sucks (the certificate chain is broken / invalid / misconfigured)
I've done tutorials like this before and struggled with comment admin; it really can go crazy! Therefore if you've any questions or comments please email me, I'll try to respond to everyone, and will update this page accordingly.
Thanks for reading, hope this helps
Has this helped? Why not treat me to an Amazon Gift Card?