Passa al contenuto principale

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 null non 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 percorsiDove 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​

StradaRitorni
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,3dizionario 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.

StradaMetodoRuolo
/conversion/book-data/{id}OTTIENIformati di input, formati di output, opzioni accettate
/conversion/start/{id}POSTcorpo {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_fmt deve 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_fmt in minuscolo.
  • Lo stato viene consumato alla prima lettura del terminale : del conversion_jobs[job_id], allora cleanup() in a finally. 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.

StradaMetodoRuolo
/book-get-last-read-position/{library}/{id}:{FMT}OTTIENIposizioni conosciute, per dispositivo
/book-set-last-read-position/{library}/{id}/{FMT}POSTsalva {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}OTTIENIevidenziazioni e note
/book-manifest/{id}/{FMT}OTTIENIIl server normalizza qualsiasi formato in manifesto per il proprio lettore
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}OTTIENIuna risorsa di libri standardizzata
/book-get-storage/{library}/{id}/{FMT}OTTIENIstato 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​

StradaMetodoRuolo
/fts/searchOTTIENIricerca nel testo dei libri, non solo metadati
/fts/snippets/{book_ids}OTTIENIestratti con contesto
/fts/reindex, /fts/indexing, /fts/disablePOSTcontrollo 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 inizialeLa realtà
È necessario scrivere un parser MOBIFalso dalla v1: ebook-convert era già abbastanza
La conversione richiede officina il MacFalso : calibre-server si converte in HTTP. iPad richiede, il server funziona, la libreria si arricchisce
Podbook deve inventare il proprio timing di posizioneParzialmente falso : Calibre ne contiene già uno, per dispositivo
Podbook dovrebbe indicizzare per la ricerca globaleFalso : /fts/search esiste
metadata.db sola lettura, non è possibile scrivereFalso : /cdb/cmd/… è il percorso di scrittura ufficiale
Il API /ajax è una base solidaFalso : 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.