- Go 69.3%
- TypeScript 29.8%
- Java 0.3%
- CSS 0.2%
- JavaScript 0.2%
- Other 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- README section for the web client: how to run it next to sondad, what it does today, the commands - the greeting on Home is read once per visit (lint: no Date during render) - checked against a real sondad: login, renewal and spent refresh tokens, media URLs with Range, listens, search, and the provider-off answers |
||
| cmd/sondad | ||
| internal | ||
| migrations | ||
| web | ||
| .gitignore | ||
| go.mod | ||
| go.sum | ||
| README.md | ||
| sonda.example.toml | ||
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. Suggestions of new artists work too (Discover). Radio queues and OpenSubsonic compatibility are not built yet, and the web client in
web/is a work in progress (see What is not there yet and Web app). 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
unsupportedin 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.
GETandHEADwithRangesupport, 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,completeandskipevents. An event counts as a listen when it iscomplete, 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 acountedflag on every event. It stays in your database and is never sent anywhere. - Your taste.
GET /me/tasteshows what Sonda has learned from your own listening: the artists you like and the kinds of music (tags) they have in common. A complete listen counts for more than a short one, a skip counts against the artist, and older listens weigh less (they halve every 90 days,taste.half_life_days; only the last ten half-lives are read). It is worked out on every request from data already in your database; nothing is sent to any provider. - Discover.
GET /discoversuggests artists you may like, in your library or not, each with a score from 0 to 1 and the parts it is made of: how close it is to the artists you like (affinity), how close its tags are to yours (genre), what your listening says about it (preference) and a bonus for what you have not played (discovery). The weights are in[scoring]in the config. A part with no data is left out and the rest rescaled, and every answer says which seeds led to each suggestion. It starts from the artists you name with?seed=, or, only if you turned ondiscover_from_listening, from the artists you play most. It needs Last.fm to be switched on to ask for anything new: when Last.fm is off and a seed's similar artists are not stored yet, the answer saysdisabled(what was stored earlier is still used). See External providers. - Artist descriptions.
GET /artists/{id}/descriptionshows what Wikipedia says about an artist: a short text, with the page it comes from, a link to it and the licence (CC BY-SA 4.0), which you must show next to it. With thewikipediaprovider and themusicbrainzone switched on (the link to Wikidata comes from MusicBrainz), Sonda follows ids and never a name: the artist's MusicBrainz id, then the Wikidata item that MusicBrainz links to it, then the Wikipedia page that Wikidata names in the first of your languages ([wikipedia] languages, the code of that Wikipedia, for example["it", "en"]) that has one. An artist without a MusicBrainz id has no description. It is kept for 30 days and removed with the provider's data. To read the descriptions of the whole library in one go, an admin starts a background job like a scan:POST /library/descriptions(follow it withGET /library/descriptions, stop it withDELETE /library/descriptions;?refresh=truereads every artist again). It only goes through artists that have a MusicBrainz id, never replaces a description by a failure, and ends at once, saying so, when a provider it needs is off. See External providers. - Artist photos.
GET /artists/{id}/imageserves a free picture of an artist from Wikimedia Commons, andGET /artists/{id}/image/creditsays whose it is and under which licence, which you must show next to it. Only free licences are kept (public domain, CC0, CC BY, CC BY-SA): non-commercial, no-derivatives, fair-use and unknown ones are refused, because Sonda stores a copy (?size=smallis 300 pixels,large1000) in the data folder. With thecommonsprovider and themusicbrainzone switched on, Sonda follows ids and never a name: the artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the picture Wikidata names for it, and Commons for its licence. Many artists will have none. Kept for 30 days (a week when there is none) and removed, files included, with the provider's data. To look for the pictures of the whole library in one go, an admin starts a background job like a scan:POST /library/artist-images(follow it withGET /library/artist-images, stop it withDELETE /library/artist-images;?refresh=truesearches every artist again). It only goes through artists that have a MusicBrainz id, never replaces a picture by a failure, and ends at once, saying so, when a provider it needs is off. See External providers. - Album covers.
GET /albums/{id}/coverserves the cover of an album from your own files: the picture embedded in them, or else acover,folder,front,albumoralbumartimage in the album's folder. It is built the first time it is asked for (a few at a time), scaled (?size=smallis 300 pixels,large1000) and kept in the data folder (storage.data_dir, you can delete it: covers are built again). A picture you replace in a folder is noticed within a week, or at once after a full rescan. When your files have no picture at all and an admin switched on thecoverartarchiveprovider, the cover is asked from the Cover Art Archive by the MusicBrainz release group id that the tags of the album's files carry (MUSICBRAINZ_RELEASEGROUPID; run a full rescan to read it for music you already indexed); your own files always come first, and only that id leaves the server. For an album split inCD1/Disc 2folders, the picture in the folder above is used. Nothing is sent anywhere unless you switched on thecoverartarchiveprovider (see External providers). It also takes?access_token=, so an<img>element can use it. To build the covers of the whole library in one go instead of one album at a time, an admin starts a background job like a scan:POST /library/covers(follow it withGET /library/covers, stop it withDELETE /library/covers;?refresh=truesearches every album again; it never replaces a cover by "no cover" because a disk was not mounted, and keeps the covers that came from the archive if you switched it off). - Wishlist and "not interested".
PUT /wishlist/{artist}puts an artist on your wishlist (GET /wishlistlists it,DELETEtakes it off), andPOST /discover/{artist}/dismisshides an artist from your Discover for good (DELETEbrings it back,GET /discover/dismissedlists them). An artist is wished or dismissed, never both, and both lists are yours alone. Discover marks the wished artists it shows (wishlisted) and never suggests a dismissed one. Nothing is downloaded or sent anywhere: the wishlist is a list for you, and for a download client you may set up later. An artist that only Last.fm named is kept while you have it marked (your lists still show it, but other users cannot see that it exists), and goes with the rest of Last.fm's data if an admin removes Last.fm's data. Removing MusicBrainz's data does not touch it. - Your own settings.
GETandPATCH /me/settingshold choices that belong to you, not to the server. Everyone starts private:discover_from_listeningis off, so this setting never sends your listening to a provider. When you turn it on, Discover may start from the artists you listen to most, and their names are sent to Last.fm (only if an admin switched it on). What Last.fm answers is kept in the shared database like any other lookup, so another local user can see, fromretrieved_atofGET /artists/{id}/similar, that someone looked up an artist, but not who. - Tags.
GET /artists/{id}/tagsshows what Last.fm and MusicBrainz say kind of music an artist plays, each with its own weights, and the genres of the artist's own files, read offline. See External providers. - Similar artists. With Last.fm switched on,
GET /artists/{id}/similarlists 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
Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client exists (see Web app) but sondad does not serve it yet, and it has no Discover or admin screens 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.
curlandjqfor 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. |
|
taste.half_life_days |
90 |
After this many days a listen weighs half as much when learning your taste (1 to 3650). | |
wikipedia.languages |
["en"] |
Languages for artist descriptions, best first: one to five codes of two or three lower case letters. | |
storage.data_dir |
SONDA_DATA_DIR |
data next to the SQLite database (data in the working directory with PostgreSQL) |
Where Sonda keeps the files it makes (covers). They are built from your music, so they need no backup. |
scoring.weight_affinity, weight_genre, weight_preference, weight_discovery |
0.40, 0.25, 0.25, 0.10 |
The weights of the parts of a Discover score (0 to 10 each, not all zero). Only their proportions matter. |
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, MusicBrainz, Wikipedia, Wikimedia Commons and the Cover Art Archive about artists and albums. This is off by default: until an admin turns a provider on, nothing leaves your server. Today Last.fm is used for similar artists and tags, MusicBrainz for tags and for the link to Wikidata, Wikipedia (with Wikidata) for descriptions of artists, Wikimedia Commons (with Wikidata) for free photos of artists, and the Cover Art Archive for the cover of an album that has none in your files.
- 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?
curl -s -X PUT $BASE/providers/musicbrainz -H "$AUTH" -d '{"enabled":true,"contact":"https://example.org/me"}'
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: to Last.fm, the artist name (or MusicBrainz id) being looked up, your API key, your IP address and the User-Agent; to MusicBrainz, only the MusicBrainz id of the artist, your IP address and a User-Agent that carries your contact. 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 (the exceptions are the three jobs that an admin starts on purpose, each of them one request that goes through the whole library, one item after the other, spaced out, and each stops when its providers keep failing: POST /library/covers, with the Cover Art Archive on, sends the release group id of every album that has no picture in its files; POST /library/artist-images, with Commons and MusicBrainz on, sends the MusicBrainz id of every artist that has one, to MusicBrainz, Wikidata and Commons; POST /library/descriptions, with Wikipedia and MusicBrainz on, sends it to MusicBrainz, Wikidata and Wikipedia), and they are spaced out, retried with backoff, and stopped by a circuit breaker if a provider is down. Descriptions (the Wikipedia provider, which also needs MusicBrainz on) send the MusicBrainz id to MusicBrainz, the Wikidata item to Wikidata and the title of the page to Wikipedia, with your IP address and a User-Agent that carries a contact (the one set for each provider; Wikimedia refuses requests without one), and never a name. Photos (the Commons provider, which also needs MusicBrainz on) send the MusicBrainz id to MusicBrainz, the Wikidata item to Wikidata, the name of the picture to Commons and the address of a copy to Wikimedia, with your IP address and a User-Agent with a contact, and never a name. Covers (the Cover Art Archive provider) send only the MusicBrainz release group id of an album, read from the tags of its own files and never a title, and only when the files have no picture; the redirects of the archive are followed only to archive.org, over https. Its covers have no licence of their own: Sonda keeps a copy for your library and never treats it as free. Discover asks Last.fm for the similar artists of each seed (the seed's name or MusicBrainz id) and, for the best suggestions that have no tags yet, for the tags of that suggestion (its name); never MusicBrainz. Seeds you name are sent when you ask. Seeds taken from your listening, which are the names of the artists you play most, are sent only if you turned on discover_from_listening yourself; otherwise Discover refuses to run without a seed. Besides the three jobs, the other 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.
Tags. GET /api/v1/artists/{id}/tags asks each provider that is on, at the same time, and keeps the answers with the same rules (7 days, 1 for an unknown artist, old data if a provider fails). Each provider has its own entry with its own weights: Last.fm's are relative to the artist (1 to 100), MusicBrainz's are counts of votes, and they are never mixed. MusicBrainz also marks the tags it lists as genres. Its tags and genres are CC BY-NC-SA, so show the attribution that comes with them.
Genres from your own files. The scan also reads the genre tag of each file (several genres separated by ;, at most five per file) and GET /artists/{id}/tags adds a files entry: the genres of the playable tracks the artist is credited on, each weighted by how many tracks have it. It needs no provider, asks nobody, and is always there.
MusicBrainz ids come from your files, never from a guess. If your files carry MusicBrainz artist ids in their tags (taggers like Picard write them), the scan reads them, offline, and keeps them on your artists, but only when each id can be paired with its artist for certain. MusicBrainz is asked only about artists whose id is known; for the others its entry says no_id. Sonda never searches MusicBrainz by name, because a search returns look-alikes and picking one would be a guess. A normal scan reads a file's tags when the file is new or changed. To pick up ids and genres for music that is already indexed, scan with full=true (POST /library/scan?full=true, or POST /libraries/{id}/scan?full=true): every file is read again, keeps its identity, and your listening history is untouched.
Taking it back. DELETE /api/v1/providers/{name}/data (admin) removes everything a provider gave: its similar artists, its tags and the records of when it was asked, and then the artists that only that data named and that you have no files for. Last.fm's terms ask for this when an agreement ends. Your own artists, music and listens stay, and the provider is not switched off. An artist that only that provider's lists named goes too, even if someone had it on their wishlist or dismissed. An artist that no list names any more is also removed when the list that named it is replaced, so they do not pile up.
The artist is sent to Last.fm by its MusicBrainz id when your files gave one (if Last.fm does not know the id, by name), otherwise by its name 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}/tags |
What Last.fm and MusicBrainz say about the artist's kind of music, from each provider that is on. |
| signed in | GET, HEAD /artists/{id}/image, GET /artists/{id}/image/credit |
A free picture of the artist from Wikimedia Commons (query size=small|large, also ?access_token=) and its credit. |
| signed in | GET /artists/{id}/description |
What Wikipedia says about the artist, with its page and licence, from the Wikipedia provider when an admin switched it on. |
| 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 /discover |
Artists you may like, with a score and its parts. Query: seed (an artist id, up to 5 times), limit (default 20, max 30), in_library=true|false. |
| signed in | GET, HEAD /albums/{id}/cover |
The cover of an album, a JPEG made from your own files. Query: size=small|large. Also accepts ?access_token=. |
| signed in | GET /wishlist, PUT /wishlist/{id}, DELETE /wishlist/{id} |
Your wishlist: list it (query limit, offset), add an artist, take one off. |
| signed in | GET /discover/dismissed, POST /discover/{id}/dismiss, DELETE /discover/{id}/dismiss |
The artists you are not interested in: list them, dismiss one, bring it back. |
| signed in | GET /me/taste |
The artists and tags Sonda learned you like, from your own listening. Query: limit (default 20, max 50). |
| signed in | GET /me/settings, PATCH /me/settings |
Your own settings (today: discover_from_listening, off by default). |
| signed in | GET /library/covers, GET /library/artist-images, GET /library/descriptions |
Progress of the job that builds the covers, looks for the artist pictures or for the artist descriptions, and how the last one ended. |
| 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, DELETE /library/covers; POST, DELETE /library/artist-images; POST, DELETE /library/descriptions |
Start, in the background, a job that builds the cover of every album, looks for the picture of every artist or for the description of every artist (?refresh=true for all), or stop it. One of each at a time. |
| admin | POST /library/scan, POST /libraries/{id}/scan |
Scan everything, or one library. ?full=true reads every file again. |
| admin | GET /providers, PUT /providers/{name}, POST /providers/{name}/test, DELETE /providers/{name}/data |
See, set up and check Last.fm and MusicBrainz, and remove what they gave. 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- and accent-insensitive substring match: bjork, BJORK and BJÖRK all find Björk, and strasse finds Straße. Accents still tell artists apart: Beyoncé and Beyonce stay two artists, and a search for either finds both.
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. An access token is checked against the database on every request, so it stops working as soon as its account is deleted, even if the same user id is given to a new account.
- 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 copysonda.db(andsonda.db-walif it exists). - PostgreSQL:
pg_dumpthe database. sonda.tomlholds the secret that signs tokens; treat the copy like a password.
Web app
A web client lives in web/ (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. sondad does not serve it yet, so for now it runs next to the server:
cd web
npm install
SONDA_URL=http://127.0.0.1:8080 npm run dev # open http://localhost:5173, /api is proxied to Sonda
What it does today: sign in (and create the first account of a new server), browse artists, albums and songs, search, and play with a queue, shuffle, repeat, media keys and a full-screen player. Artist pages show the Wikipedia text, similar artists and tags when those providers are on, each with its credit, and the photo credit next to the photo. It reports one listen per play. There are four themes (Sonda, Tokyo Night, Gruvbox dark and Gruvbox light) and two languages (English and Italian), both chosen in Settings.
More commands, all run in web/: npm test, npm run build, and npm run gen:api, which rebuilds src/api/schema.d.ts from the OpenAPI spec (it fetches the generator with npx, so it needs the network once). Discover, the admin screens and serving the app from the binary come later.
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/about/ descriptions of artists, from Wikipedia through MusicBrainz and Wikidata
internal/discovery/ similar artists: what the providers said, kept and refreshed
internal/providers/ external providers: settings, the outbound HTTP client, the Last.fm and MusicBrainz clients
internal/listening/ listen events
internal/taste/ what the listener likes, learned from the listening history
internal/discover/ the score of an artist you may like, and the suggestions
internal/feedback/ the wishlist and the artists a user is not interested in
internal/images/ covers made from the pictures in the user's own files
internal/usersettings/ the settings that belong to one user
internal/storage/ SQLite and PostgreSQL through bun, the repositories
internal/streaming/ opening a track's file safely
migrations/ SQL migrations, one folder per database
web/ the web client (React, Vite, shadcn/ui)
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.