Перейти к основному содержимому

API сервера Calibre — обзор"

Техническая и проектная документация. В этом документе сохранены исследования и предлагаемая архитектура. Не все описанные функции обязательно доступны; руководство пользователя" и код определяют текущую работу."

Опрос проведен 30 октября 2026 г. по исходному коду Calibre ("src/calibre/srv/), документация отсутствует. Реализовано и покрыто тестами в Packages/Core/Sources/CalibreKit.


1. Предупреждение, которое исходит от самого сопровождающего​

На вопрос о документации для API /ajax, Ковид Гоял отвечает, что ее не существует, что эта поверхность " ни общедоступная, ни стабильная, и что исходный код необходимо прочитать. Последствия отмечены в CalibreKit :

  • все декодирование терпимо — отсутствующий, неожиданный или null никогда не приводит к ошибке при листинге библиотеки;
  • характер сервера определяется при ветвлении (detectFlavor()), потому что Calibre-Web возвращает 404 для всего /ajax/* и предлагает только OPDS;
  • OPDS остается резервный маршрут, стандартизированный и стабильный;
  • Тесты фиксируют фактическую форму байтов, так что обновление версии Calibre ломает тест, а не приложение."

2. Три соглашения для именования библиотеки​

Это главная ловушка этого API. Он кодируется один раз в CalibreClient.url(path:query:libraryInQuery:) и проверяется четырьмя тестами."

Семейство маршрутовКуда он идет library_id
/ajax/…, /get/…Компонент пути — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…Параметр запроса — ?library_id=Calibre_Library
/book-…-last-read-position/…Компонент пути, снова

Проверено в srv/utils.py : get_library_data() чтения rd.query.get('library_id').


3. Каталог — srv/ajax.py​

МаршрутОтображает
GET /ajax/library-info{library_map, default_library} — также служит проверкой характера сервера
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, параметры query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3словарь индексируется по идентификатору, null для запрещенной книги
GET /ajax/book/{id}/{library}метаданные книги
GET /ajax/categories/{library}категории верхнего уровня
GET /ajax/category/{nom}/{library}содержимое категории, постранично
GET /ajax/books_in/{cat}/{item}/{library}идентификаторы категории

Две ловушки декодирования, обе проверены:

идентификатор отсутствует в объекте." /ajax/books индексирует свой словарь по идентификатору и не повторяет его внутри." CalibreKit внедряет его через « userInfo декодера».

0101-01-01T00:00:00+00:00 означает «нет даты». Это страж». UNDEFINED_DATE Calibre. При наивном расшифровке он выдает книгу, изданную в древности». CalibreDate возвращает ее к». nil.


4. Преобразование —». srv/convert.py​

Это открытие, которое меняет архитектуру: сервер Calibre преобразует через HTTP.».

МаршрутМетод».Роль
/conversion/book-data/{id}GET».форматы ввода, форматы вывода, принимаемые параметры».
/conversion/start/{id}POST».тело». {input_fmt, output_fmt, options} → возвращает рабочий идентификатор».
/conversion/status/{job}POST».{running, percent, msg} затем терминал». состояние; ?abort_job=1 прерывания

Подробности указаны в исходном коде, и все они важны при использовании:

  • Только POST (receive_data_methods = {'POST'}). Запрос GET отклонен."
  • input_fmt должен быть формат, который фактически есть в книге : сервер строит путь к исходному коду оттуда и отклоняет остальное. Он ожидает его в верхнем регистре, output_fmt в нижнем регистре."
  • Статус обрабатывается при первом чтении с терминала : del conversion_jobs[job_id], затем cleanup() в finally. Заключение можно прочитать только один раз. И только пользователь, запустивший задание в той же библиотеке, может его запросить. CalibreKit.convert(…) инкапсулирует цикл опроса, поэтому вызывающей стороне не нужно об этом думать.
  • Созданный формат добавляется к книге в библиотеке. : db.add_format(book_id, fmt, output_path). Таким образом, работа выполняется только один раз, и все устройства затем получают от нее выгоду. /get/EPUB/{id}.
  • Файлы рецептов отклоняются (выполнение кода), и список параметров запрещен сетью.

Полный путь, как. CalibreKit реализует его:

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. Позиция чтения и аннотации — srv/books.py​

Calibre уже синхронизирует позиции чтения на стороне сервера.

МаршрутМетод».Роль
/book-get-last-read-position/{library}/{id}:{FMT}GET».известные позиции для каждого устройства
/book-set-last-read-position/{library}/{id}/{FMT}POST».сохраняет {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GET».выделения и заметки
/book-manifest/{id}/{FMT}GET».Сервер нормализует любой формат представлен для собственного читателя
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GET».ресурс из нормализованной книги
/book-get-storage/{library}/{id}/{FMT}GET».состояние хранения

Два последствия для Podbook:

Журналы могут быть удалены .jsonl описано в первоначальных спецификациях, по крайней мере, как основной механизм: Calibre уже содержит позицию для каждого устройства, каждой книги и каждого формата. Журналы остаются полезными для того, чего Calibre не знает — позиции в аудио, блокнота со словарем.

/book-manifest является ярлыком для оценки. Сервер уже знает, как преобразовать любой формат в нормализованную структуру для своего веб-ридера. Это охватывает часть того, что BookKit должно было сделать. Перед написанием парсера следует изучить: формат манифеста является внутренним для Calibre, поэтому относитесь к нему как к поверхностному уровню /ajax, с осторожностью.

srv/kosync.py также предоставляет протокол синхронизации KOReader (/kosync/users/auth, /kosync/syncs/progress), еще один возможный подход, уже принятый другими ридерами.


6. Полнотекстовый поиск — srv/fts.py​

МаршрутМетод».Роль
/fts/searchGET».поиск в тексте книг, не только метаданные
/fts/snippets/{book_ids}GET».извлечения с контекстом
/fts/reindex, /fts/indexing, /fts/disablePOST».управление индексом

Индекс должен быть включен на стороне сервера. Поэтому Podbook не нужно индексировать саму библиотеку для глобального поиска — только для книг, импортированных вне Calibre


7. Запись в библиотеку — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L выполняет подкоманду calibredb на сервере. Это тот поддерживаемый способ записи: metadata.db не допускает второго записывающего."

Доступные команды: 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 позволяет записывать статус обработки Podbook в столбец "настроенный #podbook, видимый из Calibre, правильно."


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Стандартный, стабильный, анонсированный в Bonjour в локальной сети. Это резервный вариант, когда /ajax нет — особенно по сравнению с Calibre-Web.


9. Что это меняет для Podbook​

Первоначальная гипотезаРеальность
Необходимо написать парсер MOBIЛожь начиная с версии 1: ebook-convert было уже достаточно
Для преобразования требуется семинар по MacЛожь : calibre-server преобразовано HTTP. iPad запрашивает, сервер работает, библиотека «становится богаче
Podbook нужно изобрести собственную синхронизацию позицийЧастично неверно : Calibre уже имеет одну, для каждого устройства
Podbook нужно индексировать для глобального поискаЛожь : /fts/search существует
metadata.db только для чтения, запись невозможнаЛожь : /cdb/cmd/… является официальным путем записи
API /ajax является прочной основойЛожь : не публичный, нестабильный. Отсюда толерантное декодирование, определение природы и резервный вариант OPDS

Остается верным: файлы, защищенные DRM, не будут открываться, и для преобразования и глобального поиска где-то должен работать сервер Calibre доступно.