dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > AlbumArt (r15)

Album art display on the WPS

This patch adds the ability to display picture representing the currently played track on the WPS. This picture can be the cover art of the album the song belongs to, or a picture specific to the track itself.

%W% This feature is still unofficial and not supported by the Rockbox team. It is planned to be included in SVN, but not until some issues are solved.

Discussion and patches are found here : FS#3045.

If you don't know what a patch is or how to apply one, you should have a look at the SimpleGuideToCompiling.




When the track's metadata is read, the path of the bitmap to be displayed is found and stored with the rest of the metadata. The bitmap is only loaded when it needs to be displayed and is stored in the WPS image buffer.
This approach has several flaws :
  • Increased disk activity : the bitmap is loaded at a time when the disk isn't normally spinning.
  • Only one bitmap is stored at a time : this is a problem when skipping to the previous or next track.
  • Less pictures can be used in the WPS (a possible workaround is to increase the WPS image buffer size but this is not a good solution).

In the future

The ideal approach would be to have the bitmaps stored in the playback buffer and loaded at the same time as the rest of the metadata. That way, there are no additional disk spin-ups and each track has it's own bitmap.
This method of implementation is dependent on MetadataOnBuffer, which is part of the big playback engine rework. More information can be found on the SoftwareCodecPlayback page.


BMP only

JPEG/PNG album art is not supported. This is because the WPS code can only display bitmap pictures. A possible solution would be to decode JPEG/PNG pictures to BMP when they are loaded. However, considering how small the file size difference between a bitmap and a JPEG/PNG for a 100x100 picture is in comparison to the disk space available, this appears like a waste of CPU time. It makes more sense to make the computer convert the pictures to bitmaps of the right size.

No embedded album art support

Currently Rockbox doesn't allow reading album art from the file's tags. Even if it did, the problem would then be that most of the time, such album art is JPEG or PNG and therefore not usable (see right above).

How to use

Picture format

As explained above, the cover art pictures have to be BMP files. The bit depth can be 1, 4, 8, 15/16, 24 or 32 bit per pixel.

Where to put the pictures

The pictures can be stored in the same directory (.) as the track or in the parent directory (..). There can be a track-specific, album-specific or generic picture.
The order of priority is the following :
  1. ./ filename .bmp - same filename as currently playing music file
  2. ./ albumtitle .bmp - name of the album, found in metadata of the music file
  3. ./ cover.bmp
  4. ../ albumtitle .bmp
  5. ../ cover.bmp

The WPS tags

There are two tags you need to have in your WPS in order to display album art bitmaps :

The %Cl tag

This tag has to be alone in a line. It is very similar to the %xl tags. It is used to indicate that the WPS has album art support and defines the coordinates, size and resizing behaviour of the picture.
Its exact definition is : %Cl|x|y|[l|c|r][d|i|s]maxwidth|[t|c|b][d|i|s]maxheight|
%W% The brackets are NOT to be included in the WPS. They only indicate optional items. The last "pipe" character ( | ) has to be present.

If maxwidth and maxheight are not given (the "|" still have to be present), the picture will just be displayed at the given (x,y) position with its original size.
If maxwidth and maxheight are given, the picture will be displayed in a rectangle starting at (x,y) with a width of maxwidth and a height of maxheight. In that case, you can control the positioning by adding the following flags to the maxwidth and maxheight parameters :
  • maxwidth :
    • l : align left
    • c : align center (default)
    • r : align right
  • maxheight :
    • t : align top
    • c : align center (default)
    • b : align bottom
Additionally you can add flags to maxwidth / maxheight to control whether bigger or smaller bitmaps will automatically be resized to fit inside the maxwidth / maxheight rectangle :
  • d : decrease size - downscale the picture if it is bigger than the rectangle
  • i : increase size - upscale the picture if it is smaller than the rectangle
  • s : combination of d & i - scale the picture if it is smaller or larger than the rectangle
