Music Assistant Alexa Skill Prototype

This project is an Alexa skill prototype for controlling the Music Assistant server. It provides a Flask-based web service, an Alexa skill handler, an API, and ASK CLI integration with Docker deployment support.

How to Run

1. Using Docker (Recommended)

The easiest way to run the project is with Docker Compose. This will build and start the Alexa skill container with required environment variables, secrets, and an optional persistent ASK credential volume.

Prerequisites

• An Amazon developer account: https://developer.amazon.com/en-US/docs/alexa/ask-overviews/create-developer-account.html
• Skill Access Management enabled for your developer account: https://developer.amazon.com/alexa/console/ask/settings/access-managemen
• Docker & Docker Compose installed on your host
• A public HTTPS endpoint for the skill

Steps:

1. Ensure docker-compose.yml is present and edit environment variables as needed (e.g., SKILL_HOSTNAME, MA_HOSTNAME, PORT). SKILL_HOSTNAME is required for creating the skill manifest.

2. (Optional) Create ./secrets/app_username.txt and ./secrets/app_password.txt to provide APP_USERNAME and APP_PASSWORD for basic authentication of the web UI and API.

3. (Optional) To persist ASK CLI credentials across container restarts, mount a volume to ./<host directory>:/root/.ask, ./ask_data is used by default.

4. Start the service:

   docker compose up -d

5. The service will be available at http://localhost:5000 (or the IP/port you configured).

6. In your browser, open the setup UI at http://localhost:5000/setup. The setup page will:

   • detect existing persistent ASK credentials (if present) and skip the browser-based auth flow
   • guide you through the ASK CLI authorization flow if credentials are not present
   • run the automated skill creation/update, interaction model upload, model build polling, and testing enablement.

Note: manual creation of the skill in the Alexa Developer Console is no longer required — the /setup flow automates creation and enablement when possible.

Basic Troubleshooting

Status Page

/status

Returns a simple status page showing the local API health and an ASK CLI driven check for whether the Music Assistant skill exists, whether its endpoint matches SKILL_HOSTNAME, and whether testing is enabled. When the check is not green, the status page provides a quick link to /setup.

---

See COMPATIBILITY.md for known supported devices, languages, and regions.

See LIMITATIONS.md for known limitations.

See TODO.md for future improvements