Zum Hauptinhalt springen

Der API des Servers Calibre – notiert

Technische Unterlagen und Design. Dieses Dokument bewahrt die Studien und die geplante Architektur. Möglicherweise sind nicht alle beschriebenen Funktionen verfügbar; die Benutzerhandbuch und der Code geben den aktuellen Vorgang an.

Erklärung vom 30. Oktober 2026 aus dem Quellcode von Calibre (src/calibre/srv/), keine Dokumentation: keine vorhanden. Implementiert und durch Tests abgedeckt in Packages/Core/Sources/CalibreKit.


1. Warnung, die vom Betreuer selbst kommt​

Nach Dokumentation für API gefragt /ajax, Kovid Goyal antwortet, dass es sie nicht gibt, dass diese Oberfläche nicht existiert weder öffentlich noch stabil und dass Sie die Quelle lesen müssen. Konsequenzen bleiben erhalten CalibreKit :

  • Alle Dekodierungen sind tolerant – ein fehlendes, unerwartetes oder null führt nie dazu, dass eine Bibliothekseintragung fehlschlägt;
  • Die Art des Servers wird bei der Verbindung erkannt (detectFlavor()), weil Calibre-Web auf alles 404 antwortet /ajax/* und bietet nur OPDS;
  • OPDS bleibt die Fallback-Route, standardisiert und stabil;
  • -Tests frieren die tatsächlichen Byteformen ein, sodass ein Upgrade von Calibre einen Test und nicht die Anwendung unterbricht.

2. Drei Konventionen für die Benennung der Bibliothek​

Dies ist die Hauptfalle dieses API. Es wird einmalig kodiert CalibreClient.url(path:query:libraryInQuery:) und durch vier Tests verifiziert.

RoutenfamilieWohin geht es? library_id
/ajax/…, /get/…Pfadkomponente — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…Abfrageparameter — ?library_id=Calibre_Library
/book-…-last-read-position/…Pfadkomponente, schon wieder

Eingecheckt srv/utils.py : get_library_data() Bett rd.query.get('library_id').


3. Katalog — srv/ajax.py​

StraßeRetouren
GET /ajax/library-info{library_map, default_library} – dient auch als Server-Naturtest
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, Parameter query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3Wörterbuch indiziert nach Kennung, null für ein verbotenes Buch
GET /ajax/book/{id}/{library}die Metadaten eines Buches
GET /ajax/categories/{library}Kategorien der ersten Ebene
GET /ajax/category/{nom}/{library}der Inhalt einer Kategorie, paginiert
GET /ajax/books_in/{cat}/{item}/{library}die Identifikatoren einer Kategorie

Zwei Fallstricke bei der Dekodierung, die beide durch Tests abgedeckt werden:

Die Kennung ist nicht im Betreff enthalten. /ajax/books indiziert sein Wörterbuch nach Kennung und wiederholt es nicht darin. CalibreKit injiziert es durch die userInfo des Decoders.

0101-01-01T00:00:00+00:00 bedeutet „kein Datum“. Es ist der Wachposten UNDEFINED_DATE von Calibre. Naiv entschlüsselt, entsteht ein in der Antike veröffentlichtes Buch. CalibreDate bringt es zurück auf nil.


4. Konvertierung — srv/convert.py​

Dies ist die Entdeckung, die die Architektur verändert: Der Server Calibre konvertiert durch HTTP.

StraßeMethodeRolle
/conversion/book-data/{id}GETEingabeformate, Ausgabeformate, akzeptierte Optionen
/conversion/start/{id}POSTKörper {input_fmt, output_fmt, options} → gibt eine Job-ID zurück
/conversion/status/{job}POST{running, percent, msg} dann der Endzustand; ?abort_job=1 unterbricht

Einzelheiten sind in der Quelle angegeben und alle für die Verwendung von Bedeutung:

  • Nur POST (receive_data_methods = {'POST'}). Ein GET wird abgelehnt.
  • input_fmt muss sein ein Format, das das Buch tatsächlich hat : Der Server erstellt den Quellpfad von dort aus und verwirft den Rest. Er wartet in Großbuchstaben darauf, output_fmt in Kleinbuchstaben.
  • Der Status wird beim ersten Terminal-Lesen verbraucht : del conversion_jobs[job_id] also cleanup() in a finally. Das Fazit kann man nur einmal lesen. Und nur der Benutzer, der den Job in derselben Bibliothek gestartet hat, kann ihn abfragen. CalibreKit.convert(…) schließt die Prüfschleife ab, sodass kein Anrufer darüber nachdenken muss.
  • Das Produktformat wird dem Buch in der Bibliothek hinzugefügt : db.add_format(book_id, fmt, output_path). Die Arbeit ist also nur einmal erledigt und alle Geräte profitieren davon. /get/EPUB/{id}.
  • Rezeptdateien werden abgelehnt (Codeausführung) und eine Liste von Optionen ist vom Netzwerk verboten.

Die komplette Route, z CalibreKit implementiert es:

GET /conversion/book-data/42?library_id=L → entrées : AZW3, PDF ; sorties : epub, mobi, …
POST /conversion/start/42?library_id=L → 17
{"input_fmt":"AZW3","output_fmt":"epub","options":{}}
POST /conversion/status/17?library_id=L → {"running":true,"percent":10,"msg":"Lecture"}
POST /conversion/status/17?library_id=L → {"running":false,"ok":true,"fmt":"epub","size":912345}
GET /get/EPUB/42/L → le fichier, désormais dans la bibliothèque

5. Leseposition und Anmerkungen — srv/books.py​

Calibre synchronisiert bereits die Wiedergabepositionen, serverseitig.

StraßeMethodeRolle
/book-get-last-read-position/{library}/{id}:{FMT}GETbekannte Positionen, nach Gerät
/book-set-last-read-position/{library}/{id}/{FMT}POSTspeichert {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETHighlights und Notizen
/book-manifest/{id}/{FMT}GETServer normalisiert jedes Format im Manifest für seinen eigenen Leser
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETeine standardisierte Buchressource
/book-get-storage/{library}/{id}/{FMT}GETSpeicherstatus

Zwei Konsequenzen für Podbook:

Wir können auf die Zeitungen verzichten .jsonl wird in den ersten Spezifikationen zumindest als Hauptmechanismus beschrieben: Calibre hat bereits eine Position pro Gerät, pro Buch und pro Format. Die Protokolle sind immer noch nützlich für das, was Calibre nicht weiß – die Position im Audio, das Vokabelnotizbuch.

/book-manifest ist eine Abkürzung zum Auswerten. Der Server weiß bereits, wie er jedes Format in eine standardisierte Struktur für seinen Webreader umwandeln kann. Dies deckt einen Teil davon ab BookKit musste genügen. Dies muss vor dem Schreiben des Parsers untersucht werden: Das Format des Manifests ist intern von Calibre und muss daher als Oberfläche behandelt werden /ajax, mit Vorsicht.

srv/kosync.py macht zusätzlich das KOReader-Synchronisationsprotokoll verfügbar (/kosync/users/auth, /kosync/syncs/progress), ein weiterer möglicher Weg, der bereits von anderen Lesern übernommen wurde.


6. Volltextsuche — srv/fts.py​

StraßeMethodeRolle
/fts/searchGETSuche im Text der Bücher, nicht nur Metadaten
/fts/snippets/{book_ids}GETAuszüge mit Kontext
/fts/reindex, /fts/indexing, /fts/disablePOSTIndexsteuerung

Der Index muss serverseitig aktiviert sein. Podbook muss daher nicht die Bibliothek selbst für die globale Suche indizieren – nur für Bücher, die außerhalb von Calibre importiert werden.


7. Schreiben in der Bibliothek — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L führt einen Unterbefehl aus calibredb auf dem Server. Es ist die unterstützte Schreibweise: metadata.db duldet keinen zweiten Redakteur.

Verfügbare Befehle: add, add_format, remove, remove_format, set_metadata, set_custom, add_custom_column, remove_custom_column, custom_columns, annotations, search, list, list_categories, items, notes, data_files, embed_metadata, export, catalog, saved_searches, virtual_libraries, fts_index, fts_search, check_library, backup_metadata, restore_database, clone, trash.

set_custom Mit können Sie den Verarbeitungsstatus von Podbook in eine benutzerdefinierte Spalte schreiben #podbook, sichtbar von Calibre, richtig.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standardmäßig, stabil, in Hello im lokalen Netzwerk angekündigt. Es ist der Rückzug, wenn /ajax ist nicht dabei – insbesondere gegen Calibre-Web.


9. Was sich dadurch für Podbook ändert​

AusgangshypotheseRealität
Ein MOBI-Parser muss geschrieben werdenFalsch ab Version 1: ebook-convert hat schon gereicht
Umbau erfordert Workshop zu MacFalsch : calibre-server wird in HTTP umgewandelt. iPad-Anfragen, der Server funktioniert, die Bibliothek wird bereichert
Podbook muss sein Positions-Timing erfindenTeilweise falsch : Calibre enthält bereits einen pro Gerät
Podbook sollte für die globale Suche indizierenFalsch : /fts/search existiert
metadata.db Nur lesen, kein Schreiben möglichFalsch : /cdb/cmd/… ist die offizielle Schreibroute
Der API /ajax ist eine solide GrundlageFalsch : nicht öffentlich, nicht stabil. Daher die tolerante Dekodierung, Naturerkennung und Fallback OPDS

Immer noch wahr: DRM-geschützte Dateien werden nicht geöffnet und irgendwo muss ein Calibre-Server laufen, damit Konvertierung und globale Suche verfügbar sind.