Library and readers

Supported formats

Format	In-browser	Notes
EPUB	Yes (epub.js)	Metadata, covers, bookmarks, highlights, narration
PDF	Yes (pdf.js)	Info dictionary and embedded covers
MOBI / AZW / AZW3	Yes	Section navigation via /api/books/{id}/mobi-sections
KFX	Download	Served as a file download
CBZ / CBR	Yes	Dual-page, fit modes, RTL/manga, page API
MP3 / M4B / M4A / OGG / FLAC	Yes	HTML5 audio, chapters/tracks, range streaming

Multi-file audiobook folders are merged automatically. Local library mounts are watched for changes in addition to periodic auto-scan. S3 mounts use manual rescan or the admin auto-scan interval (no filesystem watch).

S3 library mounts

Under Settings -> Library, choose backend S3 when adding a mount. Provide endpoint, bucket, optional prefix, access key, secret key, region, path-style, and TLS. Athenaeum talks to AWS S3, MinIO, Cloudflare R2, Garage, and other MinIO-compatible APIs.

• Display path is s3://bucket/prefix
• Uploads, downloads, delete, convert, and scan go through the object store
• Covers stay under ATHENAEUM_DATA/covers
• POST /api/libraries/test-s3 validates credentials before saving

Example create body:

{
  "name": "Cloud",
  "backend": "s3",
  "s3": {
    "endpoint": "minio:9000",
    "region": "us-east-1",
    "bucket": "athenaeum",
    "prefix": "main/",
    "accessKey": "...",
    "secretKey": "...",
    "usePathStyle": true,
    "tls": false
  }
}

Metadata

Admins and users with edit_metadata can edit titles, authors, series, citation fields, and covers from the book page or PUT /api/books/{id}. Covers support upload, URL import, and delete.

Citation fields (DOI, arXiv ID, PubMed ID, journal, volume, issue, pages, year) mark an item as a research paper. Filter the library with ?format=papers. Sidecar {basename}.bib or metadata.bib next to a PDF is read on scan.

External metadata search and apply:

• POST /api/books/{id}/metadata/search (title, author, ISBN, ASIN, DOI, arXiv, PMID)
• POST /api/books/{id}/metadata/apply
• Bulk match: POST /api/library/metadata/match plus status endpoint
• Providers: GET /api/metadata/providers (Google Books, Open Library, Audnexus, Crossref, arXiv, PubMed)

BibTeX:

• Export one book: GET /api/books/{id}/bibtex
• Export papers (or ?ids=): GET /api/books/bibtex
• Import against existing files: POST /api/library/bibtex/import (JSON { "bibtex": "..." } or raw .bib body)

Optional format conversion: POST /api/books/{id}/convert?target=....

Tags, ratings, favorites

• Tags: create globally, attach per book, filter library with ?tag=
• Ratings: 1-5 stars per user (GET/PUT /api/books/{id}/rating)
• Favorites: GET/PUT /api/books/{id}/favorite and GET /api/favorites

Reader preferences

EPUB font, theme, spacing, and spread sync via GET/PUT /api/auth/reader-prefs. The browser keeps a localStorage cache for offline/first paint.

Narration (Kokoro TTS)

Open an EPUB and use narration to listen while you read.

• Default: in-browser Kokoro TTS when WebAssembly is available (ONNX Runtime Web WASM with embedded q8 weights). The full release binary embeds the ONNX runtime, model, and voices (~110+ MiB extra vs slim). Slim builds (athenaeum-slim-* / task build:slim) omit that stack.
• Fallback: the browser SpeechSynthesis API.
• Optional sidecar: run Kokoro next to Athenaeum with docker compose --profile kokoro, then set the base URL under Settings -> Administration -> Narration (TTS) (http://kokoro:8880 on the Compose network, or http://127.0.0.1:8880 from the host). Works with full and slim binaries.

Admin/API endpoints: GET/PUT /api/admin/tts, POST /api/admin/tts/test, GET /api/tts/status, GET /api/tts/voices, POST /api/tts/synthesize. See Deploying.

Sharing

Create time-limited or persistent public download links from the book page (POST /api/books/{id}/share). Recipients use /share/{token}/download without signing in. Revoke with DELETE /api/books/{id}/share/{shareId}.

SMTP and Kindle

Configure outbound SMTP under Settings -> Administration -> SMTP (GET/PUT /api/admin/smtp). Users set a delivery address under Profile (GET/PUT /api/auth/kindle-email). Send a book with POST /api/books/{id}/send.

Offline grants

Server-side offline grants (GET/POST/DELETE /api/offline) complement the PWA shell and per-track audiobook cache in the client. Grants authorize keeping a book available offline for the signed-in user.