Il API del server Calibre — annotato
Fascicolo tecnico e progetto. Il presente documento conserva gli studi e l'architettura prevista. Potrebbero non essere disponibili tutte le funzioni descritte; il guida per l'utente e il codice specificano l'operazione corrente.
Dichiarazione fatta il 30 ottobre 2026 dal codice sorgente di Calibre (src/calibre/srv/), nessuna documentazione: non esiste. Implementato e coperto da test in Packages/Core/Sources/CalibreKit.
1. Avvertimento, che proviene dallo stesso manutentore
Richiesta di documentazione per API /ajax, Kovid Goyal risponde che non esiste, che questa superficie non è né pubblico né stabile, e che devi leggere la fonte. Conseguenze mantenute CalibreKit :
- tutta la decodifica è tollerante — mancante, inaspettato o
nullnon causa mai il fallimento dell'elenco di una libreria; - la natura del server viene rilevata al momento della connessione (
detectFlavor()), perché Calibre-Web risponde 404 su tutto/ajax/*e offre solo OPDS; - OPDS rimane la via di riserva, standardizzato e stabile;
- I test congelano le forme effettive dei byte, in modo che un aggiornamento di Calibre interrompa un test anziché l'applicazione.
2. Tre convenzioni per la denominazione della biblioteca
Questa è la trappola principale di questo API. Viene codificato una volta dentro CalibreClient.url(path:query:libraryInQuery:) e verificato da quattro test.
| Famiglia di percorsi | Dove sta andando library_id |
|---|---|
/ajax/…, /get/… | componente del percorso — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | parametro di query — ?library_id=Calibre_Library |
/book-…-last-read-position/… | componente del percorso, ancora |
Check-in srv/utils.py : get_library_data() letto rd.query.get('library_id').
3. Catalogo — srv/ajax.py
| Strada | Ritorni |
|---|---|
GET /ajax/library-info | {library_map, default_library} — serve anche come test sulla natura del server |
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 | dizionario indicizzato per identificatore, null per un libro vietato |
GET /ajax/book/{id}/{library} | i metadati di un libro |
GET /ajax/categories/{library} | categorie di primo livello |
GET /ajax/category/{nom}/{library} | il contenuto di una categoria, impaginato |
GET /ajax/books_in/{cat}/{item}/{library} | gli identificatori di una categoria |
Due trappole di decodifica, entrambe coperte da test:
L'identificatore non è nell'oggetto. /ajax/books indicizza il suo dizionario per identificatore e non lo ripete al suo interno. CalibreKit lo inietta attraverso il userInfo del decoder.
0101-01-01T00:00:00+00:00 significa “nessuna data”. È la sentinella UNDEFINED_DATE di Calibre. Decodificato ingenuamente, ne risulta un libro pubblicato nell'Antichità. CalibreDate lo riporta a nil.
4. Conversione — srv/convert.py
Questa è la scoperta che cambia l'architettura: il server Calibre converte, tramite HTTP.
| Strada | Metodo | Ruolo |
|---|---|---|
/conversion/book-data/{id} | OTTIENI | formati di input, formati di output, opzioni accettate |
/conversion/start/{id} | POST | corpo {input_fmt, output_fmt, options} → restituisce un ID lavoro |
/conversion/status/{job} | POST | {running, percent, msg} poi lo stato terminale; ?abort_job=1 interrompe |
Dettagli annotati nella fonte e tutti significativi per l'uso:
- Solo POST (
receive_data_methods = {'POST'}). Un GET viene rifiutato. input_fmtdeve essere un formato che il libro ha effettivamente : il server crea il percorso di origine da lì e scarta il resto. Lo aspetta in maiuscolo,output_fmtin minuscolo.- Lo stato viene consumato alla prima lettura del terminale :
del conversion_jobs[job_id], alloracleanup()in afinally. Puoi leggere la conclusione solo una volta. E solo l'utente che ha avviato il lavoro, nella stessa libreria, può interrogarlo.CalibreKit.convert(…)avvolge il ciclo di sondaggio in modo che nessun chiamante debba pensarci. - Il formato del prodotto viene aggiunto al libro nella libreria :
db.add_format(book_id, fmt, output_path). Il lavoro viene quindi svolto una sola volta e tutti i dispositivi ne beneficiano./get/EPUB/{id}. - I file di ricette vengono rifiutati (esecuzione del codice) e un elenco di opzioni è vietato dalla rete.
Il percorso completo, ad es CalibreKit lo implementa:
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. Posizione di lettura e annotazioni — srv/books.py
Calibre sincronizza già le posizioni di riproduzione, lato server.
| Strada | Metodo | Ruolo |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | OTTIENI | posizioni conosciute, per dispositivo |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | salva {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | OTTIENI | evidenziazioni e note |
/book-manifest/{id}/{FMT} | OTTIENI | Il server normalizza qualsiasi formato in manifesto per il proprio lettore |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | OTTIENI | una risorsa di libri standardizzata |
/book-get-storage/{library}/{id}/{FMT} | OTTIENI | stato di conservazione |
Due conseguenze per Podbook:
Possiamo abbandonare i giornali .jsonl descritto nelle specifiche iniziali, almeno come meccanismo principale: Calibre detiene già una posizione per dispositivo, per libro e per formato. I registri sono ancora utili per ciò che Calibre non sa: la posizione nell'audio, il taccuino del vocabolario.
/book-manifest è una scorciatoia da valutare. Il server sa già come trasformare qualsiasi formato in una struttura standardizzata per il suo lettore web. Questo copre parte di cosa BookKit doveva fare. Da esplorare prima di scrivere il parser: il formato del manifest è interno a Calibre, quindi da trattare come la superficie /ajax, con cautela.
srv/kosync.py espone inoltre il protocollo di sincronizzazione KOReader (/kosync/users/auth, /kosync/syncs/progress), un'altra strada possibile, già adottata da altri lettori.
6. Ricerca nel testo completo — srv/fts.py
| Strada | Metodo | Ruolo |
|---|---|---|
/fts/search | OTTIENI | ricerca nel testo dei libri, non solo metadati |
/fts/snippets/{book_ids} | OTTIENI | estratti con contesto |
/fts/reindex, /fts/indexing, /fts/disable | POST | controllo dell'indice |
L'indice deve essere abilitato lato server. Podbook pertanto non deve indicizzare la biblioteca stessa per la ricerca globale, ma solo per i libri importati all'esterno di Calibre.
7. Scrivere in biblioteca — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L esegue un sottocomando calibredb sul server. Lo è il modo supportato per scrivere: metadata.db non tollera un secondo editore.
Comandi disponibili: 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 permette di scrivere lo stato di lavorazione di Podbook in una colonna personalizzata #podbook, visibile da Calibre, propriamente.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stabile, annunciato in Hello sulla rete locale. È il momento del ritiro /ajax non c'è, soprattutto contro Calibre-Web.
9. Cosa cambia per Podbook
| Ipotesi iniziale | La realtà |
|---|---|
| È necessario scrivere un parser MOBI | Falso dalla v1: ebook-convert era già abbastanza |
| La conversione richiede officina il Mac | Falso : calibre-server si converte in HTTP. iPad richiede, il server funziona, la libreria si arricchisce |
| Podbook deve inventare il proprio timing di posizione | Parzialmente falso : Calibre ne contiene già uno, per dispositivo |
| Podbook dovrebbe indicizzare per la ricerca globale | Falso : /fts/search esiste |
metadata.db sola lettura, non è possibile scrivere | Falso : /cdb/cmd/… è il percorso di scrittura ufficiale |
Il API /ajax è una base solida | Falso : non pubblico, non stabile. Da qui la decodifica tollerante, il rilevamento della natura e il fallback OPDS |
Ancora vero: i file protetti da DRM non si apriranno e un server Calibre deve essere in esecuzione da qualche parte affinché la conversione e la ricerca globale siano disponibili.