sonda/README.md
tgiachi dbbeb2aae0 docs: add the README with a runnable local demo
- what Sonda is, what works today and what does not
- build, configure (keys and environment variables) and use PostgreSQL
- a demo from an empty database to streaming a track with curl: first user,
  library, scan, browse and search, Range streaming, listen events, token
  refresh and logout, a second user
- the API at a glance, security notes, backups, tests (including the
  PostgreSQL run) and the project layout

Closes #13
2026-11-11 14:12:15 +01:00

12 KiB

Sonda

Sonda is a privacy-first, self-hosted music server written in Go. It streams the music you already own, from your own disks, and keeps everything it knows about you on your own machine.

It is a single executable, one database (SQLite by default, PostgreSQL if you prefer) and the folders that hold your music. There is no Redis, no message broker and no cloud account.

Status: early. The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Recommendations, a web client and OpenSubsonic compatibility are not built yet (see What is not there yet). The API may still change.

What works today

  • Accounts. The first user to register becomes the admin and registration then closes; admins create the other users. Short-lived access tokens (JWT) plus rotating refresh tokens, so a stolen refresh token is detected.
  • Libraries. A library is a name and a folder, managed through the API. Sonda only ever reads your music folders: it never writes, renames or deletes a file.
  • Scanner. Reads MP3 and FLAC tags and audio properties with several workers in parallel. Rescans are incremental, renamed files keep their identity, vanished files are flagged (never deleted), and a library whose folder looks empty or unreadable (an unmounted NAS) is left alone instead of being wiped.
  • Catalog. Browse and search artists, albums and tracks, with paging, by library, artist or album. Only tracks you can actually play are listed.
  • Streaming. GET and HEAD with Range support, so players can seek. Opening or prefetching a stream does not record a listen.
  • Listening history. Clients report explicit play, complete and skip events. They stay in your database; nothing is sent anywhere. Sonda makes no outbound network requests at all.

What is not there yet

Similar-artist discovery, recommendations and radio queues, a web client, OpenSubsonic compatibility, transcoding, and Last.fm/MusicBrainz/ListenBrainz integrations. The [providers.lastfm] section of the config is reserved for a later milestone and is not used yet.

Requirements

  • Go 1.27 or newer to build. The binary needs nothing else: SQLite and the tag reader are compiled in, with no CGO and no system libraries.
  • curl and jq for the demo below.
  • Optional: ffmpeg, only to generate a few test tones for the demo.

Build

go build -o bin/sondad ./cmd/sondad

Configure

Sonda reads ./sonda.toml, or the file given with --config. Every key has a default except the secret.

cp sonda.example.toml sonda.toml
# Put a random secret in it (32 characters or more). Edit the file by hand if your sed differs.
sed -i "s|^jwt_secret = .*|jwt_secret = \"$(openssl rand -hex 32)\"|" sonda.toml

sonda.toml is git-ignored because it holds the secret. Keep it readable only by the user that runs Sonda (chmod 600 sonda.toml).

Precedence is: built-in defaults, then the file, then environment variables. An unknown key in the file is an error, so a typo cannot be ignored silently.

Key Environment variable Default Meaning
server.listen SONDA_LISTEN 127.0.0.1:8080 Address to listen on. Localhost by default.
library.scan_workers 4 Files whose tags are read in parallel during a scan.
database.driver SONDA_DB_DRIVER sqlite sqlite or postgres.
database.path SONDA_DB_PATH sonda.db SQLite file (driver sqlite).
database.dsn SONDA_DB_DSN Connection string (driver postgres).
log.env SONDA_ENV production production logs JSON; dev logs readable text.
auth.jwt_secret SONDA_JWT_SECRET (required) Signs access tokens. At least 32 characters.
auth.access_ttl_minutes 15 Lifetime of an access token.
auth.refresh_ttl_hours 720 Lifetime of a refresh token (30 days).
providers.lastfm.api_key SONDA_LASTFM_API_KEY Reserved, not used yet.

