feat(library): Audiobookshelf library check, and the sync fails closed when a library cannot be read (#1519)

Adds an Audiobookshelf provider for the library check, next to the Calibre one. It reads the server over its REST API (title, author, ISBN and ASIN per item), answers for audiobooks, and has its settings in General with a test button that uses the unsaved form values. Read only.

The Hardcover sync and automatic downloads now fail closed when an enabled library cannot be read: the sync skips its cycle and an automatic download holds the request. A library that listed items at the last index and now lists none counts as a failed read. Badges still fail open.
This commit is contained in:
splitsec2 authored and GitHub committed 2026-10-23 00:21:40 -06:00
1 parent 99a6aa206b
commit ea69db3f8e
13 files changed
+835 -28

No files matched your search

+2 -2
View File
@@ -34,7 +34,7 @@ Among matching releases from the winning source, `m4b` outranks `mp3`, then more
Both shelf sync and automatic downloads ask the libraries you have enabled under [Library Check](library-check.md) whether the book is already there, for the content type being requested, and skip it if so. There is no separate switch on this tab. A library that is not enabled, or that does not hold the requested content type, never causes a skip.
The check **fails open**: a library that cannot be read is logged and the book is treated as not owned, so processing continues.
The check **fails closed** here: if an enabled library cannot be read and has not been read before, the sync cycle is skipped and an automatic download is held, and the request stays pending until the next cycle. Skipping is the safe side, because carrying on would request or download books the library already holds. Badges in search results still fail open.
## Settings
@@ -74,6 +74,6 @@ Only one run happens at a time. If a scheduled cycle is in progress, **Sync now*
**Requests appear but nothing downloads** — check **Enable automatic downloads** is on, that **Source priority** contains at least one configured source that supports audiobooks, and look for `no strict match` lines in the log. Lowering **Minimum seeders** helps on quiet trackers; loosening the title or author match is deliberately not an option.
**Books you own keep being added** — enable the library check for the format you request (see [Library Check](library-check.md)) and use its test button. Because the check fails open, a library that cannot be read only produces a log warning rather than blocking the sync.
**Books you own keep being added** — enable the library check for the format you request (see [Library Check](library-check.md)) and use its test button. A library that cannot be read shows up in the log as a skipped cycle.
**Too many requests at once** — the first sync of a large shelf creates one request per book, and the per-user pending limit from **Users & Requests** does not apply to synced requests. Start with a shelf you are happy to see in the queue in full.
+31 -5
View File
@@ -21,6 +21,26 @@ database directly. No HTTP call, no API token, and nothing is ever written back.
A result that matches the library then carries an **In library** badge in the card, list
and compact views, and in the details dialog.
## Audiobookshelf
Shelfmark asks the Audiobookshelf server over its REST API for the title, author, ISBN and
ASIN of every item, and nothing is written back.
1. In **Settings, General**, turn on **Mark audiobooks already in your Audiobookshelf
library**.
2. Set **Audiobookshelf URL** to an address the Shelfmark container can reach (often the
host's LAN IP, not the public URL), for example `http://10.0.0.91:13378`.
3. Paste an **Audiobookshelf API Token** (Audiobookshelf **Settings, Users, your user, API
Token**). Read access is enough.
4. Leave **Audiobookshelf Library IDs** blank to check every book library, or list the IDs
to check (comma separated).
5. Press **Test Audiobookshelf library**. It reports how many items it indexed, using the
values on the form, so it works before you save.
Audiobookshelf titles are often raw folder names such as `Alex Cross 02: Kiss the Girls`.
When the server reports a series for the item, the leading label and number are read as the
series, not as a different book, so a search for `Kiss the Girls` still matches.
## How a match is decided
In order of confidence:
@@ -32,12 +52,18 @@ In order of confidence:
## Behaviour worth knowing
- **It fails open.** If the database cannot be read, Shelfmark logs a warning, reuses the
last successful read if it has one, and otherwise treats the book as not owned. A broken
path degrades the badge, it never blocks a search.
- **It fails open for badges.** If a library cannot be read, Shelfmark logs a warning, reuses
the last successful read if it has one, and otherwise treats the book as not owned. A
broken path degrades the badge, it never blocks a search.
- **It fails closed for anything that acts on the answer.** The Hardcover sync and automatic
downloads would otherwise request or download books the library already holds, so when an
enabled library cannot be read and has not been read before, the sync cycle is skipped and
the request stays pending until the next one. A library that listed items a moment ago and
now lists none is treated as unreadable too, not as an emptied shelf.
- **Results are cached** for ten minutes, and refreshed early when the database file
changes, so a large library costs one read rather than one per search.
- **Ebooks only.** A Calibre library holds ebooks, so the badge answers for ebooks. The
provider interface in `shelfmark/core/library_providers/` takes more libraries: add a
- **Each library answers for its own format.** Calibre holds ebooks and Audiobookshelf holds
audiobooks, so an ebook result is only checked against Calibre and an audiobook against
Audiobookshelf. The provider interface in `shelfmark/core/library_providers/` takes more libraries: add a
module with the `LibraryProvider` shape and list it in `all_providers()`. Nothing above
that function knows which libraries exist.