From dbbeb2aae026c76bb2650cd8b9b56c08e53f692a Mon Sep 17 00:00:00 2001 From: tgiachi Date: Wed, 11 Nov 2026 14:12:15 +0100 Subject: [PATCH] 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 --- README.md | 239 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7b103ba --- /dev/null +++ b/README.md @@ -0,0 +1,239 @@ +# 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. +- **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`](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` and `failed` 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 `