# 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](#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. 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`](https://jqlang.github.io/jq/) for the demo below. - Optional: `ffmpeg`, only to generate a few test tones for the demo. ## Build ```bash 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. ```bash 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 ```toml [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: ```bash 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): ```bash ./bin/sondad ``` **3. Check it is up, create the first user, and log in:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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 `