KoReader Sync
This functionality is gated behind the feature:koreader_sync
and feature:api_keys
user
permissions. To learn more about permissions, see the
permissions guide.
KoReader is an open-source e-reader application that supports a variety of devices. Stump has a built-in implementation of the sync API that enables KoReader to sync read progress with Stump.
How it works
KoReader sync works by sending read progress updates to Stump. When you open and progress through a book in KoReader, it will send a request to Stump with KoReader-specific information for tracking your progress:
- A hash of the book, which is used to identify the book between KoReader and Stump
- The progress string (x-pointer) that KoReader uses for tracking where you are in a book with more precision for DOM-based documents
- A percentage of how far you are through the book
- The ID of the device you are using
Stump will store this information to perform various progress-related lookups when KoReader issues requests.
Setup
To set up KoReader sync with Stump, you need to:
Install KoReader on your device
Enable the KoReader routes on your Stump instance
The KoReader router is disabled by default. To enable it, you need to set the ENABLE_KOREADER_SYNC
environment variable to true
, or directly set enable_koreader_sync=true
in the Stump.toml
configuration file.
See the configuration guide for more information.
Ensure your library generates KoReader-compatible book hashes
To generate hashes on an existing library, you will need to rescan the library via the API in
order to set the regen_hashes
option. This will be improved in the near
future to expose the setting in the UI.
KoReader uses a hash of the book to identify it between KoReader and Stump. Stump implements a port of the KoReader hash generation algorithm, but it will not be generated by default.
To enable this feature, be sure the KoReader-compatible hashes
setting is enabled for a library. For more information, see the scanner configuration guide.
Generate an API key
feature:api_keys
user permissions.The API key should have at least the feature:koreader_sync
permission:
- Navigate to the app settings (
/settings/app
) - Click the
API keys
tab (/settings/app/api-keys
) - Click the
Create API key
button - Create your key and save the full value after creation
Configure a sync server in KoReader
-
Open KoReader on your device
-
Navigate to
Progress sync
>Custom sync server
-
Enter the following URL structure:
http(s)://your-server(:port)(/baseUrl)/koreader/:api_key
Troubleshooting
This section provides explanations for possible errors you may encounter while setting up or using KoReader sync
404 Not Found
If KoReader is recieving 404 errors from your Stump instance while trying to PUT
progress data, it most likely means that the book hash was not generated for that book.
KoReader uses a specific algorithm to generate hashes of books, and it uses this hash as the primary identifer when sending progress payloads to the sync API. So when the hash has not been generated in Stump, the lookup will fail. Follow the steps in the setup guide to generate hashes for your library.
Future improvements
While the KoReader sync integration is functional, there are a few improvements that could be made:
- Device management: The devices are not surfaced on the UI yet. I’d like to add functions to attach friendly names to devices so you can easily identify them (e.g.
Aaron's Kobo Clara
) - Progress translation: The progress data which gets stored is primarily for KoReader’s use, with the exception of the percentage. I’d like to add a feature to translate the x-pointer into a proper epubcfi so the native Stump reader can pick up where you left off
Have you set up KoReader sync with Stump? I’d love to hear about your experience! This is a very new integration, so if you have any feedback or run into any issues, please let me know by opening an issue