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
nullne 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 routes | Où 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
| Route | Rend |
|---|---|
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,3 | dictionnaire 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.
| Route | Méthode | Rôle |
|---|---|---|
/conversion/book-data/{id} | GET | formats d'entrée, formats de sortie, options acceptées |
/conversion/start/{id} | POST | corps {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_fmtdoit ê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_fmten minuscules.- Le statut est consommé à la première lecture terminale :
del conversion_jobs[job_id], puiscleanup()dans unfinally. 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.
| Route | Méthode | Rôle |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | positions connues, par appareil |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | enregistre {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | surlignages et notes |
/book-manifest/{id}/{FMT} | GET | le serveur normalise n'importe quel format en manifeste pour son propre lecteur |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | une 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
| Route | Méthode | Rôle |
|---|---|---|
/fts/search | GET | recherche dans le texte des livres, pas seulement les métadonnées |
/fts/snippets/{book_ids} | GET | extraits avec le contexte |
/fts/reindex, /fts/indexing, /fts/disable | POST | pilotage 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 initiale | Réalité |
|---|---|
| Un analyseur MOBI est à écrire | Faux dès la v1 : ebook-convert suffisait déjà |
| La conversion exige un atelier sur le Mac | Faux : calibre-server convertit par HTTP. L'iPad demande, le serveur travaille, la bibliothèque s'enrichit |
| Podbook doit inventer sa synchronisation de position | En partie faux : Calibre en tient déjà une, par appareil |
| Podbook doit indexer pour la recherche globale | Faux : /fts/search existe |
metadata.db en lecture seule, pas d'écriture possible | Faux : /cdb/cmd/… est la voie officielle en écriture |
L'API /ajax est une base solide | Faux : 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.