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
5.6 KiB
Your music
Accounts, libraries, the scanner and streaming: what Sonda does with the files you already own.
-
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
unsupportedin 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 calledidentical(byte for byte).POST /library/duplicates/cleandeletes 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 setlibrary.allow_delete(orSONDA_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.
GETandHEADwithRangesupport, so players can seek. Opening or prefetching a stream does not record a listen.GET /tracks/{id}/peaksgives 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 answers202withRetry-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 answerswaveform_unavailable, and that is remembered too. A friend's song has no shape yet. -
ReplayGain. The scan reads the ReplayGain tags of each file (
REPLAYGAIN_TRACK_GAIN,REPLAYGAIN_ALBUM_GAINand 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 asreplay_gain(gains in decibels, peaks as a fraction of full scale), ornullwhen 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). -
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.