View Full Version : Adding epubs to iTunes with cover images


sartori
04-02-2010, 12:41 AM
While preparing some of my books for the upcoming iPad I noticed that when importing them into iTunes the metadata and cover image were not coming up correctly.

This data can be added directly in iTunes using the Get Info option but it would be nice if this information was added by people creating books.

After a bit of investigating I think I have the solution.

For the cover image :

Place a jpg or png image in the root folder of your epub before compressing. The image must be named iTunesArtwork with no file extension.

For the meta data :

Create a file called iTunesMetadata.plist in the root folder of your epub. This file contains a lot of information but below seems to be the minimum to get what is needed for sorting and grouping books in iTunes :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>artistName</key>
<string>***AUTHOR FIRST LAST***</string>
<key>book-info</key>
<dict>
</dict>
<key>comments</key>
<string>***COMMENTS***</string>
<key>genre</key>
<string>***GENRE***</string>
<key>itemName</key>
<string>***BOOK TITLE***</string>
<key>sort-artist</key>
<string>***AUTHOR LAST, FIRST***</string>
<key>sort-artist-status</key>
<integer>1</integer>
<key>sort-name</key>
<string>***BOOK TITLE***</string>
<key>sort-name-status</key>
<integer>1</integer>
<key>year</key>
<integer>1923</integer>
</dict>
</plist>


Once you have added these two file, any epub dragged into iTunes will show all the correct metadata and cover image.

Would be really nice if Calibre or Sigil created these files when exporting an epub.

Sartori

kovidgoyal
04-02-2010, 02:15 AM
Are you kidding me? Apple decided to break the EPUB metadata standard?

sartori
04-02-2010, 02:41 AM
Hmmm, after playing around it seems iTunes does pull the metadata from the original content.opf file when importing - it then adds it's own iTunes metadata file if you do the Get Info thing in iTunes.

Not sure if this overrides the content.opf file if you make changes to it then re-import.

kovidgoyal
04-02-2010, 03:01 AM
Lets give it a couple of weeks until the picture becomes clearer.

charleski
04-02-2010, 06:16 AM
Are you kidding me? Apple decided to break the EPUB metadata standard?
You're surprised???

I was hoping they'd break the standard in a more interesting way. All of this info can be specified using the current OPF techniques. Presumably books bought from their store will have additional fields.

Looks like the cover image doesn't need to be extracted before adding the book to iTunes. The <dict> field contains a cover-image-path child, producing:

<dict>
<key>cover-image-hash</key>
<string>ALLTHESEHASHESAREQUITEINTERESTING</string>
<key>cover-image-path</key>
<string>cover.jpg</string>
</dict>
Which then shows as the cover in iTunes. It seems that iTunes looks for a metatdata element named "cover" and then uses the image with the corresponding id.

Thus, if your book has the following in its .opf file it will automatically find the cover:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
...
<meta name="cover" content="cover-image" />
...
</metadata>
<manifest>
...
<item href="[path to cover image within epub structure]" id="cover-image" media-type="image/jpeg"/>
...
</manifest>

kovidgoyal
04-02-2010, 06:43 AM
I wouldn't call adding non existing features breaking a standard. calibre for instance adds series and rating info to the OPF, but in a way that's compatible with the OPF spec.

I wished they'd used the <guide> for the cover instead.

Valloric
04-02-2010, 08:04 AM
So let me get this straight... iTunes will pull the metadata from the OPF in the epub and then do... whatever, but to get the cover image to show up you need a <meta> element identifying the ID of the cover image element in the manifest? Is that it?

I agree with Kovid, they really should have gone with the <guide> cover, but I guess I can live with this.

kovidgoyal
04-02-2010, 08:53 AM
Of course the scheme they chose is rather calibre friendly, since IIRC calibre generated EPUBs already have that metadata element set.

Valloric
04-02-2010, 09:07 AM
Of course the scheme they chose is rather calibre friendly, since IIRC calibre generated EPUBs already have that metadata element set.

So calibre currently adds a meta element referencing a cover image ID? What was the use case for that before the iPad/iTunes epub import?

