Support for Alexa Media Player

[dm7500]

Current Status

As at August 2025 experimental support is available in the beta channel

Original Post

Trying to play music from Spotify to my Alexa devices, which are set as media devices using Alexa Media Player. Alexa gives an error stating that the proper service calls must be made.

If this could be integrated in some way, it would be a game changer for playing music via HA. Happy to test anything as needed.

[marcelveldt]

I've inspected this today and so far I see no easy way to make that work. The Alexa Media Player does not allow to just send a stream URL to play which is what this integration needs. The only way to make this work properly is if somebody creates a custom Alexa skill that communicates with this integration.

I do not own a Alexa device so I can't do that.

A little googleing I just did quickly led me to several 3rd party solutions you could use to turn the Echo device into a unpnp receiver or squeezebox player. For example: https://www.amazon.com/ComputeQ-UG-Haftungsbeschr-Roomskills-Squeezebox/dp/B0983C2377

I'm happy to work with somebody to make this work but without an actual Alexa/Echo device to test with, this is not something I can start with alone

[adocampo]

I would gladly help, I'm not a developer, but I would help by testing it on my echos, unfortunately I'm located in Spain and the skill you pointed can be only installable on US echos (perhaps on DE as well, as per language selection)

[mabrochu-helpox]

I don't know how the SpotCast integration works but I'm able to play music from spotify on my alexa devices from Home Assistant, I don't believe a skill is needed.

[dm7500]

@mabrochu-helpox how do you bring the Alexa's into HA as media players though?

[Creepios]

