Music Assistant Home Assistant Settings Integration

[carlhye]

Problem statement

Music Assistant (MA) currently exists as a separate add-on that users must discover and install independently from Home Assistant (HA). There is no native pathway within HA's interface to discover, install, or access MA settings. This creates a disconnected experience where:

• New users may not know MA exists or how to find it
• The installation process requires navigating outside HA's standard settings flow
• There's no guided onboarding to help users set up their first music sources and players
• Users who already have media players configured in HA (Sonos, Bluesound, etc.) must manually reconfigure them in MA

This fragmentation makes MA feel like a third-party bolt-on rather than an integrated music solution for the HA ecosystem.

Community signals

To be gathered: This section needs to be populated with actual community feedback signals before the bet goes to the betting table. Potential sources to investigate:

• Home Assistant community forum posts and discussions
• Music Assistant GitHub issues and discussions
• Discord channels for both HA and MA
• Reddit r/homeassistant threads
• Support ticket patterns

Key questions to research:

• How do new users currently discover Music Assistant?
• What are common pain points in the MA installation process?
• Do users expect music to be integrated into HA's settings?
• What confusion exists around MA vs HA media players?
• Are there abandoned installations due to setup complexity?

Scope & Boundaries

In scope

• A "Music" entry point in HA Settings (placement options detailed below)
• Installation prompt and flow when MA is not installed
• Guided wizard for initial MA setup covering:
  • Auto-detection and import of existing HA media players as player providers
  • Music source provider selection and configuration
• Direct navigation to MA settings page when MA is already installed
• Skip options for advanced users who prefer manual configuration
• Visual mockups for placement options A and B

Not in scope

• Media browser integration (separate bet needed)
• Advanced MA settings in the wizard (crossfade, Don't Stop the Music, etc.)
• Modification of existing MA settings interface
• Changes to how MA functions once installed

Foreseen solution

Placement Options

Three placement options are proposed, each with distinct trade-offs:

Option A: Top-level Settings Entry Place "Music" as a first-class entry in the main Settings screen, alongside "Devices & services," "Automations & scenes," "Dashboards," etc.

Arguments for:

• Elevates music to a core HA capability, signaling its importance
• Maximum discoverability for new users
• Matches the mental model: "I want to set up music in my home"
• Positions HA as a complete home platform, not just automation

Arguments against:

• Adds another top-level item to an already dense menu
• May feel inconsistent if MA is the only optional top-level feature
• Could set precedent for other integrations wanting top-level placement

Option B: Separate Section (Like NFC Tags) Create a dedicated "Music" section in Settings, placed as a standalone category similar to how "Tags" (NFC tags and QR codes) appears as its own section even without physical hardware dependencies.

Arguments for:

• Gives music dedicated space without cluttering the top-level menu
• Follows existing HA pattern for software-based features (Tags section doesn't require hardware)
• Clear visual separation while maintaining discoverability
• Can stand alone without needing a parent category

Arguments against:

• Creates another section in the settings structure
• May feel arbitrary if it's the only software-based standalone section besides Tags
• Could still set precedent for other integrations wanting section-level placement

Community decision point: The implementation team should validate placement with community feedback during the cycle, using mockups to gather preferences. Three options are presented (A, B, and an unlabeled third option was explored but not included in the final bet).

Installation Flow (When MA Not Installed)

1. User taps "Music" in Settings
2. Dialog appears: "Music Assistant brings multi-room audio and music streaming to Home Assistant. Install Music Assistant?" [Install] [Cancel]
3. Installation begins (standard add-on installation process)
4. Upon completion, wizard launches automatically

Onboarding Wizard

Step 1: Player Detection

• Scan for existing HA media player integrations (Sonos, Bluesound, Chromecast, etc.)
• If found: "We found [X] media players in Home Assistant. Add them to Music Assistant?"
  • [Add All] [Select Manually] [Skip]
• If none found: "No media players detected. You can add player providers now or skip and add them later."
  • [Add Providers] [Skip]

Step 2: Music Sources

• Display available music source providers (Spotify, YouTube Music, local files, etc.)
• Show top 3-4 most popular providers initially
• "Show more providers" button to reveal full list of supported providers
• "Select at least one music source to get started"
• Provider cards with [Connect] buttons
• [Skip] option available for advanced users

Step 3: Completion

• "You're all set! Music Assistant is ready to use."
• [Go to Settings] button → lands in MA settings page

Skip Behavior: Users can skip any wizard step. Skipped configuration can be completed later via MA settings.

Post-Installation Behavior

When MA is already installed, tapping "Music" in HA Settings navigates directly to the MA settings page (existing interface).

Graphical elements created using AI, please ignore wrong icons in menus

Risks & open questions

Technical Risks:

• Does HA's settings architecture support conditional menu items (showing Music only after MA installation)?
• Can we reliably detect and map HA media players to MA player types?
• What happens if MA installation fails mid-wizard?

UX Risks:

• Will Option A placement create precedent pressure from other integration developers?
• Could the wizard oversimplify setup and hide important configuration options?
• Does Option B feel arbitrary as a standalone section, or does it follow the Tags pattern successfully?

Open Questions:

• How do we handle users who uninstall MA after initial setup?
• Should the wizard be re-accessible, or one-time only (in case the user uninstall/reinstall MA)?
• How do we handle if a user wants to install something other than MA forhandling music?
  • Should the Music menu items be owned exclusively by MA?

Appetite

Medium (1-2 cycles / 2-4 months)
This feels like a Medium bet because:

• Requires HA core modifications for settings menu injection
• Needs wizard UI development with multi-step state management
• Player auto-detection logic could be complex depending on HA's integration APIs
• Must handle edge cases (installation failures, partial completion, re-runs)
• Requires coordination between HA and MA codebases
• Needs visual design work for placement options and wizard flow

Not Large because:

• Core MA functionality remains unchanged
• Wizard is purposefully minimal (only 2-3 steps)
• No new MA features being built, just surfacing existing ones

Execution issues

No response

Decision log

Current Decision Points:

• Placement option (A vs B) - to be decided with community feedback
• Wizard re-accessibility after initial completion
• How many providers to show initially in Step 2 before "Show more providers" - and which providers?

Date	Decision	Outcome

[mik-laj]

Media browser integration (separate bet needed)

If we are adding Music to the main menu, I think we should consider adding Media Browser too. Otherwise, Music Assistant will be out of sync with what is available natively in HA. Of course, deeper changes in the Media Browser are a separate topic, but if we are designing menu paths, it is worth considering that similar things should be close to each other in the menu.

Does HA's settings architecture support conditional menu items (showing Music only after MA installation)?

Yes. If I don't have Zigbee integration installed, Zigbee isn't visible in the settings. The same applies to other connections.

[carlhye]

Hi @mik-laj

Thank you for your feedback - and I agree.

We're also already considering changes to the Media Browser as well (it should go both ways), to make Music Assistant available there too, and make content from Music Assistant playable directly from the media browser.

Currently this is another task yet to be created here, though.

[Hedda]

This section needs to be populated with actual community feedback signals before the bet goes to the betting table.

FYI, this reddit thread have some related community feedback with some comments from HA users who didn't even know about MA:

• https://www.reddit.com/r/homeassistant/comments/1sc2u4w/music_assistant_has_its_own_blog/

PS: For reference, there are also indirectly related feedback here about both Sendspin and MA needing to be promoted much better:

• Sendspin branding, trademark logotype (logo), matching badges as a brand-mark, and TOS (Terms of Service) agreement? Sendspin/spec#71

PPS: That is, if made a greater effort to highlight Sendspin then will in theory indirectly also promote Music Assistant and vice versa.