Privacy-first, self-hosted music server written in Go.
  • Go 69.3%
  • TypeScript 29.8%
  • Java 0.3%
  • CSS 0.2%
  • JavaScript 0.2%
  • Other 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
tgiachi b769ad7ac5 fix(discovery): concurrent writes, adopted artists and a client that leaves
- fix: on SQLite a transaction that read and then wrote failed at once with
  "database is locked" when another writer committed in between, because the
  busy timeout does not apply there. Transactions now start with BEGIN
  IMMEDIATE. Before this change a scan running while someone opened similar
  artists made files fail, and parallel requests stored nothing
- fix: on PostgreSQL two requests naming the same new artist could fail on the
  unique MusicBrainz id or leave two rows with one name. Creating artists, in
  the discovery store and in the scanner, now takes turns through an advisory
  lock and looks again once it has the turn
- fix: music arriving for an artist that a provider only named used to keep the
  provider's spelling and its unchecked MusicBrainz id, which later lookups
  would then send instead of the name. Such artists are now marked
  (artists.discovered); the first scan that finds them renames them to the
  spelling of the file tags, drops the id and clears the mark
- fix: a panic in the shared provider call is turned into a failure; the
  singleflight group would have re-raised it where nothing can recover
- fix: a client that leaves while Last.fm is being asked no longer gets a 500
  and an error in the log
- fix: no page can ask for more than is stored (limit tops out at 50), and the
  docs no longer say the best score is always 1
- test: concurrent saves plus a scan on both databases, checked by removing each
  fix; adoption keeps neither the name nor the id; the panic; the client that
  leaves
2026-11-11 16:47:33 +01:00
cmd/sondad feat(discovery): similar artists from Last.fm 2026-11-11 16:42:52 +01:00
internal fix(discovery): concurrent writes, adopted artists and a client that leaves 2026-11-11 16:47:33 +01:00
migrations fix(discovery): concurrent writes, adopted artists and a client that leaves 2026-11-11 16:47:33 +01:00
.gitignore feat: add sondad server with config, storage, auth and listening API 2026-11-11 12:06:15 +01:00
go.mod feat(discovery): similar artists from Last.fm 2026-11-11 16:42:52 +01:00
go.sum feat(discovery): similar artists from Last.fm 2026-11-11 16:42:52 +01:00
README.md fix(discovery): concurrent writes, adopted artists and a client that leaves 2026-11-11 16:47:33 +01:00
sonda.example.toml feat(providers): provider settings in a table and a careful outbound HTTP client 2026-11-11 16:07:12 +01:00

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. Audio in other formats (m4a, ogg, opus, wav, wma and similar) is not read yet, but it is counted as unsupported in the scan result instead of disappearing silently. NAS housekeeping folders (@Recycle, #recycle, @eaDir, .@__thumb, $RECYCLE.BIN) are skipped.
  • 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.
  • API documentation. The full API is described in OpenAPI and browsable with Swagger UI, served by Sonda itself. The UI is embedded in the binary, so opening it contacts no other server.
  • Listening history. Clients report explicit play, complete and skip events. An event counts as a listen when it is complete, or when it was played for at least 20 seconds (listening.min_listen_seconds); the rule is applied when the history is read, so changing it re-reads the past. You can read your own history, with a counted flag on every event. It stays in your database and is never sent anywhere.
  • Similar artists. With Last.fm switched on, GET /artists/{id}/similar lists artists similar to an artist, and says which of them you already have. See External providers. Without it, Sonda makes no outbound network requests at all.

What is not there yet

Recommendations and radio queues, a web client, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. MusicBrainz can be set up (see External providers) but nothing asks it anything 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).
listening.min_listen_seconds 20 A play counts as a listen after this long (1 to 3600), or when it is complete.

Libraries and the external providers are not in the config: you set them up through the API (see the demo and External providers).

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 30-second test tones:

export MUSIC="$HOME/Music"
mkdir -p "$MUSIC/demo"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=440:duration=30" -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=30" -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, failed and unsupported 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. The player reports one event per play, when the play ends or is abandoned, with the time actually played. Use one idempotency key per play: a retry with the same key is harmless, but a key that was already used is ignored even if the event differs, so an event cannot be upgraded later. An event counts as a listen when it is complete or lasted at least the configured minimum (20 seconds by default); a shorter play is stored too, but does not count:

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

