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
nullnu 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 traseu | Unde 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
| Drum | Retururi |
|---|---|
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,3 | dicț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.
| Drum | Metoda | Rol |
|---|---|---|
/conversion/book-data/{id} | GET | Formate de intrare, formate de ieșire, opțiuni acceptate |
/conversion/start/{id} | POST | Corp {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_fmttrebuie 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_fmtcu litere mici.- Starea este consumată la prima citire de către terminal :
del conversion_jobs[job_id], apoicleanup()într-ofinally. 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.
| Drum | Metoda | Rol |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | poziț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} | GET | evidențieri și note |
/book-manifest/{id}/{FMT} | GET | serverul normalizează orice format într-un manifest pentru propriul player |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | o resursă din cartea normalizată |
/book-get-storage/{library}/{id}/{FMT} | GET | starea 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
| Drum | Metoda | Rol |
|---|---|---|
/fts/search | GET | caută textul cărților, nu doar metadatele |
/fts/snippets/{book_ids} | GET | extrase cu context |
/fts/reindex, /fts/indexing, /fts/disable | POST | control 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 MOBI | Fals din v1: ebook-convert era deja suficient |
| Conversia necesită un atelier despre Mac | Fals : calibre-server convertit de HTTP. iPad solicită, serverul funcționează, biblioteca crește |
| Podbook trebuie să inventeze sincronizarea poziției sale | Parț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ă scrierea | Fals : /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.