メインコンテンツまでスキップ

CalibreサーバーのAPI - 調査

技術および設計ドキュメントに記載されています。 このドキュメントには、研究結果と提案されたアーキテクチャが保持されています。 記述されているすべての機能が必ずしも利用できるとは限りません。 ユーザーガイド およびコードには、現在の動作が規定されています。

2026年10月30日にCalibreのソースコード(src/calibre/srv/に基づいて実施された調査。ドキュメントは存在しません。実装済みでテスト対象 Packages/Core/Sources/CalibreKit.


1. メンテナー自身からの警告​

API のドキュメントについて質問された際、 /ajax Kovid Goyal 氏は、ドキュメントは存在せず、このインターフェースは 公開されておらず安定もしていないため、 ソースコードを読む必要があると回答しました。影響については、 CalibreKit :

  • すべてのデコードが許容範囲内であること、 ― 欠落したフィールド、予期しないフィールド、または null があってもライブラリ一覧が失敗することはありません。
  • サーバーの性質は分岐時に検出されます。 (detectFlavor())、Calibre-Web はすべてに対して 404 を返し、 /ajax/* OPDS のみを提供するためです。
  • OPDSはフォールバックオプションとして残ります。 これは標準化されており、安定しています。
  • テストは実際のバイト形状を固定するため、Calibreのバージョンアップによってアプリケーションではなくテストが壊れることになります。

2. ライブラリ命名規則3つ​

これがこのAPIの主な落とし穴です。 一度エンコードされ、 CalibreClient.url(path:query:libraryInQuery:) 4つのテストで検証されます。

ルートファミリーどこに配置すべきか? 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ディクショナリ IDによるインデックス, null 禁書の場合
GET /ajax/book/{id}/{library}書籍のメタデータ
GET /ajax/categories/{library}トップレベルカテゴリ
GET /ajax/category/{nom}/{library}カテゴリの内容(ページ分け済み)
GET /ajax/books_in/{cat}/{item}/{library}カテゴリのID カテゴリ

2つのデコードトラップ(両方とも以下で説明)テスト:

識別子はオブジェクトに存在しません。 /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 に関する 2 つの結果:

ログを破棄できます .jsonl 初期仕様で説明されているように、少なくとも主要なメカニズムとして、Calibreはデバイスごと、書籍ごと、フォーマットごとに位置情報を保持しています。ログは、Calibreが把握していない情報、つまり音声ファイル内の位置や語彙ノートの情報などを取得するのに役立ちます。

/book-manifest 評価へのショートカットです。 サーバーは、あらゆるフォーマットをWebリーダー用の正規化された構造に変換する方法を既に知っています。これは、 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 2つ目の書き込みは許可しません。

使用可能なコマンド 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パーサーを作成する必要があります」、v1以降は偽」、 ebook-convert 既に十分でした」、
変換にはMacに関するワークショップが必要です」、偽」、 : calibre-server HTTPによって変換されます。」 iPadからのリクエストがあり、サーバーが動作し、ライブラリは「充実しつつある」、
Podbookは独自の位置同期を考案する必要がある、一部誤り、 Calibreは既にデバイスごとに位置同期機能を持っている、
Podbookはグローバル検索のためにインデックスを作成する必要がある、偽」、 : /fts/search 存在する、
metadata.db 読み取り専用で、書き込みは不可能、偽」、 : /cdb/cmd/… 公式の書き込みパスである、
API、 /ajax 強固な基盤である、偽」、 公開されておらず、安定していない。 そのため、寛容なデコード、性質検出、およびOPDSフォールバックが必要となる、

依然として正しい:DRMで保護されたファイルは開けず、変換とグローバル検索を行うにはCalibreサーバーがどこかで稼働している必要がある「利用可能