<?sphp $this->text('pagetitle') ?>
Home of the Squeezebox™ & Transporter® network music players.

Album Artwork

From SqueezeboxWiki

Revision as of 15:28, 11 April 2017 by Pippin (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Squeezebox Server (formerly SqueezeCenter) and the Squeezebox Controller can display artwork associated with each album. This "cover art" is typically a copy of the CD/album's cover.

Artwork is displayed in several places within the Squeezebox Server Web interface. The details of the display vary depending on the skin currently being used. The "Default", "Fishbone," and "Moser" skins have browse by cover art functions, clicking on a picture of the CD/album will select the album for playing or processing. The "Fishbone" skin also displays the cover art in the status display as the songs are played.


What is Artwork, how does Squeezebox Server use it?

Artwork is cover art from CD albums. It is displayed both to beautify the Squeezebox Server interface. Any Squeezebox Server function which lists albums can show artwork by selecting the "Gallery View" icon in the upper right-hand corner of the left-hand pane.

How do I get cover art?

Many site that sell CDs include cover art in their catalog. With most browsers, you can right click on the image and select "Save image as..."

Several third party developers have written utilities to automatically retreive cover art based on the internal tags of your MP3, OggVorbis, FLAC, or other files. See the plugins page for more information.

Graphic file requirements

Squeezebox Server will display any graphic file that your browser can support. Nearly all browsers support GIF and JPG files, so most Squeezebox users use one of these file formats.

Image sizes

The image files should be modest in size, as they are sized to fit on the Controller's or player's display, or the HTML browser window. Because the images will mostly be displayed at less than 500x500 pixels, having images larger than twice that size will waste space and bandwidth, and will be slower to load.

Technical details

For each place in the skin that references a large cover art image, the Squeezebox Server software performs the following search:

  • Search in the current music directory for (in order):
    1. cover.jpg, cover.gif,
    2. folder.jpg, folder.gif,
    3. album.jpg, album.gif,
    4. thumb.jpg, thumb.gif,
    5. albumartsmall.jpg, albumartsmall.gif

Squeezebox Server will use the first image file located in this search. For the smaller, thumbnail image, a similar search is performed, except that the list is reversed, searching for thumb first. Specifically:

  • Search in the current music directory for (in order):
    1. thumb.jpg, thumb.gif,
    2. albumartsmall.jpg, albumartsmall.gif,
    3. cover.jpg, cover.gif,
    4. album.jpg, album.gif,
    5. folder.jpg, folder.gif

Squeezebox Server looks in the same path as the song, thus you would be looking for the same artfile in this case. However there is an option in Server Settings, Additional, Interface for setting filenames for Artwork, Artwork Thumbnail, and for setting a central location for artwork files. You can enter a specific filename if you use something not found in the list (eg, artwork.jpg). You may also create filenames based on song variables. If your first character is %, the server then parses the rest of the string as an InfoFormat, the same as title format is created.

/IMPORTANT: If you change this filename setting or if you have added or changed any artwork files to existing albums, you must use the rescan option Clear library and rescan everything to see your updates. Overnight scans won't do it. Go to Home - Server Settings and look for the rescan options. It can be wise to clean up your cache folder using the Squeezebox Server Control Panel (Squeezebox Server 7.4+) advanced settings tab, which will also trigger a complete rescan./

As an example of a setup using custom artwork filenames, you could create a single directory of songs and name all your artwork as artist-album.jpg. For this, enter a setting of


for Artwork or Artwork Thumbnail in the server settings section. The extension can be specified for any server supported format, .jpg is assumed if no extension is given.

/NOTE: If you use any of these custom name settings and prefer to save each artwork file to each album's specific folder, you must still specify a path for the Artwork Folder setting: copy '''the path to your music library''' to the "Artwork Folder" path. This path (e.g. C:\Documents and Settings\Username\My Documents\My Music ) is shown in the basic settings window of Squeezebox Server./

Available data elements are:

  • CT
    • Track title
    • Song genre
    • tracknumber as an integer
  • FS
    • file size as reported by the underlying Operating System.
    • Artist for pop music, sometimes conductor for classical works.
    • Album name.
    • Often the encoder used to create the MP3 / FLAC / AAC /... file.
  • YEAR
    • Year published or released.
  • SECS
    • total song length in seconds
    • (minutes and seconds),
    • volume name
  • PATH
    • Path to the song
  • FILE
    • main file name of song
  • EXT
    • file extension of song (Type in Microsoft systems)
    • current date, long
    • current date, short
    • current time.

Elements can be separated by anything (or nothing), but if you use underscores they must have a space on either side in the settings and the actual filenames (e.g. %ARTIST _ ALBUM ; "Prince _ Purple Rain.jpg"). The separators are only used if the data elements are present.

The above list is included for completeness, it is unlikely that anyone would actually want to have differing artwork files for songs of different bitrates, but the ability is in Squeezebox Server.

Artwork internal to the ID3 tags within a song takes precedence, followed by any specified filename in the server settings. If an Artwork Folder setting is used (in Server Settings, Additional, Interface) then that folder is searched first for any file matching those given for Artwork and Artwork Thumbnail. In the Thumbnail selection, the Server reverses the search list so that thumb is found before cover. This way, you can have a set of large images and a set of small ones.

Browse by artwork and status BOTH scale the same image file found for Thumb. By default, the browse by artwork constrains to 100x100, while the status contrains to 100 leaving aspect ratio intact.

Server side resizing

As of version 6.5, Skins can control the behaviour of the server side resizing performed on the image by adjusting the filename requested.

At present, there are three parameters that can be passed to the server:

  • The requested size
  • The resizing mode to be used
  • The background colour to be used. Note: this parameter is ignored in Squeezebox Server 7.6 and newer

All three parameters are optional, and should be appended to the filename, before the file extension, and separated with underscores.

Firstly, the requested size is passed as, e.g. 100x200. One of the dimensions can be omitted, e.g. 100xX, in which case the omitted dimension is chosen to maintain the aspect ratio of the image. If the size is ommited, it is taken to be the default thumbnail size if a thumb was requested, else it is the current size of the image.

In Squeezebox Server 7.6 and newer the following options that can be used:

  • m: max - default (this is being used when no option is selected), fit image into given space while keeping aspect ratio. If the target size is bigger than the original image, only the aspect ratio will be matched to the target aspect ratio. Empty space will be padded using transparent pixels and if padding is added the image returned will always be PNG, independent of the source image or selected output format.
  • p: pad - same as _m.
  • o: original - This is being used when any unknown parameter or a legacy parameter (see below) is being specified. Ignore height if given, resize only based on width. The resulting image will not be padded but transparent areas cropped to match the input images' aspect ratio.
  • F: Returns original if requested size is bigger, return downsized and padded to target aspect ratio if requested size is smaller than original image.

Effectively, in version 7.6 and newer of the server there are only two different output modes - pad the result to the target aspect ratio or crop transparent padding in the result to keep the original aspect ratio, F is a mixture of the two depending on the input image size.

Images will never be upscaled and background colors will not be used but added background padding will always be transparent.

The default output format is PNG.

The following are some examples, assuming a source image of 1000x1000.

  • /cover.jpg - returns the original image as JPEG;
  • /cover_1500x1500.png - returns the original image (unscaled) as PNG;
  • /cover_300x400 - Returns the original image scaled down to 300x400 as PNG;
  • /cover_300xX.jpg - Returns the original image scaled down to 300x300 as JPEG;
  • /cover_300x400_m.jpg - Returns the original image scaled down to 300x300 and padded with transparent pixels to 300x400 so that the original occupies the center of the image; the image is returned as PNG!
  • /cover_400x200_o - Returns an image 400x400 (!), the height parameter is being ignored;

Legacy Resizing Modes

Server versions before 7.6 used a different set of resizing parameters

The exact interpretation of the size parameter varies, depending on the resize mode specified. There are six options that can be used:

  • s - Stretch
  • S - Squash
  • p - Pad
  • c - Crop
  • f - Fit stretch
  • F - Fit squash

Stretch will resize the source image, distorting the aspect ratio to return an image of the requested size. Squash behaves similarly, except that it will return the original sized image if both the requested height and width are bigger than those of the original. Squash is used by default, unless a size has been passed explicitly, in which case, stretch is used.

Pad will resize the source image to be as wide (or high) as the requested width (height), maintaining its aspect ratio. Bars will be added above and below (to the left and right of) the image, akin to letterboxing and pillarboxing.

Crop also maintains the aspect ratio, but fills the requested size, and crops the left and right (top and bottom) from the original image.

Fit stretch behaves very similarly to pad, except that bars are not added, instead the returned image is cropped to be of the same aspect ratio as the original. Fit squash is identical, except that it will not return an image larger than the original.

Finally, a background colour can be passed, in standard RGB hex format. This is used for the bars added when padding, and any PNGs with an alpha channel will also be blended with this colour.

The following are some examples, sssuming a source image of 200x200.

  • /cover_300x400.jpg - Returns the original image stretched to 300x400.
  • /cover_300xX.jpg - Returns the original image stretched to 300x300.
  • /cover_300x400_S.jpg - Returns the original image.
  • /cover_400x200_p_0000FF.jpg - Returns an image 400x200 with the original occupying the center 200x200, and padded with blue.
  • /cover_400x200_c.jpg - Returns an image 400x200 showing the center 200x100 of the original.
  • /cover_300x400_f.jpg - Returns the original stretched to 300x300.

NOTE: At this time, the server resizing only supports JPG, PNG or GIF image formats