API af server Calibre — noteret
Teknisk fil og design. Dette dokument bevarer undersøgelserne og den påtænkte arkitektur. Ikke alle beskrevne funktioner er muligvis tilgængelige; den brugervejledning og koden angiver den aktuelle handling.
Erklæring afgivet den 30. oktober 2026 fra kildekoden til Calibre (src/calibre/srv/), ingen dokumentation: ingen eksisterer. Implementeret og omfattet af test i Packages/Core/Sources/CalibreKit.
1. Advarsel, som kommer fra vedligeholderen selv
Spurgte om dokumentation for API /ajax, Kovid Goyal svarer, at den ikke eksisterer, at denne overflade ikke er hverken offentlig eller stabil, og at du skal læse kilden. Konsekvenser bibeholdt i CalibreKit :
- al afkodning er tolerant — en manglende, uventet eller
nullfår aldrig en biblioteksfortegnelse til at mislykkes; - serverens art registreres ved forbindelse (
detectFlavor()), fordi Calibre-Web svarer 404 på alt/ajax/*og tilbyder kun OPDS; - OPDS forbliver reserveruten, standardiseret og stabil;
- -test fryser de faktiske byte-former, så en opgradering af Calibre bryder en test i stedet for applikationen.
2. Tre konventioner for navngivning af biblioteket
Dette er hovedfælden i denne API. Det er kodet én gang ind CalibreClient.url(path:query:libraryInQuery:) og verificeret ved fire tests.
| Rutefamilie | Hvor skal hen library_id |
|---|---|
/ajax/…, /get/… | stikomponent — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | forespørgselsparameter — ?library_id=Calibre_Library |
/book-…-last-read-position/… | stikomponent, igen |
Tjekket ind srv/utils.py : get_library_data() seng rd.query.get('library_id').
3. Katalog — srv/ajax.py
| Vej | Returnering |
|---|---|
GET /ajax/library-info | {library_map, default_library} – fungerer også som en servernaturtest |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parametre query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | ordbog indekseret efter identifikator, null for en forbudt bog |
GET /ajax/book/{id}/{library} | metadataene for en bog |
GET /ajax/categories/{library} | kategorier på første niveau |
GET /ajax/category/{nom}/{library} | indholdet af en kategori, pagineret |
GET /ajax/books_in/{cat}/{item}/{library} | identifikatorerne for en kategori |
To afkodningsfælder, begge dækket af test:
Identifikationen er ikke i emnet. /ajax/books indekserer sin ordbog efter identifikator og gentager den ikke indeni. CalibreKit injicerer det gennem userInfo af dekoderen.
0101-01-01T00:00:00+00:00 betyder "ingen dato". Det er vagtposten UNDEFINED_DATE af Calibre. Naivt afkodet producerer den en bog udgivet i antikken. CalibreDate bringer det tilbage til nil.
4. Konvertering — srv/convert.py
Dette er opdagelsen, der ændrer arkitekturen: serveren Calibre konverterer ved HTTP.
| Vej | Metode | Rolle |
|---|---|---|
/conversion/book-data/{id} | FÅ | inputformater, outputformater, accepterede muligheder |
/conversion/start/{id} | POST | krop {input_fmt, output_fmt, options} → returnerer et job-id |
/conversion/status/{job} | POST | {running, percent, msg} derefter terminaltilstanden; ?abort_job=1 afbryder |
Detaljer noteret i kilden, og alle væsentlige for brug:
- Kun POST (
receive_data_methods = {'POST'}). En GET afvises. input_fmtskal være et format, som bogen faktisk har : Serveren bygger kildestien derfra og kasserer resten. Han venter på det med store bogstaver,output_fmtmed små bogstaver.- Status forbruges ved første terminallæsning :
del conversion_jobs[job_id], såcleanup()i enfinally. Du kan kun læse konklusionen én gang. Og kun den bruger, der lancerede jobbet, i det samme bibliotek, kan forespørge på det.CalibreKit.convert(…)omslutter sonderingsløkken, så ingen, der ringer, skal tænke over det. - Produktformatet føjes til bogen i biblioteket :
db.add_format(book_id, fmt, output_path). Arbejdet udføres derfor kun én gang, og alle enheder får så gavn af det./get/EPUB/{id}. - Opskriftsfiler afvises (udførelse af kode), og en liste over muligheder er forbudt af netværket.
Den komplette rute, som f.eks CalibreKit implementerer 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æseposition og anmærkninger — srv/books.py
Calibre synkroniserer allerede afspilningspositioner på serversiden.
| Vej | Metode | Rolle |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | FÅ | kendte positioner, efter enhed |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | gemmer {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | FÅ | højdepunkter og noter |
/book-manifest/{id}/{FMT} | FÅ | server normaliserer ethvert format i manifest til sin egen læser |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | FÅ | en standardiseret bogressource |
/book-get-storage/{library}/{id}/{FMT} | FÅ | lagerstatus |
To konsekvenser for Podbook:
Vi kan opgive aviserne .jsonl beskrevet i de indledende specifikationer, i det mindste som hovedmekanismen: Calibre har allerede en position pr. enhed, pr. bog og pr. format. Logfilerne er stadig nyttige til det, Calibre ikke ved - positionen i lyden, notesbogen med ordforråd.
/book-manifest er en genvej til at evaluere. Serveren ved allerede, hvordan man transformerer ethvert format til en standardiseret struktur for sin weblæser. Dette dækker en del af hvad BookKit skulle gøre. Skal udforskes før skrivning af parseren: manifestets format er internt i Calibre og skal derfor behandles som overfladen /ajax, med forsigtighed.
srv/kosync.py afslører desuden KOReader-synkroniseringsprotokollen (/kosync/users/auth, /kosync/syncs/progress), en anden mulig rute, allerede vedtaget af andre læsere.
6. Fuldtekstsøgning — srv/fts.py
| Vej | Metode | Rolle |
|---|---|---|
/fts/search | FÅ | søg i bøgernes tekst, ikke kun metadata |
/fts/snippets/{book_ids} | FÅ | uddrag med kontekst |
/fts/reindex, /fts/indexing, /fts/disable | POST | indekskontrol |
Indekset skal være aktiveret på serversiden. Podbook behøver derfor ikke at indeksere selve biblioteket til global søgning — kun for bøger importeret uden for Calibre.
7. Skrivning i biblioteket — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L udfører en underkommando calibredb på serveren. Det er den understøttet måde at skrive på: metadata.db tolererer ikke en anden editor.
Tilgængelige kommandoer: 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 giver dig mulighed for at skrive behandlingsstatus for Podbook i en brugerdefineret kolonne #podbook, synlig fra Calibre, korrekt.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stabil, annonceret i Hej på det lokale netværk. Det er tilbagetrækningen hvornår /ajax er der ikke - især imod Calibre-Web.
9. Hvad dette ændrer for Podbook
| Indledende hypotese | Virkelighed |
|---|---|
| En MOBI-parser skal skrives | Falsk fra v1: ebook-convert var allerede nok |
| Konvertering kræver workshop på Mac | Falsk : calibre-server konverterer til HTTP. iPad anmoder, serveren fungerer, biblioteket er beriget |
| Podbook skal opfinde sin positionstiming | Delvis falsk : Calibre har allerede én pr. enhed |
| Podbook bør indeksere til global søgning | Falsk : /fts/search findes |
metadata.db skrivebeskyttet, ingen skrivning muligt | Falsk : /cdb/cmd/… er den officielle skriverute |
API /ajax er et solidt fundament | Falsk : ikke offentlig, ikke stabil. Derfor den tolerante afkodning, naturdetektering og fallback OPDS |
Stadig sandt: DRM-beskyttede filer åbnes ikke, og en Calibre-server skal køre et sted for at konvertering og global søgning er tilgængelig.