jgoguen/calibre-kobo-driver
Fork: 23 Star: 336 (更新于 2024-11-02 12:00:29)
license: GPL-3.0
Language: Python .
An extension of the existing KoboTouch driver provided with Calibre. This plugin allows modifying ePub files to enable extra Kobo features. I am providing code in the repository to you under an open source license. Because this is my personal repository, the license you receive to my code is from me and not my employer.
最后发布版本: v3.7.0 ( 2024-10-20 05:08:38)
Kobo KePub plugins
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 existingKoboTouch
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 theKePub 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 theKePub 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 theKePub 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:
- Page numbers show the number of page turns remaining in the current chapter
instead of the estimated number of pages for the entire book.
- The
KoboTouchExtended
driver has an option to use full-book page numbers instead if you prefer that.
- The
- Reading statistics (time left in this chapter, time for the next chapter, time to complete the book)
- The book title is at the top of each page.
- The chapter title, if any, is at the bottom of each page with the page numbers.
Depending on your preferences, there are some areas where the ePub renderer is a better choice than the KePub renderer:
- Better hyphenation. The KePub renderer sometimes hyphenates words in the wrong place if they have trailing punctuation.
- Full justification works. The KePub renderer sometimes doesn't correctly justify lines with symbols represented by HTML entities (such as em-dashes or ellipses).
- Embedded fonts are better supported.
Installation
To install the current release version of this plugin directly within calibre:
- Open calibre's preferences, choose
Plugins
, and clickGet new plugins
- Select the name of the plugins you want to install from the list of
available plugins and click
Install
- Don't see it? You may already have it installed. Restart calibre and see if you get a notification of a pending update.
- If you want to install more than one plugin, you must select and install them one at a time. Calibre displays a notification asking you to restart after each one, but you can wait until after you've installed all desired plugins to restart calibre.
- Restart calibre
Download
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.
Install from source
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
Usage
To use the device driver plugin after installing:
- Connect your supported Kobo device and wait for calibre to detect it
- Select the books you want to send to your device.
- Click the Send to device button.
To use the conversion output format plugin after installing:
- Choose the book you want to convert to KePub format
- Choose the KEPUB format from the list of output formats (top-right of the conversion window)
- Choose KePub Options from the left menu and make your option selections
- Click OK
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:
- Choose the KePub book you want to convert to a different format
- Choose the desired target format from the list of output formats (top-right of the conversion window)
- Click OK
Adding Arbitrary Styles
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 Aura H2O—AURAH2O (
kobo_extra_AURAH2O.css
) - Kobo Aura H2O Edition 2—AURAH2O_2 (
kobo_extra_AURAH2O_2.css
) - Kobo Aura HD—AURAHD (
kobo_extra_AURAHD.css
) - Kobo Aura—AURA (
kobo_extra_AURA.css
) - Kobo Aura Edition 2—AURA_2 (
kobo_extra_AURA_2.css
) - Kobo Aura One—AURAONE (
kobo_extra_AURAONE.css
) - Kobo Clara—CLARA (
kobo_extra_CLARA.css
) - Kobo Forma—FORMA (
kobo_extra_FORMA.css
) - Kobo Elipsa—ELIPSA (
kobo_extra_ELIPSA.css
) - Kobo Glo—GLO (
kobo_extra_GLO.css
) - Kobo Glo HD—GLOHD (
kobo_extra_GLOHD.css
) - Kobo Libra—LIBRA (
kobo_extra_LIBRA.css
) - Kobo Libra 2—LIBRA_2 (
kobo_extra_LIBRA_2.css
) - Kobo Nia—NIA (
kobo_extra_NIA.css
) - Kobo Sage—SAGE (
kobo_extra_SAGE.css
) - Kobo Mini—MINI (
kobo_extra_MINI.css
) - Kobo Touch—TOUCH (
kobo_extra_TOUCH.css
) - Kobo Touch 2—TOUCH (
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.
Hyphenation
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.
- Somewhere on your computer, create the directory structure
usr/local/Kobo/hyphenDicts
(capitalization is important) - Download the LibreOffice hyphenation dictionary for your language
- You're looking for a file with the
oxt
extension. This is just a ZIP archive with a different name.
- You're looking for a file with the
- Unzip the OXT file (Windows users need to rename the file to change the
extension to
zip
, which requires configuring Explorer to show file extensions, which is a good idea to do anyway) and look for the file named ashyph_[language].dic
. - Copy the hyphenation dictionary to the
hyphenDicts
folder without changing the name. - Add the
usr
folder toKoboRoot.tgz
- UNIX users (Linux, Solaris, BSD, Mac, etc.) can, from a terminal window,
run
tar czf KoboRoot.tgz usr/
from wherever you put theusr
directory. - Windows users, you're on your own. You may be able to use the free 7-Zip
archiver to create .tgz files. See this article for
more details.
- If you follow these directions, your file should have the extension
.tar.gz
. Rename this to.tgz
after creating the file and ignore the Windows warning about changing file extensions.
- If you follow these directions, your file should have the extension
- UNIX users (Linux, Solaris, BSD, Mac, etc.) can, from a terminal window,
run
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:
- United States English (en_US)
- French (fr_FR)
- Spanish (es_ES)
- German (de_DE)
- Italian (it_IT)
- Portuguese (pt_PT)
- Dutch (nl_NL)
Please note that even with this feature, hyphenation is not exact. Also remember that you can update existing dictionaries but not add new dictionaries.
Kobo JavaScript Extraction
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:
- Get a KePub file from Kobo without any Digital Restrictions Management.
- Some of Kobo's free ebooks do not have DRM.
- In some regions, Kobo devices have free ebooks pre-loaded in the
.kobo/kepub/
folder on the device which do not have DRM.
- Copy the KePub file to the calibre plugins directory
- To find the plugins directory, open calibre's preferences, choose Miscellaneous, and click Open calibre configuration directory
- Go to the plugins directory
- Rename the KePub file to
reference.kepub.epub
- Windows users must be sure to show file extensions in Windows Explorer to be able to rename the file.
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.
Generated KePub File Copying
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:
- Be somewhere you can write to
- Contain no variables
- OS X and Linux users may use a tilde (~) to refer to their home directory
instead of typing it in full (
~/calibre-debug
instead of/home/jgoguen/calibre-debug
). Windows users must always enter a full path.
- OS X and Linux users may use a tilde (~) to refer to their home directory
instead of typing it in full (
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.
Contributing
Decided you want to contribute to the development of these plugins?
- Contribute code, whether for existing bug reports, for new bugs that you found, or for new features that you 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.
- Submit bug reports. Bug reports are my to-do list for this plugin; any requests anywhere else may get missed and forgotten and direct emails are ignored. Although I'm happy to discuss the plugins on the MobileRead forums, I may still need you to create a bug report; this is so I actually remember to investigate your request.
- Test pre-released code from Github. Between releases, new code is committed to the Github repository. Submit any bug reports, feedback, feature requests you think of during your testing.
- Translate text. Translations use the Transifex translation project.
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.
Contributors
Thanks goes to these, and others, for their help and contributions to this project (emoji key):
hub2git 📖 |
dchawisher 🐛 |
Byte6d65 🐛 |
NiLuJe 💻 |
David 💻 |
Asking Questions
Wondering how to do something? Want to know if something is possible? Post your question on the MobileRead Forum thread for the relevant plugin:
Reporting a Bug
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:
- What version of calibre and plugin you are using. If you are not on the latest plugin version, you must update before submitting any bug report. If you are not on the latest version of calibre, I may not be able to reproduce the issue.
- The full error message reported by calibre, if any.
- For issues processing books, if you have a book that you are able to include that demonstrates the issue or not. DO NOT UPLOAD EBOOK FILES TO THE ISSUE TRACKER! Under no circumstances are you allowed to upload copyrighted content to a public bug. If I need a book file I'll send you a link to use to upload one.
- The calibre debug log. Bug reports without this get the
needs-information
tag applied.- 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 is automatically displayed to you.
Known Issues
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:
- Download the latest version of the code.
- Generate a new plugin ZIP file.
- Shut down calibre entirely.
- Open the calibre plugin directory.
- 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.
- Replace the file named KoboTouchExtended.zip with the new version you created. Please make sure the filename remains the same.
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.
最近版本更新:(数据更新于 2024-11-02 11:59:54)
2024-10-20 05:08:38 v3.7.0
2024-08-07 21:09:03 v3.6.11
2024-08-06 08:14:34 v3.6.10
2024-08-02 22:12:14 v3.6.9
2024-08-02 08:11:20 v3.6.8
2023-12-01 10:08:22 v3.6.7
2023-09-20 22:22:24 v3.6.6
2023-08-15 22:43:17 v3.6.5
2023-07-17 20:17:16 v3.6.4
2022-07-31 19:45:30 v3.6.3
主题(topics):
calibre, conversion, device-driver, driver-plugin, kobo, kobo-device, python
jgoguen/calibre-kobo-driver同语言 Python最近更新仓库
2024-11-05 15:03:24 Cinnamon/kotaemon
2024-11-05 11:00:51 home-assistant/core
2024-11-04 23:11:11 DS4SD/docling
2024-11-04 10:56:18 open-compass/opencompass
2024-11-04 08:51:21 yt-dlp/yt-dlp
2024-11-02 04:45:40 princeton-vl/infinigen