Rules used to find local artwork

I have a clean install of Volumio 2.246 on a Raspi 2, and I would appreciate help in understanding the logic that is used to find and display local album artwork. Web art is switched off, to keep things simple.
I have folder.jpg files in all of my album folders but they are often not displayed. I am seeing no artwork on many albums on either the Browse:Album or Playback UIs. I have tried to find some correlation between those that are shown and those that are not, but with no luck.

Can someone clarify what the application is looking for when searching for local artwork, i.e what file name(s) (cover or folder or album name etc), what location or paths are used, any file size restrictions applied?
Is there any other logic that is used to find/use the local artwork?

I have searched all of the previous questions and comments on how artwork is used and understand that images embedded in the music files are not used due to performance reasons. However i can find no definition of how local artwork is found. I’m sure this would be helpful to many users of your great software.

Edited to add that when no local artwork is found, sometimes a black “Volumio” generic image is shown, other albums show a white circle with a dot in the middle. Is this difference significant?


The following configuration works fine on my system (RPI2, music files on NAS) :

Web Album art : ON ((i) Enable retrieval of Album art from Web, if no image is found in the file folder)
Web Album Art Size : MEDIUM

The images are located in the folder of each album as “Folder.jpg”( and also embeded within the music files for another system).

You should reset the album art cache to update the display and maybe rescan the library.


Thanks for your input Fred.
My folders have a folder.jpg in them but these are not displayed. I have tried clearing the cache and rescanning the library but they are still not displayed.
Are you using the latest version (2.246)?
Turning on web art does produce some images but not the same as those in my folders.
I would be interested to know if you turn off web art and clear the cache whether you see the images from your folders.


“Are you using the latest version (2.246)?” Yes

“I would be interested to know if you turn off web art and clear the cache whether you see the images from your folders.”

Yes I can see the images stored in my folders

You should maybe clear the cache of your browser.


I remember experiencing this behavior as well.

Could you do a little experiment? In one of the folders which contains album art, but isn’t displaying properly, do the following:

rename folder.jpg to cover.jpg
ensure web art is turned OFF
clear browser cache
rescan the library

Any difference?

Hi, thanks for the suggestion.
Renamed folder.jpg to cover.jpg, cleared web art cache, cleared browser cache, rescanned library…

Sadly all to no avail. That album art is not displayed, either when browsing Albums, in the Queue or in the Playback UI. All I see is the black generic Volumio image.

Thanks anyway


Did you clear the cache of your browser ?


cleared browser cache,
I think this discussion proves my original point.
Is there a definition of what rules are required to utilise local artwork or do we just keep guessing until something works?

thanks for your input

Below is my take on this issue - this is a guide I am working on to address this and a few other issues. It is not complete yet but may be helpful to you. Please feel free to suggest edits / corrections!

Library and Artwork

If you want to get the best experience from Volumio then it is important that you organise you library and artwork correctly. This guide aims to identify the key areas that need to be considered to make sure that this happens. You cannot expect Volumio to organise and sort you collection if you don’t take care of a few housekeeping jobs first. The following guide is a recommendation on how to achieve this based on my experience and understanding of how Volumio works;


The simplest (and in my opinion best) way to organise your library is to build it with a directory structure like;

‘YourLibrary/Name of AlbumArtist/Name of Album/Songs’

In other words, your library should consist of a source (a drive or folder containing your library) which is arranged with separate folders for each AlbumArtist. Please note that this is AlbumArtist - not Artist. What’s the difference? AlbumArtist is a description of who the album is attributed to. It may contain tracks that include other Artists - typically AlbumArtist is ‘Artist X’ but it may also include tracks where the Artist is ‘Artist X with Artist Y’ or ‘Artist X feat. Artist Y’. This information is stored in the ‘tags’ for each song and Volumio uses these tags to organise your library. The tags can be edited using a variety of software packages (I use MP3tag) - Google is your friend here! In these cases the AlbumArtist should be set to ‘ArtistX’ and the Artist set accordingly.

Inside every AlbumArtist folder there should be separate folders for each album which should contain the tracks and any artwork (see below).

