🔗Progress Sync
Progress sync keeps your KOReader reading position aligned with BookLore. It can pull remote progress when you open or resume a book, and push local progress updates while you read.
Important: Do not run this feature at the same time as KOReader's built-in progress sync for the same source. Both rely on the same underlying KOReader sync mechanisms and can interfere with each other. If you need KOReader's built-in sync, use it for a different source, or disable one of the two sync systems.
🔗What it syncs
Progress sync uses KOReader's sync endpoint and stores document-position snapshots keyed by file hash:
- Pull:
GET /api/koreader/syncs/progress/:book_hash - Push:
PUT /api/koreader/syncs/progress
The synced payload includes:
- Document hash (
document) - Percentage (
percentage) - KOReader progress marker (
progress) - Timestamp (
timestamp) - Device info (
device,device_id)
🔗Enable progress sync
Go to:
Tools → BookLore Sync → What to Sync → Progress Sync
Enable Automatically keep documents in sync.
When disabled, no progress pull or push operations are performed.
🔗Pull behavior
Two toggles control when remote progress is checked:
| Setting | Default | Behavior |
|---|---|---|
| Pull progress on book open | On | Checks remote progress when a book opens (only if Wi-Fi is already connected) |
| Pull progress on resume | On | Checks remote progress after wake/resume (only if Wi-Fi is already connected) |
If there is no remote progress for a book (404 from the endpoint), this is treated as normal and reading continues with local state.
🔗Conflict strategy
When remote and local progress differ, the plugin applies one of three strategies:
- Silently - apply automatically.
- Prompt - ask for confirmation before applying.
- Disable - do not apply that direction.
You configure strategies separately for:
| Direction | Meaning |
|---|---|
| Sync to a newer state | Remote progress is ahead of local |
| Sync to an older state | Remote progress is behind local |
Defaults:
- Newer state: Prompt
- Older state: Disable
🔗Push behavior
Progress is queued and uploaded in these situations:
| Trigger | Behavior |
|---|---|
| Book open | Queues a progress snapshot |
| Book close | Queues a progress snapshot |
| Every N pages | Queues periodic snapshots after the configured number of page turns |
Use Periodically sync every # pages to set the page-turn threshold:
- Minimum value is
1page turn. - To disable periodic updates, turn off Periodic page-turn updates.
- Open/close snapshots are still queued even when periodic updates are disabled.
To avoid excessive API traffic, page-triggered uploads are debounced (25 seconds minimum between pushes).
🔗Set book to read on rating
When Set book to read on rating is enabled, submitting a rating also queues a forced 100% progress state.
This is useful if your workflow treats rating as completion and you want BookLore to mark the book as read immediately.
🔗Queue and retries
Progress updates are stored in the local pending queue and are synced as part of Sync Pending Now.
- In queue summaries, progress items are shown as
P. - Failed progress uploads remain queued and retry on future sync runs.
Use Sync & Cache → View Pending Sessions to inspect pending and synced progress counts.
🔗Interaction with Manual Sync Only
If Manual only (cache everything) is active:
- Progress snapshots are still queued locally.
- No automatic upload is attempted.
- Upload occurs when you run Sync Pending Now.