Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use Music Assistant as the music-library layer between Home Assistant and your audio files or streaming services. Install Music Assistant on Home Assistant OS or run it as a Docker server, add your local folder or NAS share, let it index and match the collection, then add the official Music Assistant integration in Home Assistant. The integration exposes Music Assistant players and lets Home Assistant browse albums and artists with media URIs such as library://album/20.
Home Assistant’s own media browser can play accessible files, but it is not a full tagged-library manager. Music Assistant adds indexed artists, albums, tracks, playlists, artwork handling and cross-source matching, which is the practical route when you want a visual album collection rather than a list of files.
As an Amazon Associate I earn from qualifying purchases.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →What is the recommended Home Assistant music-library setup?
The reliable arrangement is to keep your music files where they already live, let Music Assistant index them, and use Home Assistant as the control and automation layer. Music Assistant is a free, open-source music library manager; Home Assistant connects to it through the Music Assistant integration and media-player entities.
The three parts of the setup
- Music storage: A local folder, a NAS share, or another supported source containing your audio files.
- Music Assistant: The service that reads tags, groups tracks into albums, finds artwork and exposes a searchable library.
- Home Assistant: The interface and automation system that discovers Music Assistant players and can browse or play media.
This separation matters. Home Assistant does not itself provide the same indexed, tagged music-library workflow. Its built-in media browser is suitable for straightforward file playback, while Music Assistant is designed for browsing a collection by artist, album and playlist.
How do I install Music Assistant?
Choose the installation that matches your Home Assistant host. Home Assistant OS users can install the Music Assistant app directly; Docker users can run a separate Music Assistant server.
Install it on Home Assistant OS
- Open Settings → Apps → App store in Home Assistant.
- Find and install Music Assistant.
- Start the app after installation completes.
- Open the Music Assistant web interface from the app page.
The app approach keeps Music Assistant on the same managed Home Assistant OS machine. It is the simplest option when that machine has enough storage access and network reachability to your music collection.
Recommended Free Tools
Run Music Assistant with Docker
A Docker deployment is an alternative when Home Assistant runs in a container, on another server, or on hardware you manage separately. Follow Music Assistant’s documented Docker Compose configuration for the current image and volumes. Enable host networking: the project requires host networking for reliable speaker discovery. Without it, players that depend on local-network discovery may not appear even though the server itself is running.
Whichever deployment you choose, confirm that the Music Assistant web interface opens before configuring Home Assistant. Treat the Music Assistant server as the component that must reach both your storage and your playback devices.
How do I add a local folder or NAS music share?
Add the source from Music Assistant’s provider settings, not from Home Assistant’s media-player page. The local-files provider can read a folder on the server and supported network storage.
Supported storage locations
- A folder on the computer or Home Assistant host running Music Assistant.
- An SMB/CIFS share, commonly used by NAS devices.
- An NFS export.
- A WebDAV location.
- Google Drive or Microsoft OneDrive.
For a NAS, make the share reachable from the machine running Music Assistant, then select the local-files provider and enter the share path and credentials requested by the provider. The exact path depends on how your NAS and host expose the share; Music Assistant cannot index a share that the server itself cannot read.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteUse a predictable folder layout
A structure such as Artist/Album/track files gives the indexer useful context and makes artwork placement predictable. Multi-disc releases can use disc subfolders beneath the album folder. Keep one release together rather than scattering tracks across unrelated directories.
Music Assistant reads artist, album, track and other metadata from the files. If tags are absent, it can fall back to parsing filenames in an Artist - Title.ext pattern, but the documentation recommends proper tags because filename parsing cannot reliably express album artist, disc number, compilation status or alternate editions.
How should I tag files so albums group correctly?
Consistent tags are the main factor in whether tracks become one coherent album. Music Assistant can link the same release across local and streaming sources when the metadata is sufficient, but incomplete or contradictory tags can split one album into several entries or attach artwork slowly.
Fields that deserve special attention
- Artist: The performing artist for the individual track.
- Album: The release title, written consistently on every track in that release.
- Album artist: The release-level artist. This is especially important for compilations and albums with guest performers.
- Track and disc numbers: Keep numbering consistent so order and multi-disc grouping are preserved.
- Compilation information: Use the same compilation and album-artist conventions across every track.
Music Assistant does not modify your local tags. Online metadata can fill gaps and improve matching, but it does not rewrite the files in your library. That makes it safe to correct tags in your preferred editor and then let Music Assistant rescan or refresh the item.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
- All-in-One Complete Kit: This SANOOV RPi 5 bundle comes with Raspberry Pi 5 4GB RAM single board, active cooler, durable ABS case and screwdriver. No extra parts needed, ready to use right out of the box for beginners and hobbyists
- Powerful Single Board Computer: Equipped with 4GB RAM and high-performance processor, delivers fast running speed for 4K playback, AI projects, programming and daily computing tasks. SANOOV for raspberry pi 5 4GB is equipped with broadcom 64 quad-core Arm Cortex A76 processor with gigabit ethernet and upgraded with IEEE 802.11ac Wi-Fi, Bluetooth 5.0 dual-band 2.4Ghz and 5Ghz and Power Over Ethernet (POE). Upgrading delivers 2-3 x speed vs Pi 4, redefining the experience
- Efficient Active Cooler: Effectively lowers operating temperature and prevents performance throttling. Runs quietly even under long-time heavy load, ensures stable operation all day long. SANOOV RPi 5 4GB kit offer an active cooler, which combines an aluminium heatsink with a high-performance PWM fan. Active cooler is fully compatible with the Pi OS, which can effectively reduce the temperature of RPi5 and ensure its good performance during long-term high load operation
- Sturdy ABS Protective Case: Well-fitted for Raspberry Pi 5 board, can be secured with 4 screws to effectively protect the Pi 5 motherboard from damage, reserves full access to all ports and buttons. SANOOV uses ABS material to produce the case, which has a softer texture and feel. Meanwhile, SANOOV case adopts a layered design for easy disassembly and installation. (Tip: The Case cannot install M.2 HAT Add on Board and Solid State Drive!)
- Wide Application & Full Compatibility: Seamlessly compatible with official OS and mainstream peripheral accessories for Raspberry Pi 5. Whether you are a beginner, student, electronics hobbyist or professional developer, this all-in-one kit meets your diverse needs. It excels in IoT projects, robotics design, retro gaming devices, home media servers and other DIY creations. Backed by a large global community, you can easily find guides, technical support and shared projects online
Let the initial scan finish
After adding a source, allow the library synchronization to complete before judging the result. Online metadata retrieval runs slowly in the background, so an album may initially appear with limited information and gain artwork or a better match later. For an individual item, use the interface’s Update Metadata command to force a refresh.
Where should album artwork go?
Music Assistant can use artwork embedded in audio files or an image stored beside the files. For an album, place a folder-level image in the album directory and name it cover.jpg, folder.jpg or album.jpg.
Recommended artwork arrangement
- Create one folder for the album, optionally with disc subfolders.
- Put one square JPEG image in the album folder using one of the supported names:
cover.jpg,folder.jpgoralbum.jpg. - Keep the image beside the tracks rather than copying the same image into every audio file.
- Check that the Music Assistant server account can read the image file.
The documentation recommends one folder-level image instead of repeating identical embedded art in every track. This reduces disk use and can improve performance, while embedded artwork remains supported when that is how your files are maintained.
Artwork for multi-disc albums
If each disc has its own directory, place the release artwork where the provider can see it consistently: normally in the album folder, with disc folders beneath it. If a particular disc is being treated as a separate album, give that disc folder its own supported image and verify the album and disc tags before changing filenames.
How do I connect Music Assistant to Home Assistant?
Once Music Assistant is running and has a source, add its official integration in Home Assistant.
- Open Settings → Devices & services.
- Select Add Integration.
- Search for and choose Music Assistant.
- Accept the discovered server when Home Assistant finds it automatically.
- If discovery does not find the server, enter the Music Assistant server URL manually when prompted.
After setup, Home Assistant creates Music Assistant media-player entities. Those entities are the targets for playback and automation; the library itself remains indexed by the Music Assistant server.
How do I browse albums by cover art in Home Assistant?
Use Home Assistant’s media browsing controls with Music Assistant’s library URIs. Album and artist identifiers can come from Music Assistant search or get-library actions, or from the output of a browse-media request.
Album and artist URI examples
library://album/20identifies an album.library://artist/1identifies an artist.
Home Assistant’s media_player.browse_media action accepts these Music Assistant URIs. Start from the Music Assistant media player in a dashboard or automation, browse into the library, and select the album entry; the returned media information includes the playable items and artwork supplied by Music Assistant.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Using browse results in automations
For an automation, first obtain the album or artist URI through Music Assistant’s search or get-library functionality, then pass that URI to the media-player browse action. Use the resulting media item when calling the appropriate play-media action for the selected Music Assistant player. This avoids hard-coding a file path and keeps the automation tied to the indexed library object.
IDs in examples are illustrative. Use the URI returned by your own Music Assistant instance rather than assuming that a number from another installation refers to the same album.
Rank #3
- powful cputhe cpu of the raspberry pi 4 model b adopts the latest arm cortex-a72 architecture, which is also used in high-performance smartphones, and has evolved into a real pc.the operating clock has been changed from pi3's 1.2ghz to 1.5ghz, and the speed has become a different dimension with the updated architecture.
- video output/gputhe on-board gpu of the raspberry pi 4 supports 4kp@60 and newly supports h.265 decoding, opengl es 3.0, etc.as for the video output, two micro hdmis with smaller connectors are installed, and the raspberry pi 4 also supports dual screen output.
- usb 3.0with a new soc, the speed of the raspberry pi 4 around i/o has been improved, and finally usb 3.0 is supported.usb boot is faster and more convenient.
- network&bluetoothgigabit ethernet (wired lan) has also been significantly speeded up from 300mbps of pi 3b + to 1000mbps (logical value).in addition, bluetooth supported version has been upgraded to 5.0, and the transfer speed of pi 4 has been doubled.
- power input connectorthe power input connector of the raspberry pi 4 has been changed to usb type c. it is easier to use than micro usb and can supply a larger current reliably.the power requirement of raspberry pi 4 model b is 5v 3.0a, which is higher than the previous model.
Why are my album covers missing or albums split?
Missing artwork and duplicate-looking albums usually indicate a source-access, metadata or indexing issue rather than a Home Assistant dashboard problem.
Check the source before changing the dashboard
- Open the Music Assistant web interface and confirm the source is online.
- Verify that the server can read both the audio files and the artwork image.
- Check that the image is named
cover.jpg,folder.jpgoralbum.jpg, or that embedded art is actually present. - Confirm that every track in the release uses the same album and album-artist values.
- Wait for background metadata retrieval to finish, then run Update Metadata on the affected item.
Fix albums that are split into multiple entries
Compare the tags on the tracks in each entry. Differences in album title, album artist, disc numbering or compilation flags can make Music Assistant treat tracks as separate releases. Correct the tags in your file editor, leave the files in a consistent album folder, and let Music Assistant synchronize again.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Fix artwork that appears late
Online metadata retrieval is intentionally a background process and can be slow. A newly indexed album may therefore show a temporary placeholder or no remote artwork; forcing Update Metadata for that item is the documented way to request another lookup.
Should I use Music Assistant or Home Assistant’s built-in media browser?
Choose Music Assistant when you need a unified, searchable album library with artwork and cross-source linking. Use Home Assistant’s built-in browser when your requirement is simple playback of files that Home Assistant can access directly.
| Capability | Music Assistant | Home Assistant local media |
|---|---|---|
| Library model | Indexes artists, albums, tracks and playlists, and can link matching releases across sources. | Exposes accessible files through the built-in media browser. |
| Artwork | Supports embedded or folder artwork and metadata enrichment. | Depends on the files and media-source integration; an equivalent Music Assistant-style library workflow is not documented for this route. |
| Network sources | Local disk, SMB/CIFS, NFS, WebDAV, Google Drive and Microsoft OneDrive. | Files must already be made accessible to Home Assistant. |
| Browse and automation control | Supports media_player.browse_media, Music Assistant search, get-library and play actions. |
Provides basic media browsing and playback. |
Can I keep the collection on a NAS?
Yes. Music Assistant’s local-files provider supports NAS-style SMB/CIFS and NFS shares, as well as WebDAV. The important requirement is that the Music Assistant server, not only your laptop, can authenticate to and read the share.
NAS checklist
- Create a read-access account or share permission for the Music Assistant host.
- Confirm the share is reachable from the host’s network.
- Point the local-files provider at the mounted or provider-accessible path.
- Keep album folders and artwork files together on the share.
- Allow the initial synchronization to finish before testing album browsing.
If Music Assistant runs in Docker while the NAS is on another machine, map the share into the container according to your deployment and preserve read permissions. Host networking is still required for speaker discovery; storage access and speaker discovery are separate concerns.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWhat hardware and network requirements matter?
Music Assistant can run on Home Assistant OS or a separate Docker host. A Raspberry Pi is an explicitly supported always-on host, making it a practical option for a small home installation. A NAS is useful when the collection is stored remotely, provided the Music Assistant server can read the share and its artwork.
- Reachability: The Music Assistant server must reach the music source and playback devices.
- Permissions: The account used for a local or network source needs read access to audio and image files.
- Discovery: Docker deployments need host networking for speaker discovery.
- Consistency: Stable folder names and tags reduce re-indexing surprises.
There is no requirement to move the collection into Home Assistant’s own storage if Music Assistant can read the existing location.
What is the simplest path for different kinds of collections?
Your best path depends on whether you need library features or only playback.
Local files on the Home Assistant machine
Install Music Assistant as a Home Assistant OS app, add the local folder, wait for synchronization, then add the integration. This gives you indexed albums and artwork without introducing a second storage server.
Rank #4
- Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
- Includes Pre-Loaded 32GB EVO+ Micro SD Card (Class 10), USB MicroSD Card Reader
- CanaKit Premium High-Gloss Raspberry Pi 4 Case with Integrated Fan Mount, CanaKit Low Noise Bearing System Fan
- CanaKit 3.5A USB-C Raspberry Pi 4 Power Supply (US Plug) with Noise Filter, Set of Heat Sinks, Display Cable - 6 foot (Supports up to 4K60p)
- CanaKit USB-C PiSwitch (On/Off Power Switch for Raspberry Pi 4)
Music on a NAS
Run Music Assistant where it can reach the NAS, add the SMB/CIFS, NFS or WebDAV source, verify permissions, and keep the folder-level artwork beside each album. Use Home Assistant only after the Music Assistant library shows the expected albums.
Files plus streaming services
Add the local source and the supported streaming providers to Music Assistant. When metadata is sufficient, matching releases can be linked so the library represents one album even when more than one source copy exists.
Simple file playback
If you do not need indexed tags, album artwork management or cross-source matching, Home Assistant’s Media → My media browser may be enough. On Home Assistant OS, the /media directory is created automatically, but the files still need to be accessible to Home Assistant.
How do I maintain the library after the first setup?
Maintain the source files first, then refresh Music Assistant. Keep album folders stable, use one consistent album-artist value for each release, and store the preferred folder artwork with the album.
- Correct tags or add new files in the source folder.
- Keep artwork in the album folder using a supported filename.
- Allow Music Assistant to detect and synchronize the changes.
- Use Update Metadata on an item whose artwork or online details remain stale.
- Open Home Assistant’s Music Assistant media player and browse the affected album to verify the result.
Because Music Assistant does not rewrite local tags, your file organization and tagging tool remain the authoritative place for permanent metadata changes.
What should I check when browsing does not work?
Work from the library outward: source, index, integration, then player.
- Source: Confirm the Music Assistant provider can read the folder or NAS share.
- Index: Check that the album appears in the Music Assistant web interface and that its artwork is visible there.
- Integration: Confirm the Music Assistant integration is configured under Settings → Devices & services.
- URI: Use the album or artist URI returned by your instance, such as
library://album/20, rather than a guessed identifier. - Player: Select a Music Assistant media-player entity that is online and available to Home Assistant.
If the library looks correct in Music Assistant but not in Home Assistant, reconnecting the integration or entering the server URL manually can resolve discovery problems. If the album is absent in Music Assistant itself, fix source access, tags or metadata before troubleshooting the Home Assistant dashboard.
Frequently Asked Questions
Does Home Assistant need direct access to the original music folder?
Not necessarily. In the recommended design, Music Assistant reads the folder or NAS share and Home Assistant communicates with the Music Assistant server through its integration. Home Assistant still needs network access to that server and to the player entities it controls.
Can one Music Assistant album represent files from more than one source?
Yes, Music Assistant can link the same release across local and streaming sources when the metadata is sufficient. Incomplete tags can prevent that match and leave separate entries instead.
Will adding artwork change the audio files themselves?
No. Music Assistant does not modify local tags or embed new images into your tracks. Folder artwork and online metadata are used by the library layer while your source files remain unchanged.
Is the album number in a sample URI universal?
No. Values such as the 20 in library://album/20 are examples from the URI format. Obtain the actual album or artist URI from your own Music Assistant search, get-library result or browse-media output.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
