iTunes library, fixing a broken one or moving one

I see some discussion about fixing busted iTunes libraries, either when moving one on the same computer or migrating to a new one. Here’s what I have found works for me.

Bonus: no slow AppleScripts or payments (donations cheerfully accepted and squandered). After almost 3 1/2 years more than four years, this continues to be a widely-read posting and still seems to work. I thought it was made obsolete with iTunes 8 or somewhere along there… As it’s been viewed more than 111,000 times and been found useful a few of those times, I wouldn’t object to a donation. But rather than spend your money, you could do me a favor and help yourself at the same time. Click that link and if you buy something at Amazon.com, they’ll send me a penny, maybe more. No obligation but also no cost to you.

As an aside, if you are going to comment along the lines of “I just moved my music from one Mac to another and nothing broke so why is this so complicated?” please don’t bother. The title specifically mentions a BROKEN library, you dig? Or perhaps your library has outgrown the current location and you want to move it but retain access to it as your primary library and keep all your playlists and history. That’s what this post deals with, not replicating a working installation, but changing one to suit a new environment or fixing a botch attempt at it. Peace.
And for goodness’ sake, read all the comments: some good stuff down there. Sadly, I had to throw away all the comments, as I disconnected them from the posts they were in response to.

First, what I have discovered about how iTunes manages music collections. There are two files it uses, one that is binary (ie, machine readable for faster performance on searching, sorting, add/edit/delete operations) and one that has the same information but in a human readable format (for a certain subset of humans who can read XML natively). The XML file is written from the binary file as a backup (check the dates to confirm).

iTunes will try to open the binary file when it starts up and if it’s not readable, it will re-create it from the XML file. That’s what we’re using to fix the damage or make any sweeping changes.

First, close iTunes. You’ll be working with files it uses/writes to and you’ll muck things up if you makes changes to files it has open and then your changes get clobbered, leaving the binary and the backup unusable. Don’t do that.

1. find your Music folder/directory where these files live: you are looking for iTunes Library and iTunes Music Library.xml
   The XML file is a backup of the other file, which is the one iTunes uses:
   iTunes Library: data
iTunes Music Library.xml: XML document text [NB for Windows users: you will be looking for iTunes Library.itl and iTunes Music Library.xml.]
2. Move the iTunes Library file aside (rename it, put in your home directory, whatever). Create an empty file with the same name (or simply mangle a copy of it: seriously: this is where the backup copy comes in). If you are in the Terminal, you can just use touch(1), as in touch iTunes\ Library. You can also just open a file in whatever other editor you like and save it as iTunes Library.
3. You’ll need to edit the XML file, in a text editor, not a word processor (not Word, as if I have to explain that). vi, emacs, pico, nano, TextWrangler, BBEdit, TextMate on the Mac side, NotePad/WordPad, et al on the Other Side. You are going to search and replace the current location with the new one. Every file/track/song has it’s own stanza in that file and within that, there is a Location key. You need to replace the old one — as an absolute path — with the new one.
   An example: <key>Location</key><string>file://localhost/private/Network/Servers/shuttle
/usr/local/share/mt-daapd/media/Abbado_Berliner%20Philharmoniker/Mahler_%20Symphonie%20No.%205/01%20
Trauermarsch.%20In%20Gemessenem%20Schritt.%20Streng.%20Wie%20Ein%20Kondukt.m4a</string>
4. A quick and dirty way to do it on the command line, ie, in the Terminal?perl -pi -e.backup s|oldpath|newpath|g iTunes Music Library.xml
perl -pi.backup -e s|oldpath|newpath|g iTunes Music Library.xml

   This will create a backup file (cleverly called “iTunes Music Library.xml.backup”)

5. Now, test it. iTunes needs to find that iTunes Music file and since it can’t read it (it’s empty or damaged), it will create one from the backup you just edited. Give that a minute or three to complete. See if your files are found and playable. This should also keep your playlists (which are just another XML stanza with the elements being track ID numbers).

This has worked for me more than once and if it’s reproducible, it should work for you. But note that I recommend a backup copy of the XML file. You can go back and re-do it from scratch if you get into trouble.

And I expect this is extensible in many interesting ways, like merging libraries from different users (something with diff and patch, perhaps?), switching from one repository to another (maybe a large home repository and a smaller traveling one). I’m not clever enough to figure those out, but if anyone else does, I’d love to hear about it.

[update] This looks interesting:

I had to do some more things with my iTunes library lately – like extracting all that ratings and exporting them into a new music player software I liked to test. I therefore wrote myself a little tool in C# that does the job of reading in the whole iTunes library and giving you programmatically access to that library. It only needs to have read access to the Mediathek.xml file iTunes stores in it’s music folder and you from there on can work your way through the bazillions of music tracks you may or may not have in your library. It even does the find-and-replace job a bit easier than the solution mentioned in the article above.