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/JPEG Only

As of r20837 - 2009-05-01 Rockbox includes support for JPEG album art. This notice is left here to inform people running an outdated build of this change.

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 PNG decoding in Rockbox is only possible via 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.

File encoding restrictions

Rockbox does not support RLE-compressed BMP files, as these can not be decoded in a way that is compatible with its scaler. The same applies for progressive and mult-scan JPEG files. JPEG files must consist of a single scan with interleaved components, as progressive and multi-scan images require much more memory to decode.

Resizing (Rockbox now supports resizing)

As of r19374 - 2008-12-10 Rockbox will resize albumart if one for the specific size isn't available. This notice is left here to inform people running an outdated build of this change.

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 or JPEG files. The bit depth can be 1, 4, 8, 15/16, 24 or 32 bit per pixel. Progressive scan or multi-scan JPEG files are NOT supported, if in doubt, try opening the cover art JPEG file using the viewer plugin.

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. ext below may be bmp, jpeg, or jpg.

The order of priority is the following:

1. ./ filename . ext - same filename as currently playing music file
2. ./ albumtitle . ext - name of the album, found in metadata of the music file
3. ./cover. ext
4. ./folder.jpg
5. /.rockbox/albumart/ artist-albumtitle . ext
6. ../ albumtitle . ext
7. ../cover. ext

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|

%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

Bitmaps that are not the right size will be resized to fit in maxwidth and maxheight while maintaining aspect ratio.

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. The tag is linked to the viewport it is under, and is the last thing drawn in that viewport. It can be placed anywhere in the wps but must be after the %Cl line, and in the viewport you want it displayed in. (it can of course be inside conditionals also)

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 and %?Cn.

---

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.

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 viewport is recommended over spaces. Otherwise, lines might appear over the album art picture.

---

Useful tools

Embedded Cover Art

• Album Art Extracter for RockBox (for Windows and Linux with Mono) This application can extract and convert massively the album art embedded in music files, and create the necessary files in BMP or JPG format to display album art correctly in RockBox. It supports the creation on all locations and filename conventions which Rockbox looks for Album Art. Also can scale images to size desired.

• Artwork Extraction Perl Script A small perl script to retrieve album art images from the APIC frame of ID3v2 MP3 tags. It places the album art image file in the MP3 folder with the name of your choosing. It requires the MP3::Tag, File::Find, Image::Magick Perl modules. (Automatically scales images to 175x175 (retaining image ratio), though that can be changed by editing or removing the line that scales them.)

• EasyTAG EasyTAG is a utility for viewing and editing tags for MP3, MP2, MP4/AAC, FLAC, Ogg Vorbis, MusePack, Monkey's Audio and WavPack files. Its simple and nice GTK+ interface makes tagging easier under GNU/Linux or Windows. (Embedded images can be saved to the hard drive to be edited with other applications.)

Cover Art Downloading

• Rockbox Album Art Downloader (for Windows) Quick, easy to use, and many options. Saves in .JPG.
• Album Art Downloader (for Windows)
• Album Art Aggregator (for Windows) The link seems broken, but the soft is avaliable on a mirror site -- ClementPitClaudel - 01 Sep 2008
• Amarok can do it too
• Album Cover Art Downloader (Python/Qt) works on Linux and Windows.
• 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.
• RB Tools intends to allow easy cover art manipulation for rockbox. It can download, resize and convert album art files, using Amazon Cover Search And Yahoo Image Search for missing covers. Updated on Jan. 28, 2009.
• Create CoverSearch is a sourceforge project for downloading cover files.

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\"
  

• RB Tools also has a GUI to convert cover files automatically to bitmap format (Windows only). It's also able to resize and copy pictures to your player.

---

How to Use Embedded iTunes Cover Art On An iPod

For Windows Users

iPod Album Art Extractor

This application can extract the album art embedded in the music files in a iPod, and create the necessary files in BMP format to display album art correctly in RockBox. The entire process in fully automated. You just need to make sure your files are properly tagged.

For more information and downloading this app, visit the author's website.

Media Monkey procedure

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.

For Mac OS X Users (with iTunes)

In order to extract id3 album art to the album folder

1. Download and install Doug's Scripts for iTunes - Save Album Art to Album Folder - from here http://dougscripts.com/it...ts/ss.php?sp=savealbumart

2. Highlight the albums or tracks you would like to extract from. You can chose to extract from track art to album folder or album art to album folder. Choose album art, especially for larger libraries.

Voila!

If art is extracted into a form which Rockbox cannot read, you can create an automator workflow to search for .png, etc within your music folders and convert them to .jpeg or .bmp.

To create the workflow, open Automator, choose Custom.

1. Drag "Find Finder Items" into the workflow.
2. Choose the folder where you store your music in the Find Finder dialogue.
3. Choose "Extension" "is equal to" "png" or other undesirable image extensions.
4. Drag "Change Type of Images" into the workflow.
5. Choose To Type: "JPEG" or "BMP" whichever you prefer.
6. Save the file and run it.

When you create the workflow, you are able to choose whether you would like to save the original image file, I chose "no" for this, you can choose to save it if you would like. The program will automatically add this step if you decide to do this.

---