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
nullsoha 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ád | Merre 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
| Road | Visszaté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,3 | szó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.
| Road | Módszer | Szerep |
|---|---|---|
/conversion/book-data/{id} | GET | bemeneti formátumok, kimeneti formátumok, elfogadott opciók |
/conversion/start/{id} | POST | test {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_fmtkell 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_fmtkisbetűvel.- Az állapot az első terminálolvasáskor elfogy :
del conversion_jobs[job_id], akkorcleanup()afinally. 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.
| Road | Módszer | Szerep |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | ismert pozíciók, eszközök szerint |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | mentések {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | kiemelések és jegyzetek |
/book-manifest/{id}/{FMT} | GET | A 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} | GET | szabványosított könyvforrás |
/book-get-storage/{library}/{id}/{FMT} | GET | tá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
| Road | Módszer | Szerep |
|---|---|---|
/fts/search | GET | keresés a könyvek szövegében, nem csak a metaadatokat |
/fts/snippets/{book_ids} | GET | kivonatok kontextussal |
/fts/reindex, /fts/indexing, /fts/disable | POST | indexvezé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ézis | Valóság |
|---|---|
| MOBI-elemzőt kell írni | Hamis a v1-ből: ebook-convert már elég volt |
| A konvertáláshoz műhelymunka szükséges a következőn: Mac | Hamis : 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ét | Részben hamis : A Calibre már tartalmaz egyet, készülékenként |
| Podbook indexelnie kell a globális kereséshez | Hamis : /fts/search létezik |
metadata.db csak olvasható, írás nem lehetséges | Hamis : /cdb/cmd/… A a hivatalos írási útvonal |
A API /ajax A egy szilárd alapot | Hamis : 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.