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
nullnunca 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ília | Para 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
| Estrada | Devoluçõ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,3 | dicioná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.
| Estrada | Método | Função |
|---|---|---|
/conversion/book-data/{id} | OBTER | formatos de entrada, formatos de saída, opções aceites |
/conversion/start/{id} | PUBLICAR | corpo {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_fmtdeve 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_fmtem letras minúsculas.- O estado é consumido na primeira leitura do terminal :
del conversion_jobs[job_id], entãocleanup()numfinally. 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.
| Estrada | Método | Função |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | OBTER | posições conhecidas, por dispositivo |
/book-set-last-read-position/{library}/{id}/{FMT} | PUBLICAR | guarda {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | OBTER | destaques e notas |
/book-manifest/{id}/{FMT} | OBTER | servidor normaliza qualquer formato em manifesto para o seu próprio leitor |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | OBTER | um recurso de livro padronizado |
/book-get-storage/{library}/{id}/{FMT} | OBTER | estado 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
| Estrada | Método | Função |
|---|---|---|
/fts/search | OBTER | pesquisa no texto dos livros, e não apenas metadados |
/fts/snippets/{book_ids} | OBTER | extratos com contexto |
/fts/reindex, /fts/indexing, /fts/disable | PUBLICAR | controlo 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 inicial | Realidade |
|---|---|
| Um analisador MOBI necessita de ser escrito | Falso da v1: ebook-convert já era suficiente |
| A conversão requer workshop em Mac | Falso : calibre-server converte para HTTP. iPad pedidos, o servidor funciona, a biblioteca é enriquecida |
| Podbook deve inventar o seu tempo de posição | Parcialmente falso : Calibre já contém um, por dispositivo |
| Podbook deve indexar para pesquisa global | Falso : /fts/search existe |
metadata.db apenas leitura, não é possível escrever | Falso : /cdb/cmd/… é a via oficial de escrita |
O API /ajax é uma base sólida | Falso : 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.