Prejsť na hlavný obsah

API servera Calibre — záznam

Technická a dizajnová dokumentácia. Tento dokument obsahuje štúdie a navrhovanú architektúru. Nie všetky opísané funkcie sú nevyhnutne dostupné; Používateľská príručka používateľská príručka a kód špecifikujú aktuálnu operáciu.

Záznam z 30. októbra 2026 zo zdrojového kódu Calibre (src/calibre/srv/), žiadna dokumentácia: žiadna neexistuje. Implementované a pokryté testami v Packages/Core/Sources/CalibreKit.


1. Upozornenie, ktoré pochádza od samotného správcu​

Na otázku o dokumentácii k API /ajax Kovid Goyal odpovedá, že neexistuje, že tento povrch nie je ani verejný, ani stabilný a že je potrebné prečítať zdrojový kód. Dôsledky zohľadnené v CalibreKit :

  • všetko dekódovanie je tolerantné — chýbajúce, neočakávané alebo null pole nikdy nesklame pri výpise knižnice;
  • povaha servera sa zistí pri vetvení (detectFlavor()), pretože Calibre-Web vráti chybu 404 na všetko /ajax/* a ponúka iba OPDS;
  • OPDS zostáva záložnou možnosťou, ktorá je štandardizovaná a stabilná;
  • testy zmrazia skutočné tvary bajtov, takže aktualizácia verzie Calibre preruší skôr test ako aplikáciu.

2. Tri konvencie pre pomenovanie knižnice​

Toto je hlavné úskalie tohto API. Je zakódovaný raz v CalibreClient.url(path:query:libraryInQuery:) a overený štyrmi testami.

Rodina trásKam smeruje? library_id
/ajax/…, /get/…Komponent cesty — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…Parameter dopytu — ?library_id=Calibre_Library
/book-…-last-read-position/…Komponent cesty, znova

Zaregistrované srv/utils.py : get_library_data() Číta rd.query.get('library_id').


3. Katalóg — srv/ajax.py​

TrasaVykresľuje
GET /ajax/library-info{library_map, default_library} — slúži aj ako test povahy servera
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, parametre query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3Slovník Indexované identifikátorom, null Pre zakázanú knihu
GET /ajax/book/{id}/{library}Metadáta knihy
GET /ajax/categories/{library}Kategórie najvyššej úrovne
GET /ajax/category/{nom}/{library}Obsah kategórie, stránkované
GET /ajax/books_in/{cat}/{item}/{library}identifikátory kategória

Dve dekódovacie pasce, obe pokryté testami:

Identifikátor nie je v objekte. /ajax/books indexuje svoj slovník podľa identifikátora a neopakuje ho v ňom. CalibreKit ho vkladá cez userInfo dekodéra.

0101-01-01T00:00:00+00:00 znamená „bez dátumu“. Toto je strážca UNDEFINED_DATE Calibre. Naivne dekódovaný, vytvára knihu publikovanú v časopise Antiquity. CalibreDate ho vracia späť k nil.


4. Konverzia — srv/convert.py​

Toto je objav, ktorý mení architektúru: server Calibre konvertuje cez HTTP.

TrasaMetódaÚloha
/conversion/book-data/{id}GETVstupné formáty, výstupné formáty, akceptované možnosti
/conversion/start/{id}POSTTelo {input_fmt, output_fmt, options} → vráti funkčný identifikátor
/conversion/status/{job}POST{running, percent, msg} potom stav terminálu; ?abort_job=1 prerušenia

Podrobnosti uvedené v zdroji a všetky významné v praxi:

  • Iba POST (receive_data_methods = {'POST'}). GET je odmietnutý.
  • input_fmt musí byť vo formáte, ktorý kniha skutočne má : server odtiaľ vytvorí zdrojovú cestu a zvyšok zahodí. Očakáva ho vo veľkých písmenách, output_fmt v malých písmenách.
  • Stav sa spotrebuje pri prvom čítaní z terminálu : del conversion_jobs[job_id], potom cleanup() v finally. Záver sa dá prečítať iba raz. A dotazovať sa naň môže iba používateľ, ktorý úlohu spustil v tej istej knižnici. CalibreKit.convert(…) zapuzdruje slučku dotazovania, takže o tom žiadny volajúci nemusel premýšľať.
  • Vytvorený formát sa pridá do knihy v knižnici : db.add_format(book_id, fmt, output_path). Práca sa preto vykoná iba raz a všetky zariadenia z nej potom profitujú. /get/EPUB/{id}.
  • Súbory s receptami sú odmietnuté (spustenie kódu) a zoznam možností je blokovaný sieťou.

Úplná cesta, ako je implementovaná: CalibreKit :

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. Pozícia čítania a anotácie — srv/books.py​

Calibre už synchronizuje pozície čítania na strane servera.

TrasaMetódaÚloha
/book-get-last-read-position/{library}/{id}:{FMT}GETznáme pozície, na zariadenie
/book-set-last-read-position/{library}/{id}/{FMT}POSTzáznamy {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETHlavné body a poznámky
/book-manifest/{id}/{FMT}GETServer normalizuje akýkoľvek formát do manifestu pre svoju vlastnú čítačku
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETZdroj z normalizovanej knihy
/book-get-storage/{library}/{id}/{FMT}GETStav úložiska

Dva dôsledky pre Podbook:

Môžeme opustiť protokoly .jsonl opísané v počiatočných špecifikáciách, aspoň ako hlavný mechanizmus: Calibre už uchováva pozíciu pre každé zariadenie, každú knihu a každý formát. Protokoly zostávajú užitočné pre to, čo Calibre nevie – pozíciu v zvuku, v poznámkovom bloku so slovnou zásobou.

/book-manifest je skratka na vyhodnotenie. Server už vie, ako transformovať akýkoľvek formát do normalizovanej štruktúry pre svoju webovú čítačku. Toto pokrýva časť toho, čo malo BookKit robiť. Pred napísaním analyzátora je potrebné preskúmať nasledujúce: formát manifestu je interný pre Calibre, takže by sa s ním malo zaobchádzať ako s povrchom /ajax, ale s opatrnosťou.

srv/kosync.py tiež sprístupňuje synchronizačný protokol KOReader (/kosync/users/auth, /kosync/syncs/progress), čo je ďalší možný prístup, ktorý už prijali iné čítačky.


6. Vyhľadávanie v plnom texte — srv/fts.py​

TrasaMetódaÚloha
/fts/searchGETvyhľadáva text kníh, nielen metadáta
/fts/snippets/{book_ids}GETextrahované s kontextovým
/fts/reindex, /fts/indexing, /fts/disablePOSTovládaním indexu

Index musí byť povolený na strane servera. Podbook preto nemusí indexovať samotnú knižnicu pre globálne vyhľadávanie — iba pre knihy importované mimo Calibre.


7. Zápis do knižnice — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L vykoná podpríkaz calibredb na serveri. Toto je podporovaná metóda zápisu: metadata.db neumožňuje druhý zapisovač.

Dostupné príkazy: 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 umožňuje čistý zápis stavu spracovania Podbook do vlastného stĺpca #podbook, viditeľného z Calibre.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Štandardný, stabilný, v lokálnej sieti inzerovaný ako Bonjour. Je to záložná možnosť, keď /ajax nie je k dispozícii — najmä keď Calibre-Web nie je k dispozícii.


9. Čo sa tým zmení pre Podbook​

Počiatočná hypotézaRealita
Je potrebné napísať analyzátor MOBINepravda z v1: ebook-convert už bola postačujúca
Konverzia vyžaduje workshop na tému MacNepravda : calibre-server konvertované pomocou HTTP. iPad požiadavky, server funguje, knižnica rastie
Podbook musí vymyslieť svoju synchronizáciu pozíciíČiastočne nepravdivé : Calibre už udržiava jednu, pre každé zariadenie
Podbook musí indexovať pre globálne vyhľadávanieNepravda : /fts/search existuje
metadata.db iba na čítanie, nie je možný zápisNepravda : /cdb/cmd/… je oficiálna metóda zápisu
API /ajax je solídna databázaNepravda : nie je verejná, nie je stabilná. Preto tolerantné dekódovanie, detekcia povahy a záložná metóda OPDS

Zostáva pravdivé: Súbory chránené DRM sa neotvoria a server Calibre musí niekde bežať, aby bola k dispozícii konverzia a globálne vyhľadávanie.