Přeskočit na hlavní obsah

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 null nikdy 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 trasyKam 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​

SilniceVrací 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,3slovní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.

SilniceMetodaRole
/conversion/book-data/{id}GETvstupní formáty, výstupní formáty, akceptované možnosti
/conversion/start/{id}POSTtě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_fmt musí 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_fmt malými písmeny.
  • Stav je spotřebován při prvním čtení terminálu : del conversion_jobs[job_id] tedy cleanup() v a finally. 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.

SilniceMetodaRole
/book-get-last-read-position/{library}/{id}:{FMT}GETznámé pozice, podle zařízení
/book-set-last-read-position/{library}/{id}/{FMT}POSTuloží {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETzvýraznění a poznámky
/book-manifest/{id}/{FMT}GETserver normalizuje jakýkoli formát v manifestu pro vlastního čtenáře
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETstandardizovaný knižní zdroj
/book-get-storage/{library}/{id}/{FMT}GETstav ú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​

SilniceMetodaRole
/fts/searchGEThledání v textu knih, nejen metadata
/fts/snippets/{book_ids}GETvýňatky s kontextem
/fts/reindex, /fts/indexing, /fts/disablePOSTří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ézaRealita
Je třeba zapsat analyzátor MOBIFalse od verze 1: ebook-convert už bylo dost
Převod vyžaduje workshop na MacNepravda : 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ákladNepravda : 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í.