Clutter
Copyright ©2003, Sprote Rsrch.
http://www.sprote.com/clutter/
clutter@sprote.com
¨
Version 1.0d13 — PRERELEASE — 18 May 2003

Introduction

I used to play a lot of CDs at work. A clutter of newly-acquired discs, and older ones that had come back into heavy rotation, lay on my desk. When deciding what to listen to next, I'd run my eyes across them and something would catch my attention.

Now I use iTunes. I've ripped most of my CD collection to MP3, and I get new music in MP3 format from sites like eMusic and Epitonic. All of this music is a couple of clicks away — no more fumbling with jewel boxes. Great!

Well, except that I find, when all my music lives in a single huge alphabetized list in the iTunes window, that the things I've just acquired disappear into it and I don't notice them as much. That great Loop Guru CD I downloaded from eMusic two months ago? I'd forgotten I had it! It's down under "L" between Loop and Louis Andriessen, whom I don't listen to often.

I wanted that clutter back. It may have looked messy and disorganized, but it was really a very efficient visual cache of stuff I was likely to be looking & reaching for, and a reminder of what was new. And the cover designs are pretty!

So I wrote Clutter...

OK, Cut To The Chase. What Is This Thing?

Clutter is a small Mac OS X application that lets you put music CDs on your desktop. You can drag them anywhere — they're really windows. Line them up neatly or put them in piles, it's your choice. Each one looks like the real CD's cover, and double-clicking it tells iTunes to play that CD.

Creating these windows is easy. There is a Now Playing window that shows what's currently playing in iTunes. It automatically looks up the cover picture on Amazon.com and displays it. If Amazon doesn't have a picture, you can find it elsewhere and drag it in from your browser. Or you can scan it yourself and paste it in. Then  you can drag the picture out of the window onto your desktop and it turns into a CD window.

But there's more! This is the age of digital convergence, after all.
• If the CD was located on Amazon.com, you can jump to the Amazon web page for that CD. This is useful if you'd ... forgotten ... to buy the CD and are overcome with guilt.
• Or you can do an instant Google search of the artist/album, if you want to find other interesting stuff about it.

Requirements & Installation

You'll need Mac OS X 10.2 "Jaguar" or later. You'll also need an Internet connection for Clutter's automatic CD lookup features to work. (If you're not online, you can still paste in cover pictures manually.)

To install, put the Clutter application icon anywhere on your hard disk. You may want to put it in the main Applications folder, though that's not essential.

Double-click it to launch it (duh). If you want it to start up automatically whenever you log into the computer, open System Preferences, select Login Items, and drag Clutter into the list.

NOTE: If you live in the UK, you'll probably first want to open up the Preferences panel and select Amazon.co.uk as your search site instead of the default (US) Amazon.com.

Adding To The Clutter

