Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
An extension of the existing KoboTouch driver provided with Calibre. This plugin allows modifying ePub files to enable extra Kobo features. For the bug tracker, please visit https://bugs.launchpad.net/calibre-kobo-driver
Python PowerShell Shell CSS
Failed to load latest commit information.
conversion Add support for disabling hyphenation
css Add support for disabling hyphenation
device Add support for disabling hyphenation
metadata Fix plugin names
translations Add support for disabling hyphenation
.gitattributes Add gitattributes
.gitignore Add metadata reader/writer based on davidfor from mobileread
CONTRIBUTORS Update CONTRIBUTORS
LICENSE Update the license to GPLv3 as needed since this extends GPLv3 code and
README.md Add support for disabling hyphenation
common.py Fix plugin names
container.py Emulate Kobo's epub2 processing of the body tag
conversion_init.py Allow setting default values and updating version in one place
create-plugin.ps1 Fix plugin names
create-plugin.sh Fix plugin names
device_init.py Add conversion format output plugin
generate-pot.ps1 Add script to make translations template
generate-pot.sh Add metadata reader/writer based on davidfor from mobileread
md_reader_init.py Add metadata reader/writer based on davidfor from mobileread
md_writer_init.py Add metadata reader/writer based on davidfor from mobileread
plugin-import-name-kepubmdreader.txt Add metadata reader/writer based on davidfor from mobileread
plugin-import-name-kepubmdwriter.txt Add metadata reader/writer based on davidfor from mobileread
plugin-import-name-koboconversion.txt Various fixes found by MR members
plugin-import-name-kobotouch_extended.txt Adding existing driver work
pygettext.py Add pygettext

README.md

I Love Open Source

Kobo Touch/Glo/Mini KePub Plugins

This provides an extension of the existing KoboTouch driver provided with Calibre. This driver plugin allows modifying ePub files to enable extra Kobo features.

Please note: Modified books are not saved back into your Calibre library to prevent issues with overwriting library configurations unexpectedly, so books are processed in transit to your device every time. In most cases, the extra time required should not be noticeable.

Additionally, a calibre conversion output format plugin is available, allowing you to convert books to KePub format without a supported device.

WARNING: THE CONVERSION OUTPUT FORMAT PLUGIN GENERATES FILES WHOSE INTERNAL STRUCTURE IS STILL UNDER DEVELOPMENT. THE KEPUB FILE STRUCTURE IS NOT YET FULLY UNDERSTOOD. DO NOT, UNDER ANY CIRCUMSTANCES, DELETE THE FILES FOR THE SOURCE FORMAT. ALWAYS HAVE A NON-KEPUB FORMAT FOR YOUR BOOKS.

Download

To download this plugin, either clone the repository or download a snapshot of the master branch by clicking on the big Download ZIP button on the right side of the page. It is not necessary to download this plugin in this way unless you want to install from source (see directions below).

Installation

The current release version of this plugin may be installed directly within calibre:

  1. Open calibre's preferences, choose Plugins, and click Get new plugins
  2. To install the Kobo Touch/Glo/Mini driver plugin, select the KoboTouchExtended plugin from the list of available plugins and click Install
    1. Don't see it? You may already have it installed. Restart calibre and see if you are notified of a pending update.
  3. To install the KePub conversion output format plugin, select the KePub Output plugin from the list of available plugins and click Install
    1. Don't see it? You may already have it installed. Restart calibre and see if you are notified of a pending update. Or, this may not yet be uploaded to the calibre plugin index.
  4. Restart calibre

To install the device driver plugin from source, you must rename device_init.py to __init__.py, create a ZIP file named KoboTouchExtended.zip and include these files and folders:

  1. __init__.py
  2. container.py
  3. common.py
  4. device
  5. css
  6. plugin-import-name-kobotouch_extended.txt

To install the conversion output format plugin from source, you must rename conversion_init.py to __init__.py, create a ZIP file named KePub Output.zip and include these files and folders:

  1. __init__.py
  2. container.py
  3. common.py
  4. conversion
  5. css
  6. plugin-import-name-koboconversion.txt