Please see my comment below (https://github.com/orgs/music-assistant/discussions/431#discussioncomment-8964417)
for a possible solution!

[mabrochu-helpox]

Whith the alexa integration

[bdr99]

To be clear, this is not the official Alexa integration built into HA. This is a custom integration known as Alexa Media Player. It is found here: https://github.com/custom-components/alexa_media_player

[marcelveldt]

eveloper, but I would help by testing it on my echos, unfortunately I'm located in Spain and the skill you pointed can be only installable on US echos (perhaps on DE as well, as per language selection)

For Music Assistant to work it is required that the enddevice (the speaker) supports "play from url".
So basically we just want to send a url to a speaker. Just like a radio stream....

Music Assistant is not about playing Spotify on a speaker. Music Assistant is about playing all your online en offline media to a collection of speakers. The Spotcast implementation (and others like the alexa custom integration) send Spotify commands to the Echo speaker, not plain urls

[ohjables]

Its hacky but you can send urls like this:

service: notify.alexa_media
data:
  message: <audio src='https://url-to-mp3.mp3' />
  target: media_player.the_kitchen
  data:
    type: tts
  title: Happy Halloween

Probably not the intended use but im curious if there is another api we that could be leveraged ?

[flexage]

Can you please test that with a radio url ? If it keeps playing it is indeed an option to use that for Music Assistant

I also have the notify.alexa_media service from the Alexa Media Player Custom Component (https://github.com/custom-components/alexa_media_player/wiki) available, so I gave this a try.

First, I tried with a couple of MP3's:

service: notify.alexa_media
data:
  message: <audio src='https://kt-montage.com/files/smarthomeyourself/mp3/001.mp3'/>
  data:
    type: tts
  target: media_player.my_echo_dot_name

data:
  message: <audio src='https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3'/>
  data:
    type: tts
  target: media_player.my_echo_dot_name

The first one played, the second one didn't.

For the one that didn't work, Alexa spoke a message:

“Sorry I'm having trouble connecting to your Simon Says EU skill right now”

I then tried with a couple of internet radio urls, I tried an m3u playlist, and a generated stream url from within the m3u playlist:

service: notify.alexa_media
data:
  message: <audio src='http://pulseedm.cdnstream1.com:8124/1373_128'/>
  data:
    type: tts
  target: media_player.my_echo_dot_name

I received the same message from Alexa:

“Sorry I'm having trouble connecting to your Simon Says EU skill right now”

---

I did some sleuthing on the issue, and turned up the following related Amazon Developer Doc:

https://developer.amazon.com/en-GB/docs/alexa/custom-skills/speech-synthesis-markup-language-ssml-reference.html#audio

They say that when sending playback requests using TTS and the inline tag as above, that certain limitations around sample rates, bitrates, and runtime are imposed (copied from docs and bolded the critical blocking requirements):

• The MP3 must be hosted at an Internet-accessible HTTPS endpoint. HTTPS is required, and the domain hosting the MP3 file must present a valid, trusted SSL certificate. Self-signed certificates cannot be used.
• The MP3 must not contain any customer-specific or other sensitive information.
• The MP3 must be a valid MP3 file (MPEG version 2).
• For your speech response, the audio file cannot be longer than 240 seconds.
• The combined total time for all audio files in the outputSpeech property of the response cannot be more than 240 seconds.
• The combined total time for all audio files in the reprompt property of the response cannot be more than 90 seconds.
• The bit rate must be 48 kbps. Note that this bit rate gives a good result when used with spoken content, but is generally not a high enough quality for music.
• The sample rate must be 22050Hz, 24000Hz, or 16000Hz.
• You may need to use converter software to convert your MP3 files to the required codec version (MPEG version 2) and bit rate (48 kbps).

[marcelveldt]

ah OK so that is NOT useable ;-)

[marcelveldt]

Thanks for the extensive testing!

[flexage]

No problem, happy I could help!

[Bachigaloupe]

Yes, thanks for this testing as I too have gigs of mp3 files and several echos. Willing to test beta solutions. I don't think I can offer as much help as others but I am in the US and I see that can make a difference to Amazon

[flexage]

Enjoyed the Open Home Audio stream with you all! Very impressive stuff all around!

@marcelveldt Music Assistant seems great, and opens a world of possibilities!

I just wanted to offer up a potential path forward for supporting Echo devices, and that would be using them as a bluetooth audio target.

I regularly pair my Echo with my Macbook via bluetooth, and set it as my output device.

No special hardware of configuration needed, just the Amazon Alexa app:
Devices -> Echo & Alexa -> Select Device -> Bluetooth Connections -> Connect a Device

The simplest solution is to pair your Echo(s) with the host OS, and use them as system output device(s) - of course, that may incur limitations regarding targeting specific connected devices/groups
(or it may not... I can't purport myself to be an expert on linux audio, perhaps @pvizeli [Pascal] is better suited to answer that).

Traditionally, Bluetooth radios have supported a single audio streaming device per chip (except for a few specialist radios) - so 1 dongle = 1 speaker, 2 dongles = 2 speakers, etc....

However, the recent Bluetooth LE specification also adds "multi device audio streaming" from a single radio, I believe using the LC3 codec.

Here's some reference links:

https://embeddedcomputing.com/application/networking-5g/short-range-wireless-pan/le-audio-the-next-generation-of-bluetooth-audio-technology

https://www.bluetooth.com/learn-about-bluetooth/recent-enhancements/le-audio/

Note: It would not be the best solution in terms of making direct use of the PCM stream url you described in the video presentation, and it may not support the speaker latency/sync feature you have planned for the future - however, it is an option that maintains local-control, and I do not believe invokes the cloud once configured.

For that, I believe the only current 'official' option to request Alexa devices to play an url is using their custom skill API- and that of course requires an internet accessible url, so goes against the local-control philosophy, so is less than ideal - However Nabu Casa already provides a Home Assistant custom skill for Alexa, so I'd imagine some of the groundwork is already laid...

The relevant documentation appears to be available here: https://developer.amazon.com/en-US/docs/alexa/custom-skills/audioplayer-interface-reference.html#audio-stream-requirements

[marcelveldt]

Bluetooth could be a possible solution although I have no idea if that is 100% reliable. Just look for a HA integration for a Bluetooth media player. Another option is to use an intermediate ESP32 running the squeezelite firmware that outputs its audio to bluetooth.

1. ESP32 with PSRam
2. Install squeezelite on it: https://github.com/sle118/squeezelite-esp32
3. Activate the SLIMproto integration in HA (it will auto detect the squeezelite player(s))
4. Add the slimproto media_player to MA

[flexage]

Another option is to use an intermediate ESP32 running the squeezelite firmware that outputs its audio to bluetooth.

This is actually very sensible thinking, for a few reasons:

• Probably a smaller barrier to ingress for non-technical users than configuring Home Assistant OS (the HA supported project for flashing ESP firmware makes it a breeze)
• Makes use of the existing HA SLIMProto integration (like you say)
• Requires no code changes to MA?
• Very "on-brand" with the Audio in the Open Home presentation

Sounds like everything code and hardware related is already in place, so all that was needed was the concept and testing?

[marcelveldt]

Correct, in theory that should work and it just needs someone willing to test it.
Just make sure you have an ESP32 Wrover module (with PSRAM)

[OzGav]

@flexage Out of interest did you ever have a go at setting this up? Or any other BT connection?

[flexage]

Additional: I came across an article from last year on Mark Lewis's Blog, in which he configures audio with a bluetooth dongle on Home Assistant OS, seemed fairly simple: https://marklewis.blog/2021/02/25/home-assistant-bluetooth-speaker/

Mark was using a "Local VLC" community addon as a player, but I'm sure there's other things that can be done

[gromgsxr]

would we possibly be able to use something like this: https://www.youtube.com/watch?v=NoCPUypkimc&ab_channel=DabbleLab as a base for a custom skill to be able to play media from a url on amazon devices?

[marcelveldt]

Correct, that is what Amazon invented to do this.

[gromgsxr]

Is there a specific output URL from music assistant or homeassistant that I could point that skill kit at to see if it works? My ha is accessable via https so I would have thought the skill could play from a URL then.

Edit I pulled a generic web radio stream off the internet and built that template pointing at the URL for the radio station called it 'music assistant' I was able to get it to play the stream all good. I am also able to use the custom component 'alexa media player' to run a custom command 'open music assistant' and the stream started playing. so if I had a URL from music assistant that streams the music out of my home assistant that I could point the skill kit at I would assume I could them play music on my Alexa devices possibly.

[marcelveldt]

Music Assistant generates unique stream URL's on the fly for each playback session but if you can actually play some URL the foundation is there to make it work. Now you can go a few steps further and listen to the audio quality, is it good (enough) ? And perhaps test a few different file formats like mp3 and flac. If all that works it passed the test and there's only one issue left:

The streamservice in MA is only available on the local network on a dedicated network port. So you will need some sort of proxy that temporary opens up for the external stream request. My advice would be to fork the existing Alexa Media Player integration and override the method "play_media" in the media_player implementation. that will receive the stream URL from MA and you can add your own logic there.

[gromgsxr]

Above my skill level. Shame oh well

[erkr]

Moved to discussions, raise your votes!

[gromgsxr]

Gets my vote I'm happy to try and help if I can with testing ect.

[imduffy15]

I think we would need to create a music provider following https://developer.amazon.com/en-US/docs/alexa/music-skills/understand-the-music-skill-api.html and then hook into that via alexa_media_player through alexapys play_music function https://alexapy.readthedocs.io/en/latest/alexapy/alexapy.html#alexapy.AlexaAPI.play_music

[realroywalker]

No further update to the above, just waiting on the service call to be added into the Music Assistant code at the moment. I spoke with @marcelveldt on discord recently and he's understandably busy with work, life and other MA updates at the moment. But it's on his radar to do when he has time 😁
Once that change is in we should hopefully be most of the way there (assuming it works as intended)

[kingunlim]

thx for your update on this topic, that sounds very promissing 😬
if you guys manage this, that would be a milestone in terms of missing features!
i hope everything will work how you guys intend it! thx for all of your works!

[proffalken]

Also willing to volunteer my echos to test this - I've got the following:

• Original Echo
• Echo Dot
• Echo Flex
• Echo Dot Kids

Let me know if I can help!

[ohjables]

Curious if there has been any progress on this or if there is a targeted release that might provide this functionality? TIA!

[OzGav]

I haven’t heard any talk about this for a while so I assume little to no progress at this time. Maybe someone will,pick it up after the next release (due this month)

[zepheris]

Not a coder, just a dabler.
I found this which may help with creating a custom skill
https://github.com/dabblelab/3-alexa-audio-streaming-example-skill
This is the video that helps add the skill to your Alexa development console
https://www.youtube.com/watch?v=NoCPUypkimc

From what I understand. Activating this skill will have the backend load up an audio stream. The URL in this stream could be changed to point to your home assistant instance (or I believe nabu casa URL) for the .m3u file. If it's possible to code an audio stream, then we could use this skill.

The scenario would be to have the audio stream process start when opening the media player
Person says the invocation phrase (which you can set to whatever you want) "Alexa, open home streaming"
Alexa connects to your home assistant instance
You play some music and it's streamed to Alexa.

If this is achievable, then we could adapt the stream URL to other players. Using a m3u app on your phone to stream is one example that comes to mind.

Edit:
I just noticed that this scenario appears to have already been suggested :)

[phirestalker]

Any more progress on using the Alexa Media Player integration in conjunction with this?

[mericon]

Added an Pull request with an more detailed setup for the Skill in the Dev Console. Feel free to correct my bad English ;D

[alams154]

Thanks a bunch, just merged it

[faz17]

Has anyone installed Docker on the same device as Home Assistant? I'm using a Raspberry Pi with Haos.

[broyuken]

There’s an HA add on for this image you can try

https://github.com/mcinnes01/music-assistant-alexa-api

[xabaras75]

There’s an HA add on for this image you can try

https://github.com/mcinnes01/music-assistant-alexa-api

I am a little bit confused. I use hassos and installed the Alexa bridge addon. How can now use the new skill that suppose to be setup under docker?

[broyuken]

This is the same thing as the docker container. It is the container in addon form.

[xabaras75]

This is the same thing as the docker container. It is the container in addon form.

I find the way to build the skill. I am not sure if in the correct way. Anyhow, my problem is that when I start music directly from music assistant (usinf spotify as provider), the music streamed by my echo dot is not the song choosen in MA but another one from spotify. it's strange because the song streamed throught the api is correct (I checked the link)

[Nagusia]

The HA add-on referred to above: https://github.com/mcinnes01/music-assistant-alexa-api can be used instead of the previous 'MA Alexa API bridge' docker container. The new API + local skill plugin is only available as a docker container installation. The developer, Alams154 lists HA add-on support as a future improvement: https://github.com/alams154/music-assistant-alexa-skill-prototype/blob/master/LIMITATIONS.md, so for the moment you have to use the new version: https://github.com/alams154/music-assistant-alexa-skill-prototype

[PXLJAKE]

I have successfully installed the Music Assistant Skill. However, when trying to play music, I receive the Alexa error message: “There was a problem with the response from the requested skill.”My Setup
Skill Container: I am running the Docker container for the Local Music Assistant Skill on my Synology NAS.
Accessibility: The service is connected via a Cloudflare Tunnel with the domain stream.mydomain.de.
Console Log on Playback Attempt
When starting playback, the following message consistently appears in the Skill's console log:

“2026-01-05 15:06:22,592 INFO werkzeug 172.23.0.1 - - [05/Jan/2026 15:06:22] "POST /ma/push-url HTTP/1.1" 200 -”

I am unsure whether this response is an indicator of success or failure.

Here is my edited composer.yaml. I changed the Port to 3000 for convenience and added the ma.mydomain.de which is pointing to the Streaming port of MA which is 8097

services:
  music-assistant-skill:
    image: ghcr.io/alams154/music-assistant-skill:dev
    environment:
      - MA_HOSTNAME='ma.mydomain.de' # Domain name, including subdomain #optional, if only using APL devices
      - API_USERNAME=/run/secrets/API_USERNAME #optional
      - API_PASSWORD=/run/secrets/API_PASSWORD #optional
      - PORT=3000 #optional
      - DEBUG_PORT=5678 #optional
      - AWS_DEFAULT_REGION=us-east-1 #optional
    secrets:
      - API_USERNAME
      - API_PASSWORD
    ports:
      - 3000:3000 # Must match PORT
      - 5678:5678 # Must match DEBUG_PORT #optional
    restart: unless-stopped


secrets:
  API_USERNAME:
    file: ./secrets/api_username.txt
  API_PASSWORD:
    file: ./secrets/api_password.txt

Skill and Music Assistant Settings
Skill Endpoint: I have configured the skill according to the instructions with the endpoint stream.mydomain.de, which points to the Docker container.
Music Assistant (MA):
The API URL in MA is stream.mydomain.de.
Username and password are entered.
The language is de-DE, as I selected Germany during the skill setup and my Alexas are set to German.

--Problems with Amazon Login
Logging in to Amazon within Music Assistant is causing me significant difficulties that remain unresolved even after hours of trying and following tips.Current State
I was able to complete the login only once successfully.
My Alexa devices are listed in Music Assistant.
No OTP Secret is displayed in Music Assistant.

Problems with Re-Login
Attempts to log in again lead to an HTTP Error 404 after entering the Amazon login credentials.
Shortly before the 404 error, I briefly see the authentication page where I had previously entered the OTP app code.
Even after a new setup of the Addon, I have not been able to successfully complete the login again so that i have a OTP secret in the Settings.

[blue-brumie]

Are you using the alexa-skill-prototype repository by alams154. I was successful using that prototype repository.

I believe your skill endpoint URL is incorrect. The API Url setting is either your local ip address plus the port you used for your api bridge or one of your URLs (ma. or stream.) but I'm not sure you've got these right as you mention a ma. and stream. for your domain, one of those needs to point to the host IP address of where you ran the docker compose file. That is the alexa api Url, that one needs to go in your Alexa skill endpoint https settings and in MA Alexa player settings below the Amazon account details. The MA_HOSTNAME environment variable needs to be your MA URL, this should not be the same as the URL where its hosted.

I think you need to put the stream. URL in the docker compose file for the enviroment variable if needed as optional (I added it anyway to cover for all device types). Your ma. URL in the Alexa skill in the Alexa Developer console for Endpoints as a HTTPS. In MA when adding the Alexa provider use your ma. URL in the API Url setting. This is only going on what you provided above.

Make sure you are entering the amazon URL where your account sits in the Amazon login settings and not the api Url. This will be amazon.com, amazom.co.uk, amazom.de wherever your account is. I only entered my amazon username and password, I left the OTP blank (got encoding errors otherwise), got taken to an Amazon web page, signed in authenticated myself, got a successful verification message afterwards.

[gio-dzilla]

I have successfully installed the Music Assistant Skill. However, when trying to play music, I receive the Alexa error message: “There was a problem with the response from the requested skill.”My Setup Skill Container: I am running the Docker container for the Local Music Assistant Skill on my Synology NAS. Accessibility: The service is connected via a Cloudflare Tunnel with the domain stream.mydomain.de. Console Log on Playback Attempt When starting playback, the following message consistently appears in the Skill's console log:

“2026-01-05 15:06:22,592 INFO werkzeug 172.23.0.1 - - [05/Jan/2026 15:06:22] "POST /ma/push-url HTTP/1.1" 200 -”

I am unsure whether this response is an indicator of success or failure.

Here is my edited composer.yaml. I changed the Port to 3000 for convenience and added the ma.mydomain.de which is pointing to the Streaming port of MA which is 8097

services:
  music-assistant-skill:
    image: ghcr.io/alams154/music-assistant-skill:dev
    environment:
      - MA_HOSTNAME='ma.mydomain.de' # Domain name, including subdomain #optional, if only using APL devices
      - API_USERNAME=/run/secrets/API_USERNAME #optional
      - API_PASSWORD=/run/secrets/API_PASSWORD #optional
      - PORT=3000 #optional
      - DEBUG_PORT=5678 #optional
      - AWS_DEFAULT_REGION=us-east-1 #optional
    secrets:
      - API_USERNAME
      - API_PASSWORD
    ports:
      - 3000:3000 # Must match PORT
      - 5678:5678 # Must match DEBUG_PORT #optional
    restart: unless-stopped


secrets:
  API_USERNAME:
    file: ./secrets/api_username.txt
  API_PASSWORD:
    file: ./secrets/api_password.txt

Skill and Music Assistant Settings Skill Endpoint: I have configured the skill according to the instructions with the endpoint stream.mydomain.de, which points to the Docker container. Music Assistant (MA): The API URL in MA is stream.mydomain.de. Username and password are entered. The language is de-DE, as I selected Germany during the skill setup and my Alexas are set to German.

--Problems with Amazon Login Logging in to Amazon within Music Assistant is causing me significant difficulties that remain unresolved even after hours of trying and following tips.Current State I was able to complete the login only once successfully. My Alexa devices are listed in Music Assistant. No OTP Secret is displayed in Music Assistant.

Problems with Re-Login Attempts to log in again lead to an HTTP Error 404 after entering the Amazon login credentials. Shortly before the 404 error, I briefly see the authentication page where I had previously entered the OTP app code. Even after a new setup of the Addon, I have not been able to successfully complete the login again so that i have a OTP secret in the Settings.

Hello,

If I understand correctly, you’re in the Music Assistant web GUI trying to set up the Alexa provider for the first time, and it’s asking for your Amazon credentials. If that’s the case, I ran into the same issue. I don't think this is mentioned anywhere.....

The important thing to know is that the code Music Assistant asks for is not the usual two-step verification (2FA) code generated by apps like Google Authenticator or similar.

Here’s what you need to do instead:

1. Enter your Amazon username and password in Music Assistant.
2. In a separate browser tab, log in to your Amazon account (for example, amazon.de).
3. In the top-right corner, click “Hello, [Your Name]”, then go to “Login & Security.”
4. Open Two-Step Verification, then click Manage.
5. Under Preferred method → Authenticator app, click Add a new app.
6. At the bottom, click “I can’t scan a barcode.”
7. A popup will appear showing a long alphanumeric code (in bold). 👉 This is the code you must paste into Music Assistant where it asks for the OTP.
8. After pasting it, Music Assistant will open a popup window asking you to log in to Amazon.
9. Once you do, Amazon will generate a new code.
10. Take that newly generated code and enter it back on the Amazon page where you were adding the new authenticator app.

Once that’s done, the setup should complete successfully.

Quick note: I solved many of the issues I was having with Music Assistant by changing the log level in the settings. For example, when I had problems playing music with Alexa, I went to Music Assistant → Settings → Providers, selected the Alexa provider, then opened Advanced and set the Log level to Debug.

Also, make sure the locales match everywhere. For example, if Music Assistant is set to de-DE, your Alexa device is de-DE, and the Alexa skill is also de-DE, music still won’t play if the skill files haven’t been correctly adapted, translated, and referenced for that locale.

p.s. I am working on a fork that support spanish (es-ES) as locale, if I manage to get it to work, I will make it public.

[Rupie17]

Reading through this whole thread it seems like as of today, you can install the alexa bridge addon directly in home assistant. This way you do not need the docker container set up.
In the addon configuration you can set the port (default 3000) and basic auth if you want.

Looks like you still need to set up a skill in the alexa dev console which includes creating a custom intent, adding the Audio player interface and setting 1 or 2 endpoints?

My confusion is:
For endpoints you set the default endpoint to the alexa bridge url or the MA stream url?

And if its the alexa bridge url where do you use the Music Assistant url? or vice versa.

When I configure the Alexa provider in music assistant I can authenticate with amazon and then the API url is just the local ip: http://localhost:3000 with the basic auth set from the addon config.

[blue-brumie]

Are you using the alexa-skill-prototype repository by alams154. I was successful using that prototype repository.

My working setup uses the Alexa bridge URL as the default https endpoint.

You use the MA URL in the Alexa bridge environment variables in the docker compose file.

When configuring the Alexa provider in MA for the API Url setting, I used my Alexa bridge URL but TBH not sure if I tried my local IP using the port, but it's resolves to the same place. I'll test that when I get chance, don't like to mess with my live setup after taking a day to get this working!

I'm trying to create a write up of what I did, hopefully get that finished at the weekend. Back to work grind this week...

[Rupie17]

Appreciate the info.

I'm not using the docker container though for the bridge, it's an addon in HA now that can be used so unsure where the MA url now goes, if needed at all. Assume it is as I can play music to the echo dot, I've added the alexa provider and the echo as a player, music plays but no sound so somewhere it's breaking.

[Nagusia]

@Rupie17 If you want to use the alexa-skill-prototype repository by alams154, until a HA addon version is created you have to use the docker version. The HA addon available right now replaces the previous ma-alexa bridge api docker container.

[Rupie17]

ok makes sense. So then which skill do you use and config to get that going if I want to stick with the HA addon?

[Nagusia]

This tutorial https://www.reddit.com/r/homeassistant/comments/1o0mw4p/music_assistant_alexa_provider_setup_tutorial/ helped me set up the first version of the MA Alexa provider. I initially used the docker container for the MA Alexa API bridge, and then replaced it with the HA addon you want to use. It works, more or less, but maybe as it depends on an exteral AWS-based skill, it was not 100% reliable.
The new alexa-skill-prototype version (local skill, not AWS based) works much better IMO, but you can't use the HA addon instead of the new docker container because it doesn't include the local skill.

[msebald]

I'm also struggling with the new music-assistant-alexa-skill-prototype. What I did:

I installed the Docker container, but not through composer but on my Unraid machine. The only two options I set were the default ports 5000 and 5678 and MA_HOSTNAME (set to the public domainname where the MA streaming port is reachable through HAProxy and https) and also AWS_DEFAULT_REGION to "eu-west-1" as I am in Europa (Germany).

Then I changed the API Url in MA to http://internalip:5000 and installed the skill in Alexa Developer Console like described. I used German as language and put in "spiele audio", "start" and "spiele" in PlayAudio intent (I noticed that MA is sending "sag music assistant spiele audio" in debug logging of MA). The endpoint is set to https://publicdomainname of the music-assistant-alexa-skill-prototype Docker (also reachable through HAProxy).

When I try to play something on a Echo device I get "Ich kann den angeforderten Skill nicht erreichen." from the Echo. I think that is the German version of "There was a problem with the response from the requested skill.".

When I test the skill in Alexa Developer Console by typing "sag music assistant spiele audio" I also get the same message. Everything behind "sag music assistant" is handled the same way, so the problem seems to be "music assistant" already. Hm.

Any idea what I forgot or took a wrong turn?

[vlacour97]

Hello,
For German and French users.
I just created a pull request to fixed issue with the en-US language
music-assistant/server#2982

[vlacour97]

Other people can also contribute by implementing other languages ​​by modifying the ALEXA_LANGUAGE_COMMANDS constant in __init__.py

[gio-dzilla]

Hi there,

I am not sure how to edit the init.py file, but here is the snippet adding Italian and Spanish.

ALEXA_LANGUAGE_COMMANDS = {
"play_audio_en-US": "ask music assistant to play audio",
"play_audio_fr-FR": "music assistant",
"play_audio_es-ES": "pídele a music assistant que reproduzca audio",
"play_audio_it-IT": "chiedi a music assistant di riprodurre audio",
"play_audio_default": "ask music assistant to play audio",
}

[alams154]

I've opened a PR for Italian and Spanish
music-assistant/server#3005

[gio-dzilla]

thank you for that. I am just starting using GitHub and I didn't want to mess things up.

If anyone is interested, I also translated to es-ES the files of the Skill prototype docker image. It would be great to get the changes merged with the master image.
music-assistant-alexa-skill-prototype_translated_es-ES.zip

[alams154]

For those experiencing random songs, the issue may be related to Alexa+ if it is supported in your region and enabled on your account.

Some update to Alexa seems to have broken skill usage with Alexa+. The testing page has no input or output when launching the skill with Alexa+ but works fine if you opt out of early access.

There is now an Alexa+ store for "skills" in the Alexa app which may be related to the update that broke the skill compatibility. The API for the new "skill" framework is currently confidential and may never be open to individual/open source devs.

I will update the docs on the prototype skill eventually to notify users that Alexa+ is currently incompatible with the skill.

[OzGav]

We really need to update the MA docs to reflect the current situation as well

[alams154]

Sounds good, I will try to update them soon.

Also looks like the Alexa+ rollout or compatibility may vary depending on the device. From my Amazon account, the test page on the developer console does not work but it works from my Echo Show 8 (Gen 2) with Alexa+ enabled.

[davidesolito]

Per coloro che sperimentano canzoni casuali, il problema potrebbe essere correlato ad Alexa+ se è supportato nella tua regione e abilitato sul tuo account.

Alcuni aggiornamenti ad Alexa sembrano aver interrotto l'utilizzo delle abilità con Alexa+. La pagina di test non ha input o output quando si avvia l'abilità con Alexa+, ma funziona bene se si rinuncia all'accesso anticipato.

Ora c'è un negozio Alexa+ per "abilità" nell'app Alexa che potrebbe essere correlato all'aggiornamento che ha rotto la compatibilità delle abilità. L'API per il nuovo framework "skill" è attualmente riservata e potrebbe non essere mai aperta agli sviluppatori individuali/open source.

Alla fine aggiornerò i documenti sull'abilità prototipo per informare gli utenti che Alexa+ è attualmente incompatibile con l'abilità.

Hi, yesterday I configured my Music Assistant with Alexa. I installed Alexa API and set up the skill. Everything seems to be working correctly and I don’t see any errors in the logs, either in Alexa API or in Music Assistant.
However, when I try to play a specific song, the Echo starts playing a random track instead of the one I requested. I checked the logs on both sides (Music Assistant and Alexa API), and in both cases the correct song is being sent. I also checked the HTTP link that Alexa API sends: when I open it in Chrome, it plays exactly the song I want.
Despite this, the Echo device does not play that song and instead starts a random one. I’m located in Italy, where Alexa+ is not yet available. Could this be the reason why it’s not working?
This is driving me crazy because I followed the guides step by step, and according to the logs there are no errors at all — everything looks fine.

[alams154]

The guides are not up to date yet but it sounds like the Italian command may be wrong. I am working on improving the status page to show what step the process is going wrong.

If you are able to edit Music Assistant server, going into the Alexa provider and changing the command may help.

[alams154]

We really need to update the MA docs to reflect the current situation as well

I've created a PR:
music-assistant/music-assistant.io#450

Is this all that is needed?

[mixerrules]

Failed to authenticate with Amazon 'Cannot connect to host alexa.https:443 ssl:default [Domain name not found]'.

Hi, I've tried setting this up multiple times, the docker part and the skill part work fine, but once i try to sign in in the Alexa provider menu the amazon sign in works correctly but once i get back to the Music Assistant tab its shows a pop up with: Failed to authenticate with Amazon 'Cannot connect to host alexa.https:443 ssl:default [Domain name not found]'.

the only thing the logs output is:
2026-01-22 20:54:25.923 INFO (MainThread) [music_assistant.providers.alexa] Alexa Callback URL: https://music.mixers.network/callback/kAugd_xqixF 2026-01-22 20:54:27.482 ERROR (MainThread) [music_assistant.webserver] Error handling message: config/providers/get_entries: Failed to authenticate with Amazon 'Cannot connect to host alexa.https:443 ssl:default [Domain name not found]'.

heres my settings with email and usernames blocked out:

[mixerrules]

Those should both work, what are you getting in the container logs?

No errors just standard logged connections

Also instructions on the new skill is missing one section on the developer console which is to enable APL and AudioPlayer interfaces

And this fixed it! thank you so much!

[alams154]

Could you specify which Echo Show model you are using? That way I can update the supported devices list and provide better support to users in the future.

Also are you using en-US for your setup?

[mixerrules]

Could you specify which Echo Show model you are using?

Echo Show 8

rest of my devices are 3rd Generation Echo Dot, 2x Amazon Echo (Gen 1 Tower)

Also are you using en-US for your setup?

Yes

[davidesolito]

Did you get a chance to check why the Echo keeps playing random music? Mine still isn’t working—I try to play a specific song, but it ends up playing something completely different.

[Creepios]

Also instructions on the new skill is missing one section on the developer console which is to enable APL and AudioPlayer interfaces

Hi, I just have opened a pull request for adding these in the docs.

[alams154]

I don’t think Alexa+ is the error, but something around the use of the logic for the locale. My logs keep saying it’s expecting the locale “en-US” and not finding the es-ES locale it reverts to the default, this despite modifying not only the skill prototype but temporarily editing the MA container in HA to include ES-es as locale

Might be something I hard coded. If you can find the issue, I can make the change or you can open a PR. I hard coded en-US at one point in the provider code.

[alams154]

@davidesolito

Did you get a chance to check why the Echo keeps playing random music? Mine still isn’t working—I try to play a specific song, but it ends up playing something completely different.

Can you please provide your setup details (region, device, using skill prototype, Alexa+ if in supported region)?
If you are using the skill prototype, please provide container logs.

[davidesolito]

@davidesolito

Did you get a chance to check why the Echo keeps playing random music? Mine still isn’t working—I try to play a specific song, but it ends up playing something completely different.

Can you please provide your setup details (region, device, using skill prototype, Alexa+ if in supported region)? If you are using the skill prototype, please provide container logs.

From the logs, everything seems to be sent correctly from our side.
I verified the HTTPS endpoint exposed by the container by opening it directly in the browser, and in that case the correct (expected) song starts playing as intended. So the request handling and response generation appear to be correct.
However, when the same flow is triggered via Alexa on Echo devices, Alexa ends up playing completely different music instead of the requested song.
The issue occurs consistently across all tested devices:
Echo Dot
Echo Show 5
Echo Show 8
Echo Plus
So it does not seem to be device-specific.
Setup details:
Region: Italy (IT)
Alexa+: not available in this region
Devices: multiple Echo devices (listed above)

[alams154]

When you tested using the browser, did you use the Test tab in the Alexa Developer Console (chiedi a music assistant di riprodurre audio)?

If you are just checking the MA audio stream in the browser, this does not mean the skill is being called. You should be getting some logs in the container when your device or the Alexa Developer Console attempts to access the API.

[davidesolito]

When you tested using the browser, did you use the Test tab in the Alexa Developer Console (chiedi a music assistant di riprodurre audio)?

If you are just checking the MA audio stream in the browser, this does not mean the skill is being called. You should be getting some logs in the container when your device or the Alexa Developer Console attempts to access the API.

I tried, for example, by typing “play (track title)” on the Echo Show 5 in the skill’s test section, and the selected track plays correctly. With Music Assistant, however, it doesn’t work. So it seems that the skill works, but there’s something with Music Assistant that isn’t working as it should. I don’t understand whether I’m the one making a mistake.

[alams154]

The skill itself does not support commands like "play (track title)" so it may be playing through some sort of music service linked to your account.

If you could provide the container logs, it would be helpful. Depending on which version of the prototype skill you are using, the logs will be more or less helpful.

[shedman214]

after i enter all my credintals i get Non-base32 digit found. i have followed the guid on github?

[alams154]

You are using a wrong/invalid 2FA app key

See:
https://github.com/alandtse/alexa_media_player/wiki/Configuration#2sv-authenticator-app-key---required

[nholben]

I have everything set up and all appears to go well except the status page shows 404 errors:

Service Status

Skill running

Music Assistant Skill interaction model found; endpoint matches (alexa.******.com); testing enabled

Music Assistant API responded 404 for /ma/latest-url

{
"error": "No URL available, please check if Music Assistant has pushed a URL to the API"
}

Alexa API responded 404 for /alexa/latest-url

{
"error": "No URL available, please check if the Alexa skill has pushed a URL to the API"
}

[alams154]

The latest version of the skill improves the error message "No URL available, please check if the Alexa skill has pushed a URL to the API".

If your skill is not being invoked, you have configuration issue regarding your skill. Otherwise, the skill's logs will provide more input on where to debug.

There is now a new /simulator URL which you can test against your SKILL_HOSTNAME to see if you have properly configured your reverse proxy for the skill endpoint.

[renevlk74]

@nholben it s not ... it s show my internal ip address transformed by the reverse proxy ...should here not be a public ipv4 address or hostname instead of "http://10.10.10.10:8097/flow/EQWe7mHh/hanne ....
but domain is public accessable that goes trough my reverse proxy but stream show internal ip if it must be in the stream a public
ip how should i do that?? thx so much

[alams154]

If you are using a device with a screen, the skill works with a local IP. If not, then the skill will redirect to your MA_HOSTNAME.

But that doesn’t change the fact, that without skill invocations nothing will work. Please provide screenshots.

[renevlk74]

hi alams154
this the ouput from the simulator
Response
Status: 200
{
"response": {
"directives": [
{
"audioItem": {
"stream": {
"offsetInMilliseconds": 0,
"token": "http://stream.mydomain.xyz:8097/flow/bJb2b7wK/renes%202.%20Echo%20Dot/ad50322f4ca944f98860fb5508a2004e.mp3",
"url": "http://streammydomain.xyz:8097/flow/bJb2b7wK/renes%202.%20Echo%20Dot/ad50322f4ca944f98860fb5508a2004e.mp3"
}
},
"playBehavior": "REPLACE_ALL",
"type": "AudioPlayer.Play"
}
],
"shouldEndSession": true
},
"sessionAttributes": {},
"userAgent": "ask-python/1.19.0 Python/3.10.12",
"version": "1.0"
}
⏸
Now playing: http://stream.mydomain.xyz:8097/flow/bJb2b7wK/renes%202.%20Echo%20Dot/ad50322f4ca944f98860fb5508a2004e.mp3

also status page says ok...

but it s not playing and on my phone when i paste that url i get an ssl error

thx so much for your support

[alams154]

You do not have a valid certificate from a certificate authority, that is why you are getting the SSL error.

[mericon]

Is there any Chance that the delay to Pause will be fixed anytime?

[alams154]

It should be fixed when this PR is merged

[Nagusia]

Hi. I've just updated to ghcr.io/alams154/music-assistant-skill:0.0.29-beta and 'pause' takes around 25 seconds and 'play' 5 seconds. Let me know if I can help by providing you with any other information from logs etc.

[alams154]

This won't change until the player provider is updated. The PR has some more changes than expected and will take a while longer.

Pause on APL devices (devices with a display) doesn't work at all, it's just MA sending stop after 30 seconds because MA will terminate a paused stream after 30s.

Play time will not be shortened because whenever you hit play it is relaunching the skill on the device. This cannot be fixed with the current state of Amazon device APIs (AlexaPy and aioamazondevices).

[coryjreid]

I'm having issue configuring the Alexa Player Provider in MA. Specifically, I cannot authenticate with Amazon.

When I enter the OTP Secret in the Generic settings and click save, the page navigates back to the top-level Providers page. I then go back into the Alexa provider configuration and the OTP Secret field is filled with the expected dots, however there are less than when I entered the code. If I click AUTHENTICATE WITH AMAZON, I get the error regarding non-base32 digits in the secret. If I re-enter the code and click the auth button before saving, the auth flow happens, however auth fails.

I close the tab after the failed redirect and click the CLICK HERE IF THE POPUP DID NOT OPEN link and enter my credentials again, yet it redirects to the same page with the same error, and eventually auth times out completely with "Failed to authenticate with Amazon "Timeout while waiting for authentication callback"."

I am confident the OTP Secret is correct... I'm not sure why it's not loading correctly after saving the form.

Am I missing something blatantly obvious in the docs? Thanks for any advice!

[alams154]

Could you please provide logs from Music Assistant during these flows?

If you understand how to modify Music Assistant, one thing to try is bumping the AlexaPy version for the requirements since there was a change recently that fixed something with the auth flow.

[coryjreid]

Hi, @alams154! Thanks for your response. I'll definitely look into bumping the library version as you suggest. In the meantime here's a sanitized log I generated this morning while performing the same flow.

music_assistant.log

[alams154]

Hopefully, the patch fixes it but otherwise logs look ok. I don't remember ever being redirected to a URL containing "cvf" so maybe there is some new redirect and hopefully the fix in AlexaPy addresses that.

Another fix you can try to do is resetting your Amazon password since I also had an auth problem which was fixed by the reset.

[BingoBango80]

Could I ask for some advice please:- I think(?) I'm so close but can't quite resolve.
I've got everything setup - the Music Assistant Alexa API add-on shows that the stream is received (and I can paste the streamURL into a browser and it plays the song fine).

But I'm not getting the music out of Alexa when I try to play it through the device.

My thinking is that I've got an error in how I've set things up in Cloudflare plus I'm getting an error in the Cloudflared logs within Home Assistant (ERR Request failed error="stream 2317 canceled by remote with error code 0".....

For setting up Cloudflared I've already got a tunnel setup for my domain name (which I access home assistant through). So I added additional routes to this one rather than setup 2 separate tunnels (one for alexa.mydomain and one for music.mydomain) and then amended the Cloudflared YAML as follows:

external_hostname: mydomain.com
additional_hosts:

• hostname: alexa.mydomain.com
  service: http://192.168.1.167:3000
• hostname: music.mydomain.com
  service: http://192.168.1.167:8097

Is that right? Thanks! I'm sure I'll get there :)

