Troubleshooting steps for Music Asssistant Alexa Plugin

MASS_ALEXA_TROUBLESHOOTING.md

I had some challenges ensuring that everything was working correctly, and I used the following troubleshooting steps to resolve. Perhaps these will be helpful for you as well:

1. Local API Access

Next, ensure that the API is reachable through your local network. Using the API settings found at Settings > Player Providers > Alexa > Generic Settings, check the API using curl:

curl -u <api basic auth username>:<api basic auth password> <api url>

{streamUrl: 'http://<ma internal ip>:<ma stream port>/flow/pquZHw62/<speaker name>/<random id>.flac}

If that fails, check the deployment of your Alexa API container, primarily env vars and network config.

2. Local Stream Access

After triggering a song to play, check the logs of your music-assistant-alexa-api container to ensure that the API is receiving the request. You should see a log message like:

{
  streamUrl: 'http://<ma internal ip>:<ma stream port>/flow/pquZHw62/<speaker name>/<random id>.flac
  title: undefined,
  artist: undefined,
  album: undefined,
  imageUrl: undefined
}

Copy the stream URL and ensure that the Music Assistant URL is playable on your local network. I did this by opening the stream URL with VLC, but I found afterwards that it also plays in the browser.

vlc http://<ma internal ip>:<ma stream port>/flow/pquZHw62/<speaker name>/<random id>.flac

If that fails to play, then double check the Music Assistant Settings > Core Modules > Streamserver > Generic Settings>, and that they match your network configuration (in Docker, firewall, etc.) You can also test access via networking using Netcat. I use netcat-openbsd with nc -vz <hostname / IP> <port>.

3. Remote TLS/SSL Access

Now check to make sure that both of these URLs are working from the outside world through your cert-signing proxy (Caddy, etc.): Test the API and stream URLs by swapping the URL scheme (http -> https), hostname and port:

# Test API remote URL
curl -u <api basic auth username>:<api basic auth password> <api url>
{streamUrl: 'http://<ma internal ip>:<ma stream port>/flow/pquZHw62/<speaker name>/<random id>.flac}

# Test stream remote URL
vlc https://<ma external hostname>:<ma https port>/flow/pquZHw62/<speaker name>/<random id>.flac

If either of these (or both) fail, then there is a configuration issue with one of the following networking components:

• TCP network access
  • testable using Netcat: nc -vz <hostname / IP> <port>
• DNS
  • ensure that the MA hostnames are resolvable from outside your home network:

    nslookup
    > server 1.1.1.1
    Default server: 1.1.1.1
    Address: 1.1.1.1#53
    > mass-stream.example.com
    Name:	mass-stream.example.com
    Address: X.X.X.Y  <-- this should match your public IP address
    > mass-api.example.com
    Name:	mass-api.example.com
    Address: X.X.X.Y  <-- this should match your public IP address
    

• Certificate signing (Caddy or other HTTPS proxy with Let's Encrypt, ACME, etc.)
  • testable using openssl: echo | openssl s_client -servername <hostname> -connect <hostname>:<port> 2>/dev/null

4. Alexa Skill Debugging

If all of these steps are succeeding, then you can check the Alexa Skill. The best way that I found to troubleshoot this was using the Cloudlfare logs. At this line of the skill source, you can add:

console.log("ATTEMPTING TO PLAY: ", podcastUrl);

Then select Save, and Deploy. Once deployment completes, test a song again, and open the CloudWatch Logs link in your Alexa developer console. Find your log message in the results, and ensure that the formatting matches the stream URL tested above.

If all of these results are working, and there's still an issue, then you might have found a bug.