kovidgoyal
04-02-2010, 09:17 AM
Identifying the actual raster image that is the cover rather than just the HTML wrapper.

charleski
04-02-2010, 09:30 AM
AFAIK, the guide entry for cover is what ADE uses to generate its thumbnail, so obviously Apple have to do it differently...

Jellby
04-03-2010, 04:22 AM
So calibre currently adds a meta element referencing a cover image ID? What was the use case for that before the iPad/iTunes epub import?

If I remember correctly, Mobipocket also relied on the <meta name="cover"> tag (among other things) for identifying a cover in ePUB files. I use it in my ePUBs, it does not harm and I hoped it could be used some day...

Valloric
04-03-2010, 07:47 AM
If I remember correctly, Mobipocket also relied on the <meta name="cover"> tag (among other things) for identifying a cover in ePUB files. I use it in my ePUBs, it does not harm and I hoped it could be used some day...

I plan on adding that to Sigil, since it could be generally useful even if you're not using an iPad. Something like a right-click menu option on an image in the Book Browser: "Mark as cover image". It would also mark an image automatically if the first chapter file is "small" and contains just one image (this would naturally be overridable).

The "plist" used by the iPad/iTunes will not be added to epubs by default, but Sigil will add them if an option is selected, either on export or in an options screen.

But we still have to wait a couple of weeks to see how all this turns out. I'll be getting an iPad so I'll be waiting to get some first hand experience with the thing before I start making any iPad-specific changes.

Needless to say, iPad support is very high on my list. Sigil is used by a surprising number of ebook publishers and I'm pretty sure they care deeply about this.

charleski
04-03-2010, 08:31 AM
The "plist" used by the iPad/iTunes will not be added to epubs by default, but Sigil will add them if an option is selected, either on export or in an options screen.It might be safer to let iTunes generate the plist. It contains a couple of hashes for the cover image and package as well as a unique ID that seems to be generated by iTunes. If you import an epub which already has a plist file in it then the ID and hashes are not regenerated, but iTunes will use the data from the plist rather than that from the opf.

I would presume that the hashes and Apple-assigned ID are important for books that are going to the iBookstore.

If Apple remains consistent with their past approach to iTunes data, then it's safe for 3rd-party apps to read iTunes-generated xml, but best not to try to write it.

BTW, iTunes will recognise the dc:creator opf:file-as attribute and use it to set the artist sort field. I tested a couple of the opf:role codes, but iTunes seems to ignore them. The first dc:creator entry is used as the artist name, no matter what the assigned role is.

Valloric
04-03-2010, 11:35 AM
It might be safer to let iTunes generate the plist.

From the OP's post I gathered that iTunes will not generate the plist. You say it will. Which one is it? Does it read the OPF for the metadata, or does it need special consideration?

I guess I'll have to go and install iTunes...

EDIT: Ah, it seems I missed the OP's subsequent clarification. My bad.

charleski
04-03-2010, 01:04 PM
Just so it's clear -

If the epub doesn't have an iTuneMetadata.plist in its root, then iTunes will always generate one automatically on importing the file. In this process it scans the opf and extracts certain metadata elements as well as generating a couple of hashes and an ID number whose purposes are currently unclear.

If the epub does have a plist file in its root, then iTunes won't scan the opf metadata and won't generate the hashes or ID. It will simply use the plist as-is and ignore the metadata in the opf.

Any changes to metadata made in iTunes are written only to the plist file.

At the moment epubs do not appear to be included in the xml data created on exporting the iTunes library.

phearlez
04-08-2010, 04:38 PM
At the moment epubs do not appear to be included in the xml data created on exporting the iTunes library.

I'm not surprised by that. The AppleScript/COM interfaces and the export always have seemed to lag behind features.

paulpeer
04-09-2010, 10:53 AM
I've just added

<meta name="cover" content="img0001.jpg" />

to 30 of my ePubs, dragged them to iTunes, and they all appear perfectly with cover page and the following meta data: title, creator and subject.

MichaelCampbell
04-13-2010, 04:08 PM
Identifying the actual raster image that is the cover rather than just the HTML wrapper.