Libraries are not in the config: you add them through the API (see the demo).

Using PostgreSQL

[database]
driver = "postgres"
dsn = "postgres://user:password@localhost:5432/sonda?sslmode=disable"

Sonda creates and migrates its tables on start. The storage tests run against both databases.

Demo

This takes you from an empty database to streaming a track. Run the server in one terminal and the commands in another.

1. Get some music. Point MUSIC at a folder of MP3 or FLAC files. The path must be absolute. If you have none, generate two test tones:

export MUSIC="$HOME/Music"
mkdir -p "$MUSIC/demo"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=440:duration=5" -metadata title="Tone A" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=1 "$MUSIC/demo/a.mp3"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=660:duration=5" -metadata title="Tone B" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=2 "$MUSIC/demo/b.flac"

2. Start the server (after the Build and Configure steps above):

./bin/sondad

3. Check it is up, create the first user, and log in:

BASE=http://127.0.0.1:8080/api/v1

curl -s $BASE/health

# The first user becomes the admin; registration is then closed.
curl -s -X POST $BASE/auth/register -d '{"username":"alice","password":"correct horse battery"}'

LOGIN=$(curl -s -X POST $BASE/auth/login -d '{"username":"alice","password":"correct horse battery"}')
TOKEN=$(echo "$LOGIN" | jq -r .access_token)
REFRESH=$(echo "$LOGIN" | jq -r .refresh_token)
AUTH="Authorization: Bearer $TOKEN"

4. Add a library and scan it:

curl -s -X POST $BASE/libraries -H "$AUTH" -d "{\"name\":\"Music\",\"path\":\"$MUSIC\"}" | jq

curl -s -X POST $BASE/library/scan -H "$AUTH"
until [ "$(curl -s $BASE/library/scan -H "$AUTH" | jq .running)" = false ]; do sleep 1; done
curl -s $BASE/library/scan -H "$AUTH" | jq .last

found, added, unchanged, renamed, missing and failed tell you what the scan did. Run it again and everything is unchanged.

5. Browse and search:

curl -s "$BASE/artists?limit=5" -H "$AUTH" | jq
curl -s "$BASE/albums" -H "$AUTH" | jq '.items[] | {id, title, artist: .artist.name, tracks: .track_count}'
curl -s "$BASE/tracks?q=tone" -H "$AUTH" | jq '.items[] | {id, title, artists: [.artists[].name], format}'

6. Stream a track:

TRACK=$(curl -s "$BASE/tracks?limit=1" -H "$AUTH" | jq -r '.items[0].id')

# Ask for the first 100 bytes: the answer is 206 Partial Content with a Content-Range header.
curl -s -D - -o /dev/null -H "$AUTH" -H 'Range: bytes=0-99' $BASE/tracks/$TRACK/stream

# The whole file.
curl -s -o track.audio -H "$AUTH" $BASE/tracks/$TRACK/stream

A browser <audio> element cannot send headers, so the stream URL also accepts the access token in the query string: $BASE/tracks/$TRACK/stream?access_token=$TOKEN. That is the only route that does, and the query string is never logged.

7. Report a listen. Streaming never counts as a listen; clients say what happened. The idempotency key makes a retry harmless:

curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"complete\",\"duration_played_ms\":5000,\"idempotency_key\":\"demo-1\"}"

8. Refresh the session and log out:

NEW=$(curl -s -X POST $BASE/auth/refresh -d "{\"refresh_token\":\"$REFRESH\"}")
TOKEN=$(echo "$NEW" | jq -r .access_token)
REFRESH=$(echo "$NEW" | jq -r .refresh_token)
AUTH="Authorization: Bearer $TOKEN"

curl -s -X POST $BASE/auth/logout -d "{\"refresh_token\":\"$REFRESH\"}"

Each refresh token works once. Presenting a spent one again, more than ten seconds after it was used, ends every session of that user.

9. Add another user (admins only):