# Your history, newest first. Add ?counted=true to see only what counts.
curl -s "$BASE/listens" -H "$AUTH" | jq '.items[] | {track: .track.title, event_type, duration_played_ms, counted}'

The answer to each report says whether it counts. A reported play time far beyond the length of the track (more than twice its length plus 10 seconds) is rejected.

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

External providers

Sonda can ask Last.fm and MusicBrainz about artists. This is off by default: until an admin turns a provider on, nothing leaves your server. Today only Last.fm is used, to find similar artists.

  • Last.fm needs an API key. Create one for your own use at last.fm/api (it needs a Last.fm account). No user name or password is involved and the "shared secret" is not needed. Last.fm data is for non-commercial use only, and you should credit Last.fm when you show it.
  • MusicBrainz needs no key, but it asks every client to identify itself with a contact (a URL or an e-mail address) in the User-Agent. By default Sonda uses the address of the project, so no personal address is sent unless you choose to.

Set them up with PUT /api/v1/providers/{name} (admin), for example:

curl -s -X PUT $BASE/providers/lastfm -H "$AUTH" -d '{"api_key":"<your 32 character key>"}'
curl -s -X PUT $BASE/providers/lastfm -H "$AUTH" -d '{"enabled":true}'
curl -s $BASE/providers -H "$AUTH" | jq
curl -s -X POST $BASE/providers/lastfm/test -H "$AUTH" | jq   # does the key work?

The key is stored in the database, in clear text, and is never returned by the API or written to the log: the list only says has_api_key. Because the database holds it, treat database backups like secrets. Removing the key turns the provider off, and each provider describes in the list exactly what it sends.

What leaves your server, when a provider is on: the artist name (or MusicBrainz id) being looked up, your API key for Last.fm, your IP address and the User-Agent. Never your users, your listens, track titles or file paths. Requests only happen when someone asks for them, never as a bulk pass over your library, and they are spaced out, retried with backoff, and stopped by a circuit breaker if a provider is down. The one exception to "only when someone asks" is POST /providers/{name}/test, which an admin sends to check a key; it sends nothing but the key.

Similar artists. GET /api/v1/artists/{id}/similar asks Last.fm for the artists similar to an artist (one of yours, or one Last.fm named earlier) and keeps the answer in your database: 7 days, or 1 day when Last.fm does not know the artist. Until then a second look costs nothing and sends nothing, and if Last.fm is down you still get the last answer, marked stale. If the provider is off the answer says disabled instead of failing. Each similar artist says whether you have it (in_library); the ones you do not have are stored as artists without files. They can be opened with GET /artists/{id} but are never part of your artist lists, and if you later add their music, the scan finds them there. Last.fm's score is relative to each answer (the best one is usually 1), so compare artists only inside one answer.

The name of the artist is sent exactly as it is written in your library, and Sonda never lets Last.fm correct it into another artist. Names and ids from Last.fm are never written onto your own artists.

The API at a glance

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

Interactive documentation: open http://127.0.0.1:8080/api/docs/ in a browser. Use Authorize with the access_token from the login to try the protected operations. The OpenAPI file itself is at /api/v1/openapi.yaml. Both are public, since they describe the API and contain no data.

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 /artists/{id}/similar Artists similar to one, from Last.fm when an admin switched it on. Query: limit (default 20, max 50).
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; the answer says whether it counts as a listen.
signed in GET /listens Your own history, newest first, with counted per event. Query: limit, offset, counted=true.
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 /providers, PUT /providers/{name}, POST /providers/{name}/test See, set up and check Last.fm and MusicBrainz. The API key is write-only.
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.
  • Provider API keys are write-only through the API and never logged. They sit in the database, so protect your backups.

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) and the docs routes
internal/api/openapi/  the OpenAPI spec, embedded in the binary
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/discovery/    similar artists: what the providers said, kept and refreshed
internal/providers/    external providers: settings, the outbound HTTP client, the Last.fm client
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

The API description is internal/api/openapi/openapi.yaml, written by hand and embedded in the binary. Two tests keep it in step with the code: one fails when a route and the spec disagree in either direction, and a contract test sends real requests through every operation and validates each response (status, headers, JSON body) against the spec. Adding or changing an endpoint therefore means updating the spec in the same change. Response objects are closed (additionalProperties: false), so a field added in the code and forgotten in the spec fails the build.

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 Swagger UI assets come from github.com/swaggest/swgui (Apache-2.0), which embeds Swagger UI (Apache-2.0). The other dependencies are listed in go.mod.