API serveru Calibre — pozn.
Technický soubor a design. Tento dokument zachovává studie a předpokládanou architekturu. Všechny popsané funkce nemusí být dostupné; a uživatelská příručka a kód určují aktuální operaci.
Prohlášení učiněné dne 30. října 2026 ze zdrojového kódu Calibre (src/calibre/srv/), žádná dokumentace: žádná neexistuje. Implementováno a pokryto testy v Packages/Core/Sources/CalibreKit.
1. Varování, které přichází od samotného správce
Dotaz na dokumentaci pro API /ajax, Kovid Goyal odpovídá, že neexistuje, že tento povrch není není veřejný ani stabilní a že si musíte přečíst zdroj. Důsledky zachovány v CalibreKit :
- veškeré dekódování je tolerantní — chybějící, neočekávané nebo
nullnikdy nezpůsobí selhání výpisu knihovny; - povaha serveru je detekována při připojení (
detectFlavor()), protože Calibre-Web odpovídá 404 na všechno/ajax/*a nabízí pouze OPDS; - OPDS zůstává záložní cestou, standardizované a stabilní;
- Testy zmrazí skutečné tvary bajtů, takže upgrade Calibre přeruší test spíše než aplikaci.
2. Tři konvence pro pojmenování knihovny
Toto je hlavní past tohoto API. Je jednou zakódováno CalibreClient.url(path:query:libraryInQuery:) a ověřeno čtyřmi testy.
| Rodina trasy | Kam jde library_id |
|---|---|
/ajax/…, /get/… | komponenta cesty — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | parametr dotazu — ?library_id=Calibre_Library |
/book-…-last-read-position/… | komponenta cesty, znovu |
Přihlášeno srv/utils.py : get_library_data() postel rd.query.get('library_id').
3. Katalog — srv/ajax.py
| Silnice | Vrací se |
|---|---|
GET /ajax/library-info | {library_map, default_library} — slouží také jako test povahy serveru |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parametry query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | slovník indexováno podle identifikátoru, null za zakázanou knihu |
GET /ajax/book/{id}/{library} | metadata knihy |
GET /ajax/categories/{library} | kategorie první úrovně |
GET /ajax/category/{nom}/{library} | obsah kategorie, stránkovaný |
GET /ajax/books_in/{cat}/{item}/{library} | identifikátory kategorie |
Dvě úskalí dekódování, obě pokrytá testy:
Identifikátor není v předmětu. /ajax/books indexuje svůj slovník podle identifikátoru a neopakuje jej uvnitř. CalibreKit jej vstříkne přes userInfo dekodéru.
0101-01-01T00:00:00+00:00 znamená „bez data“. To je strážce UNDEFINED_DATE z Calibre. Naivně dekódováno, produkuje knihu vydanou v antice. CalibreDate to vrátí zpět nil.
4. Konverze — srv/convert.py
Toto je objev, který mění architekturu: server Calibre konvertuje pomocí HTTP.
| Silnice | Metoda | Role |
|---|---|---|
/conversion/book-data/{id} | GET | vstupní formáty, výstupní formáty, akceptované možnosti |
/conversion/start/{id} | POST | tělo {input_fmt, output_fmt, options} → vrátí ID úlohy |
/conversion/status/{job} | POST | {running, percent, msg} pak koncový stav; ?abort_job=1 přeruší |
Podrobnosti uvedené ve zdroji a všechny důležité pro použití:
- Pouze POST (
receive_data_methods = {'POST'}). GET je odmítnut. input_fmtmusí být formát, který kniha skutečně má : Server odtud vytvoří zdrojovou cestu a zbytek zahodí. Čeká na to velkými písmeny,output_fmtmalými písmeny.- Stav je spotřebován při prvním čtení terminálu :
del conversion_jobs[job_id]tedycleanup()v afinally. Závěr si můžete přečíst jen jednou. A dotazovat se na ni může pouze uživatel, který úlohu spustil ve stejné knihovně.CalibreKit.convert(…)uzavírá snímací smyčku, takže na to žádný volající nemusí myslet. - Formát produktu je přidán do knihy v knihovně :
db.add_format(book_id, fmt, output_path). Práce se tedy dělá jen jednou a těží z ní pak všechna zařízení./get/EPUB/{id}. - Soubory receptů jsou odmítnuty (spuštění kódu) a seznam možností je sítí zakázán.
Kompletní trasa, jako např CalibreKit jej implementuje:
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. Pozice čtení a anotace — srv/books.py
Calibre již synchronizuje pozice přehrávání na straně serveru.
| Silnice | Metoda | Role |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | známé pozice, podle zařízení |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | uloží {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | zvýraznění a poznámky |
/book-manifest/{id}/{FMT} | GET | server normalizuje jakýkoli formát v manifestu pro vlastního čtenáře |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | standardizovaný knižní zdroj |
/book-get-storage/{library}/{id}/{FMT} | GET | stav úložiště |
Dva důsledky pro Podbook:
Můžeme opustit noviny .jsonl popsané v úvodních specifikacích, alespoň jako hlavní mechanismus: Calibre již drží pozici na zařízení, na knihu a na formát. Protokoly jsou stále užitečné pro to, co Calibre nezná — pozici ve zvuku, zápisník slovíček.
/book-manifest je zkratka pro vyhodnocení. Server již ví, jak převést jakýkoli formát do standardizované struktury pro svou webovou čtečku. To pokrývá část čeho BookKit musel udělat. Před napsáním analyzátoru je třeba prozkoumat: formát manifestu je interní pro Calibre, proto se s ním zachází jako s povrchem /ajax, opatrně.
srv/kosync.py navíc odhaluje synchronizační protokol KOReader (/kosync/users/auth, /kosync/syncs/progress), další možná cesta, již přijali ostatní čtenáři.
6. Fulltextové vyhledávání — srv/fts.py
| Silnice | Metoda | Role |
|---|---|---|
/fts/search | GET | hledání v textu knih, nejen metadata |
/fts/snippets/{book_ids} | GET | výňatky s kontextem |
/fts/reindex, /fts/indexing, /fts/disable | POST | řízení indexu |
Index musí být povolen na straně serveru. Podbook proto nemusí indexovat samotnou knihovnu pro globální vyhledávání – pouze pro knihy importované mimo Calibre.
7. Psaní v knihovně — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L provede dílčí příkaz calibredb na serveru. To je tam podporovaný způsob zápisu: metadata.db netoleruje druhého editora.
Dostupné pří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 zapsat stav zpracování Podbook do vlastního sloupce #podbook, viditelné z Calibre, správně.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standardní, stabilní, oznámeno v Hello v místní síti. Je to stažení, kdy /ajax tam není – zvláště proti Calibre-Web.
9. Co se tím změní pro Podbook
| Počáteční hypotéza | Realita |
|---|---|
| Je třeba zapsat analyzátor MOBI | False od verze 1: ebook-convert už bylo dost |
| Převod vyžaduje workshop na Mac | Nepravda : calibre-server se převede na HTTP. iPad požadavky, server funguje, knihovna je obohacena |
| Podbook musí vymyslet časování své polohy | Částečně nepravdivé : Calibre již má jeden, na zařízení |
| Podbook by měl indexovat pro globální vyhledávání | Nepravda : /fts/search existuje |
metadata.db pouze pro čtení, zápis není možný | Nepravda : /cdb/cmd/… je oficiální způsob psaní |
The API /ajax je pevný základ | Nepravda : není veřejné, není stabilní. Proto tolerantní dekódov ání, detekce přírody a záložní OPDS |
Stále platí: Soubory chráněné DRM se neotevřou a někde musí běžet server Calibre, aby byla dostupná konverze a globální vyhledávání.