[alams154]

I won't be providing support for the original as that is deprecated and the prototype has significantly more debugging features and has addressed more bugs.

There is currently an open issue about the prototype for use as a HA app which I personally won't be working on until I address other issues but I will approve any PRs if someone is willing to work on it.

The original had significant more hardcoding than the prototype so language differences from en-US may be an issue.

[BingoBango80]

Ok, many thanks. I'll go back to the docker install option. Thanks for letting me know.

[BingoBango80]

Thanks @alams154 for your help.

I've setup things up on docker compose.

Similar position to yesterday - it's almost all there but the service status page is showing green for 1). skill running / 2). music assistant skill interaction model found and endpoint matches; testing enabled and locale: en-GB and 3). music assistant API is reachable (200).

But I'm getting red on Alexa API responded 404 for /alexa/latest-url
{
  "error": "Check skill invocations and skill logs.  If there are no invocations, you have made a configuration error"
}

No recent invocations

I get the same thing happening as yesterday - I can paste the stream URL in the browser and it plays, but I'm not getting any sound from the Alexa device.

Is there anything else I can try?

Many thanks.

[alams154]

You can check this issue out for a person who had a similar issue alams154/music-assistant-alexa-skill-prototype#18

This is a configuration issue on your part that you will have to debug. Feel free to open an issue on the prototype repo and I can provide more support and help provide documentation of your specific issue for people who want to use the skill in the future.

[JackoAmmerlaan]

Had exact the same issue yesterday.. Had an old skill (Music Assistant) in amazon develop console. (after deletion of that old skill all worked).