본문으로 건너뛰기

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. 라이브러리 명명에 대한 세 가지 규칙​

이것이 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() a 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 서버에 있습니다. 그렇습니다. la 쓰기에 지원되는 경로: 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 분석기를 작성해야 합니다v1부터는 거짓입니다: ebook-convert 이미 충분했습니다
Mac에 대한 워크숍이 필요합니다.거짓 : calibre-server HTTP을 통해 변환합니다. iPad이 요청하면 서버가 작동하고 라이브러리가 확장됩니다.
Podbook은 자체 위치 동기화 기능을 개발해야 합니다.부분적으로 거짓 : Calibre은 이미 장치별로 하나씩 가지고 있습니다.
Podbook은 전역 검색을 위해 인덱싱되어야 합니다거짓 : /fts/search 존재합니다
metadata.db 읽기 전용, 쓰기 접근 불가거짓 : /cdb/cmd/… 공식 쓰기 경로입니다
API /ajax 견고한 기반입니다거짓 : 공개되지 않았고 안정적이지 않습니다. 따라서 허용 가능한 디코딩, 유형 감지 및 OPDS 대체 기능이 필요합니다.

여전히 사실입니다. DRM으로 보호된 파일은 열리지 않으며, 변환 및 전체 검색을 사용하려면 Calibre 서버가 어딘가에서 실행 중이어야 합니다.