Bookclerk documentation
Bookclerk gathers the audiobooks you bought from several stores into one library that you control: it syncs what you own, downloads your copies, saves them where you choose, and connects to library servers such as Audiobookshelf.
The docs are grouped by what you want to do. Start with the first group; the others go deeper.
- Use Bookclerk: the shelf for people who buy audiobooks
- What is Bookclerk?: what it does, whether it is ready, and how to try the demo
- Getting started: install Bookclerk, create your account, connect a store and bring in your books
- Stores: Audible, Libro.fm, Chirp and GraphicAudio
- Where your books go: folders, cloud storage and file names
- Discover and wishlist: suggestions, catalog search and the wishlist
- The web app: the screens, roles and ways to sign in
- Listen in the web app: the player, bookmarks, the sleep timer and media keys
- Sharing with your household: invites, what is shared, and Audiobookshelf
- Join a library as a branch: let a second computer help
- Coming from Libation: bring over an existing library
- Troubleshooting: common problems and fixes
- Glossary: the words Bookclerk uses
- Run a server: the shelf for whoever runs Bookclerk
- Running Bookclerk: the daemon, systemd, Docker and logs
- Configuration:
config.toml, environment variables and plugin settings - Security checklist: keys, TLS, sign-in and isolation before you expose a server
- Database: SQLite, PostgreSQL or Cloudflare D1, and encrypted secrets
- Stores reference: store plugins, formats and settings
- Output and destinations reference: local and S3 destinations, naming and packaging
- Drop folders: a watched folder whose books Bookclerk adds to the library
- Web app and sign-in reference: roles, sign-in methods, routes and screens
- Integrations and sign-in: Audiobookshelf, invites and identity providers
- Managing plugins: install, approve, configure and place plugins; isolation modes
- Libraries and branches: join a library, shared branches and consent
- Notifications: channels, routes, patron choices, the inbox and the delivery log
- Public address: reach the library from the internet through an ingress plugin, with no port forwarding
- Media worker: the confined process that handles audio files
- Uploads: adding books from files, folders and archives, limits and review
- Playback reference: what the daemon stores and serves for players
- Player apps: listen in apps made for Audiobookshelf servers, through
/player - Backups, updates, import and export: native backups, schema backups, updating, Libation and PostgreSQL export
- Diagnostics: opt-in error reports
- CLI reference: every built-in
bookclerkcommand and option (generated) - Web API: every route the daemon serves, with example requests and responses (generated)
- Plugins: the plugin model, SDKs, local development and examples
- plugin.toml: package layout, identity, entrypoints and settings
- Capabilities and consent: what a plugin may ask for and how it is approved
- Entrypoints, events and the ABI: the Workers RPC surface, events, KV and queues
- Plugin registry: crate naming, archives and installing without Rust
- SQL contract: the canonical SQL that database adapters implement (v1)
- Working within database limits: what the caps are, how
all()streams,iterate()andchunk() - Plugin SDKs: choose an SDK and a runtime
- TypeScript plugin SDK, Python plugin SDK and Rust plugin SDK: a guide for each, followed by the reference generated from its code
- How it works: the shelf for contributors reading the code
- Architecture: how the pieces fit
- Discovery design: how suggestions are found and ranked
- Embedding model benchmarks: how candidate models match taste across languages, and what they cost to run
- Embedding model packs: how a model is stored on disk, how the
embedderplugin runs it, and how it was checked - Durable job queue: admission, leases and crash recovery
- Bounded storage: size caps, streams, paged scans and checkpoints
- The guest jail: why plugins run as jailed processes, and how each platform confines them
- workerd bridge: the wire between the launcher and a plugin isolate
- Node API and the live socket: how hosts of one library talk, and how the web app hears about changes
- One TLS backend: the one crypto provider every TLS connection uses, and where it is set
- Windows AppContainer: confinement notes for Windows
- Rust crates: every workspace crate, from its doc comments (generated)
- Contribute: the shelf for contributors sending a change
- Build from source and use the CLI: build the binaries and drive Bookclerk from the command line
- Dev Container: a ready-made build environment
- Web UI development: the React app, the tray, brand assets, and the UI library reference (generated)
- Visual and accessibility testing: Storybook stories, website and collector pages, axe-core checks and screenshot baselines in CI
- Continuous integration: the planner, the jobs and
CI Gate - Fuzzing: fuzz targets in CI and crash triage
- Repository automation: dependency updates, advisories, docs publishing and Worker deploys
- Release packaging: platform bundles and release CI
- Code documentation: how to document Rust, TypeScript, Python and shell
- Writing docs: how to write a docs page people can read quickly
- Licensing and the CLA: which license covers what, the contributor agreement and the trademark policy
- Research notes: store candidates and Libation parity
Build and agent conventions for this repository live in
AGENTS.md.
- Design decisions: the decision log
- Plugin capabilities v3: entrypoints, triggers, typed Cap'n Proto and
env.EVENTS - Workers RPC and workerd: jail, isolation and the workerd pin (partly superseded by v3)
- First-party identity: Owner, Administrator and Member, passkeys and OIDC
- Plugin-provided OIDC clients: players declare identity-provider clients
- SQL database contract: host-resolved canonical SQL, adapter-owned lowering
- Schema versioning: frozen schema numbers, checksums and backups
- Control plane: the bootstrap boundary, host identity and library coordination
- Untrusted-input fuzzing: every untrusted boundary ships a fuzz target
- Security advisory automation: draft advisories for shipped code
- Logging and tracing: trace everything, keep TRACE for diagnostics, show each output its own level
- Library data model: FRBR works, expressions and editions, holdings and edition files
- Web API contract checks: the document is checked against examples in tests and against real responses in CI
- Project licensing: AGPL for the project, MIT OR Apache-2.0 for the plugin SDKs, a CLA and a trademark policy
- Event delivery model: events fan out to every subscriber, jobs have one handler, subscriptions follow deployments
- Library catalog network: a branch of several libraries, what each library owns, and how libraries list and lend books
- Metadata claims and file sync: every value is a claim with its source, one resolver, evidence-based works, and two-way sync with tags and sidecar files
- Edition chapters: chapters belong to the edition, each source's list is a claim, and Bookclerk's aligned result wins unless an Administrator edits or pins
- Patron scopes and linked sign-in: which part of the library a Member sees, and how a linked server's permissions follow one authority
- Desktop window identity: the window is the person signed in to the computer, named by a per-account profile
- Playback: playback is a host feature with one core that the web player, the desktop window and app-compatible clients share
- Player API: the host serves apps made for Audiobookshelf servers at
/player, with player cards and no account password - Storage destinations: every storage plugin instance is a destination with its own template and filter, opportunistic change feeds and host-held webhooks
- Master key store: the library key can live in the OS keychain, with
master.keyas a pointer and recovery copies - Uploads and ingest batches: one batch per upload, patron holdings for uploaded books, strong identifiers only, archives expanded under caps
- What needs the operator: the rule for which actions need elevation, and the switches an Owner sets on each Administrator
- Ingress plugins: one action gives an install a stable public address, through relay or dynamic DNS plugins
- Notifications: the host routes events into send jobs, notifier plugins send them, and account mail carries reset and recovery
- Drop folders: a storage instance can be a watched drop folder instead of a destination, settled by the host and added by the ingest job
- Model plugins and the AI binding: models run in jailed plugins behind an
aientrypoint, and every caller reaches them through oneAIbinding
Source: docs/README.md at main · View as Markdown