corpus #

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.

Documentation #

• Architecture: components, routes, data flows, configuration and operations
• DuckDB: database schema
• Example DuckDB queries: statistics you can run against a user database

Quick start #

With Nix:

just shell
just nix build
just nix run

To build locally with pnpm:

pnpm install
pnpm spago install
pnpm run build
pnpm test
pnpm spago run

Scrobbling API #

Send 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.

Configuration #

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.

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.