[GRiker]

Calibre 0.7.x supports sending books to iTunes/iDevices in OSX and Windows. This thread contains in-depth information about using iTunes with calibre.

If your regular Reader is a device other than an iDevice (Sony, Kindle, Nook, etc) and you routinely connect an iPhone to your computer to charge or sync it with iTunes, you will want to disable your iDevice in calibre. See If you have problems below for details.

Quick start: 'Connect to iTunes' mode

1. Launch iTunes with no connected iDevices.
2. Launch calibre, set Preferences:
   • Preferences|General|Preferred output format to EPUB
   • Preferences|Conversion|Page Setup|Output profile to iPad
   • Preferences|Plugins|Device Interface plugins|Apple device interface - click Enable/Disable plugin so that driver is disabled (grayed out)
3. Restart calibre.
4. Select Send to device↓Connect to iTunes to connect iTunes as a Reader.
   
   
   
5. To send epubs or PDFs from calibre to iTunes:
   • Select the book(s) to send from your calibre Library window, then click Send to device. Your books are sent to 'Books' in your iTunes library.
6. To use Fetch news to download periodicals from the Internet:
   • Preferences|Interface|Automatically send downloaded news to ebook reader:
     Recommendation: checked
   • Preferences|Interface|Delete news from library when it is automatically sent to reader:
     Recommendation: unchecked
   • Click Fetch news, select the recipe you wish to download, click Download now. Repeat for other recipes, then click Save to exit the Schedule news download dialog.
   • To learn more about iPad-optimized periodicals, see 'iPad + Recipes: New optimizations in 0.7.5'.
7. When you're ready to sync your iDevice with iTunes:
   • Connect your iDevice to your computer
   • Sync your iDevice with iTunes as you normally would.
   • If you manually manage songs and videos in iTunes, you can simply drag books from the Library|Books list to your iDevice.

Options

Configuration options are accessed in Preferences|Plugins|Device Interface plugins|Apple device interface, then clicking Customize plugin.

• Select available formats and their order for this device: If you have both an epub and pdf file, the order of these formats in this list determines which will be sent to iTunes when clicking Send to device. If you want to send a particular format, use Send to device↓Send specific format.
• Use Series as Category in iTunes/iBooks: If checked, the Series name from the book's metadata will be used as the Genre in iTunes. If no Series name exists, the first tag will be used as the Genre. If unchecked, the first tag will be used as the Genre.
• Cache covers from iTunes/iBooks: If checked, calibre will read cover images from iTunes and display them in the Book Details section of the Reader pane. Calibre caches cover images to improve performance. If you have a very large library and simply want to load as fast as possible, uncheck this option.

'Connect to iDevice' mode (advanced)

Spoiler:

1. Launch iTunes with your iDevice connected.
2. Launch calibre, set Preferences:
   • Preferences|General|Preferred output format to EPUB
   • Preferences|Conversion|Page Setup|Output profile to your iDevice.
   • Preferences|Plugins|Device Interface plugins|Apple device interface - click Enable/Disable plugin so that driver is enabled (not grayed out)
3. To send epubs or PDFs from calibre to your iDevice:
   • Select the book(s) to send from your calibre Library window, then click Send to device. Your books are sent to iTunes and iBooks.
4. To use Fetch News to download periodicals from the Internet:
   • Preferences|Interface|Automatically send downloaded news to ebook reader:
     Recommendation: checked
   • Preferences|Interface|Delete news from library when it is automatically sent to reader:
     Recommendation: checked
   • Click Fetch news, select the recipe(s) you want downloaded, click Download now then Save. When the Jobs spinner has stopped and your iDevice has finished syncing, you can read your downloaded periodicals as epubs in iBooks.

'Connect to iDevice' mode - more details