Launch iTunes and play something, anything other than a stream (those aren't supported yet.) After a few seconds, Clutter's "Now Playing" window will display the track name and the artist and album. (A little spinning progress indicator appears at the top of the window while it's earching.)

If Amazon has a cover picture, that will be shown. If Amazon has more than one match, up-and-down arrows will appear to the right of the picture; you can click them to cycle through the matches. (Amazon searches are done by keyword and may not be exact. Moreover, iTunes and Amazon may not agree on the exact name, which can cause confusion.)

If Amazon doesn't have a picture, an image of a blank CD will be displayed. There are two things you can do. First, you can choose "Find Cover On Amazon..." (Cmd-F) and, in the search window, change the artist/album names in the text fields to fine-tune the search. (Sometimes it helps to remove the album name, entirely or except for one or two key words.) Pressing Lookup will do the search. After that you can look at the matches by selecting them from the pop-up menu. If you find a match, drag the picture into the picture area of the Now Playing window to update it. Clutter will remember the new picture from now on.

If Amazon didn't work out at all, you can congratulate yourself on your non-mainstream musical tastes and look for the cover picture elsewhere. (Cmd-G will open a Google search, to get you started.) If you find it on the Web, just drag the picture from your browser into the picture area of the Now Playing window. As a last resort, you can always put the CD into your scanner, scan it and copy the image to the clipboard, activate the Now Playing window, and Paste.

Now, there's no reason you have to choose a picture. If you don't care, you can just leave it as the default "blank CD" image.

NOTE: Compilation or various-artists albums can be a bit tricky. If you've set a separate artist for each track instead of using a single name like "Various Artists", then make sure the "Part of a compilation" checkbox is set in the iTunes info window for that album. Otherwise Clutter won't be able to tell that the tracks are part of the same album.

NOTE: Currently Clutter doesn't search Amazon's classical-music database, only "pop music" (everything else). That needs to be fixed.

Managing CD Windows

Once the cover is the way you like it, just drag the picture out of the Now Playing window onto any other location on the screen, and it will stick there as a window. From now on, to play that CD, just double-click the window, or click it and choose the Play command (Cmd-P). Or to play a specific track, control-click the CD and select the track from the contextual menu that appears. (For those with two-button mice, right-click works too, of course.)

A CD window may not have title bars, but it behaves mostly like a normal window. You can click to bring it to the front, drag to move it around. The "Bring All To Front" command in the Windows menu will being all Clutter windows to the front, as will clicking Clutter's Dock icon. You can also select any CD by name from the Windows menu in case you went overboard on the "clutter" theme and managed to lose it underneath other CDs.

To get rid of a CD window, choose the Close command (Cmd-W).

CD windows are a little unusual in that they support multiple selection. Note after clicking on a window that it shows a green border. This means it's selected. You can select multiple windows by shift- or command-clicking them, or use the Select All (Cmd-A) command.

Dragging a CD actually moves all selected CDs. The Delete key will delete all selected CDs at once.

You can use the commands in the View menu to make CD windows larger or smaller, or hide their drop-shadows. These commands apply to all selected CDs.

What else? Turning on "Snap To Grid" from the View menu will help you precision-align CDs if you're a neat-freak. You can copy the CD's picture using the Copy command, or paste in a new picture from any other app using the Paste command. You can choose "Buy From Amazon" to open the Amazon.com page for the CD in your browser, or "Search Google" to run a Google search on the artist and album name. (The Amazon command only works if Clutter was originally able to find the CD on Amazon and knows its Amazon ID number (ASIN)).

Troubleshooting and Other Questions

"In iTunes, I started playing a CD / stopped playing a CD / switched tracks, but Clutter's Now Playing window took a while to update."
iTunes unfortunately doesn't notify other apps when it starts/stops playing a track, so Clutter has to keep asking it. In general, Clutter only asks once every ten seconds, to avoid making a pest of itself. So you might have to wait up to ten seconds for the window to update after you do something in iTunes.

"Clutter stopped responding to my commands for a while."
Was there a spinning thingumbob at the top of the Now Playing window? If so, Clutter was talking to iTunes or to Amazon.com. Sometimes iTunes doesn't respond very quickly (especially while it's ripping a CD), and sometimes Amazon is slow, or your Internet connection might be having problems.

"Clutter stopped responding to my commands forever. It's hung."
Oops! Sounds like a bad bug. Let us know (clutter@sprote.com) as much as possible about what was going on, especially whether the thingumbob is spinning in the Now Playing window. If you're Terminal-savvy, running "sample Clutter 2" and enclosing a copy of the file written to /tmp would be a huge help.

"Clutter crashed."
Double-oops! As above, let us know. If you have crash logging enabled, please enclose a copy of the most recent backtrace from the crash log. (If not, you can enable crash logging via the Console app's preferences.)

"I tried to play a CD but Clutter hung for a while and then said there was an error running its script."
In the reports we've gotten of this, it's an AppleScript time-out, and this seems to be correlated with very large iTunes libraries. The commands Clutter uses to build its playlist seem to be handled very slowly by iTunes in this situation. In 1.0d7 we've increased the script time-out to give poor iTunes more time to work, which should help alleviate this.

"Clutter made an iTunes playlist called "(Clutter)". I don't want it doing that."
It turns out that, due to limitations of iTunes's AppleScript support, the only way to reliably get it to play the entire album in the correct order is to put the tracks into a playlist, then play the playlist. This was a last resort, but it works pretty well. (Any scripting gods out there who know a better way can write to clutter@sprote.com with suggestions!)
You can delete the playlist if you want, but Clutter will recreate it the next time you tell it to play a CD.

"The Now Playing window doesn't show a picture of a particular CD, or it shows a picture of the wrong CD."
This means the Amazon search didn't turn up the correct results. There are a number of reasons this can happen.
• Amazon doesn't carry that CD.
• Amazon carries the CD but has no picture of it (this happens).
• Amazon misspelled the name of the artist or of the CD.
• Your MP3s have misspelled artist/album names (in their ID3 tags). Make sure the name that shows up in the Now Playing window and iTunes is correct.
• There may be other CDs, even by other artists, that have keywords so similar to those of the current CD that the Amazon search threw them in as a surprise gift. There's nothing you can do about this, but that's why we gave you the little arrows so you can select the right CD, and the Google command so you can do your own web search for the cover.
If you're really sure it's Clutter's mistake, try going to www.amazon.com and typing the name of the artist and album into a Popular Music search, and see if the results differ. If so, let us know the exact name of the artist and album.

"I don't use iTunes. Will Clutter work with other MP3 players?"
Not currently, but I'd like to add support for one or two other popular players like Audion. Unfortunately, scripting MP3 players is not standardized, so this would require custom AppleScripts, if it can be done at all. If you want to try, look inside Clutter's package for AppleScript (.scpt) files, and examine them and try to make scripts that do the same thing with your favorite player. If you can send us such scripts, we'll try to integrate them into a future release (giving you full credit).

"Can't Clutter automatically look up cover pictures for all the CDs in my iTunes library?"
It could, but frankly, we're afraid of pissing off Amazon if lots of people start using this feature and hammering on their servers.

"Why just Amazon? Clutter should be able to get CD covers from _______ too."
Amazon is the only site we've found that (a) has a lot of CD covers, (b) offers a way to search for and retrieve them, and (c) allows developers to use this feature. People have suggested allmusic.com, but their privacy policy forbids (c). If you know of another site that would work, please email us and we'll consider adding it (especially if you send us some Cocoa code that does the search!)
Remember, you can always do your own CD cover search at your favorite website and drag/paste the picture into Clutter's "Now Playing" window.

"I want Clutter to use my country's Amazon site (like amazon.de) instead of amazon.com."
Amazon is adding XML search capabilities to their country sites one at a time. Right now (April 2003) the only other site that supports this is Amazon.co.uk — you can use the pop-up in the Preferences panel to select it. As other countries come on board, we'll add them too.

"I want to copy all my Clutter info to another computer. What files do I need to copy?"
The database (such as it is) of cover picturess and Amazon ASINs is located in the folder "Library/Images/com.sprote.clutter" in your home directory. 
The list of windows currently on their desktop (and their locations) is stored in the file "Library/Preferences/com.sprote.clutter Windows.plist" in your home directory.
You can copy either or both of these to the same location in your home directory on another machine.

"I want to get rid of all the data Clutter copied to my disk."
Same as above, but for "copy" read "delete".

"Clutter gets slow with a whole lot of CDs open."
Every CD is a window, and the Mac OS X window server doesn't perform well with huge numbers of open windows. Don't use Clutter to leave hundreds of CDs lying around — that's what the convenient alphabetical lists in iTunes are for :-)

Release Notes

1.0d13:
• A CD's cover art can be copied to iTunes 4 (look in the File menu).
• More fixes for HTTP proxy support ... maybe now it'll really work.
• Clutter recognizes when iTunes is playing an Internet radio station or a playlist, and you can assign custom artwork to these (drag/paste to the Now Playing window) and drag them to the desktop. (There is a pref to disable this for playlists, if you don't want it.)
• Now-Playing window zooms correctly (scales artwork to 100%).
• Now-Playing artwork draws at full size and with high-quality scaling.
• Info window improvements (OK/Cancel buttons, Close command works, can't open more than one on the same CD).
• Improved About box, with easy access to website and email.

1.0d12:
• Cover art will be retrieved from iTunes 4 if it's not known.
• You can drag CD cover images into iTunes or other apps by holding down the Option key at the time of the mouse-down.
• Clutter should work correctly again with HTTP proxies.
• The Play/Back/Forward buttons are now always shown whenever iTunes is running, even if the current track can't be determined (i.e. when playing someone else's shared music.)
• If iTunes doesn't respond when Clutter checks what's playing, it assumes the same track is still playing.
• Improved iTunes error reporting.

1.0d11:
• Resizable now-playing window
• Contextual menu on CD, with list of tracks
• Preference: Search amazon.co.uk
• Preference: Show cover in Dock icon

1.0d10:
• Snap To Grid!
• Dragging moves all selected CDs.
• Shift key constrains drag to horizontal or vertical.
• Resizing a CD makes that the default size for new CDs.
• Shows album name in blank CD window.
• New "Control" menu for iTunes controls and opening iTunes.
• Doesn't connect to Amazon if no net connection
• Amazon lookup now ignores capitalized "(Disc 1)" too (oops!)

1.0d9:
• Better handling of compilations where Artist field is different per track (provided that the "part of a compilation" flag is set in iTunes.)
• Can now play albums from iPod.
• CDs dragged out from Cmd-F window now properly get their pictures saved in the db.
• Amazon lookup handles "&" char properly, and ignores "(disc 1)" etc.
• Info window is resizeable.
• Arrow keys for back/fwd tracks in Now Playing window.
• Progress indicator in Find window displays correctly again.
• Cut/Copy/Delete enabled on image views.

1.0d8:
• Version 1.0d7 was crashing on launch for a few users; this appears to be a Cocoa bug, but we worked around it [by changing back to the old .nib format.]
• The play/back/fwd buttons now don't bring the window to the front when pressed.
• The play/back/fwd buttons are now shown when iTunes is playing a track with no artist/album information [no ID3 tags].
• The spinning progress indicator is now shown in the Now Playing window while Clutter is launching iTunes or telling it to play a CD.

1.0d7:
• New play/pause/back/forward controls at the bottom of the Now Playing window. (The spacebar has the same effect as the play/pause button.)
• Increased the time-out of the AppleScript Clutter uses to tell iTunes to play a CD. This should help make Clutter work better with very large iTunes libraries.
• The Find window no longer gets confused if there are two search results with exactly the same title. (It would lose some of the results, and forget to turn off the spinning-arrows indicator.)
• You can localize the Amazon site that the Buy Now command sends you to, by setting the AmazonSite default, by entering something like the following in the Terminal:
	defaults write com.sprote.clutter AmazonSite amazon.de
This does not affect the site used for CD cover lookups; unfortunately only amazon.com itself has the ability to do these.