HiFiBerryOS: Handling local music libraries


HiFiBerryOS: Handling local music libraries

With the June 2020 release, HiFiBerry introduced a new feature: accessing a local music library – on a USB drive or a NAS. This is a new features and not all functionalities are available in the user interface.

Music sources

USB hard disks, memory sticks

These should be detected automatically.

SMB shares

While accessing music on NAS devices via Smaba is already supported, you can’t configure this from the user interface. To configure this, login via SSH and create a file /etc/smbmounts.conf as follows:


Name is just a unique identifier that you can assign by yourself. This should look like this:


You can also add additional mount options:


Then run the command


After the music has been mounted, HiFiBerryOS will scan your library. Depending on the size, this might take from a few minutes to a few hours (for very large libraries). This process is required. You need to have some patience. If this is finished further updates of the database will only scan for new files. This will be much faster.

Artist images

HiFiBerryOS will use services as Fanart.tv to download artist pictures and display these. However, it might not find images for all artists. You can upload your own artist images. Just use square JPEG files with a resolution of about 300×300 to 600×600 pixels. Larger images will also work, but the GUI might not as responsive as it has to deal with more data. Name the image “artistname-thumb.jpg” and copy these to /data/library/artists. artistname has to match the name exactly, except upper/lowercase. This means if the artist name includes special characters as spaces, dots, hypens or similar, these have to be also in the filename. The filename for “Duke Ellington \& Johnny Hodges” has to be “duke ellington \& johnny hodges”. If it doesn’t match, HiFiBerryOS will just ignore the file.

Album covers

HiFiBerryOS will use cover pictures on the file system or cover images from the metadata of the music files itself. To make sure this works, each album has to be in a separate directory.

Tips for your music library

As HiFiBerryOS uses metadata in the files, it’s important that your music files are correctly tagged. You might use tools like the free MP3Tag to correct or add missing tags. HiFiBerryOS will automatically extract cover images from your music files.
The following tags are specifically important:

  • Track, Title, Interpret
  • Year – this will be used to sort albums
  • Album Interpret – if this is not defined, interpret is used
  • Disc number – multi-disc albums should have correct tagging to make sure tracks will be sorted correctly


Something isn’t working as expected? You need some tips how to tag files? Any other question? Post in our community area.

Last updated: July 7, 2020