Corpus is a self-hosted listening history dashboard for ListenBrainz and Last.fm. It stores scrobbles in DuckDB, adds release metadata, caches cover art and serves an Elm web interface.
- Architecture: components, routes, data flows, configuration and operations
- DuckDB: database schema
- Example DuckDB queries: statistics you can run against a user database
With Nix:
just shell
just nix build
just nix runTo build locally with pnpm:
pnpm install
pnpm spago install
pnpm run build
pnpm test
pnpm spago runSend ListenBrainz-compatible submissions to POST /1/submit-listens. Include Authorization: Token <token> and a standard ListenBrainz payload. Validate a token with GET /1/validate-token and the same header.
Corpus shows tokens once when you create, reset or approve a user. Store them securely.
users.json defines each static user's slug, source usernames, DuckDB filename, and cover and backup settings. Environment variables provide shared secrets and settings for other services.
| Variable | Purpose |
|---|---|
CORPUS_USERS_FILE |
Static user configuration (default: users.json) |
DATABASE_PATH |
Directory containing user databases |
LASTFM_API_KEY, DISCOGS_TOKEN |
Last.fm sync, and genre and cover fallbacks |
S3_BUCKET and AWS_* |
Cover cache and database backups |
COSINE_API_KEY |
Similar-track lookup |
PORT, HOST |
HTTP listener (defaults: 8000, 127.0.0.1) |
METRICS_ENABLED |
Enable Prometheus metrics at /metrics |
Set REGISTRATION_ENABLED=true to allow public registration at /register. Set ADMIN_TOKEN to enable approval at /admin. See the configuration reference for all settings, and registration for how approval works.