music-assistant

name	music-assistant
description	Control Home Assistant Music Assistant - browse library, search, play, manage preferences and moods.
version	1.0.0
metadata	{"clawdbot":{"emoji":"🎵","requires":{"env":["HA_URL","HA_TOKEN"]}}}

Music Assistant Skill

Control Home Assistant with Music Assistant integration - browse your music library, search for tracks, manage playback, set preferences, and create mood-based playlists.

Requirements

• Home Assistant instance with Music Assistant integration
• HA_URL - Your Home Assistant URL (e.g., https://ha.example.com)
• HA_TOKEN - Long-lived access token from Home Assistant

Commands

Speakers & Discovery

# List available media player speakers
ha-ma speakers

# Show Music Assistant configuration
ha-ma ma-config [--cached] [--refresh]

Browse Library

# Browse by type: artists, albums, tracks, playlists, radio
ha-ma browse <type> [--parent <id>] [--limit <n>] [--offset <n>]

# Examples
ha-ma browse artists --limit 20
ha-ma browse albums --parent "artist:123"
ha-ma browse tracks --parent "album:456"

Search

# Search for music
ha-ma search <query> [--limit <n>] [--type <media_type>]

# Examples
ha-ma search "Beatles" --limit 10
ha-ma search "jazz" --type artists

Playback Control

# Play media on a speaker
ha-ma play --speaker <entity_id> --uri <uri> [--enqueue <mode>]

# Pause/Stop/Navigation
ha-ma pause --speaker <entity_id>
ha-ma stop --speaker <entity_id>
ha-ma next --speaker <entity_id>
ha-ma prev --speaker <entity_id>

# Volume control (0-100)
ha-ma volume --speaker <entity_id> --level <0-100>

# Add to queue
ha-ma queue --speaker <entity_id> --uri <uri>

Enqueue modes: play, replace, next, add

User Preferences

# Set preference for user or household
ha-ma prefs set --user <slug> --<entity-type> <value> --score <score>
ha-ma prefs set --household <slug> --<entity-type> <value> --score <score>

# Get preferences
ha-ma prefs get --user <slug>
ha-ma prefs get --household <slug>

# Clear specific preference
ha-ma prefs clear --user <slug> --<entity-type> <value>
ha-ma prefs clear --household <slug> --<entity-type> <value>

Entity types: --artist, --album, --genre, --track

Mood Mapping

# Create or update a mood
ha-ma mood set --user <slug> --name <name> --genres <g1,g2> [--decades <d1,d2>] [--energy <low|medium|high>]
ha-ma mood set --household <slug> --name <name> --genres <g1,g2> [--energy <level>]

# List moods
ha-ma mood list --user <slug>
ha-ma mood list --household <slug>

# Get specific mood
ha-ma mood get --user <slug> --name <name>

# Delete mood
ha-ma mood delete --user <slug> --name <name>

Play History

# Recent play history
ha-ma history recent --user <slug> [--limit 20]

# List listening sessions
ha-ma history sessions --user <slug> [--limit 10]

# Avoid list management
ha-ma history avoid --user <slug> --uri <uri> [--reason <text>]
ha-ma history unavoid --user <slug> --uri <uri>
ha-ma history avoidlist --user <slug>

Memory (Play Event Logging)

# Log a play event
ha-ma memory log --user <slug> --speaker-entity <entity_id> --uri <uri> [--title ...] [--artist ...] [--album ...]

# Recent play events
ha-ma memory recent --user <slug> [--limit 10]

Configuration

Set environment variables in your OpenClaw config:

{
  "skills": {
    "entries": {
      "music-assistant": {
        "env": {
          "HA_URL": "https://your-ha-instance.com",
          "HA_TOKEN": "your-long-lived-access-token"
        }
      }
    }
  }
}

Database

The skill uses SQLite with Prisma for storing:

• User and household preferences
• Mood definitions
• Play history and sessions
• Avoid lists

Database is automatically initialized on first use.