calibre-hub

Thin API, change events and web UI on top of calibre-server

calibre-hub

A thin layer on top of calibre-server: its own JSON API with session login, change events with hooks, and a web UI. calibre-server stays the only writer of the library.

Status: backend, events and handlers (Phase 2). Spike notes: docs/spike.md. Plan: Redmine epic #8388.

API

All /api/* routes need the session cookie or an API token (Authorization: Bearer <token>, see apiTokenFiles). Unsafe methods also need the header X-Calibre-Hub: 1, unless only a token is sent (a request with a cookie always needs it). A wrong token is a 401, without falling back to the cookie. Field names are camelCase, missing values null.

Users: the login user (login.user, an admin, with the tokens of apiTokenFiles) and the further users of the module, each admin or reader, with their own password file and tokens. Lists, private tags, reading progress and reader settings are per user, the library is shared. A reader reads and downloads the library but writes only their own lists, private tags, progress and reader settings; every other unsafe request, also of routes added later, is a 403 for readers, and so are the library's upkeep pages (trash, duplicates, imports, metadata changes, suggestions, EPUB fixer, conversion, embedding, jobs, cover and metadata searches). A reader syncs lists only with a reader folder of their own (users.<name>.leseliste.target), else sync is the admin's (on or off, it would change the admin's e-reader folder). The users are kept in the state DB (users); one removed from the configuration keeps their data but can't log in.

Route
POST /api/session {user, password} login, sets hub_session (30 days, renewed on use; a new password ends the user's sessions); 429 after 5 failures in 15 min
GET /api/session, DELETE /api/session current user {user, role, sync} (role admin or reader; sync: may sync lists to a reader folder), logout
GET /api/books q (calibre search syntax), kategorie (incl. children), tag (repeatable), ptag (repeatable: the user's private tags, all of them), author, series, sort (title, author, added, modified, published, series, rating), order (asc, desc), offset, limit (≤ 500); returns {total, offset, limit, books}; every book has lists (ids of the reading lists it is in) and privateTags (the user's private tags). With list=<id> only the books of that list and its sublists (direct=1: only its own), sort then listAdded (default, newest first), title, author or series; listPath=Urlaub (listOwner, default the user) does the same for a level that may have no list of its own (404 when nothing is below it)
GET /api/books/:id one book incl. comments, lists and privateTags
GET /api/private-tags the user's private tags with their counts, by name: [{name, count}]
POST /api/private-tags {bookIds | target, add?, remove?} adds and/or removes private tags of the user (target as in bulk edits; books not in the library are left out); at once, no job: {total, changed} (the ids of the books that changed); 400 for a tag both added and removed, a comma in a tag, more than 50 tags or 10,000 books
PUT /api/books/:id/private-tags {tags} the book's private tags of the user become these: {bookId, privateTags}; 404 for an unknown book
GET /api/lists the reading lists the user sees (own ones first, favorites first, by name): [{id, name, description, owner, visibility, sync, favorite, isDefault, count, totalCount, parent, leaf, coverBookIds, createdAt, updatedAt, lastUsedAt, editable, rule, query, queryError}]; coverBookIds: the 4 most recently added books; nested lists: parent the path above ("Urlaub" for "Urlaub/2026", null at the top), leaf the last level, totalCount the distinct books incl. the sublists the user sees; rule/query: a magic shelf's rule and its calibre search (null for a list with books of its own), queryError when that search failed (count 0)
POST /api/lists {name, description?, visibility?, sync?, favorite?, isDefault?, rule?} creates a list (201), with rule a magic shelf (see below); visibility: private (default), readable, editable; names are unique per owner, ignoring case (409); a name is a path, "Urlaub/2026" (levels trimmed, no empty level: 400 for a//b, /a, a/; existing levels keep their spelling)
GET /api/lists/:id, PATCH /api/lists/:id, DELETE /api/lists/:id one list; change any of the fields above (one default list per owner: isDefault: true takes it from the other); a new name renames the sublists along (one updated event each; 409 when one of the new names is taken, 400 below itself); delete returns {list} (owner only, 403) and leaves the sublists
POST /api/lists/:id/books {bookIds} or {target} adds books (target as in bulk edits; unknown ids are left out); returns {list, added} with the ids that were new; 400 for a magic shelf (also removing)
POST /api/lists/:id/books/remove {bookIds} or {target} removes books; returns {list, removed}
PUT, DELETE /api/lists/:id/books/:bookId adds (404 for an unknown book) or removes one book; {list, added} / {list, removed}
GET /api/books/:id/lists the lists the book is in
GET /api/books/:id/cover[?size=thumb] cover image
GET /api/books/:id/download/:format book file; Range requests are passed to calibre-server (Accept-Ranges, Content-Range come back)
GET /api/books/:id/progress reading progress of the user: {latest, devices: [...]}, every device's last position, newest first; an entry is {bookId, device, deviceName, format, position, fraction, source, updatedAt}, latest is the newest (null when the book was never opened)
PUT /api/books/:id/progress {format, position, fraction, device, deviceName?, source?, age?} stores the device's position (replaces its last one unless that is newer; the time is the hub's, minus age in ms for a position read offline and sent later, at most 30 days): position depends on the format (EPUB/MOBI/AZW3/CBZ: CFI from foliate-js, PDF: page number), fraction 0..1, device an id per browser/device, deviceName shown in "Auf … weiterlesen?", source web (default) or koreader
GET /api/progress the newest position per book (progress bars on the covers): [{bookId, fraction, format, updatedAt}]
GET /api/reader/settings the user's reader settings, all fields (defaults for unset ones): {fontFamily, fontSize, lineHeight, justify, hyphenate, margin, maxWidth, columns, flow, animated, theme, override}
PUT /api/reader/settings {field: value, ...} changes the given fields, returns all; fontFamily original, serif, sans, literata, atkinson, source-serif or inter; fontSize 50..300 (%); lineHeight 1.0..2.5; margin 0..20 (% per side); maxWidth 400..2000 (px per column); columns auto, 1 or 2; flow paginated or scrolled; theme light, sepia, dark or eink; justify, hyphenate, animated, override true/false; unknown fields or bad values: 400 {error, field}
DELETE /api/books/:id moves the book to calibre's trash; returns {book} as it was
GET /api/trash books in calibre's trash, newest first: [{id, title, authors, formats, deletedAt}] (id is the id the book had)
POST /api/trash/:id/restore adds the book again from the trash (metadata, files, cover); returns {book} with a new id
GET /api/duplicates[?threshold=] groups of books that look like the same book: {threshold, groups: [{id, bookIds, keepId, sure, score, reasons: [{kind, bookIds, detail}], books: [{book, hasCover, broken, files: [{format, size, tiny}]}]}]}; kind: isbn, file, title, broken; keepId the suggested book to keep; threshold 0.5..1 (default duplicates.threshold)
POST /api/duplicates/merge {keepId, bookIds, dryRun?, lastModified?} merges bookIds into keepId (see Duplicates); dryRun: true returns {plan: {keepId, otherIds, fields: [{field, old, new}], formats: [{format, from, replace}], coverFrom, lists, progress, trash}}, else {merge, book}; 409 when the keeper changed since lastModified
GET /api/duplicates/merges the last merges, newest first: [{id, keepId, otherIds, status: running|done|failed|undone, at, undoneAt, error, fields, formats, coverFrom, listItems, progress, trashed, restored, errors}]
POST /api/duplicates/merges/:id/undo undoes a merge: {merge, books} (the keeper and the books back from the trash, with new ids); 409 when undone already
POST /api/duplicates/ignore {bookIds}, POST /api/duplicates/ignore/remove {bookIds} marks every pair of the books as no duplicates (or not any more): {ignored} / {removed}
GET /api/categories kategorie tree with counts, tags, authors, series, languages, privateTags (the user's own)
PATCH /api/books/:id, POST /api/books edit (lastModified for conflict detection, 409), upload (multipart, admins): a new book goes to the Eingang, 202 {upload: {id, name, status}}; addFormatTo adds the file to that book at once, 200 {book}; 415 for what is no book format
GET /api/intake/uploads/:id what came of an upload: status checking (the analysis or a decision is at it), waiting (in the Eingang below the threshold: entryId, confidence, threshold), duplicate (in the Eingang, looks like a book: entryId, duplicates, titles), imported (book, possibleDuplicates), formatAdded (book), copy (the same file is in the library: duplicates), trashed, gone
POST /api/books/bulk {target, changes} target: {ids: [...]} or {query: {...}, expect?, all?} (filters as in GET /api/books: q, kategorie, tag, ptag, author, series, list, listPath, listOwner, direct; any other key is a 400, and so is a query without any filter unless all: true; with expect the number of books the query matches must be that one, else 409 {expected, found}; deleting by query requires expect; the same holds for every {query} target below); changes: addTags, removeTags, kategorie, series, numberSeries (with series and ids only: series index 1..n in the order of the ids), authors, publisher, languages, rating, pubdate, pubYear (the year, month and day stay); returns 202 {jobId, total}
POST /api/jobs/:id/undo puts back what a finished bulk field change overwrote (each book's own values, remembered per book while the job ran) as a new job, only where a field still has the value the job set (a field changed since stays and shows in the undo job's errors as "changed since, left as it is: "; tags go back as a difference, so tags added since stay); once per job, 409 for a running job, a delete or one undone already; returns 202 {jobId, total}
GET /api/jobs/:id {id, status: running|done|failed, done, total, errors: [{bookId, error}], error?}; jobs are kept in the state DB, a running job resumes after a restart, the last 50 finished ones stay; error when a job stopped early. Also finds classify runs
GET /api/config {fastTags, categoryColumn, classify, metadata} for the web app (fastTags only for older web apps; lists replace them)
GET /api/classify/status {enabled, model, threshold, categories, minCategories, pending, running, lastRun}; only {enabled: false} when off
POST /api/classify {target} target: "unsorted" (default), {ids: [...]} or {query: {...}}; returns 202 {jobId, total}, 409 {categories, minCategories} while the tree is too small
GET /api/suggestions[?status=] latest suggestion per book with book: [{bookId, category, confidence, reason, model, at, status, book}]; status: pending, auto, applied, rejected, none
GET /api/suggestions/:bookId the book's suggestion, 404 without one
POST /api/suggestions/:bookId/accept [{category}] sets the suggested category, or category instead (A/B or A.B); status applied
POST /api/suggestions/:bookId/reject status rejected; the book isn't asked about again until the tree changes
POST /api/suggestions/accept {bookIds} bulk accept; returns {accepted, errors: [{bookId, error}]}
GET /api/metadata/status {enabled, sources, model, nightly, running, changedBooks, lastRun}; only {enabled: false} when off
POST /api/metadata/run {target} target: "incomplete" (default), "all", "authors" (only the author unification), {ids: [...]} or {query: {...}}; returns 202 {jobId, total} (incomplete/all/authors end with the author pass, one more step in total)
GET /api/metadata/changes bookId, since (ISO 8601), reverted (true, false), limit (≤ 5000, default 500); returns {changes: [{id, bookId, field, old, new, source, jobId, at, revertedAt}], books}, newest first
POST /api/metadata/changes/:id/revert sets the old value again; 409 when the field changed since (or the change is reverted already); returns {change, book}
POST /api/metadata/changes/revert {bookIds?, changeIds?} bulk revert (by book: all its active changes); returns {reverted, errors: [{changeId, bookId, error}]}
GET /api/books/:id/metadata/candidates[?q=] for "Metadaten holen": {candidates: [{source, score, sure, url, fields: {title, authors, isbn, publisher, pubdate, languages, comments, series, seriesIndex, coverUrl}}]}, best first; applied through PATCH /api/books/:id and .../cover/from-url
PUT /api/books/:id/cover, POST .../cover/from-file, POST .../cover/from-url set the cover from an image, a book file, a URL
GET /api/books/:id/cover/search[?q=] cover candidates from Open Library and, by ISBN, DNB (no API keys)
GET /api/embed/status {enabled, delay, pending}: books waiting for their files to be rewritten; only {enabled: false} when off
GET /api/convert/status {enabled, target, ignore, targets, running, lastRun} (enabled: added books are converted)
POST /api/convert {target?, books?} converts every book (or those of books, {ids} or {query} as in bulk edits) without target (default the configured one; EPUB, AZW3, MOBI, PDF, DOCX, FB2) that has a format not in ignore; returns 202 {jobId, total}, progress in GET /api/jobs/:id
POST /api/epub-fix {dryRun?, target?} runs the EPUB fixer over every book with an EPUB, or target ({ids} or {query} as in bulk edits); dryRun defaults to true (only checks); returns 202 {jobId, total, dryRun}, progress in GET /api/jobs/:id
GET /api/epub-fix/status {onImport, keepOriginal, running, lastRun}; lastRun is the job with dryRun, from (library, selection, added), booksWithFixes, booksWithProblems, booksFixed and counts per fix and problem (fixes, problems)
GET /api/epub-fix/jobs/:id the same for one run plus results: [{bookId, title, applied, fixes: [{code, file, detail}], problems: [...]}] (books with something to report, at most 500)
GET /api/intake[?band=&duplicates=&skipped=&origin=&library=&after=&offset=&limit=] the Eingang (admins): {enabled, progress: {state, total, done, analysed, current}, total, counts: {bulk, review, unsure, none}, takeable, unsure, skipped, last, pending, thresholds, origins, shares, unwritable, next, entries: [...]}; counts per band of the duplicates filter; state: idle, scanning, analysing; total, done, analysed count the whole list whatever the filters: every book in the Eingang, those looked at, those with a proposal; current is the file at hand; band: bulk, review, unsure, none (a file that failed); duplicates: true those that match a book or a file and stay for a person, sure the sure duplicates, false only the new ones, none of them with what is skipped; skipped=true only the skipped ones; origin: inbox or upload, backlog for what is left of its rows; limit up to 500; the surest first, ties by path, failed files last; after: the page behind this place (next of the page before, a confidence and a path, null on the last), right also while entries leave and the analysis adds some. trashable: the sure duplicates of the band and origin, whatever the duplicates filter, what trashing all of duplicates=sure takes; there it is the same as total. A sure duplicate (sure in the entry) has action: duplicate, isn't skipped, and is one of: sameBook (a proposal with the title and the same authors as the book at bookId after Dedup's normalization), match: file with a bookId whose file is still the same, or match: file with sameAs where the other copy stays: of copies of a file one is never sure, whatever the filter, unless the library has it. The marks are kept up with every pass over the roots, so entries from before them get theirs with the next pass; a copy loses its mark at once when the other file is decided. addFormats never is. takeable: what accepting all of the filter takes (no failed files, no action: duplicate, nothing skipped unless that is the filter), unsure of them below 60; left: {duplicates, failed, skipped}: what of the filter that leaves in the list (of duplicates=sure nothing); skipped of the whole list; last: the newest entry's id; pending: decided, waiting for their job (they left the list); thresholds: per source there is, see below; origins: how many of each source are in the list, whatever the filters. unwritable: {files, folders: [{path, files}]}: what the last pass over the inbox left out because the hub may not move files out of their folder (group srv or write access missing), by folder below the inbox ("" the inbox itself), the fullest first; files 0 when all is well. shares: {kinds: {new, sure, duplicates, skipped, library}, waiting, books}: all numbers of the page's bar and filters, the same whatever band, duplicates, skipped or library say. Each kind is {bulk, review, unsure, none}; every entry counts in exactly one, skipped ones only under skipped, and each number is the total of the list with that filter, so the four kinds of files add up to progress.done. They follow origin. library (the open proposals), waiting (found, not analysed yet: progress.total minus done) and books (of the library, at most a minute old, null until calibre has answered) have no source and don't. An entry: {id, path, name, folder, kind, origin, files: [{path, format, size}], status: analysed|failed, detail, proposal: {title, authors, publisher, pubdate, series, seriesIndex, isbn, languages}, confidence, band, titleConfidence, authorsConfidence, level, source, decided, isbnSource, notes, action: add|addFormats|duplicate, bookId, match, sameAs, addFormats, cover, analysedAt, skipped, error, bookTitle, sameBook, sure}; error: why the last decision came back, with match: calibre and no bookId the books calibre refused it for (Title (Author); …), none of which the hub found; bookTitle: the book at bookId; folder: the file's folder below its root, null in the root and for an upload; nothing of it is in the library yet. library=true shows the open proposals of the repair that have something to write as entries instead (one with only a conflict's note or an unconfirmed candidate stays out until a recheck finds a change, and one whose book calibre no longer has is rejected by itself): id is minus the book id, kind: library, action: update, name the file an import read or empty, bookTitle the title now, proposal the book as it would be, files its formats, status: failed and error when an accept found a field changed; ties by book id, the place in after is a confidence and a book id; adds recheck: {done, total, waiting} while a recheck runs
GET /api/intake/:id one entry with what the analysis changed against the file and everything found: changes: [{field, old, new, source}], candidates: [{source, confidence, fields, url}], the surest first, and bookTitle of the book at bookId; a library entry (negative id): old → new in changes, no candidates, unsureTag
GET /api/intake/:id/file[?format=&first=1] the entry's file to read in (the reader's formats: EPUB, KEPUB, AZW3, MOBI, AZW, FB2, CBZ, PDF; without format the reader's first), as an attachment, read-only. 404 for anything else: no such file in the entry, a file changed since the analysis, a link out of its root. No reading position is kept. first=1: a look is enough. A PDF over 8 MB comes as its first 30 pages, a DjVu (DJVU, DJV, only with first=1) as a PDF of them, 422 when its tools can't; X-Hub-Excerpt-Pages: 30 says when that isn't the whole book. Made once at low priority and kept in intake-peeks/ next to the state DB while the entry is in the list. A PDF the tools can't split, or whose first pages aren't a third smaller than the file (pages that share much get a copy each), comes whole
POST /api/intake/decide {decision, target, candidate?, picks?, title?, authors?, book?} decision: accept (the proposal), file (as in the file), format (one entry's files to the book book), trash, through a queue: 202 {jobId, total}, the job at GET /api/jobs/:id with entry ids as bookId; skip, unskip at once: 200 {total}. target: {ids: [...]}, or to accept all of a filter {query: {band, duplicates, skipped, origin}, last, expect}: last leaves out what the analysis added since, expect is takeable as shown, 409 when it differs. Trash takes the same target on the filter on sure duplicates only ({query: {band, duplicates: "sure", origin}, last, expect}, expect is trashable): each checked at that moment, against the library and the list, so a book changed since the last pass, a library file that isn't the same any more or another copy that left is a 409 too, and the mark goes. A file that can't move comes back with its error, the others go. An entry's accept takes candidate (index) and the edited title and authors, a filter's picks: {entry id: index}. A chosen candidate writes what it says, of the proposal at most title and authors it doesn't have, at the confidence of a hand edit, however low its own: Arthur chose it. Library entries (negative ids, target: {query: {library: true, band}, last, expect} with the newest book id as last) go through the repair: accept, skip, unskip and reject (at once, 200 {total}); file and trash are refused, files and library books don't mix. Accepted rows of the backlog go into import_files and their files stay, those of the inbox and uploads move to _imported/<date>/; action: addFormats adds the formats; a file that turns out to be in the library comes back as action: duplicate, accepting that adds it after all. Trash moves the files, a calibre folder as a whole, to <root>-papierkorb under their path in the root, never overwriting; the hub deletes nothing there. A failed entry is back in the list with its error
POST /api/intake/threshold {origin, value} from this confidence on (60 to 100) the source's entries are accepted after their analysis, those above it now too; null switches it off; 90 until changed. Only action: add, nothing skipped or with an error. Returns {thresholds}
POST /api/import/repair/recheck {run?} plans the books no plan got to, once each: those accepted before (status applied), those whose accept failed, and the books of an import run (default: the last one, not the Eingang's). 202 {books, job}, the job at GET /api/jobs/:id; while one runs it is returned. Its own queue, low priority, standing still while the analysis works; the analysis doesn't wait for it (hub eingang recheck [--run ID]). Hand edits stay; a plan that would write nothing leaves no entry, what was accepted stays accepted; nothing open or rejected and nothing taken in the Eingang is looked at. The proposals show in GET /api/intake?library=true
GET /api/intake/:id/cover the entry's picture (cover in the entry, 404 when it has none)
POST /api/import/cleanup {since?, minId?, maxId?, dryRun?} takes back the folder category and tags the inbox set on the books it added (see The Eingang); dry run (default): {total, entries}, else 202 with the cleanup {id, entries, job}
GET /api/import/cleanups the last 10 cleanups
GET /api/import/cleanups/:id, POST /api/import/cleanups/:id/undo {dryRun?} a cleanup with its backup; undo puts category and tags back (dry run by default, else 202 with undoJob)
/opds, /get/* calibre's OPDS feed for reader apps, HTTP Basic with the login user
/opds, /get/* calibre's OPDS feed for reader apps, HTTP Basic with any hub user
/opds/lists, /opds/lists/:id[?offset=] the reading lists as OPDS catalogs (Basic auth like /opds): a navigation feed of the lists the user sees, and per list an acquisition feed, most recently added first, 100 books per page (next/previous links); files and covers link to /get/*
GET /healthz no auth

calibre-server down: 502 with a JSON body.

Trash: calibre-server moves deleted books to <library>/.caltrash/b/<id> but has no command to list or restore them. The hub reads that folder and restores by adding the book again through calibre-server (metadata from metadata.opf, parsed by calibre-debug, so custom columns survive), which gives it a new id. The folder stays in the trash (the hub can't write the library); restored entries are remembered in the state db and hidden. The module sets the library pref expire_old_trash_after to 100 years, so nothing expires on its own; only emptying the trash in calibre deletes for good. Bulk delete: POST /api/books/bulk with changes: {"delete": true} (not combined with other changes).

Duplicates

GET /api/duplicates (the web app's "Duplikate") looks over the whole library on request (src/calibre_hub/dedup.cr, rules without calibre; duplicates.cr around it). Two books are a pair when they share

  • isbn: an ISBN, from the identifiers or in a download-site title (Anna's Archive's Title -- Author -- … -- 978… -- …, whose author also counts),
  • file: a format file with the same size and MD5 (sizes from metadata.db, read-only; a checksum only for files whose format and size another file has too, cached),
  • title: an author (normalized like the author unification: case, accents, "Last, First") and a title at least duplicates.threshold alike: the same title ignoring case and punctuation 1.0, a subtitle on one side only 0.95, one title the start of the other (3 words or more) 0.9, else the token overlap of the main titles (of the whole titles when both have a subtitle). A book without a known author ("Unknown") needs 0.9 at least and is compared with the books sharing its first title word. Volume 1 and 2 ("Band 1", "Vol. II") or two numbers of one series never pair.

A broken book (no files, or only files below 2 KiB: a download leftover) pairs with a good copy from 0.6 and gets the reason broken. Pairs join into groups; a group is sure with an ISBN, a file or the same title. Pairs marked "Keine Duplikate" (duplicate_ignored) stay out.

The suggested book to keep: not broken, the most complete metadata (known authors, ISBN, publisher, date, language, description, series, cover, tags other than auto-metadaten, category, a clean title), the best format (EPUB, KEPUB, AZW3, MOBI, … PDF …), the most formats, the oldest on a tie.

Merging (POST /api/duplicates/merge, through calibre-server like every write):

  1. Empty fields of the keeper are filled from the others (the best first): authors only instead of unknown ones, series with its number, publisher, date, languages, description, rating, category; identifiers and tags are joined (the keeper's value wins, the auto-metadaten marker stays out). One PATCH with lastModified.
  2. Formats the keeper lacks come from the others (from the library folder, else downloaded); a tiny file of its own is replaced (calibre moves the old file to its trash). Tiny files of the others are not moved.
  3. The cover of another book when the keeper has none.
  4. Reading list memberships (any owner) and reading positions (per device, the newer wins) move to the keeper in the state DB.
  5. The others go to calibre's trash (.caltrash), never deleted.

Every step is logged in duplicate_merges, so a merge can be undone (also a failed one, as far as it got): the others come back from the trash (new ids, their lists and positions with them), the moved formats go to calibre's trash again, the cover goes, the filled fields are set back where nobody changed them since (tags and identifiers lose only what the merge added); what stays is listed in errors.

An upload taken into the library says possibleDuplicates (GET /api/intake/uploads/:id), the inbox logs inbox: #42 looks like #7 (see Duplikate); both use the same detection. What looks like a book of the library waits in the Eingang as a possible duplicate, an upload sent with force is a book of its own; a byte for byte copy from the inbox or an upload goes to _duplicates/.

Reading in the browser

/read/:id[?format=] in the web app reads EPUB, KEPUB, MOBI/AZW3, FB2, CBZ and PDF with foliate-js (vendored, frontend/vendor/foliate-js). The file comes through /api/books/:id/download/:format. The position is saved per user, book and device (reading_progress in the state DB, PUT /api/books/:id/progress); the newest one wins. A book opens where this device stopped; when another device saved a newer position since, the reader asks "Auf <Gerät> bei 71 % – dort weiterlesen?". The table keeps a source per row so KOReader's sync positions can live next to the web reader's later.

Books can be made available offline in the web app (detail or reader). The file then lives in the browser's Cache Storage; a service worker (frontend/src/service-worker.js) keeps the app itself offline, but never caches /api/. Positions read offline wait in the browser and are sent on reconnect with their age, so they don't win over what another device read in the meantime.

The reader's settings (font, size, line height, justification, hyphenation, margins, column width, columns, paginated or scrolled, page-turn animation, colors, "Buchstil überschreiben") are per user and the same on every device (reader_settings in the state DB, GET/PUT /api/reader/settings). Fonts besides the book's and the system's serif/sans come with the web app (Literata, Atkinson Hyperlegible, Source Serif 4, Inter; SIL OFL, from @fontsource) and load only when chosen, no CDN. Absolute font sizes in a book's CSS (font-size: small, 12pt, 1rem) are rewritten while loading so they follow the reader's font size.

Events and handlers

calibre-server stays the only writer. Triggers in metadata.db (installed by calibre-hub-triggers in calibre-server's preStart, a package of its own so a hub update doesn't restart calibre-server) log every change to a book, its links and renamed tags/authors/series into hub_changelog; the hub only reads it. Writes the hub makes itself (inbox) emit events right away. A cheap reconcile (id, last_modified) runs on start and daily at reconcileAt.

Events: {"type": "added|changed|deleted", "bookId": 1, "changes": {"tags": [[old], [new]], "#kategorie": [...]}, "book": {...}, "at": ...}. Reading lists add {"type": "list", "action": "created|updated|deleted|added|removed", "bookId": 0, "listId": 3, "list": {...}, "previous": {...}, "bookIds": [...], "at": ...} (previous: the list before an update; bookIds: the books added or removed, or the books of a deleted list). Every executable in the handlers directory gets each event on stdin, in order per handler. Exit 0 = done, otherwise retry with backoff (10 s up to 1 h); after handlerAttempts the delivery is parked and alertCommand is called with subject and text.

Bundled handler calibre-hub handler leseliste (leseliste.enable): mirrors every reading list with sync into a folder of its own below leseliste.target (<target>/<list name>/Author - Series NN - Title.epub; epub, else pdf, else converted). A book in two synced lists is in both folders; a book that leaves a list (or is deleted) loses its file, a renamed list renames its folder, a list no longer synced loses its files (and its folder once nothing else is in it). Nested lists nest their folders (<target>/Urlaub/2026/…); a synced list takes its sublists along, unsynced ones too. It reads the lists from the state DB, read-only. It only ever removes files it copied itself, recorded in <target>/.calibre-hub-files: what the e-reader keeps next to a book (KOReader's <book>.sdr/ with progress, highlights and notes), files put there by hand and anything from before the record existed stay where they are, also when their book leaves the list. A user with a reader folder of their own (users.<name>.leseliste.target) gets a handler of their own (50-leseliste-<name>, LESELISTE_OWNERS): their synced lists go there and no longer into leseliste.target, whose handler leaves them out (LESELISTE_EXCLUDE_OWNERS). The folder follows the list's owner, also when an admin syncs someone else's list; with such a folder a reader may sync their own lists.

Book files

Embedding (embed.enable, on by default): after an edit of title, authors, author sort, series, tags, description, identifiers, languages, publisher, date, rating or cover (and when a format is added) the hub has calibre-server write the metadata and cover into the book's files (cdb embed_metadata), so a copy on a reader shows what calibre shows. Only formats calibre has a metadata writer for (EPUB, KEPUB, AZW3, MOBI, PDF, DOCX, FB2, RTF, ODT, ...); others are skipped. The queue is in the state DB (embed_queue): every edit moves the book's due time to embed.delay seconds later, so several quick edits end in one rewrite; failures are retried with backoff. A book is not rewritten again for the same metadata unless the cover or its formats changed. calibre embeds nothing into a book without a cover; for those the formats calibre-server embeds into on download (EPUB, AZW3, MOBI, PDF) are downloaded and added back. Covers set outside the hub (calibre's own web UI) don't show in events and are embedded with the next edit.

After a rewrite the hub queues a changed event with formats (the same list on both sides: the files changed), so the reading list copies the file again. Rewriting changes the file's checksum and so the document id KOReader syncs reading positions under (KOSync partial MD5); the checksum a file had before each rewrite is kept in file_checksums (book, format, partial MD5, size, time; the oldest per book and format is the original).

Conversion (convert.enable, off by default): added books (inbox, upload, calibre) without the convert.target format are converted with ebook-convert from a copy downloaded through calibre-server, and the new file is added; the original stays. Sources in convert.ignore (PDF, CBZ, CBR) are never converted from. POST /api/convert (the web app's "Bestand nach EPUB konvertieren" on the Metadaten page) does the same for the whole library, also while automatic conversion is off. Conversions are jobs in a queue of their own, resumed after a restart.

EPUB fixer (like Calibre-Web-Automated's, after kindle-epub-fix): repairs what keeps an EPUB from opening on a reader or from being accepted by Send to Kindle. Conservative: only these, as small text edits on the files that need them, every other entry copied byte for byte; running it again finds nothing.

  • mimetype: missing, wrong, compressed or not the first entry
  • xml-declaration: a content document without one gets the UTF-8 declaration
  • encoding: a declared (or meta charset) encoding that doesn't match UTF-8 content is corrected; a file entirely in a legacy encoding (as declared, else Windows-1252) is converted to UTF-8. Mixed files (UTF-8 with stray Latin-1 bytes) are only reported
  • language: a missing, empty or meaningless dc:language (und, zxx, mul) becomes the book's calibre language (two letters where there are two); without one in calibre it is only reported
  • spine-toc: the spine's toc points at the NCX (added when missing, fixed when it names no manifest item)
  • cover-meta: <meta name="cover"> added or fixed when exactly one image is the cover (cover-image, or an id/file named cover)
  • stray-img: img tags without a source are dropped
  • body-id-link: links (and NCX entries) to a chapter's body id point at the file instead
  • reported only: manifest items or references (href, src) to files that aren't in the EPUB

Like conversions it works on a copy downloaded through calibre-server and adds the repaired EPUB back (add_format); the KOReader checksum before is kept in file_checksums, and before the first repair the EPUB as it is in the library is added as format ORIGINAL_EPUB (epubFix.keepOriginal, on by default; an existing one is never replaced). A changed event with the same formats on both sides tells the reading list to copy the file again. epubFix.onImport (off by default) repairs added books with an EPUB (inbox, upload, calibre) and books that get one (conversion, added format). POST /api/epub-fix (the web app's "EPUBs prüfen" and "EPUBs reparieren" on the Metadaten page) checks the library or a selection, as a dry run unless dryRun: false. Runs are jobs in a queue of their own; what each run found per book is in GET /api/epub-fix/jobs/:id.

Private tags

Tags a user puts on books for themselves ("Urlaub", "für Lea"), kept in the hub's state DB per user and book (private_tags), never in calibre's tags, which every user shares. Nobody else sees them, also not an admin; readers keep them too. A tag keeps the spelling the user has for it already (krimi next to Krimi is Krimi). They filter the library (ptag, several: all of them), bulk targets ({query: {ptag: [...]}}) and lists (?list=&ptag=); a magic shelf can't hold them (its rule is a calibre search). A deleted book's tags are kept aside and come back when it is restored from the trash; a duplicate merge gives the keeper the tags of the others (an undo of the merge leaves them on the keeper). In the web app: "Meine Tags" in the sidebar, the detail (edited in place), the filter chips, the palette's t scope, the commands "Meinen Tag hinzufügen/entfernen" and the bulk bar, which readers get for their lists and private tags.

Reading lists

Lists like playlists, kept in the hub's state DB (calibre Desktop doesn't see them): name, description, owner, visibility (private, readable, editable; matters once there is more than one user), sync to the reader, favorite (shown in the sidebar), default list (the bookmark on the cover) and the books with the time they were added. Only the owner (or an admin) changes a list's name, place, description, visibility, sync, favorite and default flag; others add and remove the books of an editable list (403 otherwise), and a reader never touches sync, neither on nor off. A deleted book leaves its lists and goes back into them when it is restored from the trash.

Nested lists: the name is the path, Urlaub/2026 is the sublist 2026 of Urlaub. A level without a list of that name (Reise above Reise/Meer) is just a folder in the tree; with one it has books of its own. A list's page shows its books and those of its sublists (like categories), "nur direkt" only its own. Renaming a list renames its sublists (and moves their reader folders); deleting it leaves them.

Magic shelves: a list with a rule instead of books of its own, a saved search shown like a list (sidebar, overview, palette, ?list=, OPDS). The rule is conditions joined by AND (match: "all") or OR ("any"), each one {field, value, not?} over tag, kategorie (incl. the categories below it, A/B or A.B), author, series, language (calibre's code, deu) or text (calibre search syntax, like q); at most 20:

{"match": "all", "conditions": [{"field": "tag", "value": "Krimi"},
  {"field": "language", "value": "deu", "not": true}]}

The hub turns it into one calibre search ((tags:"=Krimi") and (not (languages:"=deu")), returned as query) and checks it with calibre when it is saved (400 when calibre can't search it). Its books and count come from that search on every read, so they follow the library; most recently added to the library first, the other list sorts apply. A shelf has no books of its own: adding or removing is a 400, it is never the default list and never synced to the reader (the reader folders skip it, also below a synced list). In a node with lists and shelves the lists' books come first, then the shelves' ones not among them. Only a shelf takes a new rule; a list doesn't become a shelf or the other way round.

Migration: on the first start the books with the tag leseliste.tag (default leseliste) become the list "Leseliste", synced, favorite and default list. The tag stays on the books but is no longer read; the list is the source of truth from then on.

Visibility is set in the web app ("Liste bearbeiten") and stored per list; it matters once there is more than one user. Reader apps can add https://<hub>/opds/lists as a catalog of their own. The reader folder changes from category subfolders to <target>/Leseliste/.

Inbox (inbox.path): files unchanged for inbox.stableSeconds go through the Eingang (see there); A/B/x.epub gets category A.B and tags A, B, tags embedded in the file are dropped. Originals move to _imported/<date>/ once taken, _duplicates/<date>/ when they are byte for byte in the library, _failed/<date>/ when they are no book of their format. Folders the hub can't write are skipped.

The Eingang

The one way into the library: every new book file goes through this list first, with what the hub would write and how sure it is, whichever way it came (the source, origin):

  • Inbox (inbox.path): folders become category and tags, a file leaves the folder when decided.
  • Upload (the web app, hub upload, POST /api/books; admins): waits in uploads/<id>/ next to the state DB, with the tags and category of the form. addFormatTo is the one exception, it brings no new book and goes straight to the book someone chose.

Nothing is written before a decision, Arthur's or the source's threshold. Four ways out: the proposal, as in the file, skipped (stays in the list), or the trash folder (intake.trashDir, by default papierkorb next to the inbox, without an inbox in the state directory): inbox/<path> and upload/<id>/<name> below it, the path below the source, so a file can be brought back. Another file system is fine: the file is copied, compared byte for byte and only then removed at its source, a copy that fails leaves it there and the entry says why. The hub never deletes a book file otherwise: that folder is Arthur's to empty, and an upload taken into the library stays in uploads/_imported/<date>/ like an inbox file. A byte for byte copy of a file of the library needs nobody: it goes to its source's _duplicates/<date>/, unless a decision trashes it.

Every source has its threshold, one button in the Eingang with a line per source: from that confidence on a new book goes to the library by itself, everything else waits. Both start on at 90. What looks like a book of the library, what was skipped or came back with an error always waits. So an EPUB called k.epub, whose name says nothing, waits at 75: the upload tray and hub upload say so, with a link to the Eingang.

A book file goes to calibre-server as one request, and calibre-server takes none over its --max-request-body-size (500 MB of its own, 2048 MB from the module: calibre.maxRequestBodySize). The hub knows that limit and doesn't send a larger file: the entry comes back with file is 915 MB, calibre-server takes at most 500 MB (calibre-server max request body size), in the Eingang „Die Datei hat 915 MB, calibre-server nimmt höchstens 500 MB an“, and the file stays where it is. A further format goes as base64, so it may be three quarters of the limit (and 200 MB at most from the Eingang). Should calibre-server still cut an upload off, the error says that the file may be over its limit.

The inbox is looked at every 30 s, uploads at once, and what they bring is analysed file by file; every 5 minutes the list looks at itself, for files that left or changed and for what the library has by now. The filter „Quelle“ and the source on the rows show only with more than one source in the list. hub eingang shows the same from the terminal.

There was a third source, the backlog of old collections, and a state DB may still have its rows (origin: backlog): they list and decide like the others under „Alle“, no threshold takes them, an accepted file stays where it is and import_files remembers it, a trashed one goes to backlog/ in the trash folder under its whole path, and a file that is gone leaves the list.

What the rules read from a file:

  • A folder with metadata.opf (an old calibre library, Author/Title (12)/) is one book: title, authors, series, tags, identifiers (without the old library's calibre id and uuid), description, languages, publisher and date from the OPF, the cover from cover.jpg, every book file in it a format of that book.
  • Any other book file is a book with what calibre reads from it; files with the same name and another extension in one folder are formats of one book. Tags embedded in the file are dropped. Where calibre has only its own reading of the file name ("Title - Author", the last " - " splits, "and" splits authors), the hub reads the name itself (Meta::FileName, meta_filename.cr): "Carr - Formulas and Theorems in Pure Mathematics 2e (Chelsea, 1970).djvu" becomes "Formulas and Theorems in Pure Mathematics" by Carr, Chelsea, 1970, not the title "Carr" by "Formulas" and "Theorems in Pure Mathematics 2e (Chelsea, 1970)". Which side of " - " is the person: a name score (first names, initials, "Last, First", "A, B" or "A & B" lists, "(ed)", "et al." for a person; digits, articles, title words, lower-case words, publishers for a title); a tie goes the way the folder's other files are named, else calibre's "Title - Author" stays. Read as well: "(Publisher, Year)", "(Year, Publisher)", "(Year)", libgen's "Title-Publisher (Year)" and "_ " for ":", "Author - Series 03 - Title" and "Series 03 - Title - Author", "(Series) Author - Title", "[by Author]", "Title, The", "Publisher - Title", scene names ("Wiley.Title.Sep.2010.eBook-ELOHiM"); abbreviated edition markers ("2e", "2nd ed.", "(4th Edition)") and release junk ("WW", "HQ", "[PDF]", "(German Edition)", ISBNs) go. A title or authors the file brought along (a PDF's info dict, an EPUB's OPF) stay, unless the title says nothing ("chap01 7..24", "100767", "logik-stud.dvi"); publisher, year and series only fill empty fields. Standards ([DIN EN ISO …]) keep calibre's split for the rules (Meta::Norms). A name that can't be read for sure (a tie of the name score without the folder, or no person on either side) is decided, in this order, by the file's own metadata (an author or the title of one reading), a title and author search at the metadata sources (a sure or very good match, Hardcover, DNB, Open Library as configured), and the model (metadata.useModel: it must name the authors of one reading). Still unclear, title and authors stay as calibre read them and the book gets the tag intake.unsureTag (default auto-unsicher) for a manual review. An entry names who decided (decided: name, folder, file, hardcover, dnb, openlibrary, model, unsure).
  • Book formats: EPUB, KEPUB, AZW3, AZW, MOBI, PRC, AZW4, FB2, FBZ, DOCX, ODT, RTF, PDF, DJVU, CHM, CBZ, CBR, CB7, LIT, PDB, TXT. Files without their format's signature (%PDF, PK, BOOKMOBI, ...) go to _failed; hidden files, symlinks and any folder starting with _ or . are skipped, a short file is a book: somebody put it in. Everything else stays where it is. An upload takes every format calibre knows, the name is what the analysis has then.
  • Duplicates are checked against the library before adding: the same file (size, then KOReader's partial MD5 and the first KiB; also files the hub rewrote since, by the checksum kept from before), the ISBN, or the same title with an author in common, normalized like on the duplicates page (case, accents, punctuation, download-site junk; unknown authors are no author in common). Two volumes, two numbers of a series or two editions of a standard are never duplicates, not even with the same ISBN. Unlike the duplicates page, the title must be the same, not only alike. Files without an OPF are checked by file before adding and right after by what calibre read from them: calibre's own title/author check, then ISBN and title/author (the new book is removed again). A duplicate comes back to the list, or adds the formats the library's book lacks (formatAdded). Only books in the library count: files and checksums of books removed since (also those in calibre's trash) match nothing.
  • The state DB keeps what the old imports took (import_files: path, size, mtime, book): the proposals for books of the library go by it, and nothing new comes to it but the accepted rows of the backlog.

While a decision is carried out the metadata, classify, convert and embed hooks pause, so calibre-server only adds books; afterwards they work off the new books' events as for any added book. calibre-server down: the decision waits (20 x 15 s), then stops and what it didn't get to is back in the list. A server error for one book (e.g. calibre's NoSuchBook) while calibre-server answers a plain search fails only that book, which says so in the list.

hub eingang                 # what is in the list, by source, what goes by itself
hub eingang recheck         # plans the books no plan got to, behind the analysis
hub import status           # the same as hub eingang, with the cleanups

Cleanup of an inbox import (POST /api/import/cleanup, hub import cleanup): for books the inbox added (an added event since since, or a book id from minId to maxId) the folder path is read from the hub's events (the first state of the book with a category: the category and tags the inbox set together). The category is cleared when it is still that path, and exactly the tags that are a folder of the path are removed; other tags and a category set since stay. A dry run lists the books; applied, the previous values go to the state DB and /var/lib/calibre-hub/import-cleanup-<id>.json, and undo puts them back. Running it again finds nothing left to do.

hub import cleanup --since 2026-11-02T18:00        # dry run, local time
hub import cleanup --min-id 114 --apply
hub import undo <cleanup id> --apply

Rule flow (Meta::Flow, on import and in the repair): what a book is called is read from the book first, the file name comes last.

  1. ISBN in the book: the first and last pages of PDF, EPUB, DjVu, MOBI, AZW and CHM are read (poppler, djvulibre, calibre's ebook-meta and ebook-convert, which only read the file). A PDF or DjVu without a text layer goes through Tesseract (deu+eng): the first 6 and last 2 pages at most, metadata.ocrJobs books at a time, one thread each, 90 s per page and 5 minutes per book, kept by the file's key in the state DB. Labelled ISBNs near the copyright page count first; ISBNs of the last pages and of lists need their title in the text. A catalog record is only taken when it fits the book's first pages: its title or an author appears there. A German book keeps its title when the record has only the English one, and gets the author and ISBN. Level 1 wins over everything, also the file name, unless the book says it is something else: a title or name that says something and disagrees with the record is a contradiction. The title page settles it (75, reviewed). If the text has the book's own title, the record is something it quotes (a reference list, a foreword's other edition) and isn't used; if nothing settles it, 50 and nothing is written. Junk titles (test, New Page 12, a surname) contradict nothing. A record never removes a person the book has: it adds and spells (Meta::People), only non-persons go, and a record that knows nobody of the book (an edited volume's contributor) changes no author and is reviewed.
  2. Metadata in the file: an EPUB's OPF and calibre's own are trusted, a PDF, DjVu, MOBI or CHM only where a field fits the text or the name. Known junk (Click here to log on, Administrator, Untitled Document) never counts. The repair reads the file an import read, else the library's file directly: calibre-server writes the book's metadata into what it hands out, and metadata that are the book's own again prove nothing.
  3. The file name as described above. What's missing comes from the catalogs when two of them agree, anything less goes to the review with the unsure tag and a suggestion. A format that can't be read falls to this level.

Every decision has a confidence, per title and authors, the book gets the lower one. The table is src/calibre_hub/meta_confidence.cr. From 90 a proposal can be accepted in bulk, from 60 it is reviewed, below 60 the book gets the unsure tag and no title or author is written, also on import. Value, level, source and the ISBN's source are kept per book (metadata_decisions), every change in the change log with its source and level (POST /api/metadata/changes/revert also takes source and level). A field edited by hand never changes: the event log has a change that neither the cleanup's log knows nor an import made right after adding the book. An ISBN is never replaced: another one in the book, or the same one on another book, goes to the review. A level 1 decision that is written binds the metadata run.

Proposals for books of the library: POST /api/import/repair/recheck (hub eingang recheck, "Bestand neu prüfen" in the Eingang) plans the books no plan got to, those accepted before and the last import run's, at low priority behind the analysis, also calibre folders' books by their file name. A conflict the import or a metadata run finds is flagged the same way. They show in the Eingang's filter „Schon in der Bibliothek“.

Title and authors are decided together. Where the book still has what an import left there (calibre's reading of the name, a title that says nothing, a list number, publisher, ripper or edition in the title, a tool, publisher, edition or subtitle as author), a name with an author replaces both, and a file title that is another book than the name goes with its author. A field someone edited stays: it has changed since the book's added event other than by the metadata cleanup's rules (rules, model, authors in the change log). A book with an ISBN keeps its title and authors unless they say nothing. Publisher, year and series only fill empty fields; a publisher in the authors moves to the publisher field.

A reading without an author asks the catalogs (Open Library, DNB, Hardcover) when the book has no author worth keeping or gets another title: an ISBN match, or two catalogs that agree on title and author (with nobody else agreeing on another; at least three words of title), give the authors. Less than that is unsure: the authors become Unknown or stay, the book gets the unsure tag, and the review shows what the catalogs suggest (never applied). So does a file whose own title and author are another book than its name, a new title next to the file's own author, and a book nothing is known of. The metadata run follows the same rule for a book without an author, also on import. A catalog that fails or says "too many requests" (the host then rests until its Retry-After) counts as not knowing; the run goes on. Every change goes to the metadata change log with source rules (revertible on the Metadaten page or with the revert API, the book gets auto-metadaten), and the repaired books get a metadata run (target ids). Unclear names are decided as on import (the file, the sources, the model, else the unsure tag). The proposals (per book: the fields old and new, who decided) are kept in the state DB (import_repairs). Accepting applies a proposal only if the book still has the values the plan saw, else that book fails ("changed since the plan") and the next plan proposes it anew; books accepted or rejected are left out of later plans.

Category suggestions (local model)

classify.enable: a small instruct model suggests a category for books without one, only from the existing category tree (every node of categoryColumn, parents included), never a new one. The hub talks to the Ollama HTTP API at classify.endpoint and nothing else: title, authors, series, tags, publisher, language and the description (HTML stripped, cut at 1200 characters) stay in the home network.

  • Runs: POST /api/classify (the web app's "Unsortierte klassifizieren"), nightly at classify.schedule over the books without a category, and for every book added without one (its added event). Runs are jobs in the state DB like bulk edits, in a queue of their own; a run resumes after a restart.
  • Answer: /api/chat with a JSON schema whose category is an enum of the tree's paths (A/B) or "" for no fit, temperature 0. The hub checks the answer again: unknown categories are discarded (an error for that book), confidence is clamped to 0..1, a broken answer is asked once more.
  • Suggestions at or above classify.autoApplyThreshold are applied to books without a category, together with the tag auto-kategorie (status auto; filter by the tag to check them). The rest wait for review (pending) under "Vorschläge" in the web app and in the book detail. Books that have a category (only with {ids}/{query}) are never changed, only suggested.
  • With fewer than 2 categories nothing is suggested: create a few first (assign them to some books), the status says how many there are. A rejected or no-fit book is asked again once the tree changes.
  • Model down or missing: timeouts and connection errors are retried 3 times with backoff, then the run stops as failed with error; nothing else is affected. A missing model (404) isn't retried.

Setting up the model (in the host's config, not this module):

services.ollama = { enable = true; host = "127.0.0.1"; };  # CPU is enough for a 3B model
ollama pull qwen2.5:3b   # ~2 GB, ~5-20 s per book on a CPU

The hub starts after ollama.service when both run on the same host.

Metadata cleanup

metadata.enable: completes and cleans up the metadata of the whole library, so the category suggestions work on clean titles, authors and ISBNs. Everything is applied automatically; every changed book gets the tag auto-metadaten, and every field change is logged in the state DB with old and new value and can be reverted alone or per book ("Metadaten" in the web app, or the API). Categories and other tags are never touched.

Per book (src/calibre_hub/metadata.cr, rules in meta_rules.cr, sources in meta_sources.cr):

  1. File: the EPUB's OPF (title, authors, ISBN, publisher, date, language, description, series) and ISBNs in the text of its first and last pages; a PDF's info dict and first pages (pdfinfo/pdftotext). The file is downloaded through calibre-server.

  2. Rules: download-site junk ((z-lib.org), [libgen.li], hashes, extensions, underscores), "Autor - Titel" or "Titel - Autor" in the title, "Author - Series 03 - Title", "Unbekannt"/"Unknown" as author, "Last, First", several authors in one field, all caps or all lower case, "Mckeown"/"MCKEOWN" as "McKeown" ("MACDONALD" as "MacDonald", but a "Macdonald" written so stays, and "Mack", "Macy" and the like are names of their own), a broken author sort (one that shares no name with the authors). A "(1974, Tonos)" or "(, TRO Hollis Music, Inc.)" at the end of a title goes, its year and publisher fill an empty date and publisher (source rules, after an edition found by ISBN). When the rules can't tell author from title (Wolken - Atlas) and metadata.useModel is on, the classify model is asked, with title and authors only; its answer is used only if every word in it was in the input.

  3. Sources (metadata.sources, default file hardcover dnb openlibrary): ISBNs first (calibre's, the OPF's, the text's) at every source; title and author search only when no ISBN gave a sure match, and only where the book fits the source:

    • Hardcover (GraphQL, needs metadata.hardcoverTokenFile): editions by ISBN-13/10. A hit of a title search counts only with a title similarity of at least 0.9, the same author (a title alone needs three words, for the cross-check of a book without an author), no placeholder ("Untitled") and no book about the book (summary, workbook), and the work needs an edition in the book's language (language.code3; unknown: German for a German-looking title, else English). ISBN, publisher and date come only from a clear edition (the only one in that language, or the only one of the book's publisher), never from the work (release_year).
    • DNB (SRU, MARC21): a title search only for German books (language deu, or none and a German-looking title), always with per= (surname) and spr=ger.
    • Open Library (books and search API) as the supplement.

    Candidates that aren't this book are dropped: a translation (DNB 041 h, 240 or a translator in 700 $4 trl) when the book isn't German, another language (DNB 041 a), another volume (245 n/p "Vol. 3" for a book "Vol. 1"). A match by the book's own ISBN (calibre's or the OPF's) is always kept: it should be this edition.

  4. Score 0..1: title 60 %, authors 30 %, language and year 10 %. A match by ISBN is sure when the ISBN is in calibre or the OPF, or when the result also agrees with the book (score ≥ 0.5; an ISBN on an ad page doesn't). Catalogs file ISBNs under wrong records, so even the book's own ISBN isn't sure when the record has no word of weight in common with a title that says something (a translation's other title counts as that): the title search runs as if there were no ISBN, and the book keeps it. A text match from 0.75 is accepted.

  5. Merge per field: rules' title and authors, then the file, then the candidates in the field's order of sources (from the comparison runs):

    Field Order
    description Hardcover, DNB, Open Library
    author spelling sure (ISBN) matches first, then Hardcover, DNB, Open Library
    publisher, date, language file, sure matches (DNB, Open Library, Hardcover), rules (title suffix), other matches
    series file, then DNB, Hardcover, Open Library
    subtitle only Hardcover's, added to the same title without one

    Missing fields are filled from an accepted candidate (ISBN, publisher and date only from one edition, not a work with many; a year alone takes the full date of another source with that year); an existing value is replaced only when it is broken, by a sure match that clearly differs (publisher, year, language, a completely different title; never by Hardcover's publisher, year or language), or by the same value spelled better (case, accents, "McKeown", "Le Guin" for "LeGuin", "J. R. R. Tolkien" for "Tolkien"). A sure match naming all of the book's authors and more adds the co-authors. Descriptions are only filled; a cover only for books without one.

  6. One PATCH with lastModified; a book changed meanwhile is tried once more, then on the next run.

Standards (Meta::Norms): a title in the file-name form [DIN EN ISO 11073-10404 2011-07] -- … (calibre split the rest at the last " - " into title and author; also prestandards [DIN V ENV 13606-2 …], amendments [DIN EN ISO 14971 A1 Entwurf 2003-01] as DIN EN ISO 14971/A1 and corrigenda [DIN EN ISO 14971 Berichtigung 1 2007-10]), or exactly a designation like ISO/IEC 42001:2023 by an issuing body, is a standard; books about standards are not. Its fields come from the rules alone, no online source is asked: title DIN EN ISO 11073-10404:2011-07 – Pulsoximeter (the most specific part, "(Entwurf)" for drafts), the full title as description (only when there is none; cut-off titles are completed from the PDF's cover page), author the issuing body (DIN, ISO, IEC, CEN for EN), publisher Beuth for DIN, date from the edition, language from "Englische/Deutsche Fassung", series the standard with the part as number, identifier din/iso/iec, tags Norm, Entwurf and ersetzt (an older edition when a newer final one of the same designation is in the library; the newer one's run tags the older ones too). The tags are logged as the field tags (only these three) and reverted like the other fields.

Author unification: a library-wide pass groups names by a key without case, accents, punctuation, spaces and "Last, First" and renames every variant to the best form: proper case ("McKeown"), then confirmed by Hardcover/Open Library/DNB, then the most books. Logged and revertible like the rest.

Runs are jobs in a queue of their own, resumed after a restart: POST /api/metadata/run, nightly at metadata.nightly (off by default; incomplete books plus the author pass) and for every added book. A new book is classified only after its metadata run is done or failed (at most 30 minutes later). A book whose run times out or gets a server error from calibre-server or a source while calibre-server answers otherwise is tried 3 times more (after 10, 20, 40 s), then marked failed, and the job goes on; calibre-server down (its health check fails) pauses the job until it answers again. Books still queued for a run that no running job has (left by a job that stopped early) get a job of their own on the next pass of the event watcher, so no added book misses its run. "incomplete": books missing ISBN, publisher, date, language or description, or with messy names; books checked in the last 30 days without a failed source are skipped. Requests to a source are spaced by metadata.requestInterval ms (Hardcover allows about 60 a minute, the default 1000 ms keeps below).

Hardcover token: a personal token from https://hardcover.app/account/api (with or without "Bearer "), set as metadata.hardcoverTokenFile and passed as a systemd credential (CALIBRE_HUB_HARDCOVER_TOKEN_FILE; for development also CALIBRE_HUB_HARDCOVER_TOKEN). Without one the source is skipped. When Hardcover rejects it (401/403), the source pauses for an hour, the other sources go on (the book isn't marked for retry) and alertCommand is called with "calibre-hub: Hardcover-Token abgelaufen oder ungültig", at most once a day (kept in the state DB, so a restart doesn't repeat it). A JWT token is also checked for its exp (decoded, not verified): from 14 days before expiry the alert "Hardcover-Token läuft bald ab" comes once a day.

Hardcover sync

hardcoverSync.enable (off by default) keeps Hardcover in step with the hub, in one direction (hub -> Hardcover), with the token and client of the metadata source (same pause and alerts; requests share metadata.requestInterval). Every hardcoverSync.interval seconds (900):

  1. Books -> Hardcover books (read-only): up to hardcoverSync.batch books (100) per run, newest first, are looked up: in the user's own Hardcover library (ISBN, then a very similar title by the same author), then by ISBN, then by a title and author search (like the metadata source: an edition in the book's language). The match (book, edition, pages) is kept in the state DB (hardcover_books, not in calibre); a book not found is looked up again after 30 days, any book again when its ISBN, title or first author changes.
  2. Reading progress -> status: the newest position per book of hardcoverSync.user (default login.user) whose progress changed since the last run. From 2 % the book is "Currently Reading" with the pages read (progress x the edition's pages) in its open read (one is added with today's date as start when there is none); from hardcoverSync.readAt (0.98) it is "Read" and the open read gets the finish date. Only books without a status or with "Want to Read" or "Currently Reading" are changed: "Read", "Paused", "Did Not Finish" and "Ignored" were set on Hardcover and stay (no re-read from the hub). Ratings, reviews, lists and "Want to Read" are never written; nothing comes back from Hardcover.

Private books: a book tagged with one of hardcoverSync.privateTags (Private, privat; any case) is never sent to Hardcover, neither for matching (no title or ISBN) nor its progress. Tagged after it was synced, the hub takes back what it wrote: reads it added and a user book it created are deleted (delete_user_book_read, delete_user_book; what the hub created is kept in hardcover_created), a user book that was there before (e.g. from an import) is kept with its history and set private (privacy_setting_id 3). Without the tag again, that user book gets its earlier privacy back and the book syncs as usual on the next run.

Without hardcoverSync.write (default) it is a dry run: matching runs, the planned writes are logged once per progress change (journalctl -u calibre-hub | grep 'hardcover sync: dry run'), nothing is sent. Switched to write, the books planned in the dry run are planned again and sent.

CLI

hub <command>, or calibre-hub cli <command> (the same client in the server binary, without tui), talks to a running hub with an API token. CALIBRE_HUB_URL (default https://hub.nor.sh); token from CALIBRE_HUB_TOKEN, CALIBRE_HUB_TOKEN_FILE or ~/.config/calibre-hub/token.

hub search 'title:dune or tags:sf' --sort added --order desc --limit 20
hub search --kategorie Fachbuch/Software --tag leseliste --json | jq '.books[].id'
hub show 12
hub download 12 --format pdf -o dune.pdf
hub cover 12 -o cover.jpg
hub categories kategorie
hub edit 12 --title 'Dune' --authors 'Frank Herbert' --series Dune --index 1 \
  --kategorie Roman/SF --pubdate 1965-08-01 --rating 8 --identifier isbn=9780441013593
hub edit 12 --series ''                  # empty clears
hub edit 12 --comments-file - < text.html
hub tag add 12 13 14 sf
hub tag rm 12 sf
hub list ls                              # reading lists; a list by id or name
hub list ls --tree                       # nested lists indented, levels without a list end in /
hub list show Leseliste --sort title
hub list show Urlaub/2026 --direct       # a sublist; --direct: without its sublists' books

hub list create Urlaub --description 'Für den Strand' --sync --favorite --visibility private
hub list add Leseliste 12 13
hub list rm leseliste 12
hub list delete Urlaub --yes
hub upload *.epub --tag neu --kategorie Roman/Krimi   # through the Eingang, says what came of it
hub upload dune.pdf --add-format-to 12
hub bulk --query 'series:"=Dune"' --kategorie Roman.SF --yes
hub bulk --ids 12,13 --add-tags a,b --remove-tags c --series Dune --number-series --yes
hub eingang                              # what waits for a decision, by source
hub eingang recheck                      # the rule flow on the library's books: proposals in the Eingang

Every command has --help and --json (the API's JSON; on errors {error, exitCode, ...}). Exit codes: 0 ok, 1 usage or invalid input, 2 not found, 3 conflict or duplicate, 4 not authorized, 5 server unavailable or failed. edit sends the lastModified it just read; if the book changed in between it writes nothing and shows read, current and wanted values (exit 3). upload lists the books calibre considers duplicates (--force adds anyway). bulk asks before changing unless --yes (required without a terminal) and waits for the job, listing books that failed.

Completion: hub completion fish | source, source <(hub completion bash); the packages install them for hub and calibre-hub.

The repository builds two binaries (targets in shard.yml):

Binary Entry Package What
calibre-hub src/main.cr packages.server serve, scan, install-triggers, handlers, cli (all but tui); what the NixOS module runs
hub src/hub.cr packages.hub the CLI with tui; links bubbletea.cr and its Go library

packages.default has both (for a workstation). The server binary doesn't link bubbletea.cr, so the Go library is not in the server's closure; calibre-hub cli tui points to hub tui. A Claude Code skill for the CLI is in docs/skills/calibre-hub/SKILL.md (copy it to ~/.claude/skills/calibre-hub/).

TUI

hub tui browses and edits the library in the terminal, with the same token as the CLI: the books as a table (title, authors, series, category, tags), newest first, loaded page by page where the cursor goes; the web app's sidebar (lists, categories with "Ohne Kategorie", fast tags, authors, series, tags, languages); a book's detail with its description. Colours follow the terminal's light or dark background.

Keys
j/k, gg/G, Ctrl-d/Ctrl-u, Ctrl-f/Ctrl-b move; a count in front repeats (5j) or picks the line (12G)
Enter open the book; in the sidebar: filter on/off
/ search (calibre syntax, like the web app's search field); n/N next/previous result, in a book the next/previous book
h/l, Tab sidebar and library; in the sidebar l/h unfold/fold
o/O change the sort / reverse it
gl all books (filters off)
q, Esc back (end visual mode, clear the selection, close the book, previous filter); q at the start quits
? all keys (j/k scroll)
e, F2 edit the book: a form for all fields, Tab completes (authors, series, category, tags, languages) or moves on, ↑/↓ field, Ctrl-s saves only the changed fields; on a conflict (409) both versions show, m keeps mine on top of the new one, t takes the new one
Space select or unselect the book; commands then act on the selection
v, V visual mode: moving selects from where it started (on top of what was selected); v or Esc ends it, a command ends it too and the range stays selected
Ctrl-a all matches of the search (sent as {query, expect} with the count shown; 409 when the library changed meanwhile, nothing is changed)
Shift-↓/Shift-↑ extend the selection
. the last change again (command, fast tag, default list) on the selection or the cursor book
T then 1-9 toggle a fast tag (shown at once, taken back if the hub refuses)
t the default list on or off
dd, Del to calibre's trash (asks)
D download the file (EPUB first) into the current directory
u undo the last change
gt calibre's trash: r restores the cursor entry or the selection (Space, v, Ctrl-a; several ask), one after another with the progress in the status line; u deletes them again; q back
:, > command line: Tab completes commands and values (cycles on repeat), ↑/↓ history (kept in $XDG_STATE_HOME/calibre-hub/tui-history)

Commands (:) use the CLI's words, German ones like the web palette, or the web app's action ids (:addTags x): tag add|rm TAGS, kategorie A/B, serie NAME, nummerieren NAME (volumes 1..n in selection order), autor A & B, verlag, sprache deu, eng, bewertung 0-5, jahr 1999 (- clears), list add|rm|new NAME, trash, download [FORMAT], edit, open, search Q, sort FIELD [asc|desc], select all|none, undo, repeat, papierkorb, restore, fehler (the books a job failed for), help, quit, a number jumps to that line. They follow the web app's book actions (frontend/src/lib/book-actions.ts): one book is changed right away (PATCH), a selection as a bulk job (POST /api/books/bulk, progress in the status line); more than 50 books and deleting ask first. Undo: one book back to its previous values (PATCH with the lastModified of the change), lists the other way round, deleted books from the trash, bulk field changes through POST /api/jobs/:id/undo (hubs without it say so). Bulk changes of authors, publisher, languages, rating or year need a hub whose bulk API has those fields. A visual range over rows not loaded yet loads them first (a range over all rows is sent as all matches); all matches can't be numbered, downloaded or undone after deleting (they are in the trash).

Own keys: $XDG_CONFIG_HOME/calibre-hub/tui-keys.json (~/.config/...), in the format of the web app's hub.keymap.vim (the action names of frontend/src/lib/keymap.ts, plus the TUI's own: sort, order, switchPane, searchNext, searchPrev, fastTag, undo, repeat, restore, quit). Own bindings replace the defaults of the actions they name and win over default keys; "leader" sets what <Leader> stands for (default \), the web app ignores it. Actions only the web app has are left out, anything else unknown shows in the status line.

{"leader": ",", "goTrash": ["<Leader>t"], "down": ["j", "<Down>"]}

It is built on bubbletea.cr (Crystal bindings for Bubble Tea, Lip Gloss, Bubbles and Glamour through a Go library), so only the hub binary links libbubbletea_go.so (nix/hub.nix).

Scale: see docs/scale.md (nix build .#scale-test -L).

NixOS module

{
  inputs.calibre-hub.url = "git+ssh://git@git.velalu.qa:53639/arthur/calibre-hub.git";
  # nixosConfigurations.<host>.modules = [ calibre-hub.nixosModules.default ];
  services.calibre-hub = {
    enable = true;
    library = "/srv/books/calibre";
    customColumns.kategorie = { name = "Kategorie"; hierarchical = true; };
    categoryColumn = "kategorie";
    login.passwordFile = "/run/secrets/login";
    sessionKeyFile = "/run/secrets/session-key";
    apiTokenFiles = [ "/run/secrets/hub-token-laptop" ];  # for the CLI
    # further users; role "admin" or "reader" (default)
    # leseliste.target: her own reader folder, her synced lists go there
    users.lea = { role = "reader"; passwordFile = "/run/secrets/hub-lea"; leseliste.target = "/srv/books/reader-lea"; };
    calibre.servicePasswordFile = "/run/secrets/calibre-service";
    # calibre.maxRequestBodySize = 2048;  # MB, the default; calibre-server's own is 500
    inbox.path = "/srv/books/inbox";
    leseliste = { enable = true; target = "/srv/books/reader"; };
    classify = {
      enable = true;
      # defaults: endpoint = "http://127.0.0.1:11434"; model = "qwen2.5:3b";
      # autoApplyThreshold = 0.85; schedule = "03:45" (null: no nightly run); timeout = 300;
    };
    metadata = {
      enable = true;
      # defaults: sources = [ "file" "hardcover" "dnb" "openlibrary" ]; nightly = null; useModel = classify.enable;
      # hardcoverUrl, openLibraryUrl, openLibraryCoversUrl, dnbUrl (the public services); requestInterval = 1000;
      nightly = "03:15";
      hardcoverTokenFile = "/run/secrets/hardcover-token";  # null: no Hardcover
    };
    # with metadata.hardcoverTokenFile; dry run until write = true
    # hardcoverSync = { enable = true; write = false; interval = 900; batch = 100; readAt = 0.98;
    #   privateTags = [ "Private" "privat" ]; };
    # embed = { enable = true; delay = 60; };  # the defaults
    convert = { enable = true; target = "EPUB"; ignore = [ "PDF" "CBZ" "CBR" ]; };
    # duplicates.threshold = 0.85;  # the default
    epubFix.onImport = true;  # keepOriginal = true is the default
    alertCommand = "/run/current-system/sw/bin/notify-admin";
    handlers."20-log" = pkgs.writeShellScript "log" "cat >> /var/lib/calibre-hub/events.log";
  };
}

With calibre.manage (default) the module configures calibre-server on 127.0.0.1 with Basic auth and prepares library, columns and users before each start. Secrets are passed as systemd credentials, so they can stay root-owned. nix flake check runs the specs and a NixOS VM test.

Development

How a change gets out

  1. Build it on a branch (feat/<id>-…, fix/<id>-…).
  2. Show it locally: dev/mock for the surface, dev/up for the real flow.
  3. Arthur tries it and approves it. Nothing goes to dmt before that.
  4. nix flake check, merge, rollout.

Two ways to see a branch

<branch> is optional and means the current checkout; a branch without a worktree gets one in its state directory. Every branch has its own ports, derived from its name, and its own state, so several run side by side.

dev/mock [<branch>]   # the web app against the mock hub, ready in seconds
dev/up [<branch>]     # the hub with a real calibre-server on a demo library
dev/reset [<branch>]  # back to the start; a running stack comes back up
dev/down [<branch>]   # stops both; --all for every branch

dev/mock runs pnpm dev:mock and prints the URL (password hub). The Eingang has scenarios, by URL or with the switcher at the bottom left, which only the mock has: ?scenario=voll (about 500 entries in all parts), analyse (the default, what the e2e tests know), leer, dubletten, rechte (the full Eingang with 107 inbox folders the hub may not write). A scenario holds for the tab, a decision until the page is loaded again. MSW's service worker needs a secure context, so the mock works on this machine only.

dev/up builds the hub in nix develop and the web app, makes the demo files on the first start (cached for all branches) and prints URL and login. State and logs live in ~/_nobackup/calibre-hub-dev/<slug>/, the logins are generated there and are never in the repo.

Option
--vite the web app from Vite with hot reload, against this hub, on its own port
--no-lookups no DNB and Open Library, only the file and its name
--ollama title and author cleaned by the model at 127.0.0.1:11434
--devices also at 100.64.0.2 in the tailnet, for iPhone and Boox

After a change run dev/up again: it rebuilds and restarts what changed.

The demo library has 50 books. The inbox has a case each for the flow (dev/demo.py says which file is for what): sure, to review, unsure, a scan without a text layer, a byte-identical copy (goes to _duplicates by itself), the same book with metadata embedded by calibre since, same title and authors, a possible duplicate, two copies within the Eingang, broken files, a large PDF and a long DjVu for first pages, a calibre folder of an old library. Its folders are categories like on dmt (Roman/Klassiker, Sachbuch), and the Inbox's threshold starts off, so the sure cases wait in the Eingang; the dialog there switches it on. Only titles of old books are real, the text is generated.

How close that is to dmt

calibre-server and the hub run from the units' own values: dev/hub-env.nix evaluates nix/module.nix of the branch with dmt's settings, nix/init.sh prepares the library, the triggers go in, calibre-server gets the module's command line, so a new variable of the module arrives by itself. calibre and the tools come from the nixpkgs dmt runs on (nixpkgs-stable in nixos-config's flake.lock, dev/tools.nix), the repo's own only without a nixos-config.

Each runs in a bubblewrap sandbox in place of the systemd unit, with dmt's paths: /srv/media/ebooks/{calibre,inbox,papierkorb,sync/boox} and /var/lib/calibre-hub, mounted from the state directory. The hub sees /srv/media/ebooks and the library read-only and each path of the module's ReadWritePaths writable as a mount of its own, so a file thrown away is copied there as on dmt, the system read-only, a private /tmp, no /home, no inherited environment, umask 0002, folders 2775. The hub can't write outside its state directory and can't read ~/.config/calibre-hub/token.

What differs from dmt:

  • One host user: calibre-server and hub are not two users in a group srv, so a folder without group write is no obstacle here. To see the Eingang's note on folders the hub may not write, take the write bit itself (chmod 555 <ebooks>/inbox/<folder>). Inside each branch has a user id of its own, because calibre allows one program per user: that keeps branches and calibre Desktop apart.
  • No seccomp, no RestrictAddressFamilies, ProtectKernel* only as far as bubblewrap goes.
  • The Inbox's threshold starts off, on dmt it stands at 90 until changed.
  • Seconds instead of minutes: INTAKE_START 2, INTAKE_INTERVAL 20, INTAKE_TICK 5, INBOX_STABLE 5, EMBED_DELAY 5.
  • CALIBRE_HUB_SECURE_COOKIES=false, plain http, no Traefik in front.
  • No Hardcover: no token, sync off, its URL points nowhere. No API tokens, no alerts, the model off. Lookups at the DNB and Open Library are real, reads only.
  • calibre-server doesn't announce itself by Bonjour (--disable-use-bonjour).
  • The hub is a debug build, on dmt a release build, compiled by the repo's nixpkgs, not dmt's.

iPhone and Boox

dev/up --devices needs Tailscale up on shmoz. The tailnet has no HTTPS certificates (Headscale, CertDomains null), so this is plain http, which the full stack can do: login and the reader work. A forwarder takes 100.64.0.2:<port> to the hub, which itself stays on 127.0.0.1; calibre-server stays local. A plain http page is no secure context, so there is no service worker, no saving for offline, no copy to the clipboard, and an EPUB with obfuscated fonts doesn't open (foliate-js takes SHA-1 from crypto.subtle).

The firewall of shmoz opens no hub port and doesn't trust tailscale0. If a device gets no connection, this in hosts/shmoz opens the hub's ports:

networking.firewall.interfaces.tailscale0.allowedTCPPortRanges = [ { from = 8200; to = 8599; } ];

By hand

nix develop
dev/testlib.sh /tmp/hub-testlib &      # test library + calibre-server on :18083
printf %s hub > /tmp/hub-pw
export CALIBRE_HUB_CALIBRE_URL=http://127.0.0.1:18083 CALIBRE_HUB_CALIBRE_USER=hub \
  CALIBRE_HUB_CALIBRE_PASSWORD_FILE=/tmp/hub-pw CALIBRE_HUB_CUSTOM_COLUMNS=kategorie \
  CALIBRE_HUB_LIBRARY=/tmp/hub-testlib/library CALIBRE_HUB_LIBRARY_ID=library
shards build && bin/calibre-hub serve   # API on 127.0.0.1:8084 (also builds bin/hub)
shards build hub && bin/hub tui         # CLI and TUI only
crystal spec
nix build                               # both binaries; .#server or .#hub alone

After changing dependencies: shards install && crystal2nix.

bubbletea.cr comes from GitHub (leoc/bubbletea.cr, in shard.yml and as the flake input bubbletea-cr; keep both on the same tag). Its Go library comes from the flake (BUBBLETEA_LIB_DIR in the dev shell), so the dev shell needs no Go. crystal2nix writes a bubbletea entry into shards.nix: remove it, nix/hub.nix links the flake input instead and the server package (nix/package.nix) doesn't need it.

Configuration (environment)

Variable Default
CALIBRE_HUB_CALIBRE_URL http://127.0.0.1:8083 calibre-server
CALIBRE_HUB_CALIBRE_USER calibre-hub service user in calibre-server
CALIBRE_HUB_CALIBRE_PASSWORD_FILE required without trailing newline
CALIBRE_HUB_CALIBRE_MAX_BODY_MB none (no check) calibre-server's --max-request-body-size in MB; larger book files aren't sent (module: calibre.maxRequestBodySize, 2048)
CALIBRE_HUB_LIBRARY_ID server default
CALIBRE_HUB_CUSTOM_COLUMNS none comma separated, e.g. kategorie
CALIBRE_HUB_STATE_DB calibre-hub.sqlite snapshot, event queue, bulk jobs, suggestions, reading lists
CALIBRE_HUB_HOST, CALIBRE_HUB_PORT 127.0.0.1, 8084
CALIBRE_HUB_LIBRARY none library path: changelog in metadata.db, read-only
CALIBRE_HUB_SCAN_INTERVAL 900 reconcile interval when triggers are missing
CALIBRE_HUB_RECONCILE_AT 03:30 daily reconcile, local time
CALIBRE_HUB_HANDLERS_DIR none executables called per event
CALIBRE_HUB_HANDLER_ATTEMPTS, _TIMEOUT, _RETRY_DELAY 10, 600, 10 attempts, seconds per run, seconds before the second attempt (doubled with every further one)
CALIBRE_HUB_EVENT_INTERVAL none seconds between two looks for new events of the background work; none: each its own, 2 to 10
CALIBRE_HUB_ALERT_COMMAND none called with subject and text
CALIBRE_HUB_INBOX, _INBOX_STABLE none, 120
CALIBRE_HUB_INTAKE_START, _INTERVAL, _TICK 60, 300, 30 the Eingang: seconds to the first look at the roots after a start, between two looks at them, between two looks at the inbox and uploads (and at a repair the roots wait for)
CALIBRE_HUB_UPLOADS uploads next to the state DB where uploads wait for the Eingang
CALIBRE_HUB_LIST_MIGRATE_TAG leseliste books with this tag become the list "Leseliste" on the first start
CALIBRE_HUB_API_TOKEN_FILES none comma separated files, one API token (≥ 16 characters) each, of the login user
CALIBRE_HUB_USERS none further users, comma separated name:role:passwordFile[:tokenFile|tokenFile…], role admin or reader
CALIBRE_HUB_SYNC_USERS none users with a reader folder of their own, comma separated: readers among them may sync their lists
CALIBRE_HUB_CLASSIFY false true turns on category suggestions (needs CALIBRE_HUB_CATEGORY_COLUMN)
CALIBRE_HUB_CLASSIFY_ENDPOINT, _MODEL http://127.0.0.1:11434, qwen2.5:3b Ollama API and model
CALIBRE_HUB_CLASSIFY_THRESHOLD, _SCHEDULE, _TIMEOUT, _RETRY_DELAY 0.85, 03:45, 300, 5 auto-apply from, nightly run (empty: none), seconds per answer, seconds before the model's second attempt (doubled with the third)
CALIBRE_HUB_METADATA false true turns on the metadata cleanup
CALIBRE_HUB_METADATA_SOURCES, _NIGHTLY, _MODEL, _INTERVAL file,hardcover,dnb,openlibrary, none, false, 1000 sources, nightly run, clean names with the classify model, ms between requests
CALIBRE_HUB_EMBED, _EMBED_DELAY false, 60 embed metadata into the files after edits (the module turns it on), seconds after the last edit
CALIBRE_HUB_CONVERT, _CONVERT_TARGET, _CONVERT_IGNORE false, EPUB, PDF,CBZ,CBR convert added books, target format, formats never converted from
CALIBRE_HUB_DUPLICATES_THRESHOLD 0.85 how alike two titles of one author must be to show as duplicates (0.5..1)
CALIBRE_HUB_EPUB_FIX_ON_IMPORT, _EPUB_FIX_KEEP_ORIGINAL false, true repair the EPUBs of added books, keep the EPUB before the first repair as ORIGINAL_EPUB
CALIBRE_HUB_OPENLIBRARY_URL, _OPENLIBRARY_COVERS_URL, _DNB_URL, _HARDCOVER_URL the public services base URLs (stubs in the VM test)
CALIBRE_HUB_HARDCOVER_TOKEN_FILE, _HARDCOVER_TOKEN none Hardcover API token (file first); none: source skipped
CALIBRE_HUB_HARDCOVER_SYNC, _SYNC_WRITE, _SYNC_USER false, false, CALIBRE_HUB_LOGIN_USER Hardcover sync, write (else dry run), whose progress
CALIBRE_HUB_HARDCOVER_SYNC_INTERVAL, _SYNC_BATCH, _SYNC_READ_AT 900, 100, 0.98 seconds between runs, books looked up per run, progress counted as read
CALIBRE_HUB_HARDCOVER_SYNC_PRIVATE_TAGS Private,privat tags that keep a book off Hardcover
Repository

calibre-hub

Owner
Statistic
  • 0
  • 0
  • 0
  • 0
  • 3
  • 6 days ago
  • November 1, 2026
License

Links
Synced at

Mon, 16 Nov 2026 15:03:56 GMT

Languages