From ee31e0ee7caf9e7510b7cfde1f4e096721966e90 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Sun, 15 Nov 2026 17:31:54 +0100 Subject: [PATCH 01/13] docs: note that this repo moved to git.kmalloc.org --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index be49736..5b9cb92 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Sonda +**This repository has moved.** Development continues at +[git.kmalloc.org/squid/sonda](https://git.kmalloc.org/squid/sonda); this +Codeberg mirror is archived and read-only. + 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. From 75a7898c68ca65c8c4efa0f51b72d62ac9a4db6e Mon Sep 17 00:00:00 2001 From: tgiachi Date: Mon, 16 Nov 2026 17:38:58 +0100 Subject: [PATCH 02/13] feat(web): make Sonda feel like an app on a phone A review of the phone experience (the issue) found a desktop page made smaller. What changes: feat: - The player bar is one row on a phone (cover, title, play and next, a thin line of progress) and is not there while nothing plays. A tap or a swipe up on it opens the full-screen player. - The Back gesture closes the full-screen player instead of leaving the page under it; a swipe down closes it too. The full queue is listed on a phone. - The queue is kept in the browser: a reload, or a tab that Android throws away, comes back paused on the same song at the same second. It belongs to the person signed in and is forgotten on sign-out. - Tabs have icons; the page starts at its top on a new route and back goes to where the list was; a swipe on the page no longer reloads it. fix: - The player now knows when the system pauses the audio (another app, a headset), so the button and the lock screen no longer say it plays. - The lock screen has a working seek bar and the right play/pause state. - The player bar was not hidden by max-sm:hidden: its grid rules were outside the Tailwind layers and won. They are in the components layer now. - Song rows give the title the room on a phone (no number column). - The album header is centred and the greeting is smaller on a phone; recent songs on Home show the artist. - Thumbnails ask for the small cover (300 px) and not the 1000 px one. - Pages use dvh, the viewport covers the notch, and the tabs keep clear of the gesture bar; the update notice no longer sits on the bar. - No grey tap flash, no double-tap delay, no image menu on a long press. --- README.md | 2 +- web/index.html | 2 +- web/src/auth/AuthGate.tsx | 2 +- web/src/auth/LoginPage.tsx | 2 +- web/src/components/Cover.test.tsx | 13 +- web/src/components/Cover.tsx | 17 ++- web/src/components/PageTitle.test.tsx | 2 +- web/src/components/PageTitle.tsx | 2 +- web/src/components/RouteLoading.tsx | 2 +- web/src/components/TrackRow.tsx | 5 +- web/src/components/layout/NowPlaying.tsx | 26 ++-- web/src/components/layout/PhoneTabs.test.tsx | 9 ++ web/src/components/layout/PhoneTabs.tsx | 20 +-- web/src/components/layout/Player.test.tsx | 104 ++++++++++++- web/src/components/layout/PlayerBar.tsx | 32 +++- web/src/components/layout/PlayerControls.tsx | 18 ++- web/src/components/layout/Shell.tsx | 8 +- .../layout/useBackClosesPlayer.test.tsx | 81 ++++++++++ .../components/layout/useBackClosesPlayer.ts | 41 +++++ web/src/index.css | 56 ++++--- web/src/lib/useSwipe.ts | 41 +++++ web/src/pages/AlbumPage.tsx | 10 +- web/src/pages/HomePage.test.tsx | 16 +- web/src/pages/HomePage.tsx | 9 +- web/src/pages/mixes.test.tsx | 2 +- web/src/pages/playlists.test.tsx | 4 +- web/src/pages/smart.test.tsx | 6 +- web/src/player/engine.test.ts | 39 ++++- web/src/player/engine.ts | 14 +- web/src/player/media.ts | 9 +- web/src/player/mediaSession.test.ts | 46 +++++- web/src/player/mediaSession.ts | 28 +++- web/src/player/saved.test.ts | 128 ++++++++++++++++ web/src/player/saved.ts | 140 ++++++++++++++++++ web/src/player/usePlayer.test.tsx | 25 ++++ web/src/player/usePlayer.ts | 20 ++- web/src/pwa/UpdateNotice.tsx | 2 +- 37 files changed, 892 insertions(+), 91 deletions(-) create mode 100644 web/src/components/layout/useBackClosesPlayer.test.tsx create mode 100644 web/src/components/layout/useBackClosesPlayer.ts create mode 100644 web/src/lib/useSwipe.ts create mode 100644 web/src/player/saved.test.ts create mode 100644 web/src/player/saved.ts diff --git a/README.md b/README.md index 5b9cb92..34b5a45 100644 --- a/README.md +++ b/README.md @@ -394,7 +394,7 @@ Back up the database and `sonda.toml`. Your music stays wherever you keep it. ## 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. With the app built into the binary (`make build`, or the Docker image) `sondad` serves it: open the address of the server, for example `http://127.0.0.1:8080`, and sign in. The page carries a strict Content-Security-Policy (only resources of the server itself, no inline scripts), cannot be framed and sends no referrer, and a link inside the app (`/admin/users`) works when you reload it. The player draws a live picture of what is playing, in the browser, from the sound itself (Web Audio). Settings has a choice for it, kept on the device: a spectrogram (the last seconds, low notes at the bottom, the default), the classic bars with falling caps, an oscilloscope, Milkdrop, or nothing. The bars, the oscilloscope and the spectrogram take the colour of this server or, for a friend's song, the colour of the friend. Milkdrop fills the background of the full-screen player with the pictures Winamp made famous, drawn on the device with [butterchurn](https://github.com/jberg/butterchurn) (MIT) and its presets, which are part of the app: nothing is fetched from outside. It is loaded only when chosen, and anyone who asked the system for less motion gets the spectrogram instead, because the pictures flash. The player listens to the sound and changes nothing of it, and draws only while something plays. +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. With the app built into the binary (`make build`, or the Docker image) `sondad` serves it: open the address of the server, for example `http://127.0.0.1:8080`, and sign in. The page carries a strict Content-Security-Policy (only resources of the server itself, no inline scripts), cannot be framed and sends no referrer, and a link inside the app (`/admin/users`) works when you reload it. The player draws a live picture of what is playing, in the browser, from the sound itself (Web Audio). Settings has a choice for it, kept on the device: a spectrogram (the last seconds, low notes at the bottom, the default), the classic bars with falling caps, an oscilloscope, Milkdrop, or nothing. The bars, the oscilloscope and the spectrogram take the colour of this server or, for a friend's song, the colour of the friend. Milkdrop fills the background of the full-screen player with the pictures Winamp made famous, drawn on the device with [butterchurn](https://github.com/jberg/butterchurn) (MIT) and its presets, which are part of the app: nothing is fetched from outside. It is loaded only when chosen, and anyone who asked the system for less motion gets the spectrogram instead, because the pictures flash. The player listens to the sound and changes nothing of it, and draws only while something plays. On a phone the player is one row at the foot of the page (and is not there while nothing plays); a tap or a swipe up opens the full-screen player, a swipe down or the Back gesture closes it, and the lock screen shows the song with its seek bar and follows play and pause. The queue is kept in the browser, so a page that is reloaded, or a tab that Android throws away, comes back paused on the same song at the same second. To work on the interface itself, run the Vite dev server next to a running `sondad` (set `SONDA_URL` to where it listens: the default is `http://127.0.0.1:8080`): diff --git a/web/index.html b/web/index.html index b6c7099..243714a 100644 --- a/web/index.html +++ b/web/index.html @@ -9,7 +9,7 @@ - + Sonda diff --git a/web/src/auth/AuthGate.tsx b/web/src/auth/AuthGate.tsx index 7f5fe51..7b24792 100644 --- a/web/src/auth/AuthGate.tsx +++ b/web/src/auth/AuthGate.tsx @@ -9,7 +9,7 @@ export default function AuthGate({ children }: { children: ReactNode }) { const { t } = useTranslation() if (status === 'loading') { - return
+ return
} if (status === 'anonymous') return return <>{children} diff --git a/web/src/auth/LoginPage.tsx b/web/src/auth/LoginPage.tsx index 3f225b9..1ad513e 100644 --- a/web/src/auth/LoginPage.tsx +++ b/web/src/auth/LoginPage.tsx @@ -31,7 +31,7 @@ export default function LoginPage() { } return ( -
+

{creating ? t('auth.registerTitle') : t('auth.signInTitle')}

diff --git a/web/src/components/Cover.test.tsx b/web/src/components/Cover.test.tsx index 7b610e0..207f55a 100644 --- a/web/src/components/Cover.test.tsx +++ b/web/src/components/Cover.test.tsx @@ -16,7 +16,7 @@ function placeholder(container: HTMLElement) { test('a cover asks for the album cover of the API', () => { const { container } = render() const img = container.querySelector('img')! - expect(img.getAttribute('src')).toBe('/api/v1/albums/12/cover') + expect(img.getAttribute('src')).toBe('/api/v1/albums/12/cover?size=small') expect(img).toHaveAttribute('loading', 'lazy') expect(img).toHaveAttribute('alt', '') expect(placeholder(container)).toBeNull() @@ -25,9 +25,9 @@ test('a cover asks for the album cover of the API', () => { test('the cover URL carries the access token and follows it when it changes', () => { sessionStore.setState({ accessToken: 'tok1' }) const { container } = render() - expect(container.querySelector('img')!.getAttribute('src')).toBe('/api/v1/albums/12/cover?access_token=tok1') + expect(container.querySelector('img')!.getAttribute('src')).toBe('/api/v1/albums/12/cover?size=small&access_token=tok1') act(() => sessionStore.setState({ accessToken: 'tok2' })) - expect(container.querySelector('img')!.getAttribute('src')).toBe('/api/v1/albums/12/cover?access_token=tok2') + expect(container.querySelector('img')!.getAttribute('src')).toBe('/api/v1/albums/12/cover?size=small&access_token=tok2') }) test('a cover that fails to load is replaced by the placeholder', () => { @@ -116,3 +116,10 @@ test('a cover that cannot be loaded falls back to the rings, and the picture hid expect(placeholder(container)).not.toBeNull() expect(container.querySelector('img')).toBeNull() }) + +test('a big cover asks for the full picture, a friend’s cover for the only one the friend has', () => { + const big = render() + expect(big.container.querySelector('img')!.getAttribute('src')).toBe('/api/v1/albums/12/cover') + const friend = render() + expect(friend.container.querySelector('img')!.getAttribute('src')).toBe('/api/v1/friends/3/albums/12/cover') +}) diff --git a/web/src/components/Cover.tsx b/web/src/components/Cover.tsx index 1ce7bca..92e1d1c 100644 --- a/web/src/components/Cover.tsx +++ b/web/src/components/Cover.tsx @@ -19,10 +19,14 @@ const RINGS = [ { size: '68%', opacity: 0.3 }, ] as const +/** Up to this size (CSS pixels) a cover is drawn from the small picture. */ +const SMALL_UP_TO = 150 + /** The cover of an album, or the rings of Sonda when there is none (or it cannot be loaded). */ export default function Cover({ albumId, friend, size, fluid = false }: CoverProps) { useAccessToken() // the URL carries the token, so it has to follow a renewal - const src = albumId === null ? null : mediaUrl(coverPath(friend, albumId)) + // A thumbnail asks for the small picture: a phone does not need to fetch 1000 pixels to draw 56. + const src = albumId === null ? null : mediaUrl(coverPath(friend, albumId, size <= SMALL_UP_TO)) // A failure is remembered for this URL only: a renewed token makes a new URL, which is tried again. const [failed, setFailed] = useState(null) const showImage = src !== null && failed !== src @@ -36,7 +40,16 @@ export default function Cover({ albumId, friend, size, fluid = false }: CoverPro className="relative shrink-0 overflow-hidden rounded-sm bg-muted" > {showImage ? ( - setFailed(src)} /> + window.matchMedia?.('(pointer: coarse)').matches && e.preventDefault()} + className="size-full object-cover" + onError={() => setFailed(src)} + /> ) : (
+ + + diff --git a/android/www/server.js b/android/www/server.js new file mode 100644 index 0000000..d0cc46e --- /dev/null +++ b/android/www/server.js @@ -0,0 +1,16 @@ +/** Turns what was typed into the address of a Sonda server, or null when it is not one. */ +export function normalizeAddress(input) { + const text = String(input ?? '').trim() + if (text === '') return null + const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}` + let url + try { + url = new URL(withScheme) + } catch { + return null + } + if (url.protocol !== 'https:' && url.protocol !== 'http:') return null + if (url.hostname === '') return null + // The app lives at the root of the server: a path, a query or a fragment typed by mistake is dropped. + return url.origin +} From e11ce89b2170dee476312730186d96d9f0d7efd0 Mon Sep 17 00:00:00 2001 From: sonda-release Date: Tue, 17 Nov 2026 09:42:59 +0000 Subject: [PATCH 11/13] chore(release): 0.5.0 [skip ci] ## [0.5.0](https://git.kmalloc.org/squid/sonda/compare/v0.4.2...v0.5.0) (2026-11-17) ### Features * **android:** add an Android app ([ba10b8e](https://git.kmalloc.org/squid/sonda/commit/ba10b8ef7bbcf4fe3735e7b931d1b687259cc044)), closes [#47](https://git.kmalloc.org/squid/sonda/issues/47) * **web:** talk to the Android app ([995f2e5](https://git.kmalloc.org/squid/sonda/commit/995f2e5ae013897a56743b60eeedea909fe04db9)) ### Bug fixes * **web:** show a restored queue on the lock screen ([a2d6d2a](https://git.kmalloc.org/squid/sonda/commit/a2d6d2a925edf8de89a7a4df0afbfa82004ccf87)) --- CHANGELOG.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5257286..c54bc8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## [0.5.0](https://git.kmalloc.org/squid/sonda/compare/v0.4.2...v0.5.0) (2026-11-17) + +### Features + +* **android:** add an Android app ([ba10b8e](https://git.kmalloc.org/squid/sonda/commit/ba10b8ef7bbcf4fe3735e7b931d1b687259cc044)), closes [#47](https://git.kmalloc.org/squid/sonda/issues/47) +* **web:** talk to the Android app ([995f2e5](https://git.kmalloc.org/squid/sonda/commit/995f2e5ae013897a56743b60eeedea909fe04db9)) + +### Bug fixes + +* **web:** show a restored queue on the lock screen ([a2d6d2a](https://git.kmalloc.org/squid/sonda/commit/a2d6d2a925edf8de89a7a4df0afbfa82004ccf87)) + ## [0.4.2](https://git.kmalloc.org/squid/sonda/compare/v0.4.1...v0.4.2) (2026-11-17) ### Bug fixes From 11077f40e1cf66ef7f96920106eb3e3ec5466a70 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Tue, 17 Nov 2026 14:50:52 +0100 Subject: [PATCH 12/13] docs: split the README into pages under docs/ The README had grown to about 500 lines. It now holds the intro, a quick start and an index, and the rest lives in docs/. - docs: add docs/README.md as the index of all pages - docs: move install, configuration, demo, providers, OpenSubsonic, API, security and backups, web app, Android app and development/releases to their own pages, text unchanged - docs: split the feature list into five pages under docs/features/ - docs: rewrite internal anchors as links between the new pages - chore: add docs to .dockerignore, next to README.md --- .dockerignore | 1 + README.md | 474 +------------------------------------ docs/README.md | 22 ++ docs/android.md | 21 ++ docs/api.md | 54 +++++ docs/configuration.md | 47 ++++ docs/demo.md | 104 ++++++++ docs/development.md | 67 ++++++ docs/features/README.md | 15 ++ docs/features/artwork.md | 15 ++ docs/features/listening.md | 27 +++ docs/features/music.md | 21 ++ docs/features/playlists.md | 13 + docs/features/sharing.md | 11 + docs/install.md | 45 ++++ docs/opensubsonic.md | 33 +++ docs/operations.md | 20 ++ docs/providers.md | 60 +++++ docs/web-app.md | 18 ++ 19 files changed, 603 insertions(+), 465 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/android.md create mode 100644 docs/api.md create mode 100644 docs/configuration.md create mode 100644 docs/demo.md create mode 100644 docs/development.md create mode 100644 docs/features/README.md create mode 100644 docs/features/artwork.md create mode 100644 docs/features/listening.md create mode 100644 docs/features/music.md create mode 100644 docs/features/playlists.md create mode 100644 docs/features/sharing.md create mode 100644 docs/install.md create mode 100644 docs/opensubsonic.md create mode 100644 docs/operations.md create mode 100644 docs/providers.md create mode 100644 docs/web-app.md diff --git a/.dockerignore b/.dockerignore index 15c247d..60587d7 100644 --- a/.dockerignore +++ b/.dockerignore @@ -17,6 +17,7 @@ Dockerfile .dockerignore compose.yaml README.md +docs # AI agent instruction files: never part of the project's files, wherever they are **/agent.md diff --git a/README.md b/README.md index 0ddc654..79b3829 100644 --- a/README.md +++ b/README.md @@ -8,71 +8,13 @@ Sonda is a privacy-first, self-hosted music server written in Go. It streams the 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 are not built yet, other apps can connect over OpenSubsonic (see [Other apps](#other-apps-opensubsonic)), and the web client in `web/`, which `sondad` serves, is young (see [What is not there yet](#what-is-not-there-yet) and [Web app](#web-app)). The API may still change. +> **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). Other apps can connect over OpenSubsonic (see [Other apps](docs/opensubsonic.md)), and the web client in `web/`, which `sondad` serves, is young (see [What is not there yet](docs/features/README.md#what-is-not-there-yet) and [Web app](docs/web-app.md)). The API may still change. -## What works today +## Quick start -- **Accounts.** An account is an email address and a password. The first user to register becomes the admin and registration then closes; admins create the other users. The address only identifies the account: Sonda sends no mail, does not check that the address exists, and keeps it on your server. It is trimmed and lowercased, and unique. Accounts made before addresses were asked for keep the plain name they had as their login. 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 reads your music folders: it never writes or renames a file, and it deletes one only when an admin asks to remove the extra copy of a song and you turned on `library.allow_delete` (see **Duplicates**), which is off by default. -- **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. **Scans by itself.** Every 15 minutes (`library.auto_scan_minutes`) Sonda looks at the folders of each library, which costs only the names of the files, and scans a library whose music changed: a song or a folder came, went or was renamed. A library is also scanned at least once a day, to find a song that was tagged again where it stands. It never scans while another scan runs, and a folder it cannot read (a NAS that is not mounted) is left alone. -- **Catalog.** Browse and search artists, albums and songs, with paging, by library, artist or album. Only songs you can actually play are listed. -- **Duplicates.** `GET /library/duplicates` (admin) lists the songs that are in more than one file: the same set of main artists, the same title and durations within 3 seconds, possibly on different albums. It is worked out from the index, touches no file, and returns no file path. Each group proposes the copy to keep (lossless first, then the higher bitrate, then the bigger file, then the oldest). A background job (`POST /library/duplicates/check`, like the other bulk jobs) reads the files of the groups and keeps their SHA-256, so a group can be called `identical` (byte for byte). `POST /library/duplicates/clean` **deletes the extra copies of one song from the disk**, and it is the one thing Sonda does that writes in your music folders, so it is off until you set `library.allow_delete` (or `SONDA_ALLOW_DELETE=true`) and mount the folders writable. It deletes only when an admin asks, never by itself, and the server checks again at that moment that no scan is running, that the songs are copies of one song, and that every file is still the one the last scan saw (same size and date, a regular file, not a link, inside its library): so the last copy of a song is never deleted, a file that changed is not deleted, and every file is checked before the first is deleted. The listens and the playlist items of a deleted copy move to the one that stays, so your taste and your playlists are not lost. Folders are never removed, and nothing is sent anywhere. The web app has a Duplicates section in Admin: a table of the copies of each song with the copy to keep already chosen (you can pick another), the check with its progress and a Stop button, **Delete the others** for one song and **Clean all suggestions** for all of them, each after a question that lists the files and the space it frees; with deleting off everything is visible and the delete buttons are disabled. -- **Streaming.** `GET` and `HEAD` with `Range` support, so players can seek. Opening or prefetching a stream does not record a listen. `GET /tracks/{id}/peaks` gives the shape of a song for the seek bar: 120 levels from 0 to 255, how loud it is along its length. The server finds it by decoding the file (MP3 and FLAC, in pure Go: nothing else to install), which takes a few seconds, so the first request starts the work in the background and answers `202` with `Retry-After`; it is done once for each file, worked out again if the size or the date of the file change, and one song at a time, so a NAS is not kept busy. A file that cannot be decoded answers `waveform_unavailable`, and that is remembered too. A friend's song has no shape yet. -- **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. -- **Your taste.** `GET /me/taste` shows 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 /discover` suggests 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 on `discover_from_listening`, from the artists you play most. It needs Last.fm to be turned on to ask for anything new: when Last.fm is off and a seed's similar artists are not stored yet, the answer says `disabled` (what was stored earlier is still used). See [External providers](#external-providers). A listener has one Discover at a time (a second one answers `429` with `Retry-After`), and at most three run at once on the server, so the providers are never lined up with work: one that waits more than 30 seconds for its turn answers `429` too, and one that stops waiting does none. -- **Artist descriptions.** `GET /artists/{id}/description` shows 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 the `wikipedia` provider and the `musicbrainz` one turned 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 with `GET /library/descriptions`, stop it with `DELETE /library/descriptions`; `?refresh=true` reads 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](#external-providers). -- **Artist photos.** `GET /artists/{id}/image` serves a free picture of an artist from Wikimedia Commons, and `GET /artists/{id}/image/credit` says 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=small` is 300 pixels, `large` 1000) in the data folder. With the `commons` provider and the `musicbrainz` one turned 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 with `GET /library/artist-images`, stop it with `DELETE /library/artist-images`; `?refresh=true` searches 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](#external-providers). -- **Album covers.** `GET /albums/{id}/cover` serves the cover of an album from your own files: the picture embedded in them, or else a `cover`, `folder`, `front`, `album` or `albumart` image in the album's folder. It is built the first time it is asked for (a few at a time), scaled (`?size=small` is 300 pixels, `large` 1000) 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 turned on the `coverartarchive` provider, 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. An album whose files have no id is looked up in MusicBrainz by its artist and title when the `musicbrainz` provider is on too (see the list of what leaves your server). For an album split in `CD1`/`Disc 2` folders, the picture in the folder above is used. Nothing is sent anywhere unless you turned on the `coverartarchive` provider (see [External providers](#external-providers)). It also takes `?access_token=`, so an `` 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 with `GET /library/covers`, stop it with `DELETE /library/covers`; `?refresh=true` searches 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). -- **Mixes.** `GET /mixes` lists playlists that Sonda makes for you, like the mixes of a streaming service, from what you listen to and from the genres of your music: one mix for each genre of your library that has at least 30 songs by 4 artists (the genres you play most first), and, once you have some listening history, *Your favourites* (the artists you like: the ones you play, and the ones you marked with a heart) and *Rediscover* (artists you like and have not played for a month); *New to you* is the songs you never played. `GET /mixes/{id}` gives a mix of up to 50 songs, at most 3 by one artist and never two of the same artist in a row. They are picked by weighted chance: the artists you play weigh more and songs you skipped lately or artists you avoid are left out. A mix stays the same for a day, and `?variant=2` gives another; `POST /mixes/{id}/playlist` keeps the one you are looking at as a playlist of your own. A mix is worked out when you ask for it, from your own history and the genre tags of your files: nothing is stored and nothing is sent to a provider. The id of a genre mix has the genre in it (`genre:hard rock`), so it is percent-encoded in the path. Each mix says which albums stand for it (`album_ids`: up to 4 albums that have a cover, by different artists, with most of the songs the mix draws from), for a picture made of their covers; the covers are the ones the library already has, so a mix has a picture once the covers of its albums were looked up (browsing the albums, or the covers job), and none is fetched for it. -- **ReplayGain.** The scan reads the ReplayGain tags of each file (`REPLAYGAIN_TRACK_GAIN`, `REPLAYGAIN_ALBUM_GAIN` and the two peaks), offline, and keeps them on the file; a tag that makes no sense (not a number, more than 60 dB) is left out. A song in the API has them as `replay_gain` (gains in decibels, peaks as a fraction of full scale), or `null` when its first playable file says nothing; the files indexed before this existed have none until a full rescan (`POST /library/scan?full=true`) reads their tags again. The server never changes a file or the sound: a client uses the numbers to play every song at a similar volume, as the web app does (see [Web app](#web-app)). -- **Smart playlists.** A smart playlist is a set of rules instead of a list of songs, worked out again every time you open it, so new songs and your listening change it by themselves. `POST /smart-playlists` keeps a name, the rules, an order (`random`, `most_played`, `least_played`, `recently_added` or `title`) and a limit (50 by default, 500 at most); `GET /smart-playlists/{id}/tracks` gives the songs now. Every rule that is set must hold: genres, artists and albums (is, or is not), file formats and a minimum bitrate (about the same file), added in the last N days (by the date of the file), never played, played or not played in the last N days, played at least N times (optionally counting only the plays of the last N days, which is what makes the songs in rotation lately and the top of the year), skipped or not skipped lately, only artists you like or without the ones you avoid, the length of the song, and the year it came out (`min_year` and `max_year`, both included: 1980 to 1989 is the eighties). The year comes from the tags of the file (the original date first, then the date); a song with no year never matches a year rule, and the files indexed before this existed have none until a full rescan (`POST /library/scan?full=true`) reads their tags again. `POST /smart-playlists/preview` tries rules without keeping them, and `POST /smart-playlists/{id}/playlist` keeps what you see as a normal playlist (a copy). Only the rules are stored; the songs come from the files and from your own history, nothing is sent to a provider, and a smart playlist is yours alone, and `GET /genres` lists the genres to choose from. A random order stays the same for a day, and `?variant=2` gives another. `GET /smart-playlists/{id}/covers` and `GET /smart-playlists/suggested/{key}/covers` say which albums stand for one (up to 4 that have a cover, in the order of the songs it gives now), for its picture; they are apart from the songs so that the list of smart playlists shows at once and each card fills in its cover when it arrives. Some are there without anybody making them: `GET /smart-playlists/suggested` lists a fixed set (`recently-added`, `on-rotation`, `top-year`, `most-played`, `never-played`, `forgotten`, `high-quality`, `long-tracks`), the same rules for everyone and worked out on your own library and history, nothing stored; `GET /smart-playlists/suggested/{key}/tracks` gives their songs and `POST /smart-playlists/suggested/{key}/playlist` keeps them as a playlist, and `on-rotation` is the songs you played most in the last 30 days and `top-year` the same over a year, so they change as you listen; a copy of their rules becomes a smart playlist of your own with `POST /smart-playlists`. A user can have 200. -- **Playlists.** `POST /playlists` makes a playlist (a name and an optional description) and `GET /playlists` lists yours, the one changed last first. `POST /playlists/{id}/tracks` adds 1 to 500 songs at the end or at a `position`, `GET /playlists/{id}/tracks` lists them in order, `PATCH /playlists/{id}/tracks/{item}` moves one and `DELETE` takes one out; `PATCH /playlists/{id}` renames and `DELETE /playlists/{id}` deletes (the songs stay in the library). A song can be in a playlist more than once, which is why each place has its own item id. A playlist is yours alone: someone else's answers `playlist_not_found`, as one that does not exist. A song whose files were deleted or moved away stays in the playlist and shows `available: false`; it plays again when the files come back and a scan finds them. Each playlist says which albums stand for it (`album_ids`: up to 4 albums that have a cover, in the order they first appear in it, each once), for a picture made of their covers; nothing is fetched for it. A user can have 1000 playlists of up to 10000 songs. Nothing is shared and nothing leaves your server. -- **Wishlist and "not interested".** `PUT /wishlist/{artist}` puts an artist on your wishlist (`GET /wishlist` lists it, `DELETE` takes it off), and `POST /discover/{artist}/dismiss` hides an artist from your Discover for good (`DELETE` brings it back, `GET /discover/dismissed` lists 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. The wishlist is a list for you and sends nothing anywhere; Sonda downloads nothing, but an admin can send an artist that Discover showed to their own Lidarr (see [External providers](#external-providers)), which works for an artist that has a MusicBrainz id and that Sonda knows of from a list or from your files. 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.** `GET` and `PATCH /me/settings` hold choices that belong to you, not to the server. Everyone starts private: `discover_from_listening` is 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, from `retrieved_at` of `GET /artists/{id}/similar`, that someone looked up an artist, but not who. -- **Importing from Spotify.** `POST /me/import/spotify` brings your listening history and your playlists from a Spotify data export into your own account. Ask Spotify for your data (Account, Privacy, "Extended streaming history" and "Account data") and send what it gives, as a multipart form with a `files` field for each file: the zip itself, or the JSON files in it (`Streaming_History_Audio_*.json`, the older `StreamingHistory_music_*.json` and `Playlist*.json`); a request may be up to 512 MB, and the rest of the export (the account, the searches, the library) is never opened. It all happens on your server and nothing is sent anywhere; the files are read from the request and not kept, and of each play only the song, the artist, the album, the time and how it ended are read, never the IP addresses, the country or the platform in the file. Of a play of a song you do not have that counts as listened, the name of the artist and the time are kept (and nothing else), so that Sonda can learn which artists you play together. A play is matched to a song of your library by artist and title (case, accents and punctuation do not matter, a `Remastered` note on either side does not, any credited artist will do, and a play of a compilation is matched by its album when Spotify says `Various Artists`). A match is recorded as a listen at the time of the play: `complete` when it ran to its end (or nine tenths were played), `skip` when Spotify says it was skipped or it lasted less than a listen, `play` otherwise; nothing is posted to Mastodon. Importing the same files again records nothing twice, and the same play in the extended and in the older history is one. A playlist becomes a playlist of yours with the songs that were found, in order; one whose name you already have is left alone, and one with none of its songs in your library is not made. The report counts what was added, what was already there and what is not in your library (and lists those artists, most played first), so you can see what is missing. One import of yours runs at a time. The report is kept: `GET /me/import/spotify` lists your past imports, newest first, with the numbers of each (never the files). The web app has an Import page for the form and for those numbers. -- **Suggestions from your own listening.** `GET /me/suggestions` learns which artists you play together: your history is split into sittings (plays less than 30 minutes apart) and two artists that turn up in the same sitting often are linked (a cosine over the sittings of each). It is a count over your own data, built on your server in a moment and again when plays are added, with no provider and nothing sent anywhere; it needs `discover_from_listening` in `PATCH /me/settings`. The model reads your listening events and the plays of artists you have no music of that an import kept (the artist and the time only). `library` are artists you have that go with what you play and that you did not play for two months; `missing` are artists you played at least three times and have no music of, the ones you play most that also go with what you play now first. Each says which of your artists it goes with. `POST /me/suggestions/wishlist` puts an artist you played on your wishlist by name (it is made without music and without a MusicBrainz id: Sonda never looks one up by name, so it cannot be sent to Lidarr from here). The web app has a "From your listening" tab in Discover. -- **Listening history by year and month.** `GET /listens/months` says how many listens that count you made in each calendar month, newest first, in the time zone you send as `tz` (UTC without it), and `GET /listens` takes `from` and `until` to read the listens of one of them; each listen now names its artists. The web app has a History page: a button for each year, the months of the year as bars, and the listens of the month a day at a time. -- **Statistics.** `GET /stats/library` says what the server holds: the songs that can be played (a song whose file is missing is not counted), their artists, albums, total length and the space their files take, the files by format, and the share of each genre (a song with several genres is split between them, so the shares add up to 1) and of each decade. `GET /stats/listening` says what you listened to, for all time or from `from` to `until` (dates with an offset, `until` excluded): the listens that count, the time listened, the songs and artists, the listens of each year, hour of the day and weekday in the time zone `tz`, your top ten artists and songs, the share of each genre, and how that share changed over time (`genre_timeline`: a column for each year, or for each month when all your listens are in one year, with the share of your five biggest genres, of the smaller ones and of what has no genre). Nobody else's listens are visible. The web app shows both on the Statistics page. -- **Requests to Lidarr.** `GET /lidarr/requests` (admin) lists the artists you sent to your Lidarr with `POST /artists/{id}/lidarr`, newest first, and says for each whether its music has arrived: `waiting` while there is none in the library, `arrived` once a scan found some (by the artist you sent or by an artist of the same name; the day it was first noticed is kept). Sending an artist again keeps one request with the first date; only what you sent from Sonda is listed. The web app has a Requests page (admins only), with the waiting and the arrived artists apart. -- **Sharing on Mastodon.** `PUT /me/mastodon` connects your own Mastodon account (the address of your instance and an access token that can only write posts); `GET` shows which account is connected and `DELETE` forgets it and the token. Nothing is connected by default. Once it is, each song of this server that counts as a listen is posted to your account as an unlisted status with the title, artists, album and `#NowPlaying`, and no link: at most one post a minute, never music of a friend. The token stays on the server and is never sent back. If the instance refuses the token on a post (it was revoked or expired), `GET /me/mastodon` says `problem: token_refused`, Settings shows it, and nothing is posted until you connect again with a new token. The address of the instance must be a domain name on https, and the server never connects to a private, loopback or link-local address for it, never follows a redirect and ignores proxy settings. -- **Tags.** `GET /artists/{id}/tags` shows 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](#external-providers). -- **Similar artists.** With Last.fm turned on, `GET /artists/{id}/similar` lists artists similar to an artist, and says which of them you already have. See [External providers](#external-providers). Without it, Sonda makes no outbound network requests at all. -- **Friends (federation).** Two Sonda servers can become friends, and the listeners of one can read what the other chose to share. `PUT /federation` (admin) turns federation on, which is off by default, and gives this server a name and a public address (`https`; plain `http` only on a network of your own); the server then makes its own Ed25519 key, kept in the database and never returned. `POST /federation/invites` makes an invite that works once and expires in 24 hours (only a hash of its code is kept). The other admin uses it with `POST /federation/friends`: that server is asked to accept this one, the key it answers with must be the one named in the invite, and the friend waits as `outgoing` until the first admin approves it with `POST /federation/friends/{id}/approve` (`POST /federation/friends/{id}/check` lets the waiting side find out). Either side can remove a friend with `DELETE /federation/friends/{id}`. Nothing is shared until an admin turns on `shared` for a library (`PATCH /libraries/{id}`). A friend's server then reads, with requests signed by its key (the method, the path and query, a date, a nonce and the hash of the body), the routes under `/peer`: the artists, albums and songs that have a file in a shared library, their covers once they are built, and the audio itself with `Range`. A friend never sees a path, a library id, a listen, a taste or a user, never makes this server build a cover or ask a provider, and has a few streams at a time and a number of KiB a second to share (`max_streams`, `max_kib_per_sec`); the admin sees the last requests it made (`GET /federation/requests`, the route and the size, never what was searched for). Sharing a library lets friends play it and, in practice, copy its files. A listener browses the music of a friend with `GET /friends` (the names of the friends whose friendship both admins agreed to, never an address or a key) and `GET /friends/{friend}/artists`, `albums` and `tracks` with `q`, `limit` and `offset`, and one item at a time: this server asks the friend with a signed request, checks the shape of the answer and passes it on, and nothing is kept; the ids are the friend's own. A friend that cannot be reached or no longer takes this server for a friend is told in words. The web app has a Friends section for it, shown only when there is a friend to browse. A listener plays it with `GET /friends/{friend}/tracks/{id}/stream` and sees its covers with `GET /friends/{friend}/albums/{id}/cover`, which accept the access token in the query like the local ones: this server asks the friend with a signed request, forwards `Range` and the conditional headers, and passes on only audio (or a JPEG for a cover) with `Content-Type`, `Content-Length`, `Content-Range`, `Accept-Ranges`, `Last-Modified` and `ETag`, so the friend sees this server and never the listener, and a friend cannot make this server serve anything else. A friend's song plays in the same player as the others but is never reported as a listen and does not feed taste. The admin area has a Federation section for all of it. - -- **Radio.** Stations that Sonda makes by itself from your music, with nothing to set up, and without end: *Everything*, one for each decade that has at least 30 songs by 4 artists (from the year in the tags), and the mixes you have (one for each genre, *Your favourites*, *Rediscover*, *New to you*), plus the radio of an artist from its page. `GET /radio` lists the stations and `GET /radio/{id}` gives up to 50 songs of one, **other songs every time it is asked**, picked like a mix (your taste and your hearts count, nothing skipped lately, at most 3 by one artist); `artist:` is the station of an artist (their songs weigh four times as much, with the songs of the two genres most of theirs have). The web app has a Radio page and a *Start radio* button on every artist, and its player asks for more songs by itself before the queue runs out. Apps that speak OpenSubsonic see each station as a playlist called *Radio · Rock*, with other songs every time it is opened (an app has no way to play a radio that never ends), but only when you turn on `radio_in_apps` (`PATCH /me/settings`; in Settings, *Show the radio stations in apps*): there are about two dozen of them, so it is off until you ask. Nothing is stored and nothing leaves the server. -- **Favourites.** `PUT /me/favorites/{kind}/{id}` marks a song, an album or an artist (`kind` is `tracks`, `albums` or `artists`) as a favourite and `DELETE` takes it back; `GET /me/favorites/{kind}` lists them, the newest first, and `GET /me/favorites/ids` gives every id for the hearts of a list. They are yours alone: never shown to a friend and never sent anywhere. Favourites also teach Sonda your taste: a favourite artist counts as much as three complete listens, a favourite album for its artist 1.5, a favourite song 1 (at most 6 for one artist), and the mixes of what you like give a favourite song more chance (and a song of a favourite album a little more). That feeds Discover, the mixes and the smart playlists that use your taste, and `GET /me/taste`. The web app has a heart on every song, album and artist (and in the player) and a Favourites page. Apps that speak OpenSubsonic see them as starred things. -- **Other apps.** Apps that speak OpenSubsonic (Symfonium, Feishin, Amperfy, Supersonic and others) can browse, search, play, show covers, use your playlists and report what you listened to, with a password of their own for each app (see [Other apps](#other-apps-opensubsonic)). - -## What is not there yet - -Radio queues, transcoding, ratings, and the ListenBrainz integration. The web client is built into the binary (see [Web app](#web-app)), and its admin area covers everything the API can do for an admin: libraries and scanning, users, the external providers and the bulk jobs. - -## 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 +With Docker (the image is on the registry of git.kmalloc.org, for amd64 and arm64): ```bash -make build # the web app (needs Node), then bin/sondad with the app inside -``` - -`make build` runs `npm ci` and `npm run build` in `web/`, which writes the app to `internal/webui/dist`, and then builds `sondad` with the tag `webui`, which embeds it: one program that serves the app on `/` and the API on `/api`. You can do the same by hand: `(cd web && npm ci && npm run build) && go build -tags webui -o bin/sondad ./cmd/sondad`. - -A plain `go build -o bin/sondad ./cmd/sondad` needs no Node and gives the API only; `/` then shows a page that says how to build the app. `make test` runs the Go tests and the web tests. - -### Docker - -The image holds `sondad` with the web app inside, and nothing else: it builds the app itself, so you need no Node on your machine. It runs as an ordinary user, keeps the database and the files Sonda makes under `/data`, listens on port 8080 inside the container, and does not start without `SONDA_JWT_SECRET`. - -The image is published on the registry of git.kmalloc.org, so you do not have to build it: `git.kmalloc.org/squid/sonda:latest` is the last one, and `git.kmalloc.org/squid/sonda:0.3.0` (a version from [CHANGELOG.md](CHANGELOG.md)) is one you can stay on. It runs on amd64 and on arm64 (a Raspberry Pi, an ARM NAS): one tag gives each machine its own. Anyone can pull it, with no login. To build it yourself instead, run `docker build -t sonda .` and use `sonda` where the commands below say `git.kmalloc.org/squid/sonda:latest`. - -```bash -docker pull git.kmalloc.org/squid/sonda:latest (umask 077; echo "SONDA_JWT_SECRET=$(openssl rand -hex 32)" > sonda.env) # once: keep this file docker run -d --name sonda --restart unless-stopped --stop-timeout 15 \ -p 127.0.0.1:8080:8080 \ @@ -82,413 +24,15 @@ docker run -d --name sonda --restart unless-stopped --stop-timeout 15 \ git.kmalloc.org/squid/sonda:latest ``` -Mount your music read-only wherever you like (only if you want Sonda to delete duplicate files, mount it writable and set `SONDA_ALLOW_DELETE=true`: see **Duplicates**), then add the library through the API with the path *inside* the container, `/music` above (not the folder of your host): the [Demo](#demo) works the same way with `BASE=http://127.0.0.1:8080/api/v1`, except that step 4 creates the library with `"path":"/music"`. Keep `sonda.env` and pass it every time you run a new container, for example after an upgrade: a new secret signs out everybody. The container's health check asks the port in `SONDA_LISTEN`, so it works for `0.0.0.0`, `[::]` and a port alone, but not if you bind the server to one interface address. Published like this the server answers only on this machine; to serve your network, publish the port without `127.0.0.1:` and put a reverse proxy with https in front. The other settings are the environment variables of the [table below](#configure) (`SONDA_DB_DRIVER` and `SONDA_DB_DSN` for PostgreSQL); the image sets `SONDA_LISTEN`, `SONDA_DB_PATH` and `SONDA_DATA_DIR` for the volume. +Open `http://127.0.0.1:8080`, create the first account (it becomes the admin), then add a library with the path `/music`. To build from source, or for Compose, see [Install](docs/install.md). -To keep the data in a folder of the host instead of a volume, run the container as the owner of that folder, or it cannot write there: add `--user "$(id -u):$(id -g)"` and `-v /path/to/sonda-data:/data`. Back up `sonda.db` (and treat the backup like a secret: it holds the API keys of the providers); the rest of `/data` is built from your music. +## Documentation -`compose.yaml` is the same as an example: put `SONDA_JWT_SECRET` and `MUSIC_DIR` (and `SONDA_PORT` if 8080 is taken) in a `.env` file next to it and run `docker compose up -d --build` (to use the published image and not build one, swap the `build: .` and `image:` lines for the one in the comment of the file, and run `docker compose pull && docker compose up -d`). The image has a health check on `/api/v1/health`, which is logged at debug level when it succeeds. +- **Set it up:** [Install](docs/install.md) · [Configuration](docs/configuration.md) · [Demo](docs/demo.md) · [Security and backups](docs/operations.md) +- **Use it:** [Features](docs/features/README.md) · [Web app](docs/web-app.md) · [Android app](docs/android.md) · [OpenSubsonic apps](docs/opensubsonic.md) · [External providers](docs/providers.md) +- **Build on it:** [The API at a glance](docs/api.md) · [Development and releases](docs/development.md) · [CHANGELOG](CHANGELOG.md) -If you prefer a config file to environment variables (it can hold the secret and the other settings, so a Docker or Compose secret can provide it), put a `sonda.toml` in `/data` or pass `--config /run/secrets/sonda.toml`; the variables the image sets still win over the file. - -## 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. | -| `library.auto_scan_minutes` | `SONDA_AUTO_SCAN_MINUTES` | `15` | How often, in minutes, Sonda looks at the folders of the libraries and scans the ones whose music changed (a song or a folder came, went or was renamed); `0` turns it off. Looking reads the names of the files and nothing else, so it is cheap for a NAS. A library is scanned at least once a day anyway, which finds a song that was tagged again where it stands. A folder that cannot be read (a NAS that is not mounted) is left alone. | -| `library.allow_delete` | `SONDA_ALLOW_DELETE` | `false` | Lets an admin delete the extra copy of a song from the music folders (see **Duplicates**). It is the one thing that makes Sonda write there, so it needs the folders mounted writable. A value that is not `true` or `false` is an error. | -| `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](#external-providers)). - -### 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 song. 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: - -```bash -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): - -```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 '{"email":"alice@example.org","password":"correct horse battery"}' - -LOGIN=$(curl -s -X POST $BASE/auth/login -d '{"email":"alice@example.org","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 song:** - -```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 `