Saltar para o conteúdo principal

O API do servidor Calibre — anotado

Arquivo técnico e projeto. Este documento preserva os estudos e a arquitetura prevista. Nem todas as funções descritas podem estar disponíveis; o guia do utilizador e o código especificam a operação atual.

Declaração feita em 30 de outubro de 2026 a partir do código fonte de Calibre (src/calibre/srv/), nenhuma documentação: não existe nenhuma. Implementado e coberto por testes em Packages/Core/Sources/CalibreKit.


1. Aviso, que provém do próprio mantenedor​

Questionado sobre a documentação para API /ajax, Kovid Goyal responde que não existe, que esta superfície não é nem público nem estável, e que deve ler a fonte. Consequências retidas em CalibreKit :

  • toda a descodificação é tolerante — em falta, inesperado ou null nunca causa falha na listagem de uma biblioteca;
  • a natureza do servidor é detetada na ligação (detectFlavor()), porque Calibre-Web responde 404 em tudo /ajax/* e apenas ofertas OPDS;
  • OPDS continua a ser a via alternativa, normalizado e estável;
  • Os testes congelam os formatos de bytes reais, pelo que uma atualização de Calibre interrompe um teste e não a aplicação.

2. Três convenções para dar nome à biblioteca​

Esta é a armadilha principal deste API. É codificado uma vez em CalibreClient.url(path:query:libraryInQuery:) e verificado por quatro testes.

Percurso famíliaPara onde vai library_id
/ajax/…, /get/…componente de caminho — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…parâmetro de consulta — ?library_id=Calibre_Library
/book-…-last-read-position/…componente de caminho, novamente

Check-in srv/utils.py : get_library_data() cama rd.query.get('library_id').


3. Catálogo — srv/ajax.py​

EstradaDevoluções
GET /ajax/library-info{library_map, default_library} — serve também como teste de natureza do 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,3dicionário indexado por identificador, null para um livro banido
GET /ajax/book/{id}/{library}os metadados de um livro
GET /ajax/categories/{library}categorias de primeiro nível
GET /ajax/category/{nom}/{library}o conteúdo de uma categoria, paginado
GET /ajax/books_in/{cat}/{item}/{library}os identificadores de uma categoria

Duas armadilhas de descodificação, ambas abrangidas por testes:

O identificador não está no assunto. /ajax/books indexa o seu dicionário por identificador e não o repete internamente. CalibreKit injeta através do userInfo do descodificador.

0101-01-01T00:00:00+00:00 significa “sem data”. É a sentinela UNDEFINED_DATE de Calibre. Descodificado ingenuamente, produz um livro publicado na Antiguidade. CalibreDate traz de volta para nil.


4. Conversão — srv/convert.py​

Esta é a descoberta que muda a arquitetura: o servidor Calibre converte, em HTTP.

EstradaMétodoFunção
/conversion/book-data/{id}OBTERformatos de entrada, formatos de saída, opções aceites
/conversion/start/{id}PUBLICARcorpo {input_fmt, output_fmt, options} → devolve um ID de trabalho
/conversion/status/{job}PUBLICAR{running, percent, msg} então o estado terminal; ?abort_job=1 interrupções

Detalhes anotados na fonte e todos significativos para utilização:

  • Apenas POSTAGEM (receive_data_methods = {'POST'}). Um GET é recusado.
  • input_fmt deve ser um formato que o livro possui realmente : O servidor constrói o caminho de origem a partir daí e descarta o restante. Ele espera por isso em maiúsculas, output_fmt em letras minúsculas.
  • O estado é consumido na primeira leitura do terminal : del conversion_jobs[job_id], então cleanup() num finally. Só pode ler a conclusão uma vez. E apenas o utilizador que lançou o job, na mesma biblioteca, poderá consultá-lo. CalibreKit.convert(…) envolve o loop de sondagem para que nenhum chamador tenha de pensar nisso.
  • O formato do produto é adicionado ao livro na biblioteca : db.add_format(book_id, fmt, output_path). O trabalho é, portanto, feito apenas uma vez e todos os dispositivos beneficiam dele. /get/EPUB/{id}.
  • Os ficheiros de receitas são recusados ​​(execução de código) e uma lista de opções é proibida pela rede.

A rota completa, como CalibreKit 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. Posição de leitura e anotações — srv/books.py​

Calibre já sincroniza as posições de reprodução, lado do servidor.

EstradaMétodoFunção
/book-get-last-read-position/{library}/{id}:{FMT}OBTERposições conhecidas, por dispositivo
/book-set-last-read-position/{library}/{id}/{FMT}PUBLICARguarda {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}OBTERdestaques e notas
/book-manifest/{id}/{FMT}OBTERservidor normaliza qualquer formato em manifesto para o seu próprio leitor
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}OBTERum recurso de livro padronizado
/book-get-storage/{library}/{id}/{FMT}OBTERestado de armazenamento

Duas consequências para Podbook:

Podemos abandonar os jornais .jsonl descrito nas especificações iniciais, pelo menos como mecanismo principal: Calibre já ocupa uma posição por dispositivo, por livro e por formato. Os registos continuam a ser úteis para o que Calibre não sabe — a posição no áudio, o caderno de vocabulário.

/book-manifest é um atalho para avaliar. O servidor já sabe transformar qualquer formato numa estrutura normalizada para o seu leitor web. Isto cobre parte do que BookKit tinha de servir. A explorar antes de escrever o analisador: o formato do manifesto é interno ao Calibre, pelo que deve ser tratado como a superfície /ajax, com precaução.

srv/kosync.py expõe adicionalmente o protocolo de sincronização KOReader (/kosync/users/auth, /kosync/syncs/progress), outro caminho possível, já adoptado por outros leitores.


6. Pesquisa de texto integral — srv/fts.py​

EstradaMétodoFunção
/fts/searchOBTERpesquisa no texto dos livros, e não apenas metadados
/fts/snippets/{book_ids}OBTERextratos com contexto
/fts/reindex, /fts/indexing, /fts/disablePUBLICARcontrolo de índice

O índice deve estar ativado no lado do servidor. Podbook não necessita, portanto, de indexar a própria biblioteca para pesquisa global — apenas para livros importados fora de Calibre.


7. Escrever na biblioteca — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L executa um subcomando calibredb no servidor. É o forma suportada de escrever: metadata.db não tolera um segundo editor.

Comandos disponíveis: 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 permite escrever o estado de processamento de Podbook numa coluna personalizada #podbook, visível em Calibre, corretamente.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Padrão, estável, anunciado em Hello na rede local. É a retirada quando /ajax não está lá — especialmente contra Calibre-Web.


9. O que é que isto muda para Podbook​

Hipótese inicialRealidade
Um analisador MOBI necessita de ser escritoFalso da v1: ebook-convert já era suficiente
A conversão requer workshop em MacFalso : calibre-server converte para HTTP. iPad pedidos, o servidor funciona, a biblioteca é enriquecida
Podbook deve inventar o seu tempo de posiçãoParcialmente falso : Calibre já contém um, por dispositivo
Podbook deve indexar para pesquisa globalFalso : /fts/search existe
metadata.db apenas leitura, não é possível escreverFalso : /cdb/cmd/… é a via oficial de escrita
O API /ajax é uma base sólidaFalso : não público, não estável. Daí a descodificação tolerante, a deteção de natureza e o fallback OPDS

Continua a ser verdade: os ficheiros protegidos por DRM não serão abertos e um servidor Calibre deve estar a ser executado algures para que a conversão e a pesquisa global estejam disponíveis.