Hop til hovedindhold

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 null få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.

RutefamilieHvor 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​

VejReturnering
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,3ordbog 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.

VejMetodeRolle
/conversion/book-data/{id}FÅinputformater, outputformater, accepterede muligheder
/conversion/start/{id}POSTkrop {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_fmt skal være et format, som bogen faktisk har : Serveren bygger kildestien derfra og kasserer resten. Han venter på det med store bogstaver, output_fmt med små bogstaver.
  • Status forbruges ved første terminallæsning : del conversion_jobs[job_id], så cleanup() i en finally. 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.

VejMetodeRolle
/book-get-last-read-position/{library}/{id}:{FMT}FÅkendte positioner, efter enhed
/book-set-last-read-position/{library}/{id}/{FMT}POSTgemmer {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​

VejMetodeRolle
/fts/searchFÅsøg i bøgernes tekst, ikke kun metadata
/fts/snippets/{book_ids}FÅuddrag med kontekst
/fts/reindex, /fts/indexing, /fts/disablePOSTindekskontrol

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 hypoteseVirkelighed
En MOBI-parser skal skrivesFalsk fra v1: ebook-convert var allerede nok
Konvertering kræver workshop på MacFalsk : calibre-server konverterer til HTTP. iPad anmoder, serveren fungerer, biblioteket er beriget
Podbook skal opfinde sin positionstimingDelvis falsk : Calibre har allerede én pr. enhed
Podbook bør indeksere til global søgningFalsk : /fts/search findes
metadata.db skrivebeskyttet, ingen skrivning muligtFalsk : /cdb/cmd/… er den officielle skriverute
API /ajax er et solidt fundamentFalsk : 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.