# Music Assistant + Home Assistant Speaker Control (`adroit_bluebonnet/music-assistant`) Actor

Control your self-hosted Music Assistant server (Spotify, Internet Archive, local library, AirPlay/UPnP/HomePod/Chromecast/Sonos) from anywhere with code. Play tracks/albums/playlists, control volume, queue, shuffle, repeat, multi-room. Self-hosted MA required (free, open source).

- **URL**: https://apify.com/adroit\_bluebonnet/music-assistant.md
- **Developed by:** [Marv B.](https://apify.com/adroit_bluebonnet) (community)
- **Categories:** Agents, Other, Integrations
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 search executeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

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

Welcome! With this actor you can control your **self-hosted [Music Assistant](https://music-assistant.io) 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)

```json
{
  "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

```json
{
  "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.

# Actor input Schema

## `server_url` (type: `string`):

REQUIRED. The URL of YOUR self-hosted Music Assistant server. Example format: http://192.168.1.50:8095 or https://ma.your-domain.com — this is YOUR private server, not a public service. The actor connects directly to it, so the URL must be reachable from where the actor runs (your LAN for local runs, or a public/tunnel URL for cloud runs).

## `api_token` (type: `string`):

REQUIRED. Long-lived API token created in YOUR Music Assistant server (Settings → Users → 'Create token'). Treats as secret by Apify — never shared. If you don't have Music Assistant installed yet, stop here and set it up first (see actor description).

## `action` (type: `string`):

What the actor should do on the chosen player.

## `player_name` (type: `string`):

REQUIRED. The name of the speaker/player to control, exactly as shown in YOUR Music Assistant app (e.g. 'Living Room', 'Kitchen', 'Office HomePod'). Matching is case-insensitive substring. To see your players, open your MA app or check Settings → Players. Leave blank → actor fails with a list of available players.

## `search_query` (type: `string`):

What to search for. REQUIRED for action 'play' and 'search'. Example: 'Daft Punk Around the World', 'Artist Name Album Title'. Searches across all your connected providers (Spotify, Internet Archive, local library, radio).

## `media_type` (type: `string`):

What kind of media to play from search results.

## `volume` (type: `integer`):

Volume level 0-100. Only used for action='volume\_set' or 'power'.

## `power_state` (type: `string`):

Only used for action='power'.

## `mute_state` (type: `string`):

Only used for action='mute'.

## `dry_run` (type: `boolean`):

If true, the actor shows what it WOULD do (search results, target player, parsed action) WITHOUT actually changing playback. Strongly recommended for the first run to verify your server\_url, token, and player\_name are correct before any real action.

## Actor input object example

```json
{
  "server_url": "http://",
  "action": "play",
  "media_type": "track",
  "volume": 50,
  "power_state": "true",
  "mute_state": "true",
  "dry_run": true
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "server_url": "http://"
};

// Run the Actor and wait for it to finish
const run = await client.actor("adroit_bluebonnet/music-assistant").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "server_url": "http://" }

# Run the Actor and wait for it to finish
run = client.actor("adroit_bluebonnet/music-assistant").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "server_url": "http://"
}' |
apify call adroit_bluebonnet/music-assistant --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=adroit_bluebonnet/music-assistant",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/fyCLAoOFWFNghgJLn/builds/Qb1v9SCajAQKgoJVN/openapi.json