TIP The aspect ratio of the original bitmap is always preserved.


  • %Cl|50|70||| : displays the album art at position x=50, y=70. No maxwidth or maxheight are given, so no resizing is done.
  • %Cl|50|70|sc100|sb100| : displays the found bitmap at position x=50, y=70. Smaller and larger bitmaps are resized to fit in a 100x100 rectangle and are centered horizontally at the bottom of this rectangle.

The %C tag

This tag can be placed anywhere in the WPS file, including within a conditional tag. It displays the picture.


  • %C : just displays the album cover.
  • %?mh<%C|> : only displays an album cover if the main device's hold switch is on.

The conditional tags

The %?C and %?Cn indicate whether bitmap files have been found for the current and next tracks. They work exactly like usual conditional tags : %?C<true|false> and %?Cn<true|false>.


Here are a few possible things that could cause a WPS not to display album art pictures (in no particular order) :
  • The syntax of the %Cl% tag is wrong. To see if that's the problem you can try something simple : %Cl|x|y|||.
  • The WPS image buffer is so full there is no space left for the album art bitmap. Try using a WPS without pictures to make sure.
  • The file names are wrong. Try using a "cover.bmp" file to see if it that's the problem.
  • The pictures are too big to be displayed on the WPS. Check the %Cl% tag in the WPS in comparison with the dimensions of your bitmaps.

Useful tools

Cover art downloading

Format conversion

  • FastStone Photo Resizer (for Windows)
  • iRiver H3XX Album Art Manager (for Windows). Note that despite the name, there is nothing iRiver specific about it. It looks for jpegs, resizes, converts and renames (either cover.bmp or .bmp if enough files in the folder can be ID3-identified to belong to the same album) them, leaving the copy in the same folder as the original. It works perfectly as long as your image files have some easy to recognise name, such as folder.jpg.
  • RockBox WPS cover creator script for Amarok
  • Here is a small bash script inspired by "macgabhs" (original here on MisticRiver) that should do the job (uses ImageMagick). Run it from your music directory on your DAP.
    find -iname "cover.jpg" -o -iname "cover.gif" -o -iname "cover.png" | while read file
        do convert "$file" -thumbnail 130x130 "${file%/*}"/cover.bmp
    To convert all the pictures and not only "cover.*" files, use this instead :
    find -iname "*.jpg" -o -iname "*.gif" -o -iname "*.png" | while read file
        do convert "$file" -thumbnail 130x130 "${file%.*}".bmp

Using embedded iTunes cover art on an iPod

For Windows users

This procedure was posted by ryan2632 on the forums (original topic here). I haven't tested it so I can't guarantee it will work as expected.

  • Extracting and resizing the art
    1. download MediaMonkey
    2. grab the Album Art Tagger Script from here. (about 1/3 way down the page)
    3. install both, and launch the app
    4. click on your iPod in the left pane, and let the song list load. select all (or whichever you want) and go to Tools -> Scripts -> Album Art Tagger
    5. select option 4 "Extract artwork and resize external image"
    6. in the text box below type in "D:\art\" replace 'D:\art\' with wherever you want it to extract the images. make sure you have created the folder first.
    7. click go and let it do it's work. after it scans, it will popup a confirmation dialogue. press OK, and it will pull all the art and resize it into that folder.

  • Converting from JPEG to BMP
    1. download Faststone Photo Resizer from here and install
    2. under the 'Conversion' tab, Navigate to the folder with your extracted JPG's and press Add All
    3. Set the output format to BMP and click Options. Make sure it is still at 24 bit
    4. Choose your output folder
    5. Press Start and sit back.

  • Finishing up
    1. Move all the BMP's into IPODDRIVE:\iPod_Control\Music
    2. Make sure you are running the latest version of the Album Art + BMP Resize Patch
r15 - 03 Jul 2007 - 10:47:16 - NicolasPennequin

Copyright by the contributing authors.