PayPal: https://paypal.me/jtgoguen
This provides a series of calibre extensions enabling calibre to work with ePub files with Kobo's extra features (called KePub). The following plugins are available:
KoboTouchExtended
: This is a device driver plugin extending the
capabilities of the existing KoboTouch
driver provided with Calibre to
enable extra Kobo features. Please note: modified books are not saved back
into your Calibre library to prevent issues with overwriting library
configurations, so books get converted in transit to your device every time.
In general, the extra time required should not be noticeable.KePub Output
: This is a conversion plugin allowing calibre to convert any
supported input format to KePub.KePub Metadata Writer
: This is a metadata plugin which supports the
KePub Output
plugin. Installing this plugin allows calibre to write KePub
metadata to the book as it's written out in calibre's conversion process. It
serves no purpose without the KePub Output
plugin.KePub Input
: This is a conversion plugin allowing calibre to convert KePub
to any supported output format.KePub Metadata Reader
: This is a metadata plugin which allows calibre to
read KePub metadata when converting a book from KePub format. It serves no
purpose without the KePub Input
plugin.WARNING: 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.
When viewing a KePub book on a Kobo reader, a different viewer displays the contents than an ePub file. The main benefits of using the KePub viewer are:
KoboTouchExtended
driver has an option to use full-book page numbers
instead if you prefer that.Depending on your preferences, there are some areas where the ePub renderer is a better choice than the KePub renderer:
To install the current release version of this plugin directly within calibre:
Plugins
, and click Get new plugins
Install
To download this plugin, either clone the repository or download a snapshot. It is not necessary to download this plugin in this way unless you want to install from source for some reason, such as plugin development.
Please note, installation from source is not supported on Windows or macOS prior
to 11 (Big Sur). Run scripts/build.sh
to generate the ZIP file package for all
plugins. You must have python3
and zsh
installed.
Windows users may be able to use Windows Subsystem for Linux to run the build script, but this is not tested or supported.
Add the resulting ZIP file to calibre:
Preferences
Plugins
Load plugin from file
To use the device driver plugin after installing:
To use the conversion output format plugin after installing:
WARNING: 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.
To use the conversion input format plugin after installing:
The device driver plugin, through the base KoboTouch driver provided with calibre, can copy all rules from a specific CSS file into each book during upload. To support 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 select the Modify CSS option 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
plugins support the following replacements for <DEVICE>
(capitalization is
important):
kobo_extra_AURAH2O.css
)kobo_extra_AURAH2O_2.css
)kobo_extra_AURAHD.css
)kobo_extra_AURA.css
)kobo_extra_AURA_2.css
)kobo_extra_AURAONE.css
)kobo_extra_CLARA.css
)kobo_extra_FORMA.css
)kobo_extra_ELIPSA.css
)kobo_extra_GLO.css
)kobo_extra_GLOHD.css
)kobo_extra_LIBRA.css
)kobo_extra_LIBRA_2.css
)kobo_extra_NIA.css
)kobo_extra_SAGE.css
)kobo_extra_MINI.css
)kobo_extra_TOUCH.css
)kobo_extra_TOUCH_2.css
)Please note, this overwrites 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 calibre plugin directory.
Please also be aware that support for some Kobo devices (the Aura H2O, Libra, Forma, etc.) was not added until later calibre versions than the earliest version required for this plugin. Accordingly, you'll need to be running a calibre version with support for your device for this feature to work for all devices.
The driver plugin and the conversion output plugin 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 update existing dictionaries but you cannot add new ones.
usr/local/Kobo/hyphenDicts
(capitalization is important)oxt
extension. This is just a ZIP
archive with a different name.zip
, which requires configuring Explorer to show file
extensions, which is a good idea to do anyway) and look for the
file named as hyph_[language].dic
.hyphenDicts
folder without changing
the name.usr
folder to KoboRoot.tgz
tar czf KoboRoot.tgz usr/
from wherever you put the usr
directory..tar.gz
. Rename this to .tgz
after creating the file 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'll see a screen
indicating that the Kobo device is updating; it isn't, but this method takes
advantage of the Kobo update mechanism to load the necessary dictionary files
and the Kobo device cannot distinguish between this and a real software update.
Make sure you keep your version of KoboRoot.tgz
around, you'll need to
re-apply it after every Kobo software update.
Provided languages are:
Please note that even with this feature, hyphenation is not exact. Also remember that you can update existing dictionaries but not add new dictionaries.
Both the driver and conversion output plugins include the ability to extract the Kobo JavaScript file from a free Kobo-supplied KePub which is not encumbered by any Digital Restrictions Management (DRM). To avoid distributing any of Kobo's copyrighted work, enabling this requires a little work:
.kobo/kepub/
folder on the device which do not have DRM.reference.kepub.epub
Once this file is in place with the correct name, the driver and conversion output plugins automatically extracts the Kobo JavaScript file, add it to books during conversion, and add appropriate references to content files.
On occasion, such as for debugging purposes, you may wish to have easy access to the generated KePub file. The device driver plugin has an option which allows you to enter the full, absolute path to a directory to copy generated files to after conversion. This directory must:
~/calibre-debug
instead of
/home/jgoguen/calibre-debug
). Windows users must always enter a full
path.The final path is 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 gets copied to, for
example, /home/jgoguen/calibre-debug/Camerata, Jo/A History of Vanguard Industries.kepub.epub
. Directories get created as needed.
Decided you want to contribute to the development of these plugins?
You may also prefer to contribute in some other way. You may contribute by answering questions from other people who may have issues, continuing to use this plugin and providing feedback, assisting with purchasing new Kobo readers for continued testing, and probably other ways I haven't thought of yet.
Thanks goes to these, and others, for their help and contributions to this project (emoji key):
hub2git 📖 |
dchawisher 🐛 |
Byte6d65 🐛 |
NiLuJe 💻 |
David 💻 |
Wondering how to do something? Want to know if something is possible? Post your question on the MobileRead Forum thread for the relevant plugin:
Found a bug with this plugin? Please go to Github and submit a new bug report. Under no circumstances should you send a direct email without first checking with me. At my sole discretion I may not read emails I haven't asked for. Everyone benefits from a public bug tracker, but one person benefits from a private email.
When submitting a bug, I require the following information but any extra information is good to include:
needs-information
tag applied.
If you have 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:
If you get an error like 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 re-read the Known Issues section.