Dr. Goyal: I noticed InDesign uses the "cover" metatag in its ePub creation, referencing the XHTML cover page in the manifest. Like this:
<reference type="cover" title="Book Cover" href="Cover.xhtml" />

I've struggled to get the cover art to appear properly in Stanza for iPhone. Is there an advantage to referencing the original CoverArt.jpg rather than the "Cover.xhtml", if when the XHTML file is, as you say, only a wrapper?

I study your posts and those of Valloric. I greatly appreciate your availability on this forum.

pdurrant
04-13-2010, 04:23 PM
<reference type="cover" title="Book Cover" href="Cover.xhtml" />


This is different to the meta data that iTunes uses. The <reference> element appears in the <guide> element of content.opf, and should indeed reference the xhtml file for the cover.

The meta data needs to appear in the <metadata> element, usually near the start of the .opf file, and would be something like

<meta name="cover" content="cover-image"/>

Note that name="cover" is required, but the "cover-image" bit is arbitrary, and just needs to match the id given in the manifest for the bitmap version of the cover. So, using the above, in the <manifest> element of the .opf file there would also need to be a line

<item id="cover-image" href="images/img0032.png" media-type="image/png"/>

where the id must match the 'content' bit of the meta data, and the href and media-type must correctly identify the cover bitmap.

HTH

nixwinter
04-13-2010, 05:23 PM
You're surprised???

I was hoping they'd break the standard in a more interesting way. All of this info can be specified using the current OPF techniques. Presumably books bought from their store will have additional fields.

Looks like the cover image doesn't need to be extracted before adding the book to iTunes. The <dict> field contains a cover-image-path child, producing:

<dict>
<key>cover-image-hash</key>
<string>ALLTHESEHASHESAREQUITEINTERESTING</string>
<key>cover-image-path</key>
<string>cover.jpg</string>
</dict>
Which then shows as the cover in iTunes. It seems that iTunes looks for a metatdata element named "cover" and then uses the image with the corresponding id.

Thus, if your book has the following in its .opf file it will automatically find the cover:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
...
<meta name="cover" content="cover-image" />
...
</metadata>
<manifest>
...
<item href="[path to cover image within epub structure]" id="cover-image" media-type="image/jpeg"/>
...
</manifest>



Good Lord...
How do I do that in Sigil?

Thank you for any help!!

Nix

kovidgoyal
04-14-2010, 01:52 AM
@MichaelCampbell: Referencing the raster image directly is of advantage in the scenario where a library app like calibre, or iTunes or Stanza needs to extract a cover from the EPUB.

If such a reference is present calibre will use it to efficiently extract the cover image. If it is absent calibre will render the first html file to get the cover. Other software, like iTunes is less capable and in the absence of the reference will simply fail to extract the cover.

Valloric
04-14-2010, 07:28 AM
If such a reference is present calibre will use it to efficiently extract the cover image. If it is absent calibre will render the first html file to get the cover.

Had I known this before, I would have added the functionality to Sigil a long time ago. You should have said something Kovid. :)

kovidgoyal
04-14-2010, 09:00 AM
no big deal, actually in the absence of the reference, calibre first scans the first html file, if it looks like a wrapper (i.e. no text and only one <img> or <svg:image> element it figures out the raster cover from that :)

Vintage Season
07-01-2010, 05:27 PM
Hmm... for those of us able to properly script an iTunesMetadata.plist file, in order to batch customize our files without worrying about those hashes iTunes insists on generating, would it be possible to give Sigil or Calibre the ability to properly add that file to the root of the *.epub so that the file will still pass epubcheck?

Currently, if I use 7-Zip to simply add the file in the proper location, iTunes accepts it and uses the meta tagging I've specified for grouping and sorting, but epubcheck spits out the following:ERROR: test.epub: length of first filename in archive must be 8, but was 20

Simply editing an iTunesMetadata.plist file in place, within the *.epub, also produces the same epubcheck error.

iTunes appears to be adding the iTunesMetadata.plist file without setting any file attributes, if that helps.

(If it would help more, I could also generate some quick xhtml and a couple of test files showing specific examples.)

- M.

