Hoppa till huvudinnehåll

API för server Calibre — noteras

Teknisk fil och design. Detta dokument bevarar studierna och den planerade arkitekturen. Alla funktioner som beskrivs kanske inte är tillgängliga; den användarhandbok och koden anger den aktuella operationen.

Uttalande gjort den 30 oktober 2026 från källkoden för Calibre (src/calibre/srv/), ingen dokumentation: ingen finns. Implementerad och täckt av tester i Packages/Core/Sources/CalibreKit.


1. Varning, som kommer från underhållaren själv​

Frågade om dokumentation för API /ajax, Kovid Goyal svarar att den inte existerar, att denna yta inte är varken offentlig eller stabil, och att du måste läsa källan. Konsekvenser bibehållna CalibreKit :

  • all avkodning är tolerant — en saknad, oväntad eller null orsakar aldrig att en bibliotekslistning misslyckas;
  • serverns karaktär upptäcks vid anslutning (detectFlavor()), eftersom Calibre-Web svarar 404 på allt /ajax/* och erbjuder endast OPDS;
  • OPDS förblir reservvägen, standardiserad och stabil;
  • -tester fryser de faktiska byteformerna, så att en uppgradering av Calibre bryter ett test snarare än applikationen.

2. Tre konventioner för att namnge biblioteket​

Detta är huvudfällan för denna API. Den är kodad en gång in CalibreClient.url(path:query:libraryInQuery:) och verifierad genom fyra tester.

RuttfamiljVart är på väg library_id
/ajax/…, /get/…sökvägskomponent — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…frågeparameter — ?library_id=Calibre_Library
/book-…-last-read-position/…sökvägskomponent, igen

Checkade in srv/utils.py : get_library_data() säng rd.query.get('library_id').


3. Katalog — srv/ajax.py​

VägReturer
GET /ajax/library-info{library_map, default_library} — fungerar också som ett servernaturtest
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, parametrar query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3ordbok indexerad med identifierare, null för en förbjuden bok
GET /ajax/book/{id}/{library}metadata för en bok
GET /ajax/categories/{library}kategorier på första nivån
GET /ajax/category/{nom}/{library}innehållet i en kategori, paginerad
GET /ajax/books_in/{cat}/{item}/{library}identifierarna för en kategori

Två avkodningsfällor, båda täckta av tester:

Identifieraren finns inte i ämnet. /ajax/books indexerar sin ordbok med identifierare och upprepar den inte inuti. CalibreKit injicerar den genom userInfo för dekodern.

0101-01-01T00:00:00+00:00 betyder "inget datum". Det är vaktposten UNDEFINED_DATE av Calibre. Naivt avkodad producerar den en bok publicerad i antiken. CalibreDate tar det tillbaka till nil.


4. Konvertering — srv/convert.py​

Detta är upptäckten som ändrar arkitekturen: servern Calibre konverterar med HTTP.

VägMetodRoll
/conversion/book-data/{id}HÄMTAindataformat, utdataformat, accepterade alternativ
/conversion/start/{id}POSTkropp {input_fmt, output_fmt, options} → returnerar ett jobb-ID
/conversion/status/{job}POST{running, percent, msg} sedan terminaltillståndet; ?abort_job=1 avbryter

Detaljer noterade i källan, och alla viktiga för användning:

  • Endast POST (receive_data_methods = {'POST'}). En GET nekas.
  • input_fmt måste vara ett format som boken faktiskt har : Servern bygger källsökvägen därifrån och kasserar resten. Han väntar på det med versaler, output_fmt med gemener.
  • Status förbrukas vid första terminalläsning : del conversion_jobs[job_id], alltså cleanup() i en finally. Du kan bara läsa slutsatsen en gång. Och bara användaren som startade jobbet, i samma bibliotek, kan fråga det. CalibreKit.convert(…) omsluter sonderingsslingan så att ingen som ringer behöver tänka på det.
  • Produktformatet läggs till i boken i biblioteket : db.add_format(book_id, fmt, output_path). Arbetet görs därför bara en gång och alla enheter drar då nytta av det. /get/EPUB/{id}.
  • Receptfiler nekas (kodexekvering), och en lista med alternativ är förbjuden av nätverket.

Hela rutten, som t.ex CalibreKit implementerar det:

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. Läsposition och kommentarer — srv/books.py​

Calibre synkroniserar redan uppspelningspositioner, serversidan.

VägMetodRoll
/book-get-last-read-position/{library}/{id}:{FMT}HÄMTAkända positioner, per enhet
/book-set-last-read-position/{library}/{id}/{FMT}POSTsparar {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}HÄMTAhöjdpunkter och anteckningar
/book-manifest/{id}/{FMT}HÄMTAservern normaliserar alla format i manifest för sin egen läsare
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}HÄMTAen standardiserad bokresurs
/book-get-storage/{library}/{id}/{FMT}HÄMTAlagringsstatus

Två konsekvenser för Podbook:

Vi kan överge tidningarna .jsonl beskrivs i de initiala specifikationerna, åtminstone som huvudmekanismen: Calibre har redan en position per enhet, per bok och per format. Loggarna är fortfarande användbara för det som Calibre inte vet – positionen i ljudet, vokabuläranteckningsboken.

/book-manifest är en genväg att utvärdera. Servern vet redan hur man omvandlar vilket format som helst till en standardiserad struktur för sin webbläsare. Detta täcker en del av vad BookKit var tvungen att göra. Ska utforskas innan du skriver tolken: manifestets format är internt i Calibre och ska därför behandlas som ytan /ajax, med försiktighet.

srv/kosync.py exponerar dessutom KOReader-synkroniseringsprotokollet (/kosync/users/auth, /kosync/syncs/progress), en annan möjlig väg, redan antagen av andra läsare.


6. Fulltextsökning — srv/fts.py​

VägMetodRoll
/fts/searchHÄMTAsök i böckernas text, inte bara metadata
/fts/snippets/{book_ids}HÄMTAutdrag med sammanhang
/fts/reindex, /fts/indexing, /fts/disablePOSTindexkontroll

Indexet måste vara aktiverat på serversidan. Podbook behöver därför inte indexera själva biblioteket för global sökning — endast för böcker som importeras utanför Calibre.


7. Skriva i biblioteket — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L kör ett underkommando calibredb på servern. Det är den stöds sätt att skriva: metadata.db tolererar inte en andra redigerare.

Tillgängliga kommandon: 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 låter dig skriva bearbetningsstatusen för Podbook i en anpassad kolumn #podbook, synlig från Calibre, korrekt.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stabil, annonserad i Hello på det lokala nätverket. Det är uttaget när /ajax finns inte där — särskilt mot Calibre-Web.


9. Vad detta ändrar för Podbook​

Initial hypotesVerkligheten
En MOBI-tolkare måste skrivasFalse från v1: ebook-convert var redan tillräckligt
Konvertering kräver workshop på MacFalskt : calibre-server konverterar till HTTP. iPad begär, servern fungerar, biblioteket är berikat
Podbook måste uppfinna sin positionstimingDelvis falskt : Calibre rymmer redan en, per enhet
Podbook bör indexera för global sökningFalskt : /fts/search finns
metadata.db skrivskyddad, ingen skrivning möjligFalskt : /cdb/cmd/… är den officiella skrivvägen
API /ajax är en solid grundFalskt : inte offentlig, inte stabil. Därav den toleranta avkodningen, naturdetekteringen och återgången OPDS

Fortfarande sant: DRM-skyddade filer öppnas inte, och en Calibre-server måste köras någonstans för att konvertering och global sökning ska vara tillgänglig.