Music Assistant - Comprehensive Music Server for Smart Home

Music Assistant is a modern, open-source music server that transforms your Home Assistant into a full-featured music center. If you've ever dreamed of having all your music sources - from Spotify through Apple Music to local files - in one place with the ability to stream to any device in your home, then Music Assistant is exactly what you're looking for.

What Music Assistant Can Do

Centralized Music Library

Music Assistant creates a unified library from all your music sources:

• Streaming services: Spotify, Apple Music, Tidal, Deezer, Qobuz, YouTube Music
• Home servers: Plex, Jellyfin, Subsonic
• Local files: MP3, FLAC, WAV and other formats from NAS or local storage
• Internet radio: Radio Browser, TuneIn
• Podcasts: iTunes Podcast Search, RSS feeds, gPodder, Audiobookshelf

Intelligent Track Linking

When you have the same track on Spotify and in local files, Music Assistant automatically links them. This means you can create a playlist and Music Assistant will choose the best source for playback based on availability and quality.

Wide Player Support

Music Assistant can stream to virtually any modern and smart audio device:

• AirPlay - Apple HomePod, AirPlay speakers
• Google Cast - Chromecast Audio, Google Nest speakers
• Sonos - entire Sonos speaker family
• DLNA - most network players
• Snapcast - multi-room audio with perfect synchronization
• Home Assistant media players - integration with HA players
• And many more - Alexa, Bluesound, MusicCast, Squeezelite

Advanced Audio Features

Music Assistant provides features you'll appreciate during everyday listening:

• Gapless playback - seamless playback without gaps between tracks
• Crossfade - fade between tracks for DJ effect
• Volume normalization - consistent volume across tracks
• DSP filters - equalizer and tone controls for sound tuning
• Playback synchronization - perfectly synchronized multi-room audio
• Queue transfer between players - move playback from one room to another

Home Assistant Integration

Music Assistant integrates perfectly with Home Assistant:

• Automations - start music based on events
• Announcements - interrupt music for announcements during playback
• Voice control - control music by voice through HA voice assistant
• Dashboards - add music controls to your dashboards
• Scenes - play specific music as part of a scene

Installation

Music Assistant is installed as an addon to Home Assistant, making installation very simple.

Prerequisites

Before installation, make sure you have:

• Home Assistant installed in HassOS or Supervised version
• Sufficient computing power - I recommend at least Raspberry Pi 4 (4GB RAM)
• Stable network connection for streaming

Device Performance

Music Assistant is more demanding than regular addons. On Raspberry Pi 3, operation may be slower, especially when using multiple streaming services simultaneously.

Installation Steps

1. In Home Assistant, go to Settings → Add-ons → Add-on Store

2. Click three dots in the upper right corner and select Repositories

3. Add Music Assistant repository:

   https://github.com/music-assistant/home-assistant-addon

4. After refreshing the page, you'll find Music Assistant in the list

5. Click on the addon and then the INSTALL button

6. Installation may take several minutes - the addon is quite large

Faster Path

You can use this direct link to add the repository:

First Start

After installation:

1. Enable Start on boot - Music Assistant should run continuously
2. Enable Show in sidebar - for quick access to the interface
3. Click START

The first start may take longer because the addon needs to download and install all dependencies.

Basic Configuration

After the first start, the Music Assistant web interface opens where we'll do the basic setup.

Adding Music Sources

The first step is adding your music sources:

1. In Music Assistant interface, go to Settings → Music Providers

2. Click Add Provider and select your service

3. For streaming services (Spotify, Apple Music, etc.):

   • Click on the provider
   • You'll be redirected to the service login page
   • After authorization, you'll return to Music Assistant
   • Generally, I recommend reading the documentation on how to add a specific service, as the process will often vary significantly.

4. For local files:
   • Select Filesystem
   • Enter the path to your files (e.g., /media or /share)
   • Music Assistant will start scanning and indexing files

Tip for Local Files

If you have music on NAS, you can first mount it to Home Assistant using SMB/NFS addon and then add the path to Music Assistant.

Adding Players

Music Assistant automatically detects most players on your network:

1. Go to Settings → Player Providers

2. Activate provider for your devices:

   • Google Cast - for Chromecast and Google Nest
   • AirPlay - for Apple devices
   • Sonos - for Sonos speakers
   • DLNA - for general network players
   • Home Assistant - for players in HA

3. After activating the provider, players will appear in the Players list

Home Assistant Integration

For full integration with Home Assistant, you need to install the integration:

1. In Home Assistant, go to Settings → Devices & Services

2. Click Add Integration and search for Music Assistant

3. The integration should automatically detect the running server

4. After adding, entities will be created for each Music Assistant player

Why Two Parts?

Music Assistant has two components:

• Addon - the music server itself that manages library and streaming
• Integration - connection between server and Home Assistant for automations

Using in Automations

This is where the real capabilities of Music Assistant combined with Home Assistant show. Music Assistant adds all its players as media_player entities that you can fully use in automations.

