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
nullorsakar 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.
| Ruttfamilj | Vart ä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 äg | Returer |
|---|---|
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,3 | ordbok 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äg | Metod | Roll |
|---|---|---|
/conversion/book-data/{id} | HÄMTA | indataformat, utdataformat, accepterade alternativ |
/conversion/start/{id} | POST | kropp {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_fmtmå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_fmtmed gemener.- Status förbrukas vid första terminalläsning :
del conversion_jobs[job_id], alltsåcleanup()i enfinally. 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äg | Metod | Roll |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | HÄMTA | kända positioner, per enhet |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | sparar {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | HÄMTA | höjdpunkter och anteckningar |
/book-manifest/{id}/{FMT} | HÄMTA | servern normaliserar alla format i manifest för sin egen läsare |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | HÄMTA | en standardiserad bokresurs |
/book-get-storage/{library}/{id}/{FMT} | HÄMTA | lagringsstatus |
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äg | Metod | Roll |
|---|---|---|
/fts/search | HÄMTA | sök i böckernas text, inte bara metadata |
/fts/snippets/{book_ids} | HÄMTA | utdrag med sammanhang |
/fts/reindex, /fts/indexing, /fts/disable | POST | indexkontroll |
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 hypotes | Verkligheten |
|---|---|
| En MOBI-tolkare måste skrivas | False från v1: ebook-convert var redan tillräckligt |
| Konvertering kräver workshop på Mac | Falskt : calibre-server konverterar till HTTP. iPad begär, servern fungerar, biblioteket är berikat |
| Podbook måste uppfinna sin positionstiming | Delvis falskt : Calibre rymmer redan en, per enhet |
| Podbook bör indexera för global sökning | Falskt : /fts/search finns |
metadata.db skrivskyddad, ingen skrivning möjlig | Falskt : /cdb/cmd/… är den officiella skrivvägen |
API /ajax är en solid grund | Falskt : 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.