{"id":39056757,"url":"https://github.com/ahimgit/navidrome-alexa","last_synced_at":"2026-01-17T18:01:05.951Z","repository":{"id":224629466,"uuid":"750080687","full_name":"Ahimgit/navidrome-alexa","owner":"Ahimgit","description":"Stream music from Navidrome to Amazon Echo \u0026 Alexa devices","archived":false,"fork":false,"pushed_at":"2025-05-24T06:34:05.000Z","size":1489,"stargazers_count":14,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-24T07:34:25.916Z","etag":null,"topics":["alexa","music","navidrome","self-hosted","streaming"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ahimgit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-30T00:13:07.000Z","updated_at":"2025-05-24T06:34:09.000Z","dependencies_parsed_at":"2024-06-21T12:52:56.530Z","dependency_job_id":"c9ec50e6-e9e8-40bc-8b4d-837b95e0e261","html_url":"https://github.com/Ahimgit/navidrome-alexa","commit_stats":null,"previous_names":["ahimgit/navidrome-alexa"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Ahimgit/navidrome-alexa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ahimgit%2Fnavidrome-alexa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ahimgit%2Fnavidrome-alexa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ahimgit%2Fnavidrome-alexa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ahimgit%2Fnavidrome-alexa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ahimgit","download_url":"https://codeload.github.com/Ahimgit/navidrome-alexa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ahimgit%2Fnavidrome-alexa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28514939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T17:57:59.192Z","status":"ssl_error","status_checked_at":"2026-01-17T17:57:52.527Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","music","navidrome","self-hosted","streaming"],"created_at":"2026-01-17T18:00:42.134Z","updated_at":"2026-01-17T18:01:05.892Z","avatar_url":"https://github.com/Ahimgit.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# navidrome-alexa\n\nStream your music from Navidrome UI to Amazon Echo \u0026 Alexa devices.\n\n## How it works\n\nNavidrome-Alexa is a combination of a UI widget, REST API and Alexa Skill that allow you to stream your music from\nNavidrome Web UI to Alexa devices like Amazon Echo.\nSee the below diagram for details how components interact with each other.\n\n\u003cimg alt=\"architecture\" src=\"doc/architecture.svg\"\u003e\n\n### Why it works that way\nSee below for more details on Navidrome and Alexa integrations.\n\n[ADR001 Alexa Interactions](doc/ADR001-Alexa-Interactions.md)    \n[ADR002 Navidrome Integration](doc/ADR002-Navidrome-Integration.md)\n\n### How it looks like\nUI still needs a lot of work both on the look-and-feel side and how it integrates with Navidrome.\n\n\u003cimg alt=\"ui\" width=\"40%\" src=\"doc/ui.gif\"\u003e\n\n## Installation\n\n### Prerequisites\n\n- Public-web accessible address for navidrome-alexa to accept Amazon Alexa Skill API requests\n- Public-web accessible address for Navidrome's /rest/stream endpoint \n- Reverse proxy with SSL and rewriting support ([Caddy](https://github.com/caddyserver/caddy) is used in example configuration below)\n- Amazon account to access [Alexa Developer Console](https://developer.amazon.com/alexa/console/ask) to configure self-hosted Alexa Skill\n\n### 1. Configure skill\nThis configures self-hosted Alexa skill that calls /skill endpoint of navidrome-alexa application\nand provides music streams back to echo devices. \n\n- 1.1. Open [Alexa Developer Console](https://developer.amazon.com/alexa/console/ask) and authenticate.\n- 1.2. Click \"Create New Skill\" button.\n- 1.3. Enter \"navi stream\" as skill name\n- 1.4. On the \"Experience, Model, Hosting Service\" screen select:\n    - Choose a type of experience: \"Music \u0026 Audio\" [(picture)](doc/install-1-4-1.png)\n    - Choose a model: \"Custom\" [(picture)](doc/install-1-4-2.png)\n    - Hosting services: \"Provision your own\"\n    - Click \"Next\" button\n- 1.5. On the \"Template\" screen select \"Start from Scratch\" and click \"Next\" button [(picture)](doc/install-1-5.png)\n- 1.6. On the \"Review\" screen click \"Create Skill\" button, wait till skill is created\n- 1.7. Go to \"Intents\" in left side menu and hit \"JSON editor\", copy \u0026 paste [alexa-skill.json](doc/alexa-skill.json)\n  and click \"Save\" [(picture)](doc/install-1-7.png)\n- 1.8. Go to \"Endpoint\", select \"HTTPS\" as \"Service Endpoint Type\"  [(picture)](doc/install-1-8.png)\n    - Enter public https URL pointing to your navidrome-alexa installation ending with /skill \n      (e.g. https://alexa.yourdomain.com/skill )\n    - Select SSL certificate type you use (make sure to select wildcard cert type if using it for subdomains)\n    - Click \"Save\" button\n- 1.9. Go to \"Interfaces\" left side menu, enable \"Audio Player\" and press \"Save\" [(picture)](doc/install-1-9.png)\n- 1.10. Click \"Build\" in top menu, click \"Build skill\" button, ensure skill builds successfully\n- 1.11. Got to developer console root page and click \"Copy Skill ID\", you will need it for the next\n  step.  [(picture)](doc/install-1-11.png)\n\n### 2. Configure application\nThis configures navidrome-alexa application that provides /skill endpoint to serve music stream URLs to Alexa devices \nand /api endpoint to control queuing and playback.\n\n- 2.1. Download a pre-built [release of navidrome-alexa](https://github.com/Ahimgit/navidrome-alexa/releases) or build locally.\n- 2.2. Run it passing configuration parameters below:\n\n| Command line        | Env Var                  | Default value | Description                                                                                          |\n|---------------------|--------------------------|---------------|------------------------------------------------------------------------------------------------------|\n| amazonDomain        | NA_AMAZON_DOMAIN         | amazon.com    | Base domain to use for Alexa API calls.                                                              |\n| amazonCookiePath    | NA_AMAZON_USER           | cookies.data  | Path to a writable file to store auth cookies.                                                       |   \n| amazonUser          | NA_AMAZON_PASSWORD       | _Empty_       | Amazon account email with Alexa devices, can be left blank if auth cookies already exist.            | \n| amazonPassword      | NA_AMAZON_COOKIE_PATH    | _Empty_       | Amazon account password, can be left blank if auth cookies already exist.                            | \n| apiKey              | NA_API_KEY               | _Empty_       | Required. API key to authenticate /client calls. User provided, select arbitrary string to match 4.1 |         \n| streamDomain        | NA_STREAM_DOMAIN         | _Empty_       | Required. Navidrome public server domain URL.                                                        |         \n| alexaSkillId        | NA_ALEXA_SKILL_ID        | _Empty_       | Required. Skill id to authenticate calls from Alexa. Has to match copied in 1.11.                    |     \n| alexaSkillName      | NA_ALEXA_SKILL_NAME      | navi stream   | Skill invocation name. Has to match name configured in 1.7. JSON                                     |                           \n| listenAddress       | NA_LISTEN_ADDRESS        | :8080         | Listen address.                                                                                      |                                  \n| logIncomingRequests | NA_LOG_INCOMING_REQUESTS | false         | Log API and Skill requests/responses.                                                                |            \n| logOutgoingRequests | NA_LOG_OUTGOING_REQUESTS | false         | Log outgoing (to Alexa APIs) requests/responses. **Will leak sensitive data into logs.**             | \n| logStructured       | NA_LOG_STRUCTURED        | false         | Structured (JSON) logs output                                                                        | \n\nMinimal configuration via command line example:\n\n```shell\n  na \\\n  -amazonUser your@email.com \\\n  -amazonPassword youramazonpassword \\\n  -apiKey yourlongenoughandsecureapikey \\\n  -alexaSkillId amzn1.ask.skill.xxxxx \\\n  -streamDomain https://navidrome.youdomain.com \\ \n```\nNote that Amazon may challenge you with CAPTCHA and this will require logging into mobile app from the same network to clear oauth/openid flow.\nYou can also test Amazon Alexa authentication / generate cookie file with `meow` command \n\n```shell \n  meow amazon.com your_amazon_user@email.com your_amazon_password\n```\n\n### 3. Configure proxy\nThis configures reverse proxy re-write rule that injects navidrome-alexa UI widget into Navidrome UI.\nCaddy is used as example configuration. Below examples assume that navidrome and navidrome-alexa are running on their default ports \nand on the same host as Caddy (localhost).\n\n- 3.1 Add public address for navidrome-alexa in Caddy config, this has to match URL configured in step 1.8.\n  ```\n  alexa.yourdomain.com {\n      reverse_proxy localhost:8080\n  }\n  ```\n\n- 3.2 Add rewrite rule to inject widget into Navidrome's UI. Navidrome-alexa /proxy endpoint simply concats real navidrome UI js with the widget js.\n  Note that `index-UCahLcOW.js` script name is Navidrome release [0.54.5](https://github.com/navidrome/navidrome/releases/tag/v0.54.5) specific and needs to be updated with each release.  \n  ```\n  navi.yourdomain.com {\n    reverse_proxy localhost:4533\n    handle /app/assets/index-UCahLcOW.js {\n      rewrite * /proxy?proxied=http://localhost:4533/app/assets/index-UCahLcOW.js\n      reverse_proxy http://localhost:8080\n    }\n  }\n  ```\n- 3.3. Verify that script now contains widget code with `curl -v http://navi.yourdomain.com/app/assets/index-UCahLcOW.js`\n \n### 4. Configure widget\nIf widget was injected successfully when opening Navidrome UI, there will be a new button on the player bar.\n- 4.1 Click on the speaker button, click on three dots ... [(picture)](doc/install-4-1.png)\n- 4.2 Configure settings and click Save\n  - Configure API URL (e.g. https://alexa.yourdomain.com) to match 1.8 and 3.1.\n  - Configure API Key to match apiKey selected when starting navidrome-alexa in 2.2\n  - If everything was configured correctly you should be able to select your device and play music \n\n### 5. Play\nAdd music to the Navidrome UI player queue and press play \"⏵\" button on the widget.\n\n## Monitoring\n\n### Monitoring\nNavidrome-alexa has endpoint metrics exposed via Prometheus/OpenMetrics endpoint at `/metrics`.    \nThere is also a basic cached healthcheck endpoint at `/health`\nIf you want to exclude those from public access you can configure a rule to do so:\n```\n  alexa.yourdomain.com {\n      @exclude not path /health/* /metrics/* /metrics /health \n      reverse_proxy @exclude localhost:4533\n  }\n```\n\n### Logging\nTo enable request/response logging for REST endpoints and Alexa client use configuration options `logIncomingRequests` and `logOutgoingRequests`.\n**This will leak potentially sensitive data (like authentication tokens) into log files.**\n\n## Setting up development environment\n\n### Building locally\nRun in root project folder\n```shell\ngo build -o ./build/ ./...\n``` \nYou can also use provided build script to run static checks, tests and build.\n\n### Running tests\n```shell\ngo test ./...    \n```\n\n## Known issues \u0026 todo\n- Authentication may be tricky and may require authing from a mobile app on the same network first to do CAPTCHA.     \n  You can also use ssh to proxy your browser traffic through the host where NA is installed to accept 2FA/CAPTCHA.    \n  `ssh -N -D 0.0.0.0:1080 user@yourinstallationhost` \u0026 configure your browser's  socks5 proxy to localhost:1080\n- Proper integration with Navidrome vs injected widget\n- Better UI for playback controls / progress\n- Per-device queue / state\n- More control over logging configuration\n- Voice commands are likely out of scope (although stop, resume, next, prev are supported if it already has a queue), also there is [asknavidrome](https://github.com/rosskouk/asknavidrome)\n- Proper signature validation of incoming /skill requests\n- Test Alexa supported formats and if transcoding works/fixes issues, document it\n- Multiroom playback, while it does not work with skills out of the box there are potential workarounds to explore  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahimgit%2Fnavidrome-alexa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahimgit%2Fnavidrome-alexa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahimgit%2Fnavidrome-alexa/lists"}