Aller au contenu principal

L'API du serveur Calibre — relevé

Dossier technique et conception. Ce document conserve les études et l’architecture envisagée. Toutes les fonctions décrites ne sont pas nécessairement disponibles ; le guide utilisateur et le code précisent le fonctionnement actuel.

Relevé fait le 30 octobre 2026 à partir du code source de Calibre (src/calibre/srv/), pas de documentation : il n'en existe pas. Implémenté et couvert par des tests dans Packages/Core/Sources/CalibreKit.


1. Avertissement, qui vient du mainteneur lui-même​

Interrogé sur la documentation de l'API /ajax, Kovid Goyal répond qu'elle n'existe pas, que cette surface n'est ni publique ni stable, et qu'il faut lire le source. Conséquences retenues dans CalibreKit :

  • tout décodage est tolérant — un champ absent, inattendu ou null ne fait jamais échouer le listing d'une bibliothèque ;
  • la nature du serveur est détectée au branchement (detectFlavor()), parce que Calibre-Web répond 404 sur tout /ajax/* et n'offre qu'OPDS ;
  • OPDS reste la voie de repli, lui standardisé et stable ;
  • les tests figent les formes d'octets réelles, pour qu'une montée de version de Calibre casse un test plutôt que l'application.

2. Trois conventions pour nommer la bibliothèque​

C'est le piège principal de cette API. Il est encodé une fois dans CalibreClient.url(path:query:libraryInQuery:) et vérifié par quatre tests.

Famille de routesOù va library_id
/ajax/…, /get/…composant de chemin — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…paramètre de requête — ?library_id=Calibre_Library
/book-…-last-read-position/…composant de chemin, de nouveau

Vérifié dans srv/utils.py : get_library_data() lit rd.query.get('library_id').


3. Catalogue — srv/ajax.py​

RouteRend
GET /ajax/library-info{library_map, default_library} — sert aussi de test de nature du serveur
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, paramètres query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3dictionnaire indexé par identifiant, null pour un livre interdit
GET /ajax/book/{id}/{library}les métadonnées d'un livre
GET /ajax/categories/{library}les catégories de premier niveau
GET /ajax/category/{nom}/{library}le contenu d'une catégorie, paginé
GET /ajax/books_in/{cat}/{item}/{library}les identifiants d'une catégorie

Deux pièges de décodage, tous deux couverts par des tests :

L'identifiant n'est pas dans l'objet. /ajax/books indexe son dictionnaire par identifiant et ne le répète pas à l'intérieur. CalibreKit l'injecte par le userInfo du décodeur.

0101-01-01T00:00:00+00:00 veut dire « pas de date ». C'est la sentinelle UNDEFINED_DATE de Calibre. Décodée naïvement, elle produit un livre publié dans l'Antiquité. CalibreDate la ramène à nil.


4. Conversion — srv/convert.py​

C'est la découverte qui change l'architecture : le serveur Calibre convertit, par HTTP.

RouteMéthodeRôle
/conversion/book-data/{id}GETformats d'entrée, formats de sortie, options acceptées
/conversion/start/{id}POSTcorps {input_fmt, output_fmt, options} → renvoie un identifiant de travail
/conversion/status/{job}POST{running, percent, msg} puis l'état terminal ; ?abort_job=1 interrompt

Détails relevés dans le source, et tous significatifs à l'usage :

  • POST uniquement (receive_data_methods = {'POST'}). Un GET est refusé.
  • input_fmt doit être un format que le livre possède réellement : le serveur construit le chemin source à partir de là et rejette le reste. Il l'attend en majuscules, output_fmt en minuscules.
  • Le statut est consommé à la première lecture terminale : del conversion_jobs[job_id], puis cleanup() dans un finally. On ne peut lire la conclusion qu'une fois. Et seul l'utilisateur qui a lancé le travail, dans la même bibliothèque, peut l'interroger. CalibreKit.convert(…) encapsule la boucle de sondage pour qu'aucun appelant n'ait à y penser.
  • Le format produit est ajouté au livre dans la bibliothèque : db.add_format(book_id, fmt, output_path). Le travail est donc fait une seule fois, et tous les appareils en profitent ensuite par /get/EPUB/{id}.
  • Les fichiers de recettes sont refusés (exécution de code), et une liste d'options est interdite par le réseau.

Le parcours complet, tel que CalibreKit l'implémente :

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. Position de lecture et annotations — srv/books.py​

Calibre synchronise déjà les positions de lecture, côté serveur.

RouteMéthodeRôle
/book-get-last-read-position/{library}/{id}:{FMT}GETpositions connues, par appareil
/book-set-last-read-position/{library}/{id}/{FMT}POSTenregistre {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETsurlignages et notes
/book-manifest/{id}/{FMT}GETle serveur normalise n'importe quel format en manifeste pour son propre lecteur
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETune ressource du livre normalisé
/book-get-storage/{library}/{id}/{FMT}GETétat du stockage

Deux conséquences pour Podbook :

On peut abandonner les journaux .jsonl décrits dans les specs initiales, au moins comme mécanisme principal : Calibre tient déjà une position par appareil, par livre et par format. Les journaux restent utiles pour ce que Calibre ne connaît pas — la position dans l'audio, le carnet de vocabulaire.

/book-manifest est un raccourci à évaluer. Le serveur sait déjà transformer n'importe quel format en structure normalisée pour son lecteur web. Cela recouvre une partie de ce que BookKit devait faire. À creuser avant d'écrire l'analyseur : le format du manifeste est interne à Calibre, donc à traiter comme la surface /ajax, avec prudence.

srv/kosync.py expose en plus le protocole de synchronisation de KOReader (/kosync/users/auth, /kosync/syncs/progress), autre voie possible, déjà adoptée par d'autres lecteurs.


6. Recherche plein texte — srv/fts.py​

RouteMéthodeRôle
/fts/searchGETrecherche dans le texte des livres, pas seulement les métadonnées
/fts/snippets/{book_ids}GETextraits avec le contexte
/fts/reindex, /fts/indexing, /fts/disablePOSTpilotage de l'index

L'index doit être activé côté serveur. Podbook n'a donc pas à indexer la bibliothèque lui-même pour la recherche globale — seulement pour les livres importés hors Calibre.


7. Écriture dans la bibliothèque — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L exécute une sous-commande calibredb sur le serveur. C'est la voie supportée pour écrire : metadata.db ne tolère pas un second rédacteur.

Commandes disponibles : 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 permet d'écrire l'état de traitement de Podbook dans une colonne personnalisée #podbook, visible depuis Calibre, proprement.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stable, annoncé en Bonjour sur le réseau local. C'est le repli quand /ajax n'est pas là — notamment face à Calibre-Web.


9. Ce que cela change pour Podbook​

Hypothèse initialeRéalité
Un analyseur MOBI est à écrireFaux dès la v1 : ebook-convert suffisait déjà
La conversion exige un atelier sur le MacFaux : calibre-server convertit par HTTP. L'iPad demande, le serveur travaille, la bibliothèque s'enrichit
Podbook doit inventer sa synchronisation de positionEn partie faux : Calibre en tient déjà une, par appareil
Podbook doit indexer pour la recherche globaleFaux : /fts/search existe
metadata.db en lecture seule, pas d'écriture possibleFaux : /cdb/cmd/… est la voie officielle en écriture
L'API /ajax est une base solideFaux : non publique, non stable. D'où le décodage tolérant, la détection de nature et le repli OPDS

Reste vrai : les fichiers protégés par DRM ne s'ouvriront pas, et un serveur Calibre doit tourner quelque part pour que la conversion et la recherche globale soient disponibles.