music assistant automation

🎵 Control your self-hosted Music Assistant server from any compatible AI coding agent — Claude Code, Codex CLI, Cursor, VS Code Copilot, and more.

This skill gives your AI agent hands-on control over your existing Music Assistant setup (Spotify, Internet Archive, local library, AirPlay, UPnP, HomePod, Chromecast, Sonos). One natural-language prompt is enough: "play Tame Impala on Living Room", "pause Küche", "set Bedroom volume to 25".

✨ Highlights

• Works with YOUR self-hosted MA server — no cloud signup, no extra service
• Supports 25+ providers: Spotify, Internet Archive, radio, local files, podcasts
• Multi-room audio (groups, individual control, sync playback)
• Built-in playback control (play/pause/skip/volume/queue/shuffle/repeat)
• Best-practice error handling around Music Assistant API gotchas (constructor signature, WebSocket listener lifecycle, Spotify URI prefix)

🛠 Requirements

• A self-hosted Music Assistant server (v2.x — Home Assistant add-on, Docker, or standalone). Free & open source: https://music-assistant.io
• A long-lived API token from MA Settings → Users → Create token
• Local network reachability from agent → MA server (usually LAN)

🔌 Setup (one-time)

1. Install dependencies: pip install music-assistant-client websockets aiohttp orjson
2. Store your MA token securely (env var MUSIC_ASSISTANT_TOKEN, or ~/.ma_token with chmod 600). Never paste into chat.
3. Run the included ma-play.py "Daft Punk" --player "Living Room" --dry-run to verify connection
4. Start scripting — see SKILL.md for full pattern

🏠 Perfect for Home Assistant users Music Assistant is a popular HA add-on. Combine both for music automation from any HA script or scene.

📦 What's included

• SKILL.md — main skill definition with onboarding wizard
• references/api-gotchas.md — detailed API gotchas + verified working examples
• scripts/ma-play.py — minimal CLI for search-and-play (great for testing)