To create a ZIP file:

  1. Windows users can run the create-plugin.ps1 script (requires that Powershell allow running unsigned scripts, which is not the default setting).
    1. This Powershell script is untested and unsupported; if it does not work for you and you know how to fix it, please submit a bug report with a patch or a corrected Powershell script.
    2. This Powershell script generates the ZIP file for both plugins.
  2. Linux and Mac OS X users can run the create-plugin.sh script (either grant it executable permissions first, or run sh create-plugin.sh).
    1. This script generates the ZIP file for both plugins.
  3. Create an empty ZIP file and add the files noted above for the desired plugin.
  4. Select the files noted above for the desired plugin, right-click, and add the files to a new ZIP file. This may also be referred to as a "Compressed Folder" or only be available once you choose the "Archive" option, depending on your operating system.

Add the resulting ZIP file to calibre:

  1. Preferences
  2. Plugins
  3. Load plugin from file

Usage

To use the device driver plugin after installing:

  1. Connect your Kobo Touch/Glo/Mini device and wait for it to be detected by calibre
  2. Select the book(s) you want to send to your device.
  3. Click the Send to device button.

To use the conversion output format plugin after installing:

  1. Choose the book you want to convert to KePub format
  2. Choose the KEPUB format from the list of output formats (top-right of the conversion window)
  3. Choose KePub Options from the left menu and make your option selections
  4. Click OK

WARNING: THE CONVERSION OUTPUT FORMAT PLUGIN GENERATES FILES WHOSE INTERNAL STRUCTURE IS STILL UNDER DEVELOPMENT. THE KEPUB FILE STRUCTURE IS NOT YET FULLY UNDERSTOOD. DO NOT, UNDER ANY CIRCUMSTANCES, DELETE THE FILES FOR THE SOURCE FORMAT. ALWAYS HAVE A NON-KEPUB FORMAT FOR YOUR BOOKS.

Adding Arbitrary CSS

The device driver plugin, through the base KoboTouch driver provided with calibre, has the ability to copy all rules from a specific CSS file into each book as it is uploaded. To support easily maintaining device-specific CSS files, the device driver can copy a CSS file into the correct place to allow adding it to each book. To do this, locate the calibre plugin directory, create a CSS file in there, and ensure that the Modify CSS option is selected in the driver preferences. To locate the calibre plugin directory, open calibre's preferences, choose Miscellaneous, and click the Open calibre configuration directory button. The plugin directory is in there.

The name of the CSS file must be in the format kobo_extra_<DEVICE>.css. The following replacements for <DEVICE> are currently supported (capitalization is important):

  • Kobo Aura H2O — AURAH2O (kobo_extra_AURAH2O.css)
  • Kobo Aura HD — AURAHD (kobo_extra_AURAHD.css)
  • Kobo Aura — AURA (kobo_extra_AURA.css)
  • Kobo Glo — GLO (kobo_extra_GLO.css)
  • Kobo Glo HD — GLOHD (kobo_extra_GLOHD.css)
  • Kobo Mini — MINI (kobo_extra_MINI.css)
  • Kobo Touch — TOUCH (kobo_extra_TOUCH.css)

Please note, this will blindly overwrite any kobo_extra.css you may have already sent to your Kobo device! If you have created the kobo_extra.css file on your Kobo device already and you want to make use of this feature, you must copy kobo_extra.css to the location specified above.

Please also be aware that support for the Aura H2O was only added in Calibre 2.1.0, as such, you'll need to be running Calibre 2.1 or newer for this feature to work.

Hyphenation

