The system at a glance
AudioSilo is a self-hosted audiobook platform built around a server and player. The server owns the data and the HTTP and JSON contract. The player is a thin, fully-typed read side over that contract.
| Repo | Role | Stack |
|---|---|---|
audiosilo-server | The server, the source of truth for content and the API. It serves the JSON API, the admin console and the connect page, and the web player at /web. Safe to expose to the internet. | Go 1.26, SQLite (pure-Go modernc by default; native C in the Docker image and the Linux release binaries), FTS5 |
audiosilo-frontend | The player, one codebase shipping to a web PWA, iOS and Android. The read side of the product. Its web export is served by the server at /web. | Expo SDK 58, React Native 0.88 (new architecture), React 19.3, Expo Router, Uniwind (Tailwind v4) |
The optional Bridge (audiosilo-bridge)
pairs with a server, writes to its libraries and runs the heavy jobs, so the
server stays read-only. It always calls the server, never the reverse. Its first
real job generates a book's characters and recaps into the
book's folder, with its AI agents in a separate
agent container.
The code repos and this docs site live side by side in a single workspace folder
(~/dev/audiosilo). The folder's root is itself the small audiosilo-workspace
meta repo. It holds the cross-repo glue: the integration contract, the code-health
checklist and the release runbooks. See the workspace guide
for how to check everything out and work across the repos.
Architecture
Three structural facts to internalize before reading anything else:
- The server is the only writer of the API contract. The frontend mirrors its JSON shapes by hand. There is no codegen, so a wire change is always a multi-repo change. See Cross-repo contract.
- The filesystem is the source of truth; the database is a rebuildable index.
Content is addressed by
(library_id, rel_path), never by a database id. See Invariants. - The server's content API is read-only. Files change on disk, copied in by hand or written by the Bridge through its checked mappings, and a scan updates the index.
The data flows
Streaming. The player fetches a book's chapters with
GET /libraries/{id}/chapters?path=, which answers {chapters, files, duration}.
It then streams individual audio files, never a folder or book path, with HTTP
Range requests (GET /libraries/{id}/stream?path=). Media auth rides as a ?token=
query param, because browsers can't set headers on <img> or <audio>. For a codec
that browsers can't decode (direct_playable: false), the web player streams the
server's on-the-fly MP3 instead (?transcode=1&t=, ffmpeg, gated by the
transcode capability). It re-requests the MP3 on every seek.
Progress sync. The player saves the listener's place while playing, keyed by path. It saves every 15 seconds with the app in front and the book streaming, every 60 seconds with the app in the background or the book downloaded, and at once on a pause, seek, rate change or stop (the pace). How it saves depends on the server:
- Listening sync (Sync v2). On a server with the
listening_synccapability, and while the player doesn't know the flag yet, the player records listening as events: a span of playing, a finish, an unfinish. It keeps them in a durable outbox per connection (src/playback/listening-outbox.ts) and posts them toPOST /me/listening/sync. The server (catalog.SyncListeningininternal/catalog/listening_sync.go) derives progress, listening sessions and history from them. When two devices diverge, it keeps the further place and offers the other asother_place. See seam 19 of the cross-repo contract. - The legacy save. A shipped older player, or a player on a server without the
flag, saves with
PUT /libraries/{id}/progress?path=. The server reconciles it last-write-wins byupdated_at(catalog.SaveProgress), and the client keeps an offline replay queue (src/playback/progress-sync.ts).
Realtime WebSocket sync is planned. The websocket capability flag is already
reserved for it.
Pairing. An admin mints an invite code. The code rides a URL fragment
(/connect#code=…), so it never reaches server logs. The connect page redeems it
with POST /auth/redeem, which returns a pairing token that keeps the invite's
remaining uses and expiry. The page then offers two carriers: an HTTPS web_url
(for the QR code: the app's scanner reads it, and a phone's camera app opens the
web player) and an audiosilo://connect?... custom-scheme deep link. The app or
web player exchanges the pairing token for a device-scoped
session (POST /auth/exchange), claiming one invite use per device. So each device
being set up can scan the same QR code.
File placement. Files reach a library folder outside the server's API:
copied in by hand, or written by the Bridge. A
non-destructive reindex (POST /admin/libraries/{id}/scan) picks them up. See
Organizing your library for the
folder conventions. A server-side POST /uploads endpoint is planned, not
shipped.
Design priorities
The server's priorities, in order. When they conflict, the earlier one wins.
- Safe to expose to the internet. Secure defaults, no default passwords, hashed secrets, app-layer hardening, configurable TLS. Inexperienced users will port-forward this.
- Fast regardless of library size. FTS5 search and keyset pagination, and never OFFSET on large tables.
- No-wait first connection. The filesystem view (
/fs) needs no indexing. A fresh server is browsable and playable immediately, while the index catches up in the background. - Portable. The filesystem is the source of truth; the database is a rebuildable index and cache. Delete the DB and nothing of value is lost.
How these docs are organized
- Architecture - start here. The invariants every change must preserve, the cross-repo contract (every seam between the repos), and the release pipeline.
- Server - package layout, data model, auth and security, the scanner, media serving, the built-in web UI (the admin console and the connect page), configuration, and the HTTP API.
- Player app - the Expo codebase: playback, the end of a book, the sleep timer, player UI, offline downloads, state and data, i18n, testing.
- The Bridge -
audiosilo-bridge, the optional companion that writes to a server's libraries and runs its heavy jobs: pairing and jobs, mappings, generating characters and recaps and development. - Metadata database -
audiosilo-meta, the community audiobook metadata database behind meta.audiosilo.app that the server and player enrich books from: the data model, themetaserveHTTP API, and contributing data. - Contributing - the workspace setup, per-repo gates and CI, how to land a cross-repo change, cutting a release, and writing these docs.
If you just want to run AudioSilo rather than hack on it, the user guide covers installation and everyday use.
~/dev/audiosilo/CROSS-REPO.md (checked into the workspace root, alongside
CLAUDE.md and CODE-HEALTH.md) is the normative integration contract
between the repos. These docs are a readable digest of the same material. When a
seam changes, update CROSS-REPO.md first, and these pages follow.
Where to start
- To add or change an API endpoint, read the Cross-repo contract, then Landing a cross-repo change.
- To understand why the code is shaped this way, read Invariants.
- For something that won't play, a wrong Content-Type, a scope leak or a scanner issue, go to the server docs.
- For UI that looks wrong, navigation, timeline math or offline, go to the frontend docs.
- Pairing, media auth, a new wire field or transcode touch both repos. Read the Cross-repo contract before starting.