Connect Home Assistant to Music Library & Browse Albums by Artwork

This guide walks you through connecting Home Assistant to a local music library and setting up an interface where you can browse and play albums by their cover artwork. You’ll need a working Home Assistant installation, a music library stored on a network drive or local disk, and a media player integration (like Spotify, Sonos, or a DLNA device) already configured. By the end, you’ll have a beautiful album-art-first browsing experience directly in your Home Assistant dashboard.

What You’ll Need

• Home Assistant (HA) 2023.10 or newer (older versions may work but the steps assume current UI)
• A music library folder (MP3, FLAC, M4A, etc.) accessible from the HA host (local disk, NAS, or Samba share)
• At least one media player integration (e.g., Spotify, Sonos, Chromecast, or a DLNA/UPnP player) already set up in HA
• Optional but recommended: a network share (SMB/NFS) mounted to HA if your music is on another device
• The “Music Assistant” integration (free, open-source) or the built-in “Media Source” feature

Step-by-Step

1. Mount your music library to Home Assistant. If your music is on the same machine as HA, note the full path (e.g., /media/music). If it’s on a NAS, add a Samba mount via the HA “Samba Mount” feature (Settings > System > Storage > Add Network Storage) or manually edit configuration.yaml with a shell_command or a dedicated mount add-on. For a quick test, copy a few albums to /media/music on the HA host.
2. Install the Music Assistant integration. Go to Settings > Devices & Services > Add Integration, search for “Music Assistant”, and install it. This integration scans your music folders and builds a library database, including album art.
3. Add your music folder as a Music Assistant provider. After installation, open Music Assistant from the sidebar, go to Settings > Providers, click “Add Provider”, choose “Filesystem”, and enter the path to your music folder (e.g., /media/music). Music Assistant will start scanning; this may take a while for large libraries.
4. Connect a media player to Music Assistant. In Music Assistant, go to Settings > Players, and add your existing media player (e.g., Sonos, Chromecast, or DLNA). This allows Music Assistant to send audio to that player.
5. Verify album art is being fetched. Once the scan completes, go to the Music Assistant “Albums” tab. You should see album covers. If any are missing, Music Assistant will try to fetch them from online sources (like MusicBrainz) automatically. You can also manually edit album art by clicking the album and selecting “Edit”.
6. Create a dashboard card for album browsing. Go to your dashboard (Overview), click the pencil icon to edit, then click “Add Card”. Search for “Music Assistant” or “Media Browser”. Choose the “Album Browser” card (or use the generic “Picture Entity” card with a grid). Configure the card to use the Music Assistant entity (e.g., media_player.music_assistant) and set the view to “Albums”.
7. Customize the album grid layout. In the card options, set the number of columns (e.g., 4 or 5) and the image height. You can also add a tap action to start playing the album immediately, or a hold action to open the album detail page.
8. Add a search bar (optional). If you have a large library, add a “Search” card or use the built-in search in the Music Assistant interface. For a dashboard-only approach, you can use the “Mushroom” card with a search action, but the simplest is to keep the Music Assistant panel accessible from your sidebar.
9. Test the flow. Click an album cover on your dashboard. It should start playing on the selected player. Check that the artwork displays correctly and that playback controls (play/pause, skip) work.
10. Make it permanent. If you used a temporary folder for testing, move your real library to the mounted path and update the provider path in Music Assistant. Then re-scan the library.

Common Mistakes

• Using a path that HA can’t read. Home Assistant runs in a container or venv; local paths like C:\Music won’t work. Use Linux-style paths like /media/music or a mounted SMB share.
• Forgetting to install a media player integration. Music Assistant alone won’t play audio; you must connect a player (Spotify, Sonos, etc.) in its settings.
• Expecting artwork to appear instantly. The scan and metadata fetch can take minutes to hours for large libraries. Be patient and check the Music Assistant log if nothing appears.
• Using a card that doesn’t support album art. The default “Media Control” card only shows the current track’s art, not a browsable grid. Use the Music Assistant card or a custom grid card.
• Not refreshing the dashboard. After adding the card, you may need to reload the dashboard (press F5) to see the album art.

Tips

• Organize your music folder by Artist/Album (e.g., Music/Artist/Album/track.flac). Music Assistant works best with this structure, and album art is more likely to be correct.
• Embed album art in your files (using MP3tag or similar) for faster and more reliable display.
• Use a dedicated HA instance for music if your main instance is on a low-power device like a Raspberry Pi; scanning a large library can be CPU-intensive.
• For a cleaner look, use a custom card like “Mini Media Player” with album art, but for browsing, the Music Assistant card is best.
• Set up a second player group if you want to play to multiple rooms simultaneously.

Troubleshooting

• No albums appear after scanning. Check that the folder path is correct and that HA has read permissions. In Music Assistant, go to Settings > Logs and look for “Filesystem” errors. Also verify that your music files are not corrupt.
• Album art is missing or wrong. Music Assistant fetches art from online databases. If it fails, you can manually set art by clicking the album, selecting “Edit”, and uploading an image. Alternatively, embed art in your files.
• Clicking an album does nothing. Make sure you’ve added a player in Music Assistant settings. Also check that the player is online and that the card’s “Tap action” is set to “Play” (not “More info”).
• Dashboard card shows blank squares. This usually means the images aren’t loading. Try refreshing the page, or check the browser console for errors (F12). If you’re using a reverse proxy, ensure it allows large image requests.
• Music Assistant won’t install. It’s a custom integration, so you need to add it via HACS (Home Assistant Community Store). If HACS isn’t installed, install HACS first, then search for Music Assistant in its store.
• Playback stutters or cuts out. This is usually a network issue. If your music is on a NAS, check the network speed. For wireless players, try a wired connection or move the player closer to the router.

Frequently Asked Questions

1. Can I use this with Spotify? Yes, Music Assistant can connect to Spotify as a provider, but for local library browsing, you’ll still need a filesystem provider. You can have both.
2. Do I need to install HACS? Yes, Music Assistant is not in the default HA integration list. Install HACS first, then add Music Assistant from the HACS store.
3. Will this work with my Sonos system? Yes, Music Assistant supports Sonos players. Add them in the Players section.
4. Can I browse by genre or artist as well? Yes, Music Assistant’s interface has tabs for Albums, Artists, Genres, and Playlists. You can also create a dashboard card for each.
5. Is there a way to search for a specific album? Yes, the Music Assistant panel has a search bar. On the dashboard, you can add a “Search” card that filters the album grid.
6. What file formats are supported? Most common formats: MP3, FLAC, AAC, M4A, OGG, WAV, and more. Music Assistant handles them all.

Related

• Slim Phones: Is Thinness Really What Buyers Want?
• Claude Code vs Codex CLI for Portfolio Landing Pages
• Gemini Downloadable Files: How Content Export Works