Manual
Installation
If you don't want to download and install the source code, simply get the latest executable for your platform from the download page and run it. No installation needed.
From Source
You need these dependencies to run underCover:
After you have installed the dependencies, get the latest snapshot, unzip it and run underCover.py in the 'src' folder.
Setup
During interaction with iTunes, the underCover proxy server has to run and iTunes has to use this proxy to connect to the Internet.
Please note: not only iTunes uses the underCover proxy after you change the proxy settings, but all applications that respect these settings. This means that all traffic will get routed through the underCover proxy. While this is no problem for web surfing, more demanding applications like filesharing or video streaming could have performance issues or could crash underCover. It is best to only change the proxy settings when you want to use underCover to intercept iTunes' artwork queries and reset them afterwards.
Windows
On Windows, underCover can set the systemwide proxy for you. Open underCover, navigate to the "Tools" menu, click on "Configure Windows Proxy" and then on "Activate Proxy". This will adjust the proxy settings in the Windows registry. The default settings are restored automatically when closing underCover.
If you don't like underCover mucking around in your registry, you can adjust the settings yourself:
- Go to the Control Panel
- open 'Internet Options'
- move to the 'Connections' Tab
- click on 'LAN Settings'
- in the 'Proxy server' section, check 'Use a proxy server..."
- if there are already values in the Address and Port fields, write them down so you can reset your settings after underCover has done its job
- put 127.0.0.1 in the Address field and 9988 in the Port field
- press OK
MAC OS X
- Go to System Preferences
- click on "Network"
- click on "Advanced..."
- open the "Proxies" tab
- check "Web Proxy (HTTP)" and fill in the values "127.0.0.1" and "9988", respectively
- click on "OK" and "Apply"
- Don't forget to reset the proxy settings after you're finished with underCover
Usage
Gathering Data from iTunes
After the first start of underCover, you have to feed it with queries from iTunes. Click on 'Start Proxy'. Then switch to iTunes and select all albums. Right-click on one of them and chose "Get Album Artwork". Switch back to underCover and you should see queries from iTunes trickling in. Wait until iTunes has finished querying for artwork.
If no queries show up, you may need to restart iTunes. Because iTunes is one of those applications that do not really quit when they are told to, you have either to kill the iTunesHelper.exe process, or if you don't know how, restart your computer. It helps sometimes to stop and restart the underCover proxy server.
If you can't select 'Download CD covers' in iTunes, you need to setup an iTunes Store account first. Unfortunately, iTunes will only search for artwork if you have a Store account.
Searching for Artwork
After underCover knows what music you have in your iTunes library, you can start searching for artwork. First, open the underCover settings and navigate to the 'Fetchers' tab. At the moment, there are three fetchers available
- Google Images: this fetcher simply queries images.google.com and downloads the first couple of results. Usually, the results are quite good, but sometimes you will get back strange stuff from Google. It's advised to use 'Safe Search'.
- Amazon: the Amazon fetcher uses the Amazon Web Services to query for covers from the Amazon Store. To use this fetcher, you have to register at Amazon and get an API key (it's free). The reward for this work are mostly very goot artwork results
- last.fm: this fetcher uses the last.fm API. It doesn't require any setup.
After you've set up the fetchers, you can start downloading artwork. You can either download artwork for a single album, or start a 'Batch Download'. A batch download searches for artwork for all your albums that don't have a best match yet. You can cancel the batch download at any time without losing the artwork it already downloaded.
Now it's time to choose which artwork underCover should serve to iTunes. For every album, look at what underCover found and choose the one that you like best (the 'best match'), then click on 'Serve to iTunes'. Next time iTunes asks for this album, underCover will serve it the artwork you chose.
You can press 'Filter' to only show albums that have no best match yet.
To speed up this process, you can use a couple of keyboard shortcuts. Use Page-Up/Page-Down to navigate the queries tree, and the arrow keys to select artwork. Hit the "Enter" key to set the currently selected image as the best match for the current query.
Serving Artwork Back to iTunes
If you reset your proxy settings during artwork search, set them back to 127.0.0.1:9988 and start the underCover proxy. Go to iTunes and tell it to download artwork for all albums again. And presto, all the artwork you've picked out before in underCover will now appear in iTunes.
Unlocking iTunes artwork
The iTunes Store sends the artwork to iTunes in an encrypted envelope. But iTunes stores the artwork unencrypted (in the itc2 format), and it's always 472 bytes bigger than the encrypted artwork. So all one has to do is to search for files with the 472-bytes difference in size, cut the JPEG file out of the matching itc2 file and replace the encrypted artwork with it. underCover does this automatically for you, but you have to tell it where your iTunes library is. On Windows, it's usually in "My Documents\My Music\iTunes".
Of course, this unlocking business will break as soon as Apple changes something in how they deliver the encrypted artwork. I do not intend to break the encryption scheme that Apple uses for the artwork. But as long as iTunes stores the artwork unencrypted and as long as a simple size comparison can associate the encrypted artwork with the unencrypted, we might just as well let a computer do the work.
