iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use Music Assistant as the library layer between Home Assistant and your music files. Install Music Assistant on Home Assistant OS or run it as a Docker server, add your local disk or NAS share, let it index and match the collection, then add the Music Assistant integration in Home Assistant. The resulting media-player entities can search and play your catalog, while Home Assistant’s media browser can open album and artist locations such as library://album/20.
For reliable cover art, organize files as Artist/Album/track files, keep album and album-artist tags consistent, and place one folder.jpg, cover.jpg, or album.jpg in each album folder. Home Assistant’s built-in My media browser can play accessible files, but it does not provide the same indexed, cross-source album library.
What is the simplest architecture for a Home Assistant music library?
Home Assistant is the automation and control layer; Music Assistant is the catalog layer. Music Assistant scans artists, albums, tracks, playlists, metadata, and artwork, then exposes players and library items to Home Assistant through its official integration. Your files remain on their original disk or network share.
The arrangement has three parts:
- Storage: a folder on the Home Assistant host, a NAS share, or another supported source containing the audio files and artwork.
- Music Assistant: the service that indexes tags, groups tracks into albums, retrieves optional online metadata, and links matching releases from different providers.
- Home Assistant: the interface and automation system that controls Music Assistant players and browses library URIs.
This separation matters when you have more than a few files. Home Assistant’s native media source is suitable for straightforward file playback, while Music Assistant creates a searchable library with album grouping, artwork, and cross-source matching.
What do I need before starting?
Prepare the storage path, network access, and a Home Assistant installation that can host or reach Music Assistant.
Storage and network checklist
- A Home Assistant OS system can install Music Assistant as an app. A Raspberry Pi is a supported always-on host when you want a small dedicated computer.
- A Docker deployment is supported. Use host networking so Music Assistant can discover network speakers; bridged networking can prevent discovery even when the web interface loads.
- Your music can be on local storage or a network location using SMB/CIFS, NFS, or WebDAV. Google Drive and Microsoft OneDrive are also supported by the local-files provider.
- Make sure the account used by Music Assistant can read every music and artwork folder. A share that is visible from a desktop is not necessarily mounted or authenticated for the Home Assistant host.
Prepare the collection first
Use a predictable hierarchy such as Artist/Album/01 - Track Title.flac. Keep the album artist identical for every track in a release; compilations usually need a consistent album-artist value even when individual artist tags differ. Music Assistant can fall back to parsing filenames in the form Artist - Title.ext, but its documentation recommends proper tags because filename parsing cannot reliably resolve editions, discs, or collaborations.
Music Assistant does not rewrite your local tags. It reads the embedded metadata and can fill gaps with online metadata, so correcting the source tags remains the best way to prevent split albums and incorrect matches.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How do I install Music Assistant on Home Assistant OS?
Home Assistant OS users can install Music Assistant from the built-in app store. This keeps the library service on the same machine while preserving a separate web interface for catalog management.
- In Home Assistant, open Settings → Apps → App store.
- Find Music Assistant, choose Install, and wait for the installation to finish.
- Start the app, then select its option to open the Music Assistant web interface.
- Leave the app running while the initial library scan and metadata matching take place. Large collections may continue processing in the background after the interface first opens.
If the app does not appear, check that you are using Home Assistant OS rather than a manually managed installation. Other installation types can run Music Assistant separately, but they require their own host, updates, storage permissions, and network configuration.
How do I run Music Assistant with Docker?
Docker is useful when Home Assistant and the music service run on separate machines or when you already manage containers. Use the Docker Compose instructions from the Music Assistant project for the current image and volume layout, and set the container to host networking.
Why host networking is important
Many network speakers and playback endpoints advertise themselves with local-network discovery protocols. A container on a private bridge may not receive those announcements. Host networking puts the container on the host’s network stack, improving discovery; it does not remove the need to expose the Music Assistant web port and persist its configuration and database volumes.
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
Docker deployment checks
- Persist Music Assistant’s application data so a container replacement does not force a complete re-index.
- Mount the music directory read-only when you only need playback and indexing; grant write access only if a feature explicitly requires it.
- Mount NAS paths on the Docker host first, or configure the supported network provider inside Music Assistant. A path that exists only inside another container is not automatically available.
- Confirm that firewall rules allow Home Assistant to reach the Music Assistant server and that speaker discovery is permitted on the LAN.
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 browser. The provider then scans the files and builds the library used by the integration.
- Open the Music Assistant web UI.
- Choose the option to add a music provider and select Local Files.
- Point it to the directory containing your collection, or enter the network-share details for SMB/CIFS, NFS, or WebDAV. Google Drive and Microsoft OneDrive are available as supported cloud sources.
- Save the provider and allow the first scan to complete. Keep the server powered on; indexing and online metadata retrieval continue in the background.
- Open the artists, albums, and tracks views and inspect a few releases before building automations. This catches permissions and tagging problems early.
A NAS does not need to be physically attached to the Home Assistant machine. It does need stable network access and credentials that remain valid after a reboot. If the share disconnects, Music Assistant may show an incomplete library until it can read the files again.
How should I organize tags and artwork so albums group correctly?
Album grouping depends primarily on metadata, while artwork can come from embedded images or separate files. The most dependable setup combines clean tags with one folder-level image.
Tags that matter
- Artist: the performer for the track.
- Album: the release title, spelled consistently across all tracks.
- Album artist: the release-level artist. Use a common value for compilations rather than a different album artist on every song.
- Track and disc numbers: preserve ordering for multi-disc releases.
Inconsistent album-artist values can split one release into several apparent albums. Different spellings, punctuation, or edition names can also prevent Music Assistant from linking local files to the same release on a streaming provider.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Supported cover-file names
Place one image in the album directory and name it cover.jpg, folder.jpg, or album.jpg. If each disc has its own folder, place the appropriate image in those disc folders or in the parent album folder according to your layout. Embedded artwork is also supported.
A single folder-level image is preferable to embedding an identical large image in every track: it saves disk space and reduces the amount of artwork Music Assistant must read. Use a common image format and verify that the service account can read the file.
What happens during matching?
Music Assistant can link the same release across local and streaming sources when the metadata is sufficient, so one album entry can represent multiple playable copies. When tags are incomplete, matches may split and artwork may take longer to appear. Online metadata is retrieved slowly in the background; select Update Metadata on an individual item to force a refresh after correcting tags or artwork.
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.
How do I connect Music Assistant to Home Assistant?
After Music Assistant is running and has a provider, add its official integration to Home Assistant. Home Assistant normally discovers the server automatically on the local network.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →- Open Settings → Devices & services.
- Select Add Integration.
- Search for and choose Music Assistant.
- Accept the discovered server, or enter the Music Assistant server URL manually if discovery does not find it.
- Finish setup and open the created Music Assistant media-player entities to confirm that a player and library are available.
If manual setup works but automatic discovery does not, the services are usually on different VLANs, subnets, or firewall zones. Check routing and discovery rules rather than repeatedly reinstalling the integration.
How do I browse albums with cover art in Home Assistant?
Use Home Assistant’s media browser with the Music Assistant media-player entity. Album and artist locations are represented by Music Assistant URIs, for example library://album/20 and library://artist/1; the numeric IDs are examples and differ between libraries.
Browse interactively
- Open the Home Assistant Media view.
- Select a Music Assistant player or media source when prompted.
- Open the library’s artists or albums area.
- Choose an album to see its cover, tracks, and playback actions.
- Select a track or the album-level play action and choose the target player.
The displayed artwork comes from the metadata Music Assistant has indexed. If an album appears without a cover, fix the source artwork or tags in Music Assistant first; changing a Home Assistant dashboard card does not repair the library record.
Use a URI in an automation or script
Home Assistant’s media_player.browse_media action accepts Music Assistant album and artist URIs. Obtain the exact URI from the Music Assistant search or get-library actions, or from browse-media output, rather than guessing an ID. This lets a dashboard, script, or automation open a specific album while leaving the library and artwork management in Music Assistant.
Crashes, 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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Because IDs are library-specific, export or inspect the current URI after rebuilding a database. Do not assume that an album URI from one Music Assistant server will refer to the same release on another server.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Why are album covers missing or albums split?
Most visual problems originate in storage access, tags, or the timing of metadata enrichment. Work through these checks in order.
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)
| Symptom | Likely cause | Fix |
|---|---|---|
| The album is absent | The provider cannot read the folder, or the initial scan has not finished. | Verify the path and credentials in Local Files, confirm the files are readable by the Music Assistant process, and wait for the scan to complete. |
| Tracks appear as separate albums | Album or album-artist tags differ between files. | Normalize those tags, keep disc and release information consistent, then rescan or update metadata. |
| The album exists but has no cover | No supported image was found, the image is unreadable, or matching is still pending. | Add folder.jpg, cover.jpg, or album.jpg beside the tracks, check permissions, and run Update Metadata. |
| Artwork appears late | Online metadata retrieval runs in the background. | Allow the server time to process the item; force an individual metadata update after correcting the source. |
| Local and streaming copies do not combine | Metadata is not specific or consistent enough to identify the same release. | Correct album, album-artist, track, and disc tags and retry matching. |
| Speakers are not discovered in Docker | The container is isolated on bridge networking. | Run the Music Assistant container with host networking and check LAN firewall rules. |
| Home Assistant cannot find the server | Discovery traffic is blocked or the services are on different networks. | Use the manual server URL during integration setup, then fix routing or discovery if automatic detection is required. |
Should I use Music Assistant or Home Assistant’s built-in My media?
Choose Music Assistant when you want an indexed, searchable catalog with artwork and multiple sources. Choose My media when you only need Home Assistant to expose accessible files for basic playback.
| Capability | Music Assistant | Home Assistant local media |
|---|---|---|
| Library model | Indexed artists, albums, tracks, playlists, and cross-source links. | Accessible files exposed through the built-in media browser. |
| Artwork | Embedded or folder artwork, plus 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 OneDrive. | Files must be made accessible to Home Assistant. |
| Automation and browsing | media_player.browse_media, Music Assistant search, get-library, and play actions. |
Basic media browsing and playback. |
| Best fit | Large or mixed-source collections where album identity and artwork matter. | A small, known set of files that Home Assistant can reach directly. |
Home Assistant OS creates a /media directory automatically for local media. That option can be perfectly adequate for a few files, but it does not replace Music Assistant’s tagging, matching, and provider-management workflow.
Free tools Windows power users keep installed
One-click scans. No signup required.
How do I keep the library reliable after setup?
- Keep the album folder and cover image together when moving releases so the provider can find artwork again.
- Use stable, descriptive tags instead of relying on filename parsing.
- Back up Music Assistant’s application data if you run it in Docker, and back up the original music files separately.
- After a large tag cleanup, allow a complete scan and inspect compilations, multi-disc sets, and releases with guest artists.
- When adding a second source, check whether Music Assistant links it to an existing release or creates a separate item; correct metadata before manually maintaining duplicates.
- Keep the Music Assistant server and Home Assistant reachable on the same trusted network, or configure the required routing and firewall exceptions deliberately.
Frequently Asked Questions
Can Music Assistant run without Home Assistant?
Yes. Music Assistant is a standalone, free, open-source music library manager with its own web interface. Home Assistant is optional for automations, dashboards, and control of the resulting media-player entities.
Do I need an internet connection for local album playback?
Local playback can use files on your disk or NAS without a streaming subscription. Internet access is useful for online metadata enrichment and matching, so newly added albums may have less complete artwork or information when the server is offline.
Will moving an album folder break its Home Assistant URI?
It can. A URI such as library://album/20 identifies an item in a particular Music Assistant library, not a permanent filesystem path. After a move or a database rebuild, retrieve the current URI from search or browse-media output before updating automations.
Can I show Music Assistant album covers on a custom dashboard?
Yes. Use a media-player card or a dashboard control that reads the selected Music Assistant media item, then browse to the album through the media browser. The card displays whatever artwork Music Assistant has successfully indexed; dashboard styling cannot create missing source art.
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.