Both plugins includes the ability to add a CSS file to each book enabling KePub hyphenation. The standard hyphenation dictionaries provided on Kobo devices are somewhat deficient for some languages; fixing this (or adding your own dictionary) requires a little work and requires that you can create gzipped tarballs (.tgz files). Note that you can only update existing dictionaries, you cannot add new ones.

  1. Somewhere on your computer, create the directory structure usr/local/Kobo/hyphenDicts
  2. Download the LibreOffice (or OpenOffice) hyphenation dictionary for your language
    1. This will be a file with the 'oxt' extension. This is just a ZIP archive with a different name.
  3. Unzip the OXT file and look for the file named as hyph_[language].dic.
  4. Copy the hyphenation dictionary to the hyphenDicts folder without changing the name.
  5. Add the usr folder to KoboRoot.tgz
    1. UNIX users (Linux, Solaris, BSD, Mac) can, from the command line, run tar czf KoboRoot.tgz usr/ from wherever you put the usr directory.
    2. Windows users, you're on your own. It has been reported that using the free 7-Zip archiver you can create .tgz files. See http://gettingeek.com/how-to-create-tarball-compress-to-gzip-under-windows-tar-gz-379.html for more details.
      1. If you follow these directions exactly, your file will have the extension .tar.gz. You can safely rename this to .tgz after the file has been created and ignore the Windows warning about changing file extensions.

Once you have created KoboRoot.tgz copy it to the .kobo directory on your Kobo device, unmount/eject the drive, and unplug the device. You will see a screen indicating that the Kobo device is updating; it is not, but this method takes advantage of the Kobo update mechanism to load the necessary dictionary files. Make sure you keep your version of KoboRoot.tgz around, you will need to re-apply it after every Kobo software update!

Provided languages are:

  1. English (en_US)
  2. French (fr_FR)
  3. Spanish (es_ES)
  4. German (de_DE)
  5. Italian (it_IT)
  6. Portugese (pt_PT)
  7. Dutch (nl_NL)

Please note that even with this feature, hyphenation is not exact. Also remember that you can only update existing dictionaries.

Kobo JavaScript Extraction

Both plugins includes the ability to extract the Kobo JavaScript file from a free Kobo-supplied KePub which is not encumbered by any Digital Restrictions Management (DRM). Enabling this requires a little work:

  1. Obtain a KePub file from Kobo which is provided to you without any Digital Restrictions Management.
    1. Some of Kobo's free eBooks are provided without DRM
    2. In some regions, Kobo devices are sold with free ebooks in the .kobo/kepub/ folder which do not have DRM
  2. Copy the KePub file to the calibre plugins directory
    1. To find the plugins directory, open calibre's preferences, choose Miscellaneous, and click Open calibre configuration directory
    2. Go to the plugins directory
  3. Rename the KePub file to reference.kepub.epub
    1. Windows users must be sure to show file extensions in Windows Explorer to be able to properly rename the file.

Once this file is in place and correctly named this plugin will automatically extract the Kobo JavaScript file, add it to books during conversion, and add appropriate references to content files.

Generated KePub File Copying

On occasion, such as for debugging purposes, you may wish to have easy access to the generated KePub file. There is an option in the device driver plugin which allows you to enter the full, absolute path to a directory where all generated files will be copied to once they have been converted. This directory must:

  1. Be somewhere you can write to
  2. Contain no variables
    1. OS X and Linux users may use a tilde (~) to refer to their home directory instead of typing it in full (/home/jgoguen/calibre-debug may be entered as ~/calibre-debug). Windows users must always enter a full path.

The final path will be a combination of this path and the save template for the plugin. If your debug path is /home/jgoguen/calibre-debug and your save template is {author_sort}/{title} then a KePub file would be copied to, for example, /home/jgoguen/calibre-debug/Camerata, Jo/A History of Vanguard Industries.kepub.epub. Directories will be created as needed.

Contributing

