Ugrás a fő tartalomhoz

A Calibre szerver API-je – megjegyezve

Műszaki dokumentáció és terv. Ez a dokumentum megőrzi a tanulmányokat és a tervezett architektúrát. Előfordulhat, hogy nem minden leírt funkció érhető el; a felhasználói kézikönyv és a kód határozza meg az aktuális műveletet.

Nyilatkozat 2026. október 30-án a Calibre forráskódjából (src/calibre/srv/), nincs dokumentáció: nem létezik. Megvalósítása és tesztelése ben Packages/Core/Sources/CalibreKit.


1. Figyelmeztetés, amely magától a karbantartótól származik​

A API dokumentációjával kapcsolatban kérdezték /ajax, Kovid Goyal azt válaszolja, hogy nem létezik, ez a felület nem sem nyilvános, sem nem stabil, és el kell olvasnia a forrást. A következmények megmaradtak CalibreKit :

  • minden dekódolás toleráns — hiányzó, váratlan vagy null soha nem okoz kudarcot a könyvtár listázásában;
  • a szerver jellegét a rendszer észleli a csatlakozáskor (detectFlavor()), mert a Calibre-Web mindenre 404-re válaszol /ajax/* és csak OPDS ajánlatot tesz;
  • OPDS marad a tartalék útvonal, szabványos és stabil;
  • A tesztek lefagyasztják a tényleges bájt alakzatokat, így a Calibre frissítése nem az alkalmazást, hanem a tesztet szakítja meg.

2. Három konvenció a könyvtár elnevezésére​

Ez a API fő csapdája. Egyszer van kódolva CalibreClient.url(path:query:libraryInQuery:) , és négy teszttel ellenőrizték.

ÚtvonalcsaládMerre tart library_id
/ajax/…, /get/…útvonal összetevő — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…lekérdezési paraméter — ?library_id=Calibre_Library
/book-…-last-read-position/…útvonal összetevő, ismét

Bejelentkezett srv/utils.py : get_library_data() ágy rd.query.get('library_id').


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

RoadVisszatér
GET /ajax/library-info{library_map, default_library} — a szerver természeti tesztjeként is szolgál
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, paraméterek query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3szótár azonosítóval indexelve, null egy betiltott könyvért
GET /ajax/book/{id}/{library}egy könyv metaadatai
GET /ajax/categories/{library}első szintű kategóriák
GET /ajax/category/{nom}/{library}egy kategória tartalma, oldalszámozva
GET /ajax/books_in/{cat}/{item}/{library}egy kategória azonosítói

Két dekódolási buktató, mindkettőt tesztelték:

Az azonosító nem szerepel a tárgyban. /ajax/books A azonosító szerint indexeli a szótárát, és nem ismétli meg benne. CalibreKit beadja a userInfo a dekóder.

0101-01-01T00:00:00+00:00 A jelentése „nincs dátum”. Az őrszem UNDEFINED_DATE / Calibre. Naiv módon dekódolva egy Ókorban megjelent könyvet készít. CalibreDate visszahozza ide nil.


4. Konverzió — srv/convert.py​

Ez az a felfedezés, amely megváltoztatja az architektúrát: a Calibre szerver a HTTP segítségével konvertál.

RoadMódszerSzerep
/conversion/book-data/{id}GETbemeneti formátumok, kimeneti formátumok, elfogadott opciók
/conversion/start/{id}POSTtest {input_fmt, output_fmt, options} → feladatazonosítót ad vissza
/conversion/status/{job}POST{running, percent, msg} , majd a terminál állapota; ?abort_job=1 megszakítja

A forrásban feltüntetett részletek, és minden, ami a használat szempontjából jelentős:

  • Csak POST (receive_data_methods = {'POST'}). A GET elutasításra kerül.
  • input_fmt kell lennie a könyv tényleges formátuma : A szerver onnan építi fel a forrás elérési útját, a többit pedig elveti. Nagybetűvel várja, output_fmt kisbetűvel.
  • Az állapot az első terminálolvasáskor elfogy : del conversion_jobs[job_id], akkor cleanup() a finally. A következtetést csak egyszer lehet elolvasni. És csak az a felhasználó kérdezheti le, aki elindította a munkát, ugyanabban a könyvtárban. CalibreKit.convert(…) A beburkolja a vizsgálóhurkot, így a hívó félnek sem kell ezen gondolkodnia.
  • A termék formátuma hozzáadódik a könyvtárban lévő könyvhöz : db.add_format(book_id, fmt, output_path). A munkát ezért csak egyszer kell elvégezni, és ezután minden eszköz profitál belőle. /get/EPUB/{id}.
  • A rendszer elutasítja a receptfájlokat (kódvégrehajtás), és a hálózat tiltja az opciók listáját.

A teljes útvonal, pl CalibreKit megvalósítja:

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. Olvasási pozíció és megjegyzések — srv/books.py​

Calibre már szinkronizálja a lejátszási pozíciókat a szerver oldalon.

RoadMódszerSzerep
/book-get-last-read-position/{library}/{id}:{FMT}GETismert pozíciók, eszközök szerint
/book-set-last-read-position/{library}/{id}/{FMT}POSTmentések {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETkiemelések és jegyzetek
/book-manifest/{id}/{FMT}GETA szerver bármilyen formátumot normalizál kiáltványban a saját olvasója számára
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETszabványosított könyvforrás
/book-get-storage/{library}/{id}/{FMT}GETtárolási állapot

A Podbook két következménye:

Elhagyhatjuk az újságokat .jsonl A a kezdeti specifikációkban le van írva, legalábbis fő mechanizmusként: Calibre már rendelkezik egy pozícióval eszközönként, könyvenként és formátumonként. A naplók továbbra is hasznosak abban, amit Calibre nem tud – a hanganyagban, a szókincsben elfoglalt pozícióra.

/book-manifest A egy parancsikon az értékeléshez. A szerver már tudja, hogyan alakítson át bármilyen formátumot szabványosított struktúrává webolvasója számára. Ez annak egy részét fedi BookKit kellett tennie. Az elemző írása előtt meg kell vizsgálni: a jegyzék formátuma a Calibre belsője, ezért felületként kell kezelni /ajax, óvatosan.

srv/kosync.py A emellett felfedi a KOReader szinkronizálási protokollt (/kosync/users/auth, /kosync/syncs/progress), egy másik lehetséges útvonal, amelyet más olvasók már elfogadtak.


6. Teljes szöveges keresés — srv/fts.py​

RoadMódszerSzerep
/fts/searchGETkeresés a könyvek szövegében, nem csak a metaadatokat
/fts/snippets/{book_ids}GETkivonatok kontextussal
/fts/reindex, /fts/indexing, /fts/disablePOSTindexvezérlés

Az indexet engedélyezni kell a szerver oldalon. A Podbook ezért nem kell magát a könyvtárat indexelnie a globális kereséshez – csak a Calibre-n kívül importált könyvek esetében.


7. Írás a könyvtárban — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L végrehajt egy alparancsot calibredb a szerveren. ez van a támogatott írási mód: metadata.db A nem tolerál egy második szerkesztőt.

Elérhető parancsok: 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 A lehetővé teszi a Podbook feldolgozási állapotának beírását egy egyéni oszlopba #podbook, Calibre-ből látható, megfelelően.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Szabványos, stabil, a Hello-ban jelentették be a helyi hálózaton. Ez a visszavonás, amikor /ajax A nincs ott – különösen a Calibre-Web ellen.


9. Mit változtat ez a Podbook esetében​

Kezdeti hipotézisValóság
MOBI-elemzőt kell írniHamis a v1-ből: ebook-convert már elég volt
A konvertáláshoz műhelymunka szükséges a következőn: MacHamis : calibre-server konvertál HTTP-re. iPad kérések, a szerver működik, a könyvtár gazdagodik
Podbook ki kell találnia a pozíció időzítésétRészben hamis : A Calibre már tartalmaz egyet, készülékenként
Podbook indexelnie kell a globális kereséshezHamis : /fts/search létezik
metadata.db csak olvasható, írás nem lehetségesHamis : /cdb/cmd/… A a hivatalos írási útvonal
A API /ajax A egy szilárd alapotHamis : nem nyilvános, nem stabil. Ezért a toleráns dekódolás, természetérzékelés és tartalék OPDS

Még mindig igaz: a DRM-védett fájlok nem nyílnak meg, és a Calibre szervernek futnia kell valahol az átalakításhoz és a globális kereséshez.