charleski
07-01-2010, 05:55 PM
Currently, if I use 7-Zip to simply add the file in the proper location, iTunes accepts it and uses the meta tagging I've specified for grouping and sorting, but epubcheck spits out the following:ERROR: test.epub: length of first filename in archive must be 8, but was 20

Just checked this, and 7-zip rewrites the archive in a way that moves the mimetype file away from its required position at the start of the archive.
No of characters in 'mimetype': 8. No of characters in 'iTunesMetadata.plist': 20.

The problem lies with 7zip re-ordering the file, and there's not much that can be done unless the 7zip team decides to change it. It looks like 7zip simply isn't suitable for editing epubs unless you're very careful in recreating the archive after edits. I use WinRAR, largely because it allows you to open internal files straight into an editor of your choice. Unfortunately it's not free, but it's never shown this problem.

Vintage Season
07-01-2010, 05:59 PM
No of characters in 'mimetype': 8. No of characters in 'iTunesMetadata.plist': 20.

:rofl: That much, I had figured out.

Thanks for verifying the behavior I encountered, though.

- M.

Vintage Season
07-01-2010, 09:50 PM
The problem lies with 7zip re-ordering the file, and there's not much that can be done unless the 7zip team decides to change it. It looks like 7zip simply isn't suitable for editing epubs unless you're very careful in recreating the archive after edits. I use WinRAR, largely because it allows you to open internal files straight into an editor of your choice. Unfortunately it's not free, but it's never shown this problem.

Solved... and for anyone interested in doing what I described (manually adding an iTunesMetadata.plist file), you can use Info-Zip's free Zip 3.0 (http://www.info-zip.org/Zip.html) utility to properly add the file, without messing up the order, via the following command line:zip "path to my.epub" "iTunesMetadata.plist"

- M.

Vintage Season
07-01-2010, 10:44 PM
... and if it really matters to anyone (iTunes doesn't seem to care) whether or not the Archive bit is cleared (which is iTunes' current manner of handling the task, although the resultant filesize seems to be the same either way), that can be accomplished by using this line instead of the earlier one:zip -AC "path to my.epub" "iTunesMetadata.plist"

... which allows one to include specific iTunes tags and sorting structure, such as this, in a custom iTunesMetadata.plist:
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>artistName</key>
<string>AuthorFirstName AuthorLastName</string>
<key>book-info</key>
<dict>
<key>cover-image-path</key>
<string>OEBPS/Images/cover.jpg</string> <-- make sure this is correct for your book!
</dict>
<key>genre</key>
<string>Genre</string>
<key>itemName</key>
<string>Title</string>
<key>releaseDate</key>
<string>yyyy-mm-dd</string>
<key>sort-artist</key>
<string>AuthorLastName, AuthorFirstName</string>
<key>work</key>
<string>Grouping/Series (if applicable)</string>
<key>sort-name</key>
<string>Grouping/Series (if applicable) Number (if applicable): Title</string>
</dict>
</plist>


Assuming your *.epub passed validation before you added the iTunesMetadata.plist, and you follow this method, it should still pass after you add the file.

- M.

JSWolf
07-05-2010, 09:21 AM
Just take a look at how Calibre does the cover. It works fine in iBooks.

menneske
09-30-2010, 12:37 PM
I wish to review the first ePUB collection of poetry published in Denmark by a real establishment poet. And there are several things to critisize, which is not the poet's text.

Can I assume..., IF there is an iTunes plist in the ePUB, but no real metadata showing up in Sigil, that the focus for the producer and/or publisher was on iPad/pod/Touch and not really on any other e-reader device?

What could I assume, when there is no front cover on this book? Besides it probably not just being a case of forgetfulness? IS is impossible to make it look good? Or do they assume it would get a cover, when it ends up in iTunes? (But even so, that cover is only visible on the bookshelf of iBooks - not when you leaf through the book).

Poetry with re-flowing lines and re-sizeable font is a catastrophy!

Is there a way to make an ePub NON-flowing - or would it have to be a pdf - assuming pdf-readers on reader devices don't all become flowing text...?

kovidgoyal
09-30-2010, 12:39 PM
See this demo for how to format peotry in an EPUB

http://calibre-ebook.com/user_manual/conversion.html#epub-advanced-formatting-demo