= Manual = == Installation == If you don't want to download and install the source code, simply get the latest executable for your platform from the [wiki:Download download page] and run it. No installation needed. === From Source === You need these dependencies to run underCover: * [http://www.python.org/download/releases/2.5.4/ Python] * [http://www.riverbankcomputing.co.uk/software/pyqt/intro PyQt4] * [http://www.sqlobject.org/download.html SQLObject] * [http://www.pythonware.com/products/pil/ PIL] ([http://passingcuriosity.com/2009/installing-pil-on-mac-os-x-leopard/ instructions for OSX]) * [http://pypi.python.org/pypi/winpaths winpaths] (only on Windows) After you have installed the dependencies, get the [http://undercover.piquadrat.ch/hg/underCover/archive/underCover-latest.zip 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 [[Image(http://undercover.piquadrat.ch/raw-attachment/wiki/_attachments/proxy_osx.png)]] == 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 [http://aws.amazon.com Amazon Web Services] to query for covers from the Amazon Store. To use this fetcher, you have to [https://aws-portal.amazon.com/gp/aws/developer/registration/index.html 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 [http://www.last.fm/api/ 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 [http://www.falsecognate.org/2007/01/deciphering_the_itunes_itc_fil/ 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.