Decided you want to contribute to the development of these plugins? Awesome! You have many options:

  1. Contribute code, whether for existing bug reports, for new bugs that you found, or for new features that you really want to see implemented. To contribute code, you may fork the repository and send a GitHub pull request, or you may send me a PM on MobileRead with a git patch file. A tutorial on creating a git patch can be found here
  2. Submit bug reports on Launchpad. Launchpad bug reports are my to-do list for this plugin; any requests anywhere else are likely to get missed and forgotten and direct emails will be silently ignored. Although I'm happy to discuss the plugin here, I may still ask you to create a bug report; this is so I actually remember to investigate your request!
  3. Test pre-released code from GitHub. Between releases, new code is committed to the GitHub repository and may be installed using directions provided in this file. Based on your testing, you may submit bug reports, provide feedback, think of new feature requests, or just generally enjoy early access (and not necessarily stable code!) to upcoming versions of the plugin.
  4. Translate the plugin on [the plugin's Launchpad Translations page][lptranslation]

You may also prefer to contribute in some other way. You may donate to me via PayPal, contribute to my fundraiser, send BitCoins to 1JwHa28vQ33FzCofRMNgpzfUcNGpoh3hUR, or you may also contribute by answering questions from other people who may have issues, purchasing items from my wishlists (not yet linked, I'll get on that soon-ish), continuing to use this plugin and providing feedback, and probably a few other ways I haven't thought of yet.

[lptranslation]:

Asking Questions

Wondering how to do something? Want to know if something is possible? Ask your question on the MobileRead Forum thread for the device driver plugin or the MobileRead Forum thread for the conversion output format plugin.

Reporting a Bug

Found a bug with this plugin? Great! Please use the Launchpad issue tracker to send me reports of issues or feature requests. Under no circumstances should I be emailed directly unless I have asked to have something sent to me. Any emails I haven't asked for may be silently ignored at my sole discretion. Everyone can benefit from a public bug tracker, but only one person benefits from a private email.

When submitting a bug, I require the following information as a minimum, but any additional information is good to include:

  1. What version of calibre and this plugin you are using. If you are not on the latest version of either, I will require that you update before I accept any bug report.
  2. The full error message reported by calibre, if any.
  3. For issues processing books, whether or not you have a book that you are able to send me that demonstrates the issue. Please follow the directions when submitting a new bug to provide me with a book. Under no circumstances should copyrighted content be uploaded to a public bug.
  4. The calibre debug log.
    1. To get the calibre debug log, click the arrow beside the "Preferences" menu, choose "Restart in debug mode", repeat the same action that caused the issue, and close calibre. The debug log will be automatically displayed to you.

Known Issues

When using Kobo firmware 2.9.0 or later, sideloaded KePub files do not display in-book statistics.

If you have previously installed the device driver plugin in calibre 0.9.18 or earlier, then you upgrade to calibre 0.9.19 or later and can't update the plugin or install the conversion output format plugin, you must manually replace the device driver plugin ZIP file:

  1. Download the latest version of the code.
  2. Generate a new plugin ZIP file.
  3. Shut down calibre entirely.
  4. Open the calibre plugin directory.
    1. Don't know where this is? Before you close calibre, open calibre's preferences, choose Miscellaneous, and click the Open calibre configuration directory button. The plugin directory is in there.
  5. Replace the file named KoboTouchExtended.zip with the new version you created. Please make sure the file name remains the same.

If you get an error similar to the following:

Traceback (most recent call last):
File "site-packages\calibre\gui2\preferences\plugins.py", line 310, in add_plugin
File "site-packages\calibre\customize\ui.py", line 361, in add_plugin
File "site-packages\calibre\customize\ui.py", line 53, in load_plugin
File "site-packages\calibre\customize\zipplugin.py", line 169, in load
File "importlib__init__.py", line 37, in import_module
File "site-packages\calibre\customize\zipplugin.py", line 147, in load_module
File "calibre_plugins.kobotouch_extended.__init__", line 4
<!DOCTYPE html>
^
SyntaxError: invalid syntax

The solution is to go back to the top of this file and read it again.

In some circumstances people have reported that while reading a book uploaded with this plugin they suddenly realize that a large amount of time (two hours or more) has passed without their awareness of the passage of time. The only known solution is to finish reading your current book. Voracious readers tend to report this issue more frequently. Please note, sleep is only a temporary resolution.

Something went wrong with that request. Please try again.