Mergi la conținutul principal

API al serverului Calibre — notat

Fișă tehnică și proiectare. Acest document păstrează studiile și arhitectura avută în vedere. Nu toate funcțiile descrise pot fi disponibile; cel ghid de utilizare și codul specifică operațiunea curentă.

Declarație făcută la 30 octombrie 2026 din codul sursă al Calibre (src/calibre/srv/), nu există documentație: nu există. Implementat și acoperit de teste în Packages/Core/Sources/CalibreKit.


1. Avertisment, care vine de la însuși întreținătorul​

Întrebat despre documentația pentru API /ajax, Kovid Goyal răspunde că nu există, că această suprafață nu este nici public, nici stabil și că trebuie să citiți sursa. Consecințele reținute în CalibreKit :

  • toată decodificarea este tolerantă — un dispărut, neașteptat sau null nu provoacă niciodată eșecul unei liste de biblioteci;
  • natura serverului este detectată la conectare (detectFlavor()), deoarece Calibre-Web răspunde 404 la toate /ajax/* și oferă doar OPDS;
  • OPDS rămâne ruta de rezervă, standardizat și stabil;
  • Testele îngheață formele reale de octeți, astfel încât o actualizare a Calibre întrerupe un test mai degrabă decât aplicația.

2. Trei convenții pentru denumirea bibliotecii​

Aceasta este capcana principală a acestui API. Este codificat o dată în CalibreClient.url(path:query:libraryInQuery:) și verificat prin patru teste.

Familie de traseuUnde se duce library_id
/ajax/…, /get/…componentă cale — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…parametru de interogare — ?library_id=Calibre_Library
/book-…-last-read-position/…componentă cale, din nou

S-a înregistrat srv/utils.py : get_library_data() pat rd.query.get('library_id').


3. Catalog — srv/ajax.py​

DrumRetururi
GET /ajax/library-info{library_map, default_library} — servește și ca test de natură a serverului
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, parametri query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3dicționar indexat după identificator, null pentru o carte interzisă
GET /ajax/book/{id}/{library}metadatele unei cărți
GET /ajax/categories/{library}categorii de nivel I
GET /ajax/category/{nom}/{library}conținutul unei categorii, paginat
GET /ajax/books_in/{cat}/{item}/{library}identificatorii unei categorii

Două capcane de decodare, ambele acoperite de teste:

Identificatorul nu este în subiect. /ajax/books își indexează dicționarul după identificator și nu îl repetă în interior. CalibreKit îl injectează prin userInfo al decodorului.

0101-01-01T00:00:00+00:00 înseamnă „fără dată”. Este santinela UNDEFINED_DATE din Calibre. Naiv decodificat, produce o carte publicată în Antichitate. CalibreDate îl readuce la nil.


4. Conversie — srv/convert.py​

Aceasta este descoperirea care schimbă arhitectura: serverul Calibre convertește, prin intermediul HTTP.

DrumMetodaRol
/conversion/book-data/{id}GETFormate de intrare, formate de ieșire, opțiuni acceptate
/conversion/start/{id}POSTCorp {input_fmt, output_fmt, options} → returnează un identificator funcțional
/conversion/status/{job}POST{running, percent, msg} apoi starea terminalului; ?abort_job=1 întrerupe

Detalii notate din sursă, toate semnificative în practică:

  • Numai POST (receive_data_methods = {'POST'}). O cerere GET este respinsă.
  • input_fmt trebuie să fie un format pe care cartea îl are de fapt : serverul construiește calea sursă de acolo și respinge restul. Îl așteaptă cu majuscule, output_fmt cu litere mici.
  • Starea este consumată la prima citire de către terminal : del conversion_jobs[job_id], apoi cleanup() într-o finally. Concluzia poate fi citită o singură dată. Și numai utilizatorul care a început jobul, în aceeași bibliotecă, îl poate interoga. CalibreKit.convert(…) încapsulează bucla de interogare, astfel încât niciun apelant să nu fie nevoit să se gândească la el.
  • Formatul produs este adăugat în cartea din bibliotecă : db.add_format(book_id, fmt, output_path). Prin urmare, lucrarea este efectuată o singură dată, iar toate dispozitivele beneficiază apoi de aceasta prin: /get/EPUB/{id}.
  • Fișierele de rețete sunt respinse (execuție de cod), iar o listă de opțiuni este blocată de rețea.

Calea completă, așa cum este implementată de: 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. Poziția de citire și adnotări — srv/books.py​

Calibre sincronizează deja pozițiile de citire pe partea serverului.

DrumMetodaRol
/book-get-last-read-position/{library}/{id}:{FMT}GETpoziții cunoscute, per dispozitiv
/book-set-last-read-position/{library}/{id}/{FMT}POSTînregistrări {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETevidențieri și note
/book-manifest/{id}/{FMT}GETserverul normalizează orice format într-un manifest pentru propriul player
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETo resursă din cartea normalizată
/book-get-storage/{library}/{id}/{FMT}GETstarea de stocare

Două consecințe pentru Podbook:

Putem abandona jurnalele .jsonl descrise în specificațiile inițiale, cel puțin ca mecanism principal: Calibre deține deja o poziție per dispozitiv, per carte și per format. Jurnalele rămân utile pentru ceea ce Calibre nu știe - poziția în audio, caietul de vocabular.

/book-manifest este o scurtătură pentru evaluare. Serverul știe deja cum să transforme orice format într-o structură normalizată pentru playerul său web. Aceasta acoperă o parte din ceea ce BookKit trebuia să facă. Ceva de analizat înainte de a scrie parserul: formatul manifestului este intern pentru Calibre, deci ar trebui tratat ca suprafața /ajax, cu precauție.

srv/kosync.py expune și protocolul de sincronizare KOReader (/kosync/users/auth, /kosync/syncs/progress), o altă posibilă abordare, deja adoptată de alți cititori.


6. Căutare full-text — srv/fts.py​

DrumMetodaRol
/fts/searchGETcaută textul cărților, nu doar metadatele
/fts/snippets/{book_ids}GETextrase cu context
/fts/reindex, /fts/indexing, /fts/disablePOSTcontrol index

Indexul trebuie să fie activat pe server. Prin urmare, Podbook nu trebuie să indexeze biblioteca în sine pentru căutare globală — doar pentru cărțile importate în afara Calibre.


7. Scrierea în bibliotecă — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L execută o subcomandă calibredb pe server. Aceasta este cel/cea/cei/cele metoda acceptată pentru scriere: metadata.db nu permite un al doilea scriitor.

Comenzi disponibile: 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 permite scrierea stării de procesare a Podbook într-o coloană personalizată #podbook, vizibilă din Calibre, în mod curat.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stabil, promovat ca Bonjour în rețeaua locală. Este soluția de rezervă atunci când /ajax nu este disponibil — în special când Calibre-Web nu este disponibil.


9. Ce se schimbă pentru Podbook​

Ipoteza inițialăRealitate
Trebuie scris un parser MOBIFals din v1: ebook-convert era deja suficient
Conversia necesită un atelier despre MacFals : calibre-server convertit de HTTP. iPad solicită, serverul funcționează, biblioteca crește
Podbook trebuie să inventeze sincronizarea poziției saleParțial fals : Calibre menține deja una, per dispozitiv
Podbook trebuie să indexeze pentru căutare globalăFals : /fts/search există
metadata.db doar citire, nu este posibilă scriereaFals : /cdb/cmd/… este metoda oficială de scriere
API /ajax este o bază de date solidăFals : nu este publică, nu este stabilă. Prin urmare, decodarea tolerantă, detectarea naturii și soluția alternativă OPDS

Rămâne adevărat: fișierele protejate prin DRM nu se vor deschide și un server Calibre trebuie să ruleze undeva pentru ca conversia și căutarea globală să fie disponibile.