El API del servidor Calibre - anotado
Expediente técnico y diseño. Este documento conserva los estudios y la arquitectura prevista. Es posible que no todas las funciones descritas estén disponibles; el guía del usuario y el código especifican la operación actual.
Declaración realizada el 30 de octubre de 2026 a partir del código fuente de Calibre (src/calibre/srv/), no hay documentación: no existe ninguna. Implementado y cubierto por pruebas en Packages/Core/Sources/CalibreKit.
1. Advertencia, que proviene del propio mantenedor
Preguntado sobre la documentación para API /ajax, Kovid Goyal responde que no existe, que esta superficie no es ni público ni estable, y que hay que leer la fuente. Consecuencias retenidas en CalibreKit :
- toda decodificación es tolerante — una falta, inesperada o
nullnunca provoca que falle el listado de una biblioteca; - la naturaleza del servidor se detecta al conectarse (
detectFlavor()), porque Calibre-Web responde 404 en todo/ajax/*y solo ofrece OPDS; - OPDS sigue siendo la ruta alternativa, estandarizado y estable;
- Las pruebas congelan las formas de bytes reales, de modo que una actualización de Calibre interrumpe una prueba en lugar de la aplicación.
2. Tres convenciones para nombrar la biblioteca
Esta es la trampa principal de este API. Está codificado una vez en CalibreClient.url(path:query:libraryInQuery:) y verificado mediante cuatro pruebas.
| Familia de rutas | ¿Adónde va? library_id |
|---|---|
/ajax/…, /get/… | componente de ruta — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | parámetro de consulta — ?library_id=Calibre_Library |
/book-…-last-read-position/… | componente de ruta, otra vez |
Registrado srv/utils.py : get_library_data() cama rd.query.get('library_id').
3. Catálogo — srv/ajax.py
| Carretera | Devoluciones |
|---|---|
GET /ajax/library-info | {library_map, default_library} — también sirve como prueba de naturaleza del servidor |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parámetros query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | diccionario indexado por identificador, null por un libro prohibido |
GET /ajax/book/{id}/{library} | los metadatos de un libro |
GET /ajax/categories/{library} | categorías de primer nivel |
GET /ajax/category/{nom}/{library} | el contenido de una categoría, paginado |
GET /ajax/books_in/{cat}/{item}/{library} | los identificadores de una categoría |
Dos errores de decodificación, ambos cubiertos por pruebas:
El identificador no está en el asunto. /ajax/books indexa su diccionario por identificador y no lo repite en su interior. CalibreKit lo inyecta a través del userInfo del decodificador.
0101-01-01T00:00:00+00:00 significa "sin fecha". Es el centinela UNDEFINED_DATE de Calibre. Ingenuamente decodificado, produce un libro publicado en la Antigüedad. CalibreDate lo devuelve a nil.
4. Conversión — srv/convert.py
Este es el descubrimiento que cambia la arquitectura: el servidor Calibre convierte, por HTTP.
| Carretera | Método | Rol |
|---|---|---|
/conversion/book-data/{id} | OBTENER | formatos de entrada, formatos de salida, opciones aceptadas |
/conversion/start/{id} | ENVIAR | cuerpo {input_fmt, output_fmt, options} → devuelve una identificación de trabajo |
/conversion/status/{job} | ENVIAR | {running, percent, msg} luego el estado terminal; ?abort_job=1 interrumpe |
Detalles anotados en la fuente y todos los importantes para su uso:
- PUBLICAR solamente (
receive_data_methods = {'POST'}). Se rechaza un GET. input_fmtdebe ser un formato que realmente tiene el libro : El servidor crea la ruta de origen a partir de ahí y descarta el resto. Lo espera en mayúsculas,output_fmten minúscula.- El estado se consume en la primera lectura del terminal :
del conversion_jobs[job_id], entoncescleanup()en unfinally. Sólo puedes leer la conclusión una vez. Y sólo el usuario que lanzó el trabajo, en la misma biblioteca, puede consultarlo.CalibreKit.convert(…)envuelve el bucle de sondeo para que ninguna persona que llama tenga que pensar en ello. - El formato del producto se agrega al libro en la biblioteca. :
db.add_format(book_id, fmt, output_path). Por lo tanto, el trabajo se realiza una sola vez y todos los dispositivos se benefician de él./get/EPUB/{id}. - Se rechazan los archivos de recetas (ejecución de código) y la red prohíbe una lista de opciones.
La ruta completa, como por ejemplo 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. Posición de lectura y anotaciones — srv/books.py
Calibre ya sincroniza las posiciones de reproducción, del lado del servidor.
| Carretera | Método | Rol |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | OBTENER | posiciones conocidas, por dispositivo |
/book-set-last-read-position/{library}/{id}/{FMT} | ENVIAR | guarda {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | OBTENER | destacados y notas |
/book-manifest/{id}/{FMT} | OBTENER | el servidor normaliza cualquier formato en manifiesto para su propio lector |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | OBTENER | un recurso de libro estandarizado |
/book-get-storage/{library}/{id}/{FMT} | OBTENER | estado de almacenamiento |
Dos consecuencias para Podbook:
Podemos abandonar los periódicos .jsonl descrito en las especificaciones iniciales, al menos como mecanismo principal: Calibre ya ocupa una posición por dispositivo, por libro y por formato. Los registros siguen siendo útiles para lo que Calibre no sabe: la posición en el audio, el cuaderno de vocabulario.
/book-manifest es un atajo para evaluar. El servidor ya sabe transformar cualquier formato en una estructura estandarizada para su lector web. Esto cubre parte de lo que BookKit tenía que hacer. Para explorar antes de escribir el analizador: el formato del manifiesto es interno a Calibre, por lo tanto, debe tratarse como la superficie /ajax, con precaución.
srv/kosync.py expone adicionalmente el protocolo de sincronización KOReader (/kosync/users/auth, /kosync/syncs/progress), otra posible ruta, ya adoptada por otros lectores.
6. Búsqueda de texto completo — srv/fts.py
| Carretera | Método | Rol |
|---|---|---|
/fts/search | OBTENER | buscar en el texto de los libros, no solo metadatos |
/fts/snippets/{book_ids} | OBTENER | extractos con contexto |
/fts/reindex, /fts/indexing, /fts/disable | ENVIAR | control de índice |
El índice debe estar habilitado en el lado del servidor. Por lo tanto, Podbook no tiene que indexar la biblioteca para la búsqueda global, solo para libros importados fuera de Calibre.
7. Escribiendo en la biblioteca — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L ejecuta un subcomando calibredb en el servidor. es el forma admitida de escribir: metadata.db no tolera un segundo editor.
Comandos 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 le permite escribir el estado de procesamiento de Podbook en una columna personalizada #podbook, visible desde Calibre, correctamente.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Estándar, estable, anunciado en Hola en la red local. Es la retirada cuando /ajax no está allí, especialmente contra Calibre-Web.
9. Para qué cambia esto Podbook
| Hipótesis inicial | Realidad |
|---|---|
| Es necesario escribir un analizador MOBI | Falso de v1: ebook-convert ya fue suficiente |
| La conversión requiere taller en Mac | Falso : calibre-server se convierte en HTTP. iPad solicitudes, el servidor funciona, la biblioteca se enriquece |
| Podbook debe inventar su sincronización de posición | Parcialmente falso : Calibre ya tiene uno, por dispositivo |
| Podbook debe indexarse para la búsqueda global | Falso : /fts/search existe |
metadata.db solo lectura, no es posible escribir | Falso : /cdb/cmd/… es la ruta de escritura oficial |
El API /ajax es una base sólida | Falso : no público, no estable. De ahí la decodificación tolerante, la detección de la naturaleza y el retroceso OPDS |
Sigue siendo cierto: los archivos protegidos con DRM no se abren y debe estar ejecutándose un servidor Calibre en algún lugar para que la conversión y la búsqueda global estén disponibles.