Album Art Display on the WPS

Introduction

This feature allows for the display of an image representing the currently playing track on the While Playing Screen. This picture can be the cover art of the album the song belongs to, or a picture specific to the track itself, depending on how you name the file. Read on for more details.

Limitations

BMP Only

JPEG album art is currently not supported. Supporting JPEG requires adding a JPEG decoder to the Rockbox core. This is wanted, but won't be done until someone actually decides to. The decoder already exists as a plugin. PNG support seems more unlikely as there currently is no PNG decoder in Rockox, not even as a plugin.

No Embedded Album Art Support

Currently Rockbox doesn't allow reading album art from the file's tags. In fact, it's presence has been known to cause freezes and other problems so it's advised that it be removed from your files. But even if it could read embedded album art the problem would then be that most of the time such album art is JPEG or PNG and therefore not usable (see above).

No Resizing

Resizing isn't implemented yet. It is planned, but no time estimate is available. However, it is possible to have the bitmaps in different sizes to allow themes to use the best one (see below).

How To Use Album Art

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 Images

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. /.rockbox/albumart/ artist-albumtitle .bmp
5. ../ albumtitle .bmp
6. ../cover.bmp

You can also specify the size in each filename. e.g. cover.100x100.bmp will be used for themes that display a 100x100 album art picture. Size-specific pictures will be looked for before looking for the files listed above.

The following characters will be replaced with an underscore (_) when looking for albumtitle.bmp or artist-albumtitle.bmp: \ / : < > ? * |. Double quotes will be replaced by singlequotes.

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]maxwidth|[t|c|b]maxheight|

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

Bitmaps that are too big will be cropped to fit in maxwidth and maxheight.

Examples

• %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|c100|b100| : displays the found bitmap at position x=50, y=70. Smaller bitmaps are centered horizontally at the bottom of this rectangle. Bigger bitmaps are cropped to 100x100.

The %C tag

This tag displays the picture. It can be placed anywhere in the WPS file, including within a conditional tag. It is recommended to place it in the last line of your WPS so that the album art bitmap gets drawn last when the WPS is refreshed. Otherwise you might see some lines overlapping the bitmap.

Examples

• %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>.

Troubleshooting

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 file names are wrong. Try using a "cover.bmp" file to see if it that's the problem.
• Your bitmaps are invalid or too big. You can't use bitmaps that are bigger than your player's screen size.

If lines are being drawn over your album art picture, there are two things you should check:

• Put the %C tag on the last line of your WPS. That way it will be drawn last, over the lines that were covering it previously.
• To place text on the right of the album art picture, using a margin is recommended over spaces. Otherwise, lines might appear over the album art picture.

Useful tools

Cover Art Downloading

• Album Art Downloader (for Windows)
• Album Art Aggregator (for Windows)
• Amarok can do it too
• RockAA (Java) This tool can save Cover art in .bmp in many different ways:
  • For a folder (cover.bmp)
  • Single file (Artist - Track Name.bmp)
  • Multiple files (each cover gets named according to the files you selected)
• Album Art 4 MP3 (for Windows) This tool not only downloads cover art, but also resizes cover art to user defined dimensions (using image resampling) and saves images in bmp, jpg and png formats. The ability to resize images is particularly useful since Rockbox can't yet resize images but simply crops images larger than maxwidth and maxheight dimensions specified by the WPS %Cl tag.

Format Conversion

• FastStone Photo Resizer (for Windows)
• IrfanView -- freeware: supports batch conversion (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.

  #!/bin/sh
  find -iname "cover.jpg" -o -iname "cover.gif" -o -iname "cover.png" | while read file
      do convert "$file" -thumbnail 130x130 "${file%/*}"/cover.bmp
  done
  

  To convert all the pictures and not only "cover.*" files, use this instead :

  #!/bin/sh
  find -iname "*.jpg" -o -iname "*.gif" -o -iname "*.png" | while read file
      do convert "$file" -thumbnail 130x130 "${file%.*}".bmp
  done
  

• Rockbox art converter script (for Windows Scripting Host) Install leadcommandlineutils.exe from the archive, extract content of progbar.zip to x:\Windows\System and run progbar.reg. If you want to use the outputname option you need to overwrite the rockboxartsupdate.vbs with the updated version that is uploaded in a more recent post of the linked thread.
  
  Accepted parameters:
  

  /artname: (default: folder.jpg) /size: (default: 150) /outputname: (default: cover.bmp) /source:"x:" (default: ask)
  

  Example commandline:

  RockboxArtsUpdate.vbs /artname:cover.jpg /size:140 /outputname:cover.140x140 /source:"F:\Music\"
  

How to Use 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.

NOTE: This method does NOT work for files in AAC format if you use MediaMonkey 2.x

NOTE: This method does NOT work if your music directory structure is more than two folders deep. It was written assuming you were using the iTunes database directory structure.

• 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\<album>

     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.

• Generating Album Art of different sizes
  1. Instead of putting in

     D:\art\<album>

     you can put in

     D:\art\<album>.100x100

  2. Change the album art size in the same window to the album art size you inputed in the step above. This will generate out album art images with a name such as "cover.100x100.bmp".
  3. You can do this multiple times and generate out different sizes this way for pictureflow and different WPS'.

• 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 to IPODDRIVE:\iPod_Control\Music. Or up to one folder down. See above. Pay attention to the limited number of places you can put the cover art.