This article originally appeared in TidBITS on 2013-11-06 at 11:08 a.m.
The permanent URL for this article is:
Include images: Off

Managing an iBooks Metadata Mess

by Michael E. Cohen

You’ve downloaded a shiny new EPUB from somewhere that isn’t Apple’s rechristened iBooks Store, and it’s on your Desktop in OS X 10.9 Mavericks. You drop that EPUB file on the iBooks icon, the book opens, and you read it with pleasure. Then, one day, you look at the Categories view in iBooks and you notice that the EPUB is part of an ever-growing category known as Uncategorized. This astonishes you because the same EPUB, when you synced it from your Mac to your iPad through iTunes, shows up categorized as Fiction. What gives? Why is it Uncategorized on your Mac and Fiction on your iPad?

[image link] [1]

It’s because of an odd bug in iBooks. It all has to do with metadata (embedded information about your ebook), and how iBooks handles that metadata for EPUBs that originate from outside the iBooks Store.

(Things are going to get geeky here, so if that frightens you, skip down to the end of the article where I explain how to work around this bug.)

EPUBs and Metadata -- Some months back I wrote a piece about managing book metadata in iTunes, “Managing Books in iTunes: This Novel Has a Nice Beat [2],” 14 January 2013. In it, I described two files that, between them, control how iBooks lists a book.

An EPUB is actually a specially constructed .zip archive that contains a bunch of other files. One of the two files that I talked about can be found inside every EPUB: the .opf file. Among other things, the .opf file contains a bunch of metadata statements — that is, specific bits of code that describe the EPUB. One of these (or maybe more than one, but only the first one is recognized by iBooks) describes the EPUB’s subject. For example, a statement like <dc:subject>Fiction</dc:subject> says that the EPUB is Fiction. Ideally, when the EPUB ends up in iBooks, it will be assigned to the Fiction category.

iBooks, however, doesn’t use the raw metadata in the .opf file for assigning the EPUB to a category. Instead, it uses a special file designed by Apple for use in iBooks (and, as you might guess from its name, in iTunes). This file is named iTunesMetadata.plist. The iTunesMetadata.plist contains a bunch of metadata entries about the EPUB. One of those entries, named “genre”, is the one that iBooks uses to assign an EPUB to a category.

But, you may be thinking, where does that iTunesMetadata.plist come from? Good question. When you buy an EPUB from the iTunes Store, the iTunesMetadata.plist is already inside the EPUB. However, for EPUBs that come from other sources, there is no such file. Before Mavericks, iTunes would make this file when you added the EPUB to your book library in iTunes; what is interesting is that in this bright new shiny iBooks-on-the-Mac era, iTunes still does this job!

When you add an EPUB to iBooks from a source other than the iBooks Store, iBooks sends out a call to iTunes to look into the EPUB’s .opf file, scavenge through the metadata as best it can, and use what it finds to create an iTunesMetadata.plist for the EPUB and fill it with data. So, if the EPUB contains the statement <dc:subject>Fiction</dc:subject> in its .opf file, the “Fiction” part of the statement becomes the “genre” in the iTunesMetadata.plist file that iTunes creates for the EPUB.

Great! Except for that bug I mentioned. And here it is: iBooks apparently assigns a newly added EPUB to a category before iTunes has a chance to create the iTunesMetadata.plist file and let iBooks know about it. And, since the EPUB has no iTunesMetadata.plist, and hence no “genre” entry, at the time the EPUB is assigned to a category, it ends up being categorized as Uncategorized.

However, when iTunes finishes its iTunesMetadata.plist construction project, the EPUB in your iBooks library on the Mac does have the file. Consequently, the next time you sync your Mac’s iBooks library with your iPad (and you do that via iTunes, so, even if iTunes wasn’t running when you added your EPUB to iBooks, it can build the file when you sync), the EPUB that you sync to your iPad contains the iTunesMetadata.plist file, and the book shows up on your iPad categorized as Fiction.

And that’s why your EPUB is Uncategorized on your Mac but is Fiction on your iPad.

The Workaround -- Because iBooks 1.0 on Mavericks lacks the Get Info command that iTunes has, you have no way of editing the “genre” for the book to fix it. However, here’s what you can do to make iBooks on your Mac display the EPUB in the proper category.

First, make sure that iTunes is running. Next, open the new EPUB in iBooks. This causes iBooks to make a copy of the EPUB, store it deep inside your ~/Library folder, and to ask iTunes to add an iTunesMetadata.plist file to the book.

Next, drag the EPUB from the iBooks Library window to your Desktop. This causes iBooks to make another copy of the EPUB that it just created and put it on your Desktop. At this point you have three copies of the book: the original (with no iTunesMetadata.plist file), the copy inside of your ~/Library folder (with its new iTunesMetadata.plist file), and a new copy on your Desktop (also with an iTunesMetadata.plist file inside).

Now for the switcheroo: Select the EPUB in iBooks (make sure you are looking at All Books view), and choose Edit > Delete (or just press the Delete key). iBooks asks you if you are sure you want to delete the book from your Mac. You are, so click Delete.

Finally, drag the copy of the EPUB that iBooks created on your Desktop back into iBooks. When you look at the EPUB’s category in iBooks it now reflects the “genre” entry in the iTunesMetadata.plist file.

(You might think you could edit the “genre” statement in an EPUB’s iTunesMetadata.plist file directly, using a text editor like BBEdit or Xcode’s Property List Editor, and you’d be right. Unfortunately, it’s harder than just exporting and reimporting, since iBooks hides your EPUBs deep within your Home directory’s Library; you can find them here: ~/Library/Containers/ However, iBooks also expands each EPUB file into a folder, and names that folder with a unique string of essentially random characters, so good luck figuring out which book goes with which folder!)

This is a silly workaround for a silly but incredibly annoying bug, but what can you do? Wait for Apple to bring back Get Info in iBooks? It may be a while…