GuidesIntegrationsKoReader

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

🔐
This step requires the feature:api_keys user permissions.

The API key should have at least the feature:koreader_sync permission:

  1. Navigate to the app settings (/settings/app)
  2. Click the API keys tab (/settings/app/api-keys)
  3. Click the Create API key button
  4. Create your key and save the full value after creation

Configure a sync server in KoReader

  1. Open KoReader on your device

  2. Navigate to Progress sync > Custom sync server

  3. 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:

  1. 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)
  2. 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

Reading ListsKobo