README
Hardcover.app for KOReader
A KOReader plugin to update your Hardcover.app reading status
Installation
- Download and extract the latest release: https://github.com/Billiam/hardcoverapp.koplugin/releases/latest
- Rename
hardcover_config.example.luatohardcover_config.lua - Fetch your API key from https://hardcover.app/account/api (just the part after
Bearer) - Add your API key to the
tokenfield inhardcover_config.lua, between the''quotes. For example:token = 'abcde...fghij' - Install plugin by copying the
hardcoverapp.kopluginfolder to the KOReader plugins folder on your device
Usage
The Hardcover plugin's menu can be found in the Bookmark top menu when a document is active.
Linking a book
Before updates can be sent to Hardcover, the plugin needs to know which Hardcover book and/or edition your current document represents.
You can search for a book by selecting Link book from the Hardcover menu. If any books can be found based
on your book's metadata, these will be displayed.
If you cannot find the book you're looking for, you can tap the magnifying glass icon in the upper left corner and begin a manual search.
Selecting a Hardcover book or edition will link it to your current document, but will not automatically update your reading status on Hardcover. This can be done manually from the update status menu, or using the track progress option.
To clear the currently linked book, tap and hold to the Linked book menu item for a moment.
After selecting a book, you can set a specific edition using the Change edition menu item. This will present a list
of available editions for the currently linked book. No manual edition search is available
Updating reading status
To change your book status (Want To Read, Currently Reading, Read, Did Not Finish) on Hardcover, you open the
Update status menu after linking your book. You can also remove the book from your Hardcover
library using the Remove menu item.
From this menu you can also update your current page and book rating, and add a new journal entry
Tap and hold the book rating menu item to clear your current rating.
Add a journal entry quote
Selecting text to quote:
After selecting document text in a linked document, choose Hardcover quote from the highlight menu to display the
journal entry form, prefilled with the selected text and page.
Automatically track progress
Automatic progress tracking is optional: book status and reading progress can instead be
updated manually from the Update status menu.
When track progress is enabled for a book which has been linked (manually or automatically), page and status updates will automatically be sent to Hardcover for some reading events:
- Your current read will be updated when paging through the document, no more than once per minute. This frequency can be configured.
- When marking a book as finished from the file browser, the book will be marked as finished in Hardcover
- When reaching the end of the document, if the KOReader settings automatically mark the document as finished, the book will be marked as finished in Hardcover. If the KOReader setting instead opens a popup, the book status will be checked ten seconds later, and if the book has been marked finished, it will be marked as finish in Hardcover.
For all documents, but in particular for reflowable documents (like epubs), the current page in your reader may not match that of the original published book.
Some documents contain information allowing the current page to map to the published book's pages. For these documents, the mapped page will be sent to Hardcover if possible.
For documents without these, your progress will be converted to a percentage of the number of pages in the original
published book, with a calculation like:
round((document_page_number / document_total_pages) * hardcover_edition_total_pages).
In both cases, this may not exactly match the page of the published document, and can even be far off if there are large differences in the total pages.
Suggest a book
The suggest a book menu item will display up to 10 books from your Want To Read list in random order. Selecting one of the books in the dialog will start a file search for that book on your device, based on the title. The plugin does not know which books you have or do not have on your device.
The selected books/order are preserved when reopening the dialog (until KOReader is restarted), but you can use the refresh button in the upper left corner to get a new list of 10 books.
Settings
Automatic linking
With automatic linking enabled, the plugin will attempt to find the matching book and/or edition on Hardcover when a new document is opened, if no book has been linked already. These options are off by default.
- Automatically link by ISBN: If the document contains ISBN or ISBN13 metadata, try to find a matching edition for that ISBN
- Automatically link by Hardcover: If the document metadata contains a
hardcoveridentifier (with a URL slug for the book) or ahardcover-editionwith an edition ID, try to find the matching book or edition. (see: RobBrazier/calibre-plugins) - Automatically link by title: If the document metadata contains a title, choose the first book returned from hardcover search results for that title and document author (if available).
Track progress settings
By default, (when enabled) updates will be sent to hardcover at a frequency you can select, no more often than once per minute. If you don't need updates this frequently, and to preserve battery, you can decrease this frequency further.
You can also choose to update based on your percentage progress through a book. With this option, an update will be sent when you cross a percentage threshold (for example, every 10% completed).
Always track progress by default
When always track progress is enabled, new documents will have the track progress
option enabled automatically. You can still turn off Track progress on a per-document basis when this setting is
enabled.
Books still must be linked (manually or automatically) to send updates to Hardcover.
Enable wifi on demand
On some devices, wifi can be enabled on demand without interruption. When this feature is enabled, wifi will be enabled automatically before some types of background API requests (namely updating the initial application cache, and updating your reading progress), and then disabled afterward.
This can improve battery life significantly on some devices, particularly with infrequent page updates.
This feature is not used for all network requests. If wifi has not been manually enabled the following will not work:
- fetching or updating your reading status manually
- manually updating your reading progress from the menu
Confirm changes to book read status
By default, changes to a book's read status (Want to Read, Did Not Finish, etc) will immediately update in Hardcover as soon as you press them. Enable this setting to display a confirmation prompt before those changes are sent.
Compatibility mode
When enabled, book and edition searches will be displayed in a simplified list with minimal data. This mode is the default for KOReader versions prior to v2024.07
Contributors
Similar repos
Languages
Lua
100.0%
README
Hardcover.app for KOReader
A KOReader plugin to update your Hardcover.app reading status
Installation
- Download and extract the latest release: https://github.com/Billiam/hardcoverapp.koplugin/releases/latest
- Rename
hardcover_config.example.luatohardcover_config.lua - Fetch your API key from https://hardcover.app/account/api (just the part after
Bearer) - Add your API key to the
tokenfield inhardcover_config.lua, between the''quotes. For example:token = 'abcde...fghij' - Install plugin by copying the
hardcoverapp.kopluginfolder to the KOReader plugins folder on your device
Usage
The Hardcover plugin's menu can be found in the Bookmark top menu when a document is active.
Linking a book
Before updates can be sent to Hardcover, the plugin needs to know which Hardcover book and/or edition your current document represents.
You can search for a book by selecting Link book from the Hardcover menu. If any books can be found based
on your book's metadata, these will be displayed.
If you cannot find the book you're looking for, you can tap the magnifying glass icon in the upper left corner and begin a manual search.
Selecting a Hardcover book or edition will link it to your current document, but will not automatically update your reading status on Hardcover. This can be done manually from the update status menu, or using the track progress option.
To clear the currently linked book, tap and hold to the Linked book menu item for a moment.
After selecting a book, you can set a specific edition using the Change edition menu item. This will present a list
of available editions for the currently linked book. No manual edition search is available
Updating reading status
To change your book status (Want To Read, Currently Reading, Read, Did Not Finish) on Hardcover, you open the
Update status menu after linking your book. You can also remove the book from your Hardcover
library using the Remove menu item.
From this menu you can also update your current page and book rating, and add a new journal entry
Tap and hold the book rating menu item to clear your current rating.
Add a journal entry quote
Selecting text to quote:
After selecting document text in a linked document, choose Hardcover quote from the highlight menu to display the
journal entry form, prefilled with the selected text and page.
Automatically track progress
Automatic progress tracking is optional: book status and reading progress can instead be
updated manually from the Update status menu.
When track progress is enabled for a book which has been linked (manually or automatically), page and status updates will automatically be sent to Hardcover for some reading events:
- Your current read will be updated when paging through the document, no more than once per minute. This frequency can be configured.
- When marking a book as finished from the file browser, the book will be marked as finished in Hardcover
- When reaching the end of the document, if the KOReader settings automatically mark the document as finished, the book will be marked as finished in Hardcover. If the KOReader setting instead opens a popup, the book status will be checked ten seconds later, and if the book has been marked finished, it will be marked as finish in Hardcover.
For all documents, but in particular for reflowable documents (like epubs), the current page in your reader may not match that of the original published book.
Some documents contain information allowing the current page to map to the published book's pages. For these documents, the mapped page will be sent to Hardcover if possible.
For documents without these, your progress will be converted to a percentage of the number of pages in the original
published book, with a calculation like:
round((document_page_number / document_total_pages) * hardcover_edition_total_pages).
In both cases, this may not exactly match the page of the published document, and can even be far off if there are large differences in the total pages.
Suggest a book
The suggest a book menu item will display up to 10 books from your Want To Read list in random order. Selecting one of the books in the dialog will start a file search for that book on your device, based on the title. The plugin does not know which books you have or do not have on your device.
The selected books/order are preserved when reopening the dialog (until KOReader is restarted), but you can use the refresh button in the upper left corner to get a new list of 10 books.
Settings
Automatic linking
With automatic linking enabled, the plugin will attempt to find the matching book and/or edition on Hardcover when a new document is opened, if no book has been linked already. These options are off by default.
- Automatically link by ISBN: If the document contains ISBN or ISBN13 metadata, try to find a matching edition for that ISBN
- Automatically link by Hardcover: If the document metadata contains a
hardcoveridentifier (with a URL slug for the book) or ahardcover-editionwith an edition ID, try to find the matching book or edition. (see: RobBrazier/calibre-plugins) - Automatically link by title: If the document metadata contains a title, choose the first book returned from hardcover search results for that title and document author (if available).
Track progress settings
By default, (when enabled) updates will be sent to hardcover at a frequency you can select, no more often than once per minute. If you don't need updates this frequently, and to preserve battery, you can decrease this frequency further.
You can also choose to update based on your percentage progress through a book. With this option, an update will be sent when you cross a percentage threshold (for example, every 10% completed).
Always track progress by default
When always track progress is enabled, new documents will have the track progress
option enabled automatically. You can still turn off Track progress on a per-document basis when this setting is
enabled.
Books still must be linked (manually or automatically) to send updates to Hardcover.
Enable wifi on demand
On some devices, wifi can be enabled on demand without interruption. When this feature is enabled, wifi will be enabled automatically before some types of background API requests (namely updating the initial application cache, and updating your reading progress), and then disabled afterward.
This can improve battery life significantly on some devices, particularly with infrequent page updates.
This feature is not used for all network requests. If wifi has not been manually enabled the following will not work:
- fetching or updating your reading status manually
- manually updating your reading progress from the menu
Confirm changes to book read status
By default, changes to a book's read status (Want to Read, Did Not Finish, etc) will immediately update in Hardcover as soon as you press them. Enable this setting to display a confirmation prompt before those changes are sent.
Compatibility mode
When enabled, book and edition searches will be displayed in a simplified list with minimal data. This mode is the default for KOReader versions prior to v2024.07
Similar repos
Contributors
Languages
Lua
100.0%