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/search | GET». | поиск в тексте книг, не только метаданные |
/fts/snippets/{book_ids} | GET». | извлечения с контекстом |
/fts/reindex, /fts/indexing, /fts/disable | POST». | управление индексом |
Индекс должен быть включен на стороне сервера. Поэтому 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 доступно.