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
nullfü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.
| Routenfamilie | Wohin 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ße | Retouren |
|---|---|
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,3 | Wö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ße | Methode | Rolle |
|---|---|---|
/conversion/book-data/{id} | GET | Eingabeformate, Ausgabeformate, akzeptierte Optionen |
/conversion/start/{id} | POST | Kö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_fmtmuss 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_fmtin Kleinbuchstaben.- Der Status wird beim ersten Terminal-Lesen verbraucht :
del conversion_jobs[job_id]alsocleanup()in afinally. 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ße | Methode | Rolle |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | bekannte Positionen, nach Gerät |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | speichert {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | Highlights und Notizen |
/book-manifest/{id}/{FMT} | GET | Server normalisiert jedes Format im Manifest für seinen eigenen Leser |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | eine standardisierte Buchressource |
/book-get-storage/{library}/{id}/{FMT} | GET | Speicherstatus |
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ße | Methode | Rolle |
|---|---|---|
/fts/search | GET | Suche im Text der Bücher, nicht nur Metadaten |
/fts/snippets/{book_ids} | GET | Auszüge mit Kontext |
/fts/reindex, /fts/indexing, /fts/disable | POST | Indexsteuerung |
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
| Ausgangshypothese | Realität |
|---|---|
| Ein MOBI-Parser muss geschrieben werden | Falsch ab Version 1: ebook-convert hat schon gereicht |
| Umbau erfordert Workshop zu Mac | Falsch : calibre-server wird in HTTP umgewandelt. iPad-Anfragen, der Server funktioniert, die Bibliothek wird bereichert |
| Podbook muss sein Positions-Timing erfinden | Teilweise falsch : Calibre enthält bereits einen pro Gerät |
| Podbook sollte für die globale Suche indizieren | Falsch : /fts/search existiert |
metadata.db Nur lesen, kein Schreiben möglich | Falsch : /cdb/cmd/… ist die offizielle Schreibroute |
Der API /ajax ist eine solide Grundlage | Falsch : 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.