Basic Automation Examples

Morning wake-up with music:

automation:
  - alias: "Morning wake-up music"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: media_player.volume_set
        target:
          entity_id: media_player.living_room
        data:
          volume_level: 0.15
      - service: media_player.media_play
        target:
          entity_id: media_player.living_room

Start music when arriving home:

automation:
  - alias: "Music on arrival"
    trigger:
      - platform: state
        entity_id: person.name
        to: 'home'
    condition:
      - condition: time
        after: '18:00:00'
        before: '22:00:00'
    action:
      - service: media_player.media_play
        target:
          entity_id: media_player.living_room

Pause music during phone call:

automation:
  - alias: "Pause on phone call"
    trigger:
      - platform: state
        entity_id: sensor.phone_state
        to: 'ringing'
    action:
      - service: media_player.media_pause
        target:
          entity_id: media_player.living_room

Advanced Control

Music Assistant entities support all standard media_player services:

• media_player.media_play - Play
• media_player.media_pause - Pause
• media_player.media_stop - Stop
• media_player.media_next_track - Next track
• media_player.media_previous_track - Previous track
• media_player.volume_set - Set volume
• media_player.volume_up / volume_down - Increase/decrease volume
• media_player.play_media - Play specific media

Playing Specific Content

To play a specific track, album, playlist, or radio, you can use the standard media_player.play_media service or the more advanced music_assistant.play_media.

Basic usage with media_player.play_media:

service: media_player.play_media
target:
  entity_id: media_player.living_room
data:
  media_content_type: music
  media_content_id: "Queen"  # Artist, album, or track name

Music Assistant supports various media_content_id formats:

• Name: Queen or Queen - Innuendo
• Streaming URI: spotify://artist/12345 or spotify://playlist/xyz
• Streaming URL: https://open.spotify.com/track/...
• Library URI: library://track/123, library://album/456, library://playlist/789, library://radio/3

Advanced usage with music_assistant.play_media:

For more control over playback, you can use the special Music Assistant service:

service: music_assistant.play_media
target:
  entity_id: media_player.living_room
data:
  media_id: "Innuendo"
  media_type: album
  artist: "Queen"  # Filter by artist
  enqueue: replace  # play, replace, next, replace_next, add
  radio_mode: true  # Automatically generate similar tracks

The enqueue parameter determines how content is added to the queue:

• play - Play now
• replace - Replace entire queue and play
• next - Add as next in queue
• replace_next - Replace everything after current track
• add - Add to end of queue

Radio mode automatically creates a playlist of similar tracks based on the selection.

Advanced Features

Player Groups (Multi-room Audio)

Music Assistant allows creating player groups for synchronized playback:

1. In the interface, click on a player
2. Select Group with and choose other players
3. Music will play synchronized on all devices

Perfect Synchronization

For best synchronization, I recommend using Snapcast provider, which ensures sub-millisecond synchronization.

Announcements During Playback

Music Assistant can pause music, play an announcement, and then continue:

service: music_assistant.play_announcement
target:
  entity_id: media_player.living_room
data:
  url: "https://www.example.com/doorbell.mp3"
  announce_volume: 60

Announcement Parameters

You can also use the use_pre_announce: true parameter to play a sound before the announcement to alert listeners.

Queue Transfer Between Players

You can move playback from one room to another without interruption:

service: music_assistant.transfer_queue
target:
  entity_id: media_player.kitchen  # Target player
data:
  source_player: media_player.living_room  # Source player
  auto_play: true  # Automatically start playback

Tips and Tricks

Using with Spotify Connect

If you have Spotify Premium, you can install the Spotify Connect plugin, which allows controlling Music Assistant directly from the Spotify app.

Scrobbling to Last.fm

Music Assistant supports sending listening history to Last.fm:

1. Install Last.fm Scrobbler plugin
2. Connect your Last.fm account
3. All played music is automatically recorded

Performance Optimization

If Music Assistant runs slowly:

• Reduce the number of active music providers
• Disable automatic synchronization for large libraries
• Consider using external database (PostgreSQL)

Alternatives and Comparison

Feature	Music Assistant	Volumio	Mopidy	Plex
Multiple sources	✅	❌	✅	❌
HA integration	✅	Partial	✅	Partial
Gapless playback	✅	✅	❌	✅
Multi-room sync	✅	❌	✅ (Snapcast)	✅
Web UI	✅	✅	❌	✅
Free	✅	Partial	✅	Partial
Easy installation	✅	✅	❌	✅

Summary

Music Assistant is a truly impressive project that brings professional music functionality to Home Assistant.

What I like:

• Unified library from all sources
• Automatic track linking
• Excellent Home Assistant integration
• Advanced audio features (gapless, crossfade)
• Active development and community

What could be better:

• Requires more powerful hardware
• Occasional issues with some streaming services
• Documentation still not completely comprehensive
• Initial setup can be complex for beginners and adding some sources is really complicated

If you have Home Assistant and want perfect control over music throughout your home, Music Assistant is the clear choice.