1. The iDevice driver is very different than a conventional calibre driver which sees the connected device as a USB drive. The iDevice driver accomplishes its tasks by talking to iTunes through an automation interface. As a result, settings in iTunes influence how various operations are carried out. I have not tested all of the possible combinations of iTunes settings that one might use, so it's entirely possible that your configuration will trigger unexpected results. This overview discusses the most common settings.
2. It's a good idea to sync your iDevice with iTunes before connecting your iDevice to calibre for the first time. Syncing apps and other media between your iDevice and iTunes before working with calibre will speed up transfers.
3. In iTunes Preferences|Advanced, the checkbox Copy files to iTunes Media folder when adding to library is significant. If the box is unchecked, iTunes remembers the location of the file (calibre's copy). If the box is checked, iTunes makes a copy of the file to its own storage. However, iTunes also modifies calibre's copy of the epub by adding a plist file. Files so modified by iTunes have been tested in the calibre viewer and in Adobe Digital Editions with no observed problems.
   Recommendation: unchecked.
   If you are currently using iTunes to manage other media for your iDevice, and this is checked, leave it checked. iTunes will make its own copy of the added books rather than referencing calibre's copy. Any new media you add to iTunes will be stored in iTunes, as before.
4. In iTunes Device Summary, the Manually manage music and videos checkbox influences how syncs are accomplished:
   • If unchecked, calibre adds all of the transferred epubs to iTunes, then does a single sync operation to transfer all of the uploaded epubs to iBooks on your iDevice at once. If iTunes decides that other items need to be synced at the same time, it will do so during this sync cycle. This could include doing an incremental backup of your iDevice.
   • If checked, books are sent to the iDevice directly without a full sync cycle. (Calibre still keeps a copy into iTunes for future reference.)
   There will be performance differences between the two settings depending on your usage patterns and your OS, but the driver is designed to work with either setting.
   Recommendation: start with unchecked. Windows users: things seem to work better with the checkbox unchecked.
5. Launch calibre. When a connected iDevice is detected, calibre will launch iTunes (minimized) if it's not already running. Calibre does not support multiple iDevices connected simultaneously. If calibre detects more than one physically connected iDevice in iTunes (iPad, iPhone, iPod Touch), the driver will not launch. This includes devices that have been ejected but not physically disconnected.
6. In calibre, set Preferences|General|Preferred output format to 'EPUB', and Preferences|Conversion|Page Setup|Output profile to 'iPad'.
7. The first time you connect your iDevice to calibre, calibre will be caching metadata and thumbnails as it scans iTunes and iBooks, making subsequent connections much faster.
8. The iDevice 'Reader' icon will be shown next to the 'Library' icon, indicating that calibre is connected to your iDevice. Click it to see books in the Books playlist on your iDevice.
9. To upload books in either epub or PDF format from calibre to your iDevice, select the book(s) to transfer from your Library, then click Send to device.
10. iTunes/iBooks supports a single Category tag. You may choose to use either a tag or a Series name as the Category by indicating your preference in Preferences|Plugins|Device Interface plugins|Apple device interface. Click Customize plugin. Use Series as Category in iTunes/iBooks has the following meaning:
    • checked: If your book has a Series name, it will be used as the Category in iTunes/iBooks. If your book does not have a Series name, a tag will be used.
    • unchecked: If you have multiple tags assigned to a book in calibre, the first tag beginning with an alpha character will be used. Special tags like '[Project Gutenberg]' or '+' are ignored.
11. Recipes and catalogs may be sent to the iDevice.
12. While calibre is running, it's best to do all iDevice-related actions through calibre rather than iTunes. Minimizing iTunes while calibre is running will reduce the temptatation to meddle.
13. Syncing is initiated after clicking Send to device or Remove books in the Reader view. In some cases, the syncing operation between iTunes and your iDevice will continue after calibre is done with its part. Watch the screen on the iDevice to know when the sync is done.
14. Unlike some other readers, the iDevice may be used while connected to the computer. This means that you can open your uploaded books in iBooks (after syncing is complete) while the iDevice is still connected to calibre. You don't need to eject the iDevice until you want to disconnect the iPad from your computer.
15. You can copy books from your iDevice to your computer using Save to disk, but be aware that all epubs acquired through the iBooks store are encrypted with Apple's Fairplay DRM, and thus not readable anywhere but on your iDevice.
16. Books with DRM are able to have their metadata updated in calibre.
17. iBooks stores epubs on the iDevice in uncompressed form. As a result, you will notice that the size of the book shown in calibre's Library window (and iTunes) is different than the size of the book on the iDevice.

What's the difference between 'Connect to iTunes' and 'Connect to iDevice'?

Spoiler:

'Connect to iTunes' uses iTunes as the Reader device. Clicking the Reader icon (the iTunes logo) shows a list of books in the iTunes Library. After sending books from calibre to iTunes, you sync iTunes with your iDevice at your convenience. This is the recommended mode.
'Connect to iDevice' uses your iDevice as the Reader device. Clicking the Reader icon (an iPad) shows a list of books in the iBooks library on your iDevice. Sending books from calibre to your iDevice happens immediately, without requiring you to sync. This mode is more complex.
Users are encouraged to use the 'Connect to iTunes' mode, as it adapts to the way that you're already using iTunes. You don't need to be concerned with any of the iTunes preferences or optional settings. When you're ready to update the contents of your iDevice, sync as you normally would.
If you choose to use 'Connect to iDevice' mode, spend some time reading and understanding the significance of the various iTunes settings that will affect calibre interactions.

Known Issues

Spoiler:

1. The driver currently sends comments from calibre to iTunes, however the automation interface to iTunes limits the transferred text to 256 characters. This is a limitation of the iTunes automation interface in both OSX and Windows.
2. If you use calibre to delete a book that you purchased through the iBookstore (free or paid), iTunes may pop up a dialog asking you to confirm. This does not happen with books transferred from calibre.
3. If you bring up a modal dialog in iTunes, for example Get Info to examine the book's metadata, the iDevice will appear to disconnect in calibre after a short time. As soon as you close the modal dialog in iTunes, the connection will be restored in calibre.
4. (OSX only) If iTunes|DEVICES|iDevice|Summary|Options|Manually manage music and videos is checked, the automation interface will generate an error when trying to send artwork to the iDevice. This is as of iTunes 9.2, hopefully that bug will be fixed by Apple at some point.
5. It is currently not possible to set the cover for PDFs via the automation interface. iTunes/iBooks uses the cover specified within the PDF file.
6. When transferring PDF files, there is a period of several seconds per book when it appears that nothing is happening. What is happening is that calibre is updating the PDF's metadata before sending the book, but there is no user feedback. There is an existing bug report #5949 addressing this issue. If you are sending multiple PDFs, the cumulative time without user feedback can be substantial.
7. 'Connect to iDevice' mode can only deal with one connected iDevice. When the driver loads, it confirms that there is only one iDevice connected. However, if you connect a second iDevice later, calibre won't know which device to communicate with. Using 'Connect to iTunes' avoids this problem.

Under the hood

Spoiler:

• The driver was tested with OSX 10.6 (Snow Leopard), Windows XP, Windows 7, and a 3G iPad. With OSX, 10.5 or newer is required (Leopard or Snow Leopard).
• You must have iTunes installed on your system, as calibre talks to the iDevice through iTunes. You should install the latest version of iTunes, 9.2 as of this writing. If in doubt, download the most recent version from apple.com. To check your installed version, click iTunes|About iTunes in the iTunes menu.
• There will be no Linux support in this driver, as there is no Linux version of iTunes.
• The driver sends only epubs and PDFs to iBooks via iTunes via a physical USB connection.
• If you have a cover assigned in calibre, it will be used in iTunes and in iBooks as the book's cover, superseding any cover within the file. As of iTunes 9.2 and iBooks 1.1, this works only for epubs, not PDFs. The cover art provided in the PDF will be used by iTunes/iBooks.
• Calibre uses an automation interface to send commands to iTunes. The automation interface for OSX is completely different than the automation interface for Windows. Some operations have problems in one environment but not the other. The driver attempts to recover gracefully from any errors when talking to iTunes through the automation interface.
• When downloading calibre recipes, the driver changes the metadata before sending the book to iTunes. For example, if you download the NYTimes, the title will be shown as 'The New York Times', and the author will be shown as today's date, e.g. 'Friday, June 18, 2010'. Title sort is 'New York Times', author sort is 'New York Times 2010-06-18'. Periodicals are tagged with 'News' by default, which becomes the Category for the book in iBooks.
  If you are using recipes, be aware that Preferences|Interface|Automatically send downloaded news to ebook reader and Preferences|Interface|Delete news from library when it is automatically sent to reader should be set according to your preferences.
• Current iTunes <> Calibre metadata mappings as of 0.7.7:
  • Album - Title
  • Artist - Author
  • Composer - uuid
  • Description - (description generated when sending file)
  • Enabled - True
  • Sort Artist - author_sort
  • Sort Name - (function stripping 'A', 'An', 'The' from title)
  • Comments - Comments
  • Rating - Rating
  • Genre - (first tag starting with alpha character)
  If option to use Series as Genre is checked:
  • Genre - Series
  • Episode ID - Series
  • Episode Number - series_index
  • Sort Name - Series (series_index formatted as 0xxx.yyyy)

If you have problems ...

Spoiler:

• Books are disappearing from iTunes

  If you have enabled/disabled the Apple device driver in Preferences, restart calibre.

• Calibre doesn't recognize my iDevice

  Confirm that you have only one iDevice (iPad, iPhone, iPod) connected.

• I don't want calibre to recognize my iDevice

  If you would prefer that calibre ignore any connected iDevices, disable the Apple device interface in Preferences|Plugins|Device Interface plugins.

• Calibre doesn't crash, but it's not doing what I expect
  1. Confirm that you're up to date with the latest release of calibre.
  2. If you're using 'Connect to iDevice', try using the recommended 'Connect to iTunes' mode as described at the beginning of this post.
  3. Start calibre in debug mode. With iTunes running, open a command window then type:
     

     calibre-debug -g >calibre.txt

  4. Repeat the steps to recreate the scenario. Exit calibre, create a ticket in the calibre bug database. Attach 'calibre.txt' to your bug report. Please provide as much relevant context as possible to help recreate the problem, including the steps you took prior to observing the problem, your OS, and the nationality of your iTunes installation.
• Calibre crashes
  1. Confirm that you're up to date with the latest release.
  2. If you're using 'Connect to iDevice', try using the recommended 'Connect to iTunes' mode as described at the beginning of this post.
  3. If you're still crashing, launch calibre in debug mode. With iTunes running, launch calibre from a command window:
     

     calibre-debug -g >calibre_crash.txt

  4. Repeat the steps to create the problem. After the crash, create a ticket in the calibre bug database. Attach 'calibre_crash.txt' to your bug report. Please provide as much relevant context as possible to help recreate the problem, including your OS and the nationality of your iTunes installation.
• Everything's perfect except for this one missing feature I can't believe you forgot

  Go to calibre's project management site to create a feature request.

Please post comments, problem, suggestions regarding iDevice support in this thread. Include your OS, the version of iTunes you're using, and the nationality of your installed iTunes.

G