What about ‘Compilation’ type albums?

A Compilation album is an album containing tracks by disparate artists - in other words there is no single ‘AlbumArtist’ for the whole album. It is a collection of songs by different artists. In this case, you should set the AlbumArtist tag to be ‘Various Artists’ or something similar. You can use another descriptor if you want (VA or Various etc…). What ever you decide to use make sure that Volumio understands that the descriptor you use is an indication of a "compilation’ type album. You can set this by adding the descriptor used within ‘Compilation Metadata Fields’ if it is not already there (in the ‘Settings’, ‘My Music’ screen). Place each of these albums within a folder named ‘Various Artists’ (or whatever descriptor you decide to use). The structure should look like

‘Yourlibrary/Various Artists/Name of Album/Songs’


Below is a summary of how Volumio uses albumart:

Volumio displays artwork for Artists and Albums on various pages (screens). Having the correct artwork for Artists and Albums enhances the visual display on pages significantly and makes it easy to scan the page visually and find the album you want.

  1. Volumio will look for album artwork to display from within the album folder for each album (* See below for recognised file names). If it finds a relevant artwork file it will copy it to the Volumio artwork folder (/data/albumart/folder/path to album) for future use.

  2. If it fails to find artwork AND you have ‘Show Embedded Albumart’ ON (in ‘Settings’, ‘My Music’, ‘Album Art Settings’) it will then look for embedded artwork in the song files. If it finds artwork it will copy it to the artwork metadata folder (/data/artwork/metadata/path to album).

  3. If that fails AND you have ‘Web Album Art’ ON (in ‘Settings’, ‘My Music’, ‘Album Art Settings’) it will attempt to download the album cover from the internet and save a copy to the albumart web folder (/data/albumart/web/path to album). You can set the resolution of downloaded artwork from the ‘Settings’, ‘My Music’ screen. The available options are;


Which size works best will be dictated by the size of screen used to run the Volumio application. If you use a small mobile phone or tablet then the smaller sizes will be adequate but if you use a large computer or TV screen then you will want to use ‘Extra-large’ or even ‘Mega’.

  • Album art is normally stored as ‘folder.jpg’ within the album folder but Volumio will search for files with any of the following names and use them;



I made a test as follows (Web Album Art: OFF) :

  • I remove the images from an album forder (AlbumArtSmall.jpg, Folder.jpg)
  • Reset Album Art Cache
  • Back to Album page, I reload the page
  • Go back to album page: the default image is displayed (white circle)
  • I put back the “Folder.jpg” in the album folder
  • Reset Album Art Cache
  • Back to Album page, I reload the page
  • Go back to album page: the correct album image is displayed

My music files are organized as follows:

Artist folder
------------------> Album folder (1) : music files . . . , Folder.jpg
------------------> Album folder (2) : music files . . . , Folder.jpg
------------------> . . . . . .

I hope this can help.


Many thanks to both, especially to “liberator” for his detailed explanation. I think the problem may be my folder structure, which are not as consistent as suggested. i will do some work to simplify and match Fred’s.

Just one further question. There is a reference to a setting “Show embedded Album Art”. Can you identify where this setting can be found? My understanding from other forum posts by michelangelo was that Volumio did not use images embedded in the music file. Is this correct?


I have edited my post to include the location of the setting. You will find it in ‘Settings’, ‘My Music’, ‘Album Art Settings’ - you must be on the latest ‘test’ release to see this until another full release is done (soon I hope!). You can download the latest ‘test’ release by going to volumio/dev in your browser and setting ‘Test Mode’ to True. Then go to ‘Settings’, ‘System’, ‘System Updates’ and press ‘Check Updates’. You can then install the latest Development version which includes the embedded albumart option.

Thanks for the info re the “test” version. However I don’t think the application is working as expected.

I have SSH’ed onto the RasPi and found the artwork folders, these contain no artwork at all, even though the library folders do contain “folder.jpg” files.
I have attached images of the SSH into the Artwork cache
the actual folder in the Library
and Image URL from Album View

