#KOReader calibre plugin
Hi,
This project has moved to GitHub. This repository on sourcehut will not be updated any longer.
Harm
A calibre plugin to synchronize metadata from KOReader to calibre.
KOReader creates sidecar files that hold read progress and annotations. This plugin reads the data from those sidecar files and updates calibre's metadata based on them. It is inspired by the Kobo Utilities plugin, that synchronizes reading progress between the original Kobo firmware (“Nickel”) and custom columns in calibre.
Note that at the moment the sync is one-way—from the KOReader device to calibre—and only works for USB and wireless devices. For the latter, you'll need KOReader 2021.04 or newer.
Releases will also be uploaded to this plugin thread on the MobileRead Forums. If you are on there as well, please let me know what you think of the plugin in that thread.
#Using this plugin
#Download and install
- Go to your calibre's “Preferences” > “Plugins” > “Get new plugins” and search for “KOReader Sync”
- Click “Install”
- Restart calibre
#Alternatively
- Download the latest release from here.
- Go to your calibre's “Preferences” > “Plugins” > “Load plugin from file” and point it to the downloaded ZIP file
- Restart calibre
#Setup
- Pick and choose the metadata you would like to sync and create the appropriate columns in calibre. These are your options:
- A “Floating point numbers” column to store the current percent read, with “Format for numbers” set to
{:.0%}.
- An “Integers” column to store the current percent read.
- A regular “Text” column to store the location you last stopped reading at.
- A “Rating” column to store your rating of the book, as entered on the book's status page.
- A “Long text” column to store your review of the book, as entered on the book's status page.
- A “Long text” column to store your bookmarks and highlights of the book, with “Interpret this column as” set to “Plain text formatted using markdown”. (Highlights are an unordered list with their metadata in an HTML comment.)
- A regular “Text” column to store the reading status of the book, as entered on the book status page (“Finished”, “Reading”, “On hold”).
- A “Date” column to store the date on which the first highlight or bookmark was made. (This is probably around the time you started reading.)
- A “Date” column to store the date on which the last highlight or bookmark was made. (This is probably around the time you finished reading.)
- A regular “Text” column to store the MD5 hash KOReader uses to sync progress to a KOReader Sync Server. (“Progress sync” in the KOReader app.) This might allow for syncing progress to calibre without having to connect your KOReader device, in the future.
- A “Long text” column to store the raw contents of the metadata sidecar, with “Interpret this column as” set to “Plain text”.
- Add “KOReader Sync” to “main toolbar when a device is connected”, if it isn't there already.
- Right-click the “KOReader Sync” icon and “Configure”.
- Map the metadata you want to sync to the newly created calibre columns.
- Click “OK” to save your mapping.
- From now on just click the “KOReader Sync” icon to sync all mapped metadata for all books on the connected device to calibre.
#Things to consider
- The plugin overwrites existing metadata without asking. That usually isn’t a problem, because you will probably only add to KOReader’s metadata. But be aware that you might lose data in calibre if you’re not careful.
#Supported devices
This plugin has been tested successfully with:
- Kobo Aura connected over USB, which means it will probably work for all comparable Kobo devices (
KOBO and KOBOTOUCH)
- Kobo Aura H2O over USB (
KOBOTOUCHEXTENDED, see #6 for details)
- Kobo Aura connected wirelessly, which means it will probably work for all calibre connect devices (
SMART_DEVICE_APP)
- A connected folder (
FOLDER_DEVICE)
- Kindle Keyboard (
KINDLE2, see #1 for details)
- Tolino Vision 4 HD (
TOLINO, see this comment for details)
- PocketBook Touch Lux 5 (which uses the
POCKETBOOK626 driver, so it will probably work for all comparable PocketBook devices, see #8 for details)
- PocketBooks that use the
POCKETBOOK622 driver
This plugin is not compatible with:
MTP_DEVICE (see #2 for details)
#Issues
If you encounter any issues with the plugin, please submit them here.
#Acknowledgements
#Contributing to this plugin
#Notes & Tips
- My first attempt was actually to sync calibre with KOReader's read progress through the progress sync plugin and a sync server. Read here why that did not work. This plugin might actually make that possible now by allowing you to store KOReader's MD5 hash in calibre...
- calibre allows you to auto-connect to a folder device on boot, which greatly speeds up your workflow when testing. You can find this under “Preferences” > “Tweaks”, search for
auto_connect_to_folder. Point that to the dummy_device folder in this repository. (I have included royalty free EPUBs for your and my convenience.)
- If you're testing and don't actually want to update any metadata, set
DRY_RUN to True in __init__.py.
- I work in PyCharm, which offers a remote debugging server. To enable that in this plugin, set
PYDEVD to True in __init__.py.You might need to change sys.path.append in action.py.
- The supported device drivers can be found in the
supported_devices list at line 387 in action.py. Adding a new type here is the first step to adding support, but make sure all features are tested thoroughly before releasing a version with an added device
#Downloading dependencies
#Testing in calibre
Make sure you have the dependencies. Then:
Alternatively, build a release and load that:
#Building a release
Make sure you have the dependencies and have set the correct version number in __init__.py, pluginIndexKOReaderSync.txt and Makefile. Also update Changelog. Then:
#Debugging a release
- Download the required release from here
- Add it to calibre by running this in your terminal:
calibre-customize -a "KOReader Sync vX.X.X-alpha.zip", where X.X.X refers to the version you downloaded
- Start calibre in debug mode with
calibre-debug -g
- Configure the KOReader plugin as described here
- Connect your device
- Run the sync by clicking the KOReader icon in your toolbar
- Check the details of the message when it's done if any/all books have been synced correctly
- Check your (custom) columns for one of those books to see if their contents are what they should be
- Check the output in your terminal for lines containing
koreader to see what it did
#Changelog
All notable changes to this project will be documented here.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
#Changed
- Use calibre's built-in UTC timezone (source), because
tzdata isn't available on Windows (see #13)
#Added
- Calculate first and last bookmark date columns
#Added
#Added
#Changed
- Don't break for unknown device class, but try to sync anyway
#Added
- Enable
TOLINO, for real this time
#Added
#Added
#Added
#Added
#Fixed
- Skip metadata sidecars that cannot be decoded (e.g. from a very old version of KOReader)
#Changed
- Use
path instead of lpath for book paths to go around MTP_DEVICE lowercasing the latter
- Disable
MTP_DEVICE because it cannot be supported (see #2)
#Added
#Added
#Added
- Support for highlights and bookmarks
- Counts to post-sync alerts
- An
.editorconfig and .pylintrc to define code layout
#Changed
README.md to reflect current state of development
#Fixed
#Added
#Added
- Support for
KOBO and KOBOTOUCH devices
#Added
- Support for all possible filetypes
- Variables to easily enable a dry-run when debugging and remote debugging
#Added
- Everything needed for a first working version of the plugin
dummy_device and dummy_library for easy debuggingMakefile to build a plugin release as a ZIP fileTODO to keep to-dos in one placeenvironment.yml, in case anyone wants to recreate my Conda environment- This
README.md