Multiple Library Confusion

The Basics

When iTunes is first installed, it creates several support files and folders in your [username]/Music/iTunes/ folder:

• a database file, named "iTunes Library"—or "iTunes Library.itl" as of iTunes version 10.4. This is where iTunes stores all the information about your tracks and playlists. (iTunes is, afterall, pretty much a database manager with a music/video player nailed on.)
• an XML file, named "iTunes Music Library.xml". (Note: this may be renamed to "iTunes Library.xml" in later versions of iTunes.) This file is periodically updated by iTunes and contains meta-data information about tracks and playlists and stuff, but, despite a common myth, iTunes does not use it. It is there primarily so other applications can access information about iTunes (GarageBand, iPhoto, apps using the Media Browser, and so on).

Also created is an "iTunes Media" folder—named "iTunes Music" for versions of iTunes prior to 9.0. This is the default location for files when they are imported to iTunes from CD or converted from existing tracks and—if "Copy files to iTunes Music folder when adding to library" is checked in iTunes' Preferences > Advanced—when files are otherwise added to iTunes. The "iTunes Media" folder can actually be re-located anywhere and renamed via Preferences > Advanced (although one would still refer to it metonymically as the "iTunes Media" folder, even if it was named "Supa Monsta Killa Musica Extravaganza").

Of course, there is an Album Artwork folder, and perhaps an iPod Games folder, and iTunes 8 added the iTunes Library Genius.itdb and iTunes Library Extras.itdb files.

Multiple Libraries

When iTunes introduced multiple library management—with iTunes 7 in September 2006—it enabled users to create separate database libraries that didn't have to be in your [username]/Music/iTunes/ folder. Essentially, when this feature is invoked (by holding down the Option key when launching iTunes) iTunes can create or open another library—that is, another set of the support files and folders I listed above—in a different location. With two exceptions: the XML file created is named "iTunes Library.xml" which differentiates it from the original default "iTunes Music Library.xml" and your "iTunes Media" folder remains where it is, although a new empty "iTunes Media" folder is created in the location you selected.

Note: modern versions of iTunes (v10 and later) may name the default XML file in ~/Music/iTunes/ "iTunes Library.xml" in which case there is no name differentiation; the location serves as the differentiation.

Additionally, the file path of the most recently loaded iTunes multiple library's XML file is stored in a preference file. This file is [username]/Library/Preferences/com.apple.iApps.plist. This preference file may also contain pointers to your iPhoto library, and perhaps similar information for other applications. This file is made available so that other apps, if they need to, can locate the most recent database files for iTunes or iPhoto. And as with its XML file, iTunes doesn't refer to this file either. It is for the enlightenment of other applications.

The iApps.plist points to the location of my iTunes library's XML file

How Confusion Can Ensue

Some of my AppleScripts for iTunes use a routine which reads the iApps.plist in order to obtain the location of the current iTunes library's XML file in order to get information from it. I often get reports that these scripts don't seem to be working correctly; that the information seems to be wrong or doesn't correlate with track tags in iTunes. When the Correspondent and I investigate this phenomenon, very often it is because the iApps.plist contains the wrong location for the current iTunes library.

I must admit that I am not certain when the [username]/Library/Preferences/com.apple.iApps.plist file gets updated with the location of the current iTunes library. But that may be neither here nor there. What does appear to be consistent among most of these Correspondents is one or more of these factors:

• They use the multiple library feature, knowingly or otherwise
• Their "other" library is located on an external drive
• They use a notebook computer and/or the external drive is frequently unmounted and mounted

So, what appears to be happening is that the iApps.plist file is erroneously updated with the original default location of the XML file and not the location of the XML file for the multiple library they most recently used on the external drive. Or visa versa.

There can be other extenuating circumstances: Frequently reported is that users have forgotten that they ever used the multiple library feature not realising that the multiple library they established will continue to be their default library until they Option-start iTunes and select another. In other instances, an external drive containing the database files and/or the "iTunes Media" folder may not be mounted when iTunes is launched. This obliges iTunes to fall back on the default (and wrong) files in the [username]/Music/iTunes/ folder. Other symptoms involve convoluted sharing set-ups or having moved, copied, or aliased (or symlinked) files or folders from the default [username]/Music/iTunes/ folder rather than follow Apple's instructions for moving an iTunes Media folder to a new location. Heck, I don't know what people are doing at their house. But the result is that the supposed "official" location to the current iTunes database files is erroneous.

ANYway...

If you suspect a disconnect between your current iTunes library location and what the iApps.plist maintains, you can easily open the iApps.plist with Text Edit and see what is listed. It will be gibberishy, but readable enough to confirm a problem. (If you have the Property List Editor.app it'll be easier to read, like the screenshot above.)

And here is what I have recommended to users to correct the problem (but please use caution following this tip. It has worked for virtually everyone I have recommended it to, but I can't make guarantees on how it will result at your house since I don't have your details):

• Make sure the drive that contains your multiple library folder is mounted. Quit iTunes. Wait until it is definetly totally shut down.
• (At this point I might have suggested that you trash the iApps.plist file, however, if this file also contains a non-standard location for your iPhoto library, then this might be lost if you trash the plist file.)
• Start iTunes while HOLDING DOWN THE OPTION KEY. When it asks you if you want to open or create a library, choose open and navigate to the multiple library folder on the external drive, select it, and click OK. In a few moments, iTunes should be up and running.
• To be sure the iTunes database is updated, create an empty playlist and give it a name, drag any track to it, play that track in that playlist for a 10-20 seconds or so, stop the track, and delete the playlist (the track will not be deleted).
• Quit iTunes again, wait for it to shut down, then restart it NORMALLY. That should be enough for the database to be updated.
• Check the iApps.plist to see if it reflects the correct database file location.