I would have expected the Album artwork to be in the appropriate folder in the cache, but they do not seem to be there.
Have I misunderstood the structure or logic?


I am experiencing the same problems. When accessing the Volume player (a RPI) via the browser interface, there is only a few of the albums, where the art is shown.

If I access the player via the Volumio iOS app, there is no problem, the art is shown correctly.

Please clear your browser cache or clear the cache from ‘Settings’ ‘My Music’ (Album Art Settings) by pressing ‘Reset Album Art Cache’. Then load the Browse Albums page again.

The images will only be written if your browser requests them - it will not do that if the images are in the browser cache, even if they are the wrong images!

The URL for the image should look similar to this:

The albumart image should be saved in the cache folder as something like ‘extralarge.jpeg’.

Also, please check (In ‘Settings’ ‘System’) which version you are now running.

As per the OP, I am running the latest version (2.246)

I see no images , other than the black Volumio generic image, on either Chrome on Win 10 or iOS on an iPad, using Safari.
The album art cache has a folder structure that match the folders in my library but they contain nothing, as shown in the SSH image above.

The image URL matches, as shown in my post above, with that given by liberator, with one difference. On my system, the URL does not contain the token “metadata=false”, is this significant?


Firstly, you have not changed your directory structure as you said you would. If you HAD changed it then the path to the Al Green album would be:

/data/albumart/folder/mnt/NAS/USB2/Al Green/Greatest Hits <<<Note the folder with the album name.

Secondly, you are not running the latest Development version. You are running 2.246. The latest development version is 2.253.

That being said, your albumart should still work as described with the exception of the Metadata option described. The artwork url you quote is consistent with version 2.246 and is correct.

Please try the following;

Remove all other image files from the Al Green folder and change the name of ‘Folder.jpg’ to ‘folder.jpg’

Go to ‘Settings’ ‘My Music’ and the press ‘Reset Album Art Cache’

Then Browse Albums again. Do you have artwork for the Al Green album?

Firstly I removed all other image files from the Al Green folder, cleared the browser cache, reset the Album Art cache in “My Music”. No difference, still the black generic Volumio image in both the Browse Album and Playback UIs.

Secondly, I renamed the Folder.jpg to folder.jpg - cleared browser cache and Artwork cache, still no difference.

Repeated the above steps on a folder which followed the Artist:Album structure, i.e “Adele/25/music files and just folder.jpg” Still no images displayed.

As expected, after Resetting the Album Art cache in “My Music”, the folder /data/albumart has no content.
After visiting the Album view in the Browse tab then the folder /data/albumart has a mirror image of the library folder structure on my NAS, such as;
however these folders have no content.

It looks like the Album Art cache is not being loaded with the folder.jpg files that exist in the library. Is it possible that the fact that the library is on a remote NAS could be causing an issue?

thanks for your help


The test I did replicated your setup. I created a remote NAS and duplicated your directory structure. It worked fine so I don’t think it is because it is a NAS.

Can you confirm that you have a folder ‘/data/albumart/folder/mnt/NAS/USB2/Al Green’? This folder is only created if Volumio finds a valid albumart file in the music library album folder. If the folder has been created then it indicates that it found your folder.jpg. If the folder is empty then it indicates that it was then unable to copy the file to the cache folder. We will then need to look at file permissions on your NAS.

Another thing worth trying in order to narrow this down would be to plug your USB drive directly in to your Volumio device (RPI?) and see if it then works correctly. If it works then we know it is something to do with file permissions on the NAS.

Thanks for the input and effort.
Yes, there is a folder in the album art cache called “Al Green” but it is empty.

My “NAS” is a large USB stick plugged into the USB port on my Router, which shares it on the network via CIFS.
It is formatted as FAT32 and is accessible as a network drive on my Win 10 PC and I can read and write to that drive. The drive was found, mounted and scanned in Volumio. Volumio plays the music from the drive without any issues, apart from the missing images.
It is possible that it is “read-only” as I guess Volumio connected without any credentials. Could this cause a problem when trying to copy the folder.jpg file off the NAS into the cache?