The original node-sonos-http-api by Jimmy Shimizu has been the standard way to control Sonos speakers over HTTP for years. It’s JavaScript, loosely typed, and hasn’t been actively maintained. sonos-alexa-api is a ground-up TypeScript rewrite that adds Alexa skill compatibility, tightens up the API, and cuts response times significantly.
What’s different
The rewrite prioritizes speed. Most operations come back under 200ms. The codebase is fully typed TypeScript with 96% test coverage. Runtime dependencies are minimal by design — the kind of thing that matters when you’re running this on a home server that you don’t want to babysit.
Alexa skill compatibility is the main feature addition. You can wire the API directly to an Alexa custom skill and control your Sonos speakers by voice without going through a third-party service. The API handles the Alexa request/response format and maps it to Sonos commands.
Music service support
Apple Music, Spotify, and Pandora are all supported. Spotify uses OAuth2 with automatic token refresh. Pandora includes backoff logic to handle bot detection. Service authentication status is exposed via a dedicated endpoint that shows token state and expiry, which is useful when something stops working and you need to know why.
Deployment
Docker Compose is the recommended deployment:
git clone https://github.com/kshartman/sonos-alexa-api
cd sonos-alexa-api
cp .env.example .env
# Configure music services and optional HTTP auth
docker-compose up -dHTTP Basic Authentication is optional. If you’re on a trusted network you can bypass it with CIDR notation in the config. Sonos S2 systems are supported; S1 is not.
Diagnostics
The package includes utility scripts for auditing the setup — validating presets, identifying ghost Pandora favorites, checking system infrastructure, and generating a server summary in both human-readable and JSON format for use with monitoring tools.
The code is on GitHub: kshartman/sonos-alexa-api.