🎵 Music Assistant Control — Home Assistant & Self-Hosted Speaker Automation

Welcome! With this actor you can control your self-hosted Music Assistant server effortlessly through code — from anywhere, without opening the app. Play tracks, albums, or playlists on your AirPlay, UPnP, HomePod, Chromecast, or Sonos speakers, adjust the volume, manage the queue, toggle shuffle/repeat, or control individual rooms and your full multi-room setup.

🏠 Home Assistant users: Music Assistant runs beautifully as a Home Assistant add-on. This actor is the perfect companion to automate your speakers from Home Assistant scripts, automations, or any external system via a simple API call.

💡 In short: You provide your server URL + token + the player you want — everything else runs automatically. Perfect for smart-home automations, scheduled playback (e.g. a "good-night" song at 19:30), or just starting music quickly without reaching for your phone.

⚠️ Important note: This actor controls your server. It is not a music streaming service. You must already be running a Music Assistant server on your own hardware (Home Assistant add-on, NAS, Docker, Pi). No Music Assistant = this actor cannot work.

---

🔧 Prerequisites (set this up first)

1. Install Music Assistant — free & open source
   • Home Assistant Add-on, or Docker: docker run -d --name music-assistant --network host ghcr.io/music-assistant/server:latest
   • Docs: https://music-assistant.io/docs/latest/installation/
2. Connect a provider (Spotify, Internet Archive, local files, radio) in the MA app.
3. Create an API token: MA app → Settings → Users → Create token. Copy it — you'll paste it as api_token below.
4. Note your server URL: e.g. http://192.168.1.50:8095 (LAN) or a tunnel/HTTPS URL if running in the cloud.
5. Note a player name: open the MA app, look at Settings → Players (e.g. "Living Room", "Kitchen HomePod").

---

🚀 Usage

Input fields

Field	Required	Description
server_url	✅	URL of YOUR MA server (see prerequisites).
api_token	✅	API token from YOUR MA server. Stored as Apify secret.
action	✅	play / pause / play_pause / next / previous / volume_set / volume_up / volume_down / mute / power / search
player_name	✅	Name of the speaker to control (case-insensitive substring match).
search_query	⚠️ for play/search	What to search (track, album, artist, playlist).
media_type	—	track (default) / album / artist / playlist
volume	—	0-100, for volume_set / power
power_state	—	true/false, for power
mute_state	—	true/false, for mute
dry_run	—	true (default) = show what would happen, no changes

Example: first run (safe, dry-run)

{
  "server_url": "http://192.168.1.50:8095",
  "api_token": "YOUR_TOKEN_HERE",
  "action": "search",
  "player_name": "Living Room",
  "search_query": "Daft Punk Around the World",
  "media_type": "track",
  "dry_run": true
}

This returns search results + confirms your player is found — without playing anything.

Example: play on a speaker

{
  "server_url": "http://192.168.1.50:8095",
  "api_token": "YOUR_TOKEN_HERE",
  "action": "play",
  "player_name": "Kitchen",
  "search_query": "Tame Impala The Less I Know The Better",
  "media_type": "track",
  "dry_run": false
}

---

🌐 Running from the cloud (Apify platform)

The actor runs in Apify's cloud. Your MA server is on your private LAN. To let the cloud actor reach it:

• Option A — local run: apify run from a machine on your LAN (no tunneling needed).
• Option B — tunnel: expose your MA server via Tailscale / WireGuard / ngrok / Cloudflare Tunnel, then use that HTTPS URL as server_url.
• Option C — standby listener: run a small relay on your LAN that calls this actor (advanced).

Each user controls their own server — the actor is stateless and stores nothing.

---

🔍 What it does / doesn't

Does:

• Search across all your MA providers
• Play tracks / albums / artists / playlists
• Volume, mute, power, shuffle, repeat, skip, queue
• Multi-room (control any or all players)
• Returns structured JSON (current item, state, volume)

Doesn't:

• Provide music (you bring Spotify/etc.)
• Store credentials (token stays in your Apify secret)
• Scrape anything (uses the official MA WebSocket API)
• Work without a self-hosted MA server

---

💰 Pricing

Model: Pay-per-event (PER_EVENT) — $0.01 per command, no cap. A single play action costs $0.01. Bulk operations (e.g. multi-room control) scale linearly. You only pay for what you actually run.

---

📄 License

MIT — use freely, modify, self-host.