Music Assistant

Control Music Assistant (Home Assistant music server) - playback, volume, queue management, and library search. Use when user wants to play/pause music, skip...

Control your Music Assistant server for music playback, queue management, and library browsing.

Setup

Before using this skill, you need to configure your Music Assistant connection:

# Required
export MA_URL="http://YOUR_SERVER_IP:8095/api"
export MA_TOKEN="YOUR_BEARER_TOKEN"

# Optional - auto-detected if not set
export MA_PLAYER="your_player_id"

Finding your token:

1. Open Music Assistant web UI
2. Go to Settings → Security
3. Create or copy your Long-Lived Access Token

Finding your player ID:

./scripts/mactl.py players

Quick Start

# Basic controls
./scripts/mactl.py play          # Play/pause toggle
./scripts/mactl.py next          # Skip track
./scripts/mactl.py volume 75     # Set volume to 75%

# Search and play
./scripts/mactl.py search "nirvana"
./scripts/mactl.py play-search "pink floyd"  # Search and play first result

# Check what's playing
./scripts/mactl.py status
./scripts/mactl.py queue

Playback Controls

./scripts/mactl.py play          # Play/pause toggle
./scripts/mactl.py pause         # Pause
./scripts/mactl.py stop          # Stop playback
./scripts/mactl.py next          # Next track
./scripts/mactl.py prev          # Previous track

Volume

./scripts/mactl.py volume 75     # Set volume 0-100
./scripts/mactl.py mute          # Mute
./scripts/mactl.py unmute        # Unmute

Queue Management

./scripts/mactl.py shuffle true  # Enable shuffle
./scripts/mactl.py shuffle false # Disable shuffle
./scripts/mactl.py repeat all    # Repeat mode (off|all|one)
./scripts/mactl.py clear         # Clear queue
./scripts/mactl.py queue-items   # List queue contents

Search & Play

# Search library
./scripts/mactl.py search "pink floyd"
./scripts/mactl.py search "nirvana" --type track album
./scripts/mactl.py search "metallica" --limit 5

# Search and immediately play first result
./scripts/mactl.py play-search "smells like teen spirit"
./scripts/mactl.py ps "comfortably numb"  # shorthand

# Play by URI (for scripts/advanced use)
./scripts/mactl.py play-uri "spotify://track/4gHnSNHs8RyVukKoWdS99f"

Status & Info

./scripts/mactl.py status        # Show player status + now playing
./scripts/mactl.py queue         # Queue status
./scripts/mactl.py recent        # Recently played items
./scripts/mactl.py players       # List all available players

Library

./scripts/mactl.py sync          # Trigger library sync

Examples

"Play some Nirvana"

./scripts/mactl.py play-search "nirvana"

"What's playing?"

./scripts/mactl.py status

"Skip this track"

./scripts/mactl.py next

"Set volume to 50%"

./scripts/mactl.py volume 50

"Turn on shuffle"

./scripts/mactl.py shuffle true

Direct API Access

For operations not covered by the CLI, use the JSON-RPC API directly:

curl -s "http://YOUR_SERVER:8095/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MA_TOKEN" \
  -d '{"message_id":"1","command":"player_queues/all"}'

API documentation is available at: http://YOUR_SERVER:8095/api-docs

Key API Commands

Command	Args	Description
players/all	-	List all players
player_queues/all	-	List all queues
player_queues/play_pause	queue_id	Toggle play/pause
player_queues/next	queue_id	Next track
player_queues/previous	queue_id	Previous track
player_queues/stop	queue_id	Stop playback
player_queues/shuffle	queue_id, shuffle_enabled	Set shuffle
player_queues/repeat	queue_id, repeat_mode	Set repeat (off/all/one)
player_queues/clear	queue_id	Clear queue
player_queues/items	queue_id, limit, offset	Get queue items
player_queues/play_media	queue_id, uri	Play by URI
music/search	search, media_types, limit	Search library
music/recently_played_items	limit	Recent items
music/sync	media_types, providers	Sync library
config/players/get	player_id	Get player settings