Saltar al contenido principal

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 null nunca 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​

CarreteraDevoluciones
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,3diccionario 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.

CarreteraMétodoRol
/conversion/book-data/{id}OBTENERformatos de entrada, formatos de salida, opciones aceptadas
/conversion/start/{id}ENVIARcuerpo {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_fmt debe 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_fmt en minúscula.
  • El estado se consume en la primera lectura del terminal : del conversion_jobs[job_id], entonces cleanup() en un finally. 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.

CarreteraMétodoRol
/book-get-last-read-position/{library}/{id}:{FMT}OBTENERposiciones conocidas, por dispositivo
/book-set-last-read-position/{library}/{id}/{FMT}ENVIARguarda {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}OBTENERdestacados y notas
/book-manifest/{id}/{FMT}OBTENERel servidor normaliza cualquier formato en manifiesto para su propio lector
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}OBTENERun recurso de libro estandarizado
/book-get-storage/{library}/{id}/{FMT}OBTENERestado 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​

CarreteraMétodoRol
/fts/searchOBTENERbuscar en el texto de los libros, no solo metadatos
/fts/snippets/{book_ids}OBTENERextractos con contexto
/fts/reindex, /fts/indexing, /fts/disableENVIARcontrol 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 inicialRealidad
Es necesario escribir un analizador MOBIFalso de v1: ebook-convert ya fue suficiente
La conversión requiere taller en MacFalso : calibre-server se convierte en HTTP. iPad solicitudes, el servidor funciona, la biblioteca se enriquece
Podbook debe inventar su sincronización de posiciónParcialmente falso : Calibre ya tiene uno, por dispositivo
Podbook debe indexarse para la búsqueda globalFalso : /fts/search existe
metadata.db solo lectura, no es posible escribirFalso : /cdb/cmd/… es la ruta de escritura oficial
El API /ajax es una base sólidaFalso : 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.