HOMEii Music Flow is a premium Music Assistant dashboard card for Home Assistant. This documentation is the main place to learn how to install it, configure it, understand every major feature, and troubleshoot real-world Music Assistant setups.
- Install the card: Getting Started
- Configure Music Assistant, Sendspin,
card_id, and URL player overrides: Configuration - Learn what every screen does: Feature Guide
- Choose the right phone/tablet/dashboard mode: Layouts And Mobile Modes
- Generate a support report: Diagnostics
- Fix common problems: Troubleshooting
If you are new to HOMEii Music Flow, use this path:
HOMEii Music Flow needs:
- Home Assistant with dashboards/custom cards enabled.
- Music Assistant installed and connected to Home Assistant.
- At least one Music Assistant player exposed as a Home Assistant
media_player. - HACS, or manual access to
/config/www/community/. - A modern browser: Chrome, Edge, Safari, iOS WebKit, Android WebView, or a current Home Assistant Companion app.
Optional features need optional setup:
- This device / Sendspin browser player: direct Music Assistant URL and token.
- Announcements: a working Home Assistant TTS entity.
- Automation helper: an
input_texthelper for the active HOMEii player. - Remote artwork and Direct API: a browser-reachable Music Assistant URL, preferably HTTPS when Home Assistant is opened through HTTPS.
| Page | Use it for |
|---|---|
| Getting Started | HACS install, manual install, first card, first checks |
| Configuration | YAML options, visual editor, Music Assistant connection, Sendspin, card_id, query-string player overrides |
| Feature Guide | Main player, library, queue, Library Wheel, Queue Wheel, FLOW, Studio, lyrics, announcements, favorites, history |
| Layouts And Mobile Modes | Phone, tablet, desktop, compact, full, edge-to-edge, Section view, Panel view |
| Diagnostics | What Diagnostics v7 checks, how to copy a useful report, what each warning usually means |
| Troubleshooting | Missing artwork, empty queue, no players, HTTPS/HTTP issues, Companion app quirks |
For the most polished experience:
- Use a Panel view or a full-width Section view for the primary music dashboard.
- On phones, use Full or Edge to edge mode if HOMEii Music Flow is the main screen.
- Use Compact only when HOMEii Music Flow shares a dashboard with other cards.
- If multiple HOMEii cards run in the same browser, give each one a unique
card_id. - Keep Diagnostics available in the card settings. It is the fastest way to understand user reports.
Current documentation target: HOMEii Music Flow 5.9.3
5.9.3 documentation highlights:
- Reusable dashboards with
card_id - Open a dashboard directly to a player with URL parameters
- Library Wheel and Queue Wheel
- Phone edge-to-edge mode
- Diagnostics v7
- Group management and group-volume shortcuts
- Radio source preference and favorites-only library filtering
Release notes:
HOMEii Music Flow is an independent community project. It is not an official Home Assistant or Music Assistant project.
Thanks to the Music Assistant, Home Assistant, HACS, Sendspin, and Embla projects, and to all community testers and translators who helped shape the card.