TOKEN=$(curl -s -X POST $BASE/auth/login -d '{"username":"alice","password":"correct horse battery"}' | jq -r .access_token)
AUTH="Authorization: Bearer $TOKEN"
curl -s -X POST $BASE/users -H "$AUTH" -d '{"username":"bob","password":"another long password"}' | jq

The API at a glance

Everything lives under /api/v1. Bodies are JSON. Errors always look like {"error":{"code":"...","message":"..."}}.

Who Method and path What it does
anyone GET /health Liveness check.
anyone POST /auth/register Create the first user (admin). Closed afterwards.
anyone POST /auth/login, /auth/refresh, /auth/logout Open, renew and end a session.
signed in GET /auth/me, POST /auth/password Your account; change your password (signs you out everywhere).
signed in GET /artists, /albums, /tracks and /…/{id} Browse and search. Query: q, limit (default 50, max 200), offset, library_id, artist_id, album_id.
signed in GET, HEAD /tracks/{id}/stream Stream the original file. Also accepts ?access_token=.
signed in POST /listens Record a play, complete or skip.
signed in GET /library/scan Scan status and the last result.
admin GET, POST /libraries; PATCH, DELETE /libraries/{id} Manage libraries. Deleting one removes its index entries, never your files.
admin POST /library/scan, POST /libraries/{id}/scan Scan everything, or one library.
admin GET, POST /users; PATCH, DELETE /users/{id}; PUT /users/{id}/password Manage users and the admin role. The last admin cannot be demoted or deleted.

A library path must be an absolute, existing folder, never the filesystem root, and never inside or around another library. Search is a case-insensitive substring match: BJÖRK finds Björk, but accents are kept, so bjork does not.

Security notes

  • Sonda listens on localhost only, unless you change server.listen. To use it from other machines, put it behind a reverse proxy that terminates HTTPS.
  • Passwords are hashed with Argon2id. Refresh tokens are stored only as hashes.
  • Music folders are read-only to Sonda. Streaming opens files through os.Root, so a path can never leave its library, even if a symlink is swapped in later.
  • File paths are never returned by the catalog, and audio file paths are not logged.

Back up

Back up the database and sonda.toml. Your music stays wherever you keep it.

  • SQLite: sqlite3 sonda.db ".backup sonda-backup.db" works while Sonda runs. Or stop Sonda and copy sonda.db (and sonda.db-wal if it exists).
  • PostgreSQL: pg_dump the database.
  • sonda.toml holds the secret that signs tokens; treat the copy like a password.

Development

go vet ./...
go test -race ./...

The default test run needs no network and uses SQLite only. To run the same storage tests against PostgreSQL as well, start a throwaway server and point the tests at it:

docker run -d --rm --name sonda-test-pg -e POSTGRES_PASSWORD=sonda -e POSTGRES_DB=sonda -p 127.0.0.1:55432:5432 postgres:17-alpine
SONDA_TEST_POSTGRES_DSN='postgres://postgres:sonda@127.0.0.1:55432/sonda?sslmode=disable' go test -race ./...
docker rm -f sonda-test-pg

Tests that read real audio need ffmpeg and are skipped when it is missing.

Layout:

cmd/sondad/            the server: wiring, config, logging, shutdown
internal/api/http/     the REST API (thin handlers)
internal/auth/         users, roles, passwords, access and refresh tokens
internal/catalog/      browsing and searching artists, albums, tracks
internal/library/      libraries, the scanner, the event hub, the tag reader
internal/listening/    listen events
internal/storage/      SQLite and PostgreSQL through bun, the repositories
internal/streaming/    opening a track's file safely
migrations/            SQL migrations, one folder per database

Migrations are plain SQL files in migrations/sqlite and migrations/postgres. They must describe the same schema, and a test checks that both folders hold the same files. Add a new numbered file to both whenever the schema changes.

Third-party code

Audio tags are read with go.senan.xyz/taglib, which embeds TagLib compiled to WebAssembly and is licensed under the LGPL 2.1. The other dependencies are listed in go.mod.