Compare commits

...
Sign in to create a new pull request.
Author SHA1 Message Date
e11ce89b21 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](ba10b8ef7b)), closes [#47](#47)
* **web:** talk to the Android app ([995f2e5](995f2e5ae0))

### Bug fixes

* **web:** show a restored queue on the lock screen ([a2d6d2a](a2d6d2a925))
2026-11-17 09:42:59 +00:00
d57fbe3ef1 Merge pull request 'Add an Android app' (#48) from feat/android-app into main
All checks were successful
release / release (push) Successful in 34s
release / base (push) Successful in 2s
release / image (amd64) (push) Successful in 3m21s
release / image (arm64) (push) Successful in 3m20s
release / manifest (push) Successful in 2s
2026-11-17 09:42:26 +00:00
tgiachi
ba10b8ef7b feat(android): add an Android app
A Capacitor shell that opens a Sonda server in a WebView. It asks for the
address of the server the first time and remembers it, trusts the certificate
authorities installed on the phone, and keeps a notification with the
controls so that the music goes on with the screen off.

Fixes #47
2026-11-17 10:41:39 +01:00
tgiachi
995f2e5ae0 feat(web): talk to the Android app
A WebView has no Media Session API. When the page runs inside the app it
tells the app what plays, as one message per change, and the app asks the page
back when a button of its notification is pressed. Settings has a Change server
link, shown only inside the app.
2026-11-17 10:41:39 +01:00
tgiachi
a2d6d2a925 fix(web): show a restored queue on the lock screen
A queue that came back after a reload was set before the player started to
follow the state, so the lock screen never heard about its song: no title and
no controls until the song changed, and a press of play told it nothing.
The lock screen is now told about the restored song, paused, where it was.
2026-11-17 10:41:39 +01:00
f6a3cd6b5e chore(release): 0.4.2 [skip ci]
## [0.4.2](https://git.kmalloc.org/squid/sonda/compare/v0.4.1...v0.4.2) (2026-11-17)

### Bug fixes

* **web:** make the seek bar fit the width of a phone ([6220238](6220238068)), closes [#45](#45)
2026-11-17 09:03:27 +00:00
23845391d4 Merge pull request 'Make the seek bar fit the width of a phone' (#46) from fix/seek-bar-fits-phone into main
All checks were successful
release / release (push) Successful in 36s
release / base (push) Successful in 2s
release / image (amd64) (push) Successful in 3m55s
release / image (arm64) (push) Successful in 3m56s
release / manifest (push) Successful in 2s
2026-11-17 09:02:52 +00:00
tgiachi
6220238068 fix(web): make the seek bar fit the width of a phone
The shape of the track has 120 thin bars. With a 2px gap and a 1px minimum
width each they need 358px, so on a phone the bar ran past the right edge of
the full-screen player, the page scrolled sideways and the play button was
off centre.

The bars now have no minimum width and a 1px gap on a phone; wide screens
keep the 2px gap.

Fixes #45
2026-11-17 10:02:30 +01:00
85a1f9dc8a chore(release): 0.4.1 [skip ci]
## [0.4.1](https://git.kmalloc.org/squid/sonda/compare/v0.4.0...v0.4.1) (2026-11-17)

### Bug fixes

* **web:** keep the controls of the full-screen player on screen on a phone ([a757743](a757743161)), closes [#43](#43)
2026-11-17 08:41:25 +00:00
755220d08a Merge pull request 'Keep the controls of the full-screen player on screen on a phone' (#44) from fix/player-controls-on-screen into main
All checks were successful
release / release (push) Successful in 34s
release / base (push) Successful in 2s
release / image (amd64) (push) Successful in 3m23s
release / image (arm64) (push) Successful in 3m21s
release / manifest (push) Successful in 2s
2026-11-17 08:40:52 +00:00
tgiachi
a757743161 fix(web): keep the controls of the full-screen player on screen on a phone
On a short phone screen the play, previous and next buttons were pushed
under the bottom edge and needed a scroll to reach.

- The seek bar and the controls sit in one block that sticks to the bottom
  on a phone, above the safe area; what comes next scrolls beneath it.
- The cover is capped by the height of the screen as well as its width.
- The sound picture is lower on a phone.

Wide screens keep the same layout as before.

Fixes #43
2026-11-17 09:40:38 +01:00
5eff98a639 chore(release): 0.4.0 [skip ci]
## [0.4.0](https://git.kmalloc.org/squid/sonda/compare/v0.3.0...v0.4.0) (2026-11-16)

### Features

* **web:** make Sonda feel like an app on a phone ([75a7898](75a7898c68))

### Documentation

* note that this repo moved to git.kmalloc.org ([ee31e0e](ee31e0ee7c))
2026-11-16 16:39:55 +00:00
95f9be70bd Merge pull request 'Make Sonda feel like an app on a phone' (#42) from fix/phone-app-feel into main
All checks were successful
release / release (push) Successful in 36s
release / base (push) Successful in 2s
release / image (amd64) (push) Successful in 4m7s
release / image (arm64) (push) Successful in 4m5s
release / manifest (push) Successful in 2s
2026-11-16 16:39:21 +00:00
tgiachi
75a7898c68 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.
2026-11-16 17:38:58 +01:00
tgiachi
ee31e0ee7c docs: note that this repo moved to git.kmalloc.org 2026-11-16 17:20:12 +01:00
43200dda05 chore(release): 0.3.0 [skip ci]
## [0.3.0](https://git.kmalloc.org/squid/sonda/compare/v0.2.0...v0.3.0) (2026-11-16)

### Features

* publish the Docker image for ARM as well ([b37e3db](b37e3db037))
2026-11-16 13:34:30 +00:00
2e194da4e3 Merge pull request 'Docker image for ARM as well' (#40) from feat/arm64-image into main
All checks were successful
release / release (push) Successful in 36s
release / base (push) Successful in 2s
release / image (amd64) (push) Successful in 3m11s
release / image (arm64) (push) Successful in 3m11s
release / manifest (push) Successful in 2s
2026-11-16 13:33:56 +00:00
tgiachi
b37e3db037 feat: publish the Docker image for ARM as well
The image is now made for amd64 and for arm64, and each tag (X.Y.Z, X.Y,
latest) points at both, so a Raspberry Pi or an ARM NAS pulls the right one.

- Dockerfile: the web and Go stages run on the builder and the Go program is
  cross-compiled (GOARCH from SONDA_ARCH or TARGETARCH); what the image needs
  besides the program (time zones, the user, the folders) is made in a stage
  of the builder, so the last stage runs no command and needs no emulation.
- release workflow: the runner has no Docker and cannot run ARM, and kaniko
  takes the base of every stage for one platform, so the arm64 image starts
  from the arm64 Alpine by digest (found at each release), kaniko builds one
  image per architecture, and crane sets the architecture of each and joins
  them under the tags.
2026-11-16 14:33:41 +01:00
dae5118354 chore(release): 0.2.0 [skip ci]
## [0.2.0](https://git.kmalloc.org/squid/sonda/compare/v0.1.0...v0.2.0) (2026-11-16)

### Features

* scan the libraries by themselves when their music changed ([89f1b52](89f1b5275a))
2026-11-16 12:09:51 +00:00
3490849837 Merge pull request 'Release by itself at every merge' (#38) from ci/semantic-release into main
All checks were successful
release / release (push) Successful in 38s
release / image (push) Successful in 3m44s
2026-11-16 12:09:16 +00:00
tgiachi
9905c4788f ci: pin the release tools to versions that work together
The preset of the commit messages in its 10th version cannot be read by the generator of
the release notes that semantic-release 25 comes with: use its 8th, and pin the
analyzer and the generator too. Found by a dry run before the first release.
2026-11-16 13:08:58 +01:00
tgiachi
a478c95536 ci: release by itself at every merge, with semantic-release
At every merge into main a workflow reads the Conventional Commits since the last release,
works out the version, writes CHANGELOG.md, tags the commit and makes the release on the
forge; when there is a release it builds the image from the tag and pushes it to
git.kmalloc.org/squid/sonda as X.Y.Z, X.Y and latest. The runner has no Docker, so the
image is built with kaniko.

The version is no longer written in the code: the release sets it (-X main.version) in the
Dockerfile and the Makefile, and a build that no release made says dev.
2026-11-16 13:07:17 +01:00
985bd3ed13 Merge pull request 'Scan the libraries by themselves when their music changed' (#36) from feat/auto-scan into main 2026-11-16 12:05:32 +00:00
tgiachi
89f1b5275a feat: scan the libraries by themselves when their music changed
Every 15 minutes (library.auto_scan_minutes, SONDA_AUTO_SCAN_MINUTES, 0 turns it off)
Sonda takes the signature of each library, a hash of the names of everything in it folder
by folder, which costs only the names of the files and so suits a NAS that sleeps. A
library whose signature changed (a song or a folder came, went or was renamed) is
scanned the usual way; every library is also scanned at least once a day, to find a song
tagged again where it stands.

It does not scan while another scan runs, tries again at the next look when a scan failed,
leaves alone a folder that cannot be read (a NAS that is not mounted), and ignores the
housekeeping folders of a NAS.
2026-11-16 13:05:09 +01:00
1b58f8412c Merge pull request 'Docker image published: say it in the README' (#34) from docs/published-image into main 2026-11-16 11:52:18 +00:00
tgiachi
482644a7bf docs: the Docker image is published
The image is on the registry of git.kmalloc.org: git.kmalloc.org/squid/sonda:latest and
a tag with the commit. The README says so, with the commands for pulling and running
it, and compose.yaml says how to use it instead of building.
2026-11-16 12:51:50 +01:00
ab05ec081f Merge pull request 'Radio stations in apps only when I ask' (#32) from feat/radio-in-apps-setting into main 2026-11-16 11:33:54 +00:00
tgiachi
ed32aac228 feat: the radio stations are in the apps only when the person asks
A new setting, radio_in_apps, off until the person turns it on (Settings, Apps and
devices, or PATCH /me/settings). With it off, the list of playlists of an OpenSubsonic
app is only the playlists of the person, and a station asked for by id is not found.
With it on, the stations come as playlists called Radio · Rock.

- migration 0036: user_settings.radio_in_apps
- usersettings, the settings API and the OpenAPI spec have the new field; the PATCH
  now keeps each setting apart (naming one no longer sets the other)
- Settings has a switch
2026-11-16 12:33:09 +01:00
8e278f04c2 Merge pull request 'Radio in the web app' (#30) from feat/radio-web into main 2026-11-16 11:19:29 +00:00
tgiachi
0b3bf8d49f feat: a Radio page, endless play, and the radio of an artist
The Radio page shows the stations Sonda makes by itself, in groups (made for you,
by genre, by decade). A click starts one and the player knows it is a radio: before
the queue runs out it asks the server for other songs of the same station and puts
them at the end (not the ones already queued; a station so small that all its songs
are queued starts them over), one question at a time, never twice within two seconds,
and again after ten when the server cannot answer. Every artist has a Start radio
button. The full-screen player says which station plays.

- Radio item in the menu (Library group), on the Library page and in the phone tab
- player store: radio and appendTracks; useRadioRefill
2026-11-16 12:18:15 +01:00
f146a94368 Merge pull request 'Radio stations that Sonda makes by itself' (#29) from feat/radio-stations into main 2026-11-16 11:14:16 +00:00
tgiachi
407b20334a feat: radio stations that Sonda makes by itself
Stations made from the music, random and without end, with nothing to set up: the
mixes the listener has (genres, favourites, rediscover, new to you), everything,
one for each decade that has 30 songs by 4 artists, and the radio of an artist (their
songs, four times as likely, and the songs of the two genres most of theirs have).
Every time a station is asked for it picks other songs, with the same weights as the
mixes (taste, hearts, nothing skipped lately).

- mixes.Service.Radios and Radio; Filter has All and years, the store has Decades
- GET /radio and GET /radio/{id}, in the OpenAPI spec
- OpenSubsonic: each station is a playlist (rd-<id>, "Radio · Rock") that has other
  songs every time it is opened, for apps that cannot play a radio that never ends
2026-11-16 12:13:55 +01:00
e37f1165ae Merge pull request 'OpenSubsonic: getUser, so that apps can log in' (#26) from fix/opensubsonic-getuser into main 2026-11-16 10:51:04 +00:00
tgiachi
d6064763e7 fix: OpenSubsonic apps can log in: getUser and the calls that follow
Feishin asks getUser right after the login and failed on the missing user. getUser
now says who the login is, with the roles of an app (play, download, playlists,
covers; never admin), and only about the person of the login.

Also answered with nothing, because apps ask them straight away: getArtistInfo(2),
getAlbumInfo(2), getTopSongs, getSimilarSongs(2), getLyrics, getLyricsBySongId,
getInternetRadioStations, getScanStatus, startScan and the play queue calls, and
getStarred, the older way to ask for the favourites.

A call that is not known is now in the server log with its name.
2026-11-16 11:50:44 +01:00
e77b014437 Merge pull request 'Search with a preview while I type' (#24) from feat/search-preview into main 2026-11-16 10:43:07 +00:00
tgiachi
4052ab8ce1 feat: a search box with a preview of what matches
A box on top of every page except the search (on a phone the Search tab does
this) opens a list while the person types: up to 3 artists, 3 albums and 5 songs,
each with its picture. A click opens an artist or an album and plays a song; the
arrows move through the list, Enter opens what is marked, or with nothing marked
the page with all the results, and Escape closes it. The last row, always in
sight, opens all the results.

The pictures of artists are not asked for: asking makes the server look the
artist up at a provider, which a list of whatever matched a few letters should
not do.
2026-11-16 11:33:23 +01:00
ea2478b786 Merge pull request 'Square the corners of the web app' (#22) from feat/sharp-corners into main 2026-11-16 10:28:24 +00:00
tgiachi
9bf6fd0039 style: square the corners of the web app
The base radius goes from 8 px to 2 px, which squares buttons, fields, dialogs,
covers and cards at once. The things that were made round on purpose are square
now too: the play button, the switch and its knob, the chip of a friend, the bars
of the statistics, the tab marker, the dot of a request, and the volume slider
(a thin track and a bar for a knob). The rings of a missing cover stay round:
they are the drawing of Sonda.
2026-11-16 11:27:18 +01:00
c5f548e74e Merge pull request 'Favourites teach Sonda my taste' (#20) from feat/favorites-signal into main 2026-11-16 10:08:43 +00:00
tgiachi
ca5cbbf088 feat: favourites teach Sonda my taste
A heart adds to what the listening says of an artist: a favourite artist counts
as much as three complete listens, a favourite album 1.5 for its album artist and
a favourite song 1 for each of its main artists, at most 6 for one artist, without
fading with time. An artist hearted but never played is liked, with no listens.
That feeds Discover, the mixes and the smart playlists that use the taste, and
GET /me/taste.

In the mixes of what the listener likes (genre mixes, Your favourites,
Rediscover) a hearted song is wanted 1.5 times as much and a song on a hearted
album 1.25 times. New to you is not changed.
2026-11-16 11:08:20 +01:00
84b61ce6aa Merge pull request 'Favourites in the web app' (#18) from feat/favorites-web into main 2026-11-16 09:56:37 +00:00
tgiachi
a93260af05 feat: favourites in the web app
A heart on every song, album and artist, in the player bar and the full-screen
player, and a Favourites page with the songs, albums and artists, newest first.
The heart changes at once and goes back if the server refuses. Hearts are only
for music of this server: a friend's song has none.

- FavoriteButton, useIsFavorite and useSetFavorite
- /favorites page, a Favourites item in the Library group of the menu, on the
  Library page and in the phone Library tab
2026-11-16 10:56:12 +01:00
f7c24fa6f4 Merge pull request 'Favourites in the API and in OpenSubsonic apps' (#17) from feat/favorites-api into main 2026-11-16 09:51:37 +00:00
tgiachi
74f683d26e feat: favourites of songs, albums and artists, in the API and in apps
A person can mark songs, albums and artists as favourites. They are theirs
alone: never shown to a friend, never sent anywhere. Only what can be played is
listed.

- migration 0035 favorites, internal/favorites, storage.FavoritesRepo
- PUT/DELETE /me/favorites/{kind}/{id}, GET /me/favorites/{kind} and
  GET /me/favorites/ids, in the OpenAPI spec
- catalog.Filter IDs now also reads artists by id
- OpenSubsonic: star, unstar, getStarred2, the starred date on songs, albums and
  artists, and getAlbumList2 of type starred
2026-11-16 10:51:07 +01:00
17c134ef8b Merge pull request 'OpenSubsonic: playlists and listens' (#14) from feat/opensubsonic-playlists into main 2026-11-16 09:22:34 +00:00
tgiachi
a0dc4458ef feat: OpenSubsonic playlists and listens
Apps can use the playlists of a person and report what they listened to.

- getPlaylists, getPlaylist, createPlaylist (with songs, or in place of an
  existing one), updatePlaylist (name, comment, songs to add, places to remove),
  deletePlaylist: the same playlists as the web app
- scrobble records a complete listen once however many times an app tries
  again, and shares it on Mastodon when the person connected it; a now playing
  message records nothing; getNowPlaying answers with nothing
- README section on connecting other apps
2026-11-16 10:22:11 +01:00
2cb67b1bdc Merge pull request 'OpenSubsonic: playback, covers, lists and search' (#13) from feat/opensubsonic-media into main 2026-11-16 08:45:30 +00:00
tgiachi
ccee5e8719 feat: OpenSubsonic playback, covers, lists and search
Apps can play and browse: stream and download send the original file (Range,
HEAD), getCoverArt serves the cover of an album, an artist or the album of a
song (300 pixels or less is the small one), getAlbumList2 knows every kind of
list, getRandomSongs and getSongsByGenre list songs, search3 finds artists,
albums and songs, and the starred calls answer with nothing so apps do not break.

- catalog.Filter has IDs to read albums and songs by id
- storage.SubsonicRepo answers the album and song lists (random, newest,
  frequent, recent, by name, by artist, by year, by genre)
2026-11-16 09:45:07 +01:00
90d1b7949f Merge pull request 'OpenSubsonic: core (auth, system, browsing)' (#12) from feat/opensubsonic-core into main 2026-11-16 08:32:37 +00:00
tgiachi
1ae8e77d81 feat: OpenSubsonic core, login with a device password
/rest speaks the OpenSubsonic API (Subsonic 1.16.1) so that other apps can browse
the music of a server. A call logs in with the password of a device: an apiKey,
Subsonic's token (u, t, s) or the password itself (u, p). The account password is
never accepted there.

- devices: ByKey, ByToken, ByPassword and the note of last use
- opensubsonic package: JSON and XML answers, ping, getLicense,
  getOpenSubsonicExtensions, tokenInfo, getMusicFolders, getArtists, getArtist,
  getAlbum, getSong, getGenres
- storage.SubsonicRepo: year, genres, size, bitrate, suffix and added date
2026-11-16 09:32:11 +01:00
32214127c9 Merge pull request 'A password for each app or device' (#11) from feat/device-passwords into main 2026-11-16 08:15:38 +00:00
tgiachi
010f2e5057 feat: a password for each app or device
A person can make a password for each app that connects to their server, in
Settings, Apps and devices. The secret is shown once, can be taken back, and
is for the music API of other apps only: it cannot sign in or change the
account. Secrets are kept sealed (AES-256-GCM, key derived from the jwt secret)
because token login needs them in clear, and a hash finds a device by its key.

- migration 0034 device_passwords (sqlite, postgres)
- internal/devices service, storage repo
- GET/POST /me/devices, DELETE /me/devices/{id}, in the OpenAPI spec
- Settings section with copy and remove
2026-11-16 09:15:25 +01:00
9451765861 Merge pull request 'Show how the genres I listen to changed over time' (#6) from feat/genre-timeline into main 2026-11-15 17:19:26 +00:00
tgiachi
08c83c948f feat: how the genres I listen to changed over time
- GET /stats/listening has genre_timeline: the share of the five biggest genres, of the smaller ones and of the songs with no genre, for each year, or for each month when all the listens are in one year, in the listener's time zone; years and months with no listen are empty
- web: a stacked column chart on the Statistics page, coloured in tints of the colour of this server so it follows every theme, with a legend; left out when there is only one column
- README: the new field
2026-11-15 18:17:33 +01:00
c52386f335 Merge pull request 'A statistics page' (#4) from feat/statistics into main 2026-11-15 17:06:18 +00:00
e6af9a118e Merge pull request 'Show the version of Sonda' (#3) from feat/show-version into main 2026-11-15 17:05:46 +00:00
tgiachi
d51f155a4d feat: a statistics page
- GET /stats/library: the songs that can be played with their artists, albums, length and size, the files by format, the share of each genre and decade
- GET /stats/listening: listens, time listened, songs and artists, listens by year, hour and weekday in the listener's time zone, top artists and songs, the share of each genre, for all time or a period
- a song with several genres is split between them, so the shares add up
- web: a Statistics page in the Your listening group, with bars made of CSS and four periods
- the MP3 files, which the scanner calls mpeg, are shown as MP3
- README: the two endpoints
2026-11-15 17:55:43 +01:00
tgiachi
0742ee88a9 fix: the new module path in the build info file 2026-11-15 17:32:15 +01:00
tgiachi
14710c3a55 Merge remote-tracking branch 'origin/main' into feat/show-version 2026-11-15 17:31:25 +01:00
tgiachi
a880b87a9e chore: move the module path to git.kmalloc.org/squid/sonda
Migrating hosting from Codeberg to git.kmalloc.org. Renames the
module path in go.mod, every internal import, and the OCI image
source label in the Dockerfile. Build and full test suite verified
green after the rename.
2026-11-15 17:30:29 +01:00
tgiachi
00e5254fde feat: show the version of Sonda
- GET /version (signed-in users only) answers the version and, when the binary knows it, the commit it was built from and whether the files had uncommitted changes
- the commit is read from the build info Go records in a git checkout, so no build flag is needed
- the side menu shows the version under the privacy line, and Settings has an About section with it
- the menu's own requests (friends, version) are not counted as requests of an admin page in the Shell tests
2026-11-15 17:30:14 +01:00
squidd
69c85a7b52 Merge pull request 'Brand pass, part two: the app icons and the wording' (#200) from chore/brand-pass-2 into main 2026-11-15 17:15:52 +01:00
tgiachi
c4982d85c3 chore: brand pass, part two
- the favicon and the four PNG icons are in the colours of the current theme (#08161d ground, #37e0c2 wave)
- IT: Rimuovi for every remove, Elimina where a file is deleted
- EN: Create (not Make) for an invite, a playlist and a token; '{{genre}} mix' in lower case
- phone tabs: the Friends bar is amber only when Friends is the open tab
- README: songs in the prose, tracks only in paths and fields
- a short description in the page head
2026-11-15 17:14:51 +01:00
squidd
9c636fa65a Merge pull request 'A brand pass: one wording for the same thing' (#198) from chore/brand-pass into main 2026-11-15 17:10:45 +01:00
tgiachi
32dd307535 chore: a brand pass, one wording for the same thing
- the provider settings are named where they are (Admin → Providers), not 'the server settings'
- EN: deleting duplicates says delete, 'song' everywhere, 'at least once' for the forgotten songs, 'email', 'photos' for artist pictures, singular and plural for the history months
- IT: impersonal like the rest of the text, 'niente' not 'nulla', 'mandato' for what is sent to Lidarr, 'playlist smart', 'importazione'
- type: nothing under 13px, the federation pages use the scale, dialog titles are bold like every heading
- no shadow on the update notice
- web manifest colours are the ones of the current theme
- README: 'turned on', 'email'
2026-11-15 17:09:37 +01:00
squidd
8be9e93551 Merge pull request 'Fold the side menu to a strip of icons' (#196) from feat/sidebar-collapse into main 2026-11-15 15:11:04 +01:00
tgiachi
78f3f7ec9e feat(web): fold the side menu to a strip of icons
- a button next to the logo folds the menu to icons and opens it again
- folded, each link keeps its name for a screen reader and shows it as a tooltip, the group names stay for a screen reader, the logo becomes the mark
- the choice is kept in this device's storage
- no button on a phone, where the tabs replace the menu
2026-11-15 15:09:58 +01:00
squidd
0fb57fe4f0 Merge pull request 'An icon next to each link in the side menu' (#194) from feat/sidebar-icons into main 2026-11-15 15:06:39 +01:00
tgiachi
3512f0cbaa feat(web): an icon next to each link in the side menu
- each link has a lucide icon in place of the dot; the icon of the open page is the colour of this server, Friends keeps the friend colour
- the group headings line up with the words again
- tests: every link has a decorative icon, no two pages share one
2026-11-15 15:05:17 +01:00
squidd
fee06e2bb9 Merge pull request 'A page of the artists I sent to Lidarr, and whether they arrived' (#192) from feat/lidarr-requests into main 2026-11-15 12:33:31 +01:00
tgiachi
af933ad9ea feat(lidarr): a page of the artists I sent to Lidarr, and whether they arrived
Sonda kept no record of what an admin sent to Lidarr. Each send is now kept
(migration 0033, lidarr_requests), once for each artist, with the first date.
GET /lidarr/requests lists them newest first and says for each whether its
music is in the library: it is noticed when the list is read, by the artist
that was sent or by an artist of the same name that a scan made, and the day
it first was is kept.

The web app has a Requests page for admins, under Discover in the menu and on
Home on a phone, with the waiting and the arrived artists apart.
2026-11-15 12:32:29 +01:00
squidd
d31d4da1bd Merge pull request 'Organise the menu in groups' (#190) from feat/sidebar-groups into main 2026-11-15 12:17:14 +01:00
tgiachi
b2549336ba feat(web): the menu in groups
The left menu was a flat list of 14 links. It is now in groups, in the order
of what a person does: find (Home, Search, Discover), the library (Artists,
Albums, Songs, Playlists, Smart playlists, Mixes), their listening (History,
Import) and Friends, with Settings and Admin at the foot. Only the library and
the listening have a quiet heading; space tells the groups apart.

The phone follows it: the Library page lists the same rows in the same order
with a "Your listening" section, Discover (which has no tab) is a row at the
end of Home, and More keeps Settings and Admin.
2026-11-15 12:14:57 +01:00
squidd
2b6e80fda6 Merge pull request 'Browse my listening history by year and month' (#188) from feat/history into main 2026-11-15 12:08:08 +01:00
tgiachi
9f63121028 feat(history): browse my listening by year and month
GET /listens/months counts the listens that count in each calendar month,
newest first, in the time zone the client sends (the zone database is built
into the binary). GET /listens takes from and until to read one month, and
each listen now names its artists.

The web app has a History page: a button for each year with its listens, the
months of the year as bars, and the listens of the chosen month a day at a
time, with the choice kept in the address.
2026-11-15 12:07:19 +01:00
squidd
9ce7beb42d Merge pull request 'Suggestions learned from my own listening' (#186) from feat/suggestions into main 2026-11-15 11:10:26 +01:00
tgiachi
7c961028bb feat(discover): suggestions learned from my own listening
A new model (internal/affinity) splits my listening into sittings (plays less
than 30 minutes apart) and links the artists that are often played in the same
sitting. It is built from my listening events and from the plays of artists I
have no music of that an import kept, on my server, with no provider, and is
built again when plays are added (migration 0032 keeps it as a cache).

GET /me/suggestions gives two lists, each artist with the artists it goes
with: the ones I have and did not play for two months, and the ones I played
at least three times and have no music of. It needs discover_from_listening.
POST /me/suggestions/wishlist puts an artist I played on my wishlist by name.
Discover has a "From your listening" tab for both lists.
2026-11-15 11:09:19 +01:00
squidd
7b18478fe4 Merge pull request 'Keep the artist and the time of plays of artists I do not have' (#185) from feat/outside-plays into main 2026-11-15 10:51:26 +01:00
tgiachi
3ba087bcc5 feat(import): keep the artist and the time of plays of artists I do not have
The plays of songs that are not in the library were only counted. Now, when
such a play counts as listened (not a skip, long enough), its artist and its
time are kept in a new table (migration 0031, outside_plays), so a model can
later learn which artists are played together, also those not in the library.
No title, album, IP address, country or platform is stored. The same play is
kept once however many times the export is imported, and the report says how
many were kept (history.kept_outside).
2026-11-15 10:50:29 +01:00
squidd
01cbab21be Merge pull request 'A page for imports, with the numbers of each one kept' (#182) from feat/import-page into main 2026-11-15 10:34:53 +01:00
tgiachi
aa4883b955 feat(import): an Import page, with the numbers of every import kept
The report of an import used to be shown once in Settings and lost. Each
import is now stored (migration 0030, spotify_imports) as the report in
JSON, and GET /me/import/spotify lists the past ones, newest first.
POST /me/import/spotify answers with the same shape plus id and created_at.

The web app gets an Import page (menu, More tab) with the form and one card
for each past import: plays read, added, already there, not in the library,
the playlists it made and the artists that are missing. Settings only links
to it. An import that finds nothing is not kept, and a report that cannot be
stored is still returned to the person who asked.
2026-11-15 10:34:12 +01:00
squidd
83b578ea4c Merge pull request 'Import my Spotify history and playlists' (#180) from feat/spotify-import into main 2026-11-14 16:27:02 +01:00
tgiachi
c08a234159 feat(import): bring my Spotify history and playlists in
I want my listening history and my playlists from Spotify in Sonda, so that Mixes, Discover and the smart playlists know what I listened to before.

- POST /me/import/spotify takes the zip of a Spotify data export, or the JSON files in it (extended streaming history, the older StreamingHistory files, the playlists), as a multipart form. A request may be up to 512 MB; the zip is limited in how much it may inflate and how many files it may hold, and only the history and playlist files are opened.
- Everything is read on the server and nothing is sent anywhere. The files are not kept, and of each play only the song, artist, album, time and how it ended are read: never the IP addresses, the country or the platform.
- A play is matched to a song of the library by artist and title (no case, accents or punctuation; a "Remastered" note on either side; any credited artist; a compilation by its album). A match is recorded as a listen at the time of the play: complete, skip or play. Nothing is posted to Mastodon.
- Importing the same files again records nothing twice, and the same play in the two shapes of history file is counted once. One import per person at a time.
- A playlist becomes a playlist of mine with the songs that were found; one with a name I already have is left alone, and one with none of its songs found is not made.
- The report counts what was added, what was already there and what is not in the library, and lists the missing artists, most played first.
- Settings gets an Import from Spotify section; the API client can send files.
- English and Italian.
2026-11-14 16:25:58 +01:00
squidd
2bc74b2d26 Merge pull request 'Play every song at a similar volume with ReplayGain' (#178) from feat/replaygain into main 2026-11-14 16:03:40 +01:00
tgiachi
a92326c1b4 feat(player): play every song at a similar volume with ReplayGain
I want songs from different albums to play at about the same loudness without touching the volume.

- The scan reads REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_ALBUM_GAIN and the two peaks from each file, offline, and keeps them on the file (migration 0029, SQLite and PostgreSQL). A tag that makes no sense (not a number, more than 60 dB) is left out. Files indexed before have none until a full rescan.
- A track in the API carries them as replay_gain (null when its first playable file says nothing).
- The web player levels each song with them: the sound passes through a gain node, so a quiet song can be raised too, but never so much that its peak would clip (and never more than 12 dB when there is no peak). Without Web Audio the element is turned down instead.
- A new Playback section in Settings chooses song by song (default), album by album or off; the choice stays on the device.
- README: the ReplayGain entry, and the old line that said the year was not in the index is removed.
- English and Italian.
2026-11-14 16:02:23 +01:00
squidd
e9f85c2f39 Merge pull request 'Attiva and disattiva in the Italian texts' (#176) from fix/italian-on-off into main 2026-11-14 11:02:09 +01:00
tgiachi
d29d824f56 fix(i18n): attiva and disattiva instead of accendi and spegni
Providers, federation, Lidarr and Discover now say attiva, attivo, disattivato in Italian, which reads better for settings than accendi and spegni.
2026-11-14 11:00:44 +01:00
squidd
a507741460 Merge pull request 'A pass over the Italian texts' (#174) from fix/italian-pass into main 2026-11-14 10:52:54 +01:00
tgiachi
8263e0ca43 fix(i18n): a pass over the Italian texts
Rifai tutto sounded wrong, and a number of other texts were calques from English or used different words for the same thing.

- Riesegui tutto instead of Rifai tutto.
- brano everywhere instead of canzone, eliminare instead of cancellare, Successivo and Precedente in the player, one kind of quotes and of apostrophe.
- Fixes to sentences with the wrong meaning or grammar: removing a friend, the invite hint, the jobs that need a provider turned on, the plural of what a purge removes, the Duplicates texts.
2026-11-14 10:52:15 +01:00
squidd
f3ab8f0c8e Merge pull request 'Show the albums added last on Home' (#172) from feat/recently-added into main 2026-11-14 10:29:41 +01:00
tgiachi
246cdc63d3 feat: Recently added on Home, with a newest-first order for albums
I can now see on Home what I added to the library lately.

- GET /albums takes sort=recent: the albums added last first, by the date of the newest file of the album that is not missing, then the newest album. The default stays by title and any other value is invalid_input.
- The albums shelf on Home is Recently added and asks for that order; See all leads to /albums?sort=recent, which the albums page understands.
- English and Italian.
2026-11-14 10:29:08 +01:00
squidd
2f1a86dedb Merge pull request 'Smart playlists by the year a song came out' (#170) from feat/smart-year into main 2026-11-14 10:20:24 +01:00
tgiachi
d3695d00d6 feat(smart): smart playlists by the year a song came out
I can now ask for songs from a year to a year, for example the eighties.

- The year is read from the tags of each file (the original date first, then the date) and kept on the track: migration 0028 adds tracks.year (SQLite and PostgreSQL).
- Two new rules, min_year and max_year, both included and checked (1000 to 2999, the first not after the second). The index answers them. A song with no year never matches.
- Files indexed before have no year until a full rescan reads their tags again; the editor and the API description say so.
- The smart playlist editor gets From year and Up to year, and the rules are described in words.
- English and Italian.
2026-11-14 10:19:39 +01:00
squidd
6028d8e686 Merge pull request 'Say in Settings when Mastodon no longer accepts my token' (#168) from feat/mastodon-revoked-token into main 2026-11-14 10:04:56 +01:00
tgiachi
a7a258464b feat(mastodon): say in Settings when the instance no longer accepts the token
When the instance refuses the token on a post (it was revoked or expired), the account now remembers it: GET /me/mastodon says problem: token_refused and nothing is posted until I connect again with a new token.

- migration 0027 adds mastodon_accounts.problem (SQLite and PostgreSQL).
- Only a refused token marks the account; an instance that is down does not.
- Saving the account again clears the problem.
- Settings shows the warning and the form with the instance already filled in, next to Disconnect.
- English and Italian.
2026-11-14 10:04:07 +01:00
squidd
2962698baa Merge pull request 'A Duplicates section in the admin area' (#166) from feat/admin-duplicates into main 2026-11-14 09:53:28 +01:00
tgiachi
4ede6d4118 feat(web): a Duplicates section in the admin area
I can now see the songs that are in more than one file and delete the extra copies from Admin.

- A table of the copies of each song (album, format, bitrate, size, length) with the copy to keep already chosen and changeable.
- The check that reads the files, with a question first, progress, Stop, and the result of the last run; the groups are read again when it ends.
- 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. It stops at the first refusal and says what was already deleted.
- With deleting off everything is visible and the delete buttons are disabled, with the reason.
- English and Italian.
2026-11-14 09:52:57 +01:00
squidd
58a596c88e Merge pull request 'Post what I listen to on Mastodon, if I connect an account' (#165) from feat/mastodon-post into main 2026-11-13 21:59:41 +01:00
tgiachi
0dc7782028 feat: post what I listen to on Mastodon, if I connect an account
In Settings a person connects their Mastodon account: the address of their instance and an access token that can only write posts. Nothing is connected by default, and disconnecting forgets the token.

- When a track of this server counts as a listen, it is posted as an unlisted status: title, artists, album and #NowPlaying, with no link. Music of a friend is never reported as a listen, so it is never posted. At most one post a minute for each person, in the background, with a bounded queue.
- PUT, GET and DELETE /me/mastodon. The token is never sent back.
- The address of the instance is typed by a person, so it must be a domain name on https, and the client never connects to a private, loopback or link-local address (checked on the address it really dials, so a name that points inside is no way in), never follows a redirect, ignores proxy settings and reads at most a megabyte.
- New table mastodon_accounts (SQLite and PostgreSQL) that goes with the account.
- README: the feature, and the credit for butterchurn and its presets.
2026-11-13 21:59:03 +01:00
squidd
7aa822f6bb Merge pull request 'The player can draw the sound as bars, an oscilloscope or Milkdrop' (#163) from feat/visualizers into main 2026-11-13 21:33:08 +01:00
tgiachi
1d19e014a3 feat(web): choose how the player draws the sound: bars, oscilloscope, Milkdrop
Settings has one choice, kept on the device, in place of the spectrogram switch: Spectrogram, Bars, Oscilloscope, Milkdrop or None. Whoever had turned the spectrogram off stays on None.

- Bars: the classic spectrum, with a cap on each bar that waits and falls.
- Oscilloscope: the wave of the sound as it plays.
- Milkdrop: butterchurn and its presets fill the background of the full-screen player behind a veil. They are loaded only when chosen, change by themselves every 25 seconds or with a button, and give way to the spectrogram where WebGL is missing or the system asks for less motion.
- The bar of the player keeps a small picture; for Milkdrop it is the spectrogram.
- The analyser also hands over the wave and the audio node.
2026-11-13 21:32:10 +01:00
squidd
f25d8f0dcf Merge pull request 'A switch in Settings to turn the spectrogram off' (#161) from feat/spectrogram-toggle into main 2026-11-13 19:53:17 +01:00
tgiachi
ce3c8598c8 feat(web): a switch in Settings to turn the spectrogram off
The choice stays on the device, like the theme. When it is off the player
draws nothing and the spectrogram is not there at all.
2026-11-13 19:52:36 +01:00
squidd
f17d9eb66d Merge pull request 'The seek bar shows the waveform of a friend's track' (#159) from feat/friend-waveform into main 2026-11-13 19:47:33 +01:00
tgiachi
7243fe7a04 feat: the seek bar shows the waveform of a friend's track
A friend's server works out the peaks of a track in a shared library and gives
them to a signed friend (GET /peer/tracks/{id}/peaks). This server asks for them
and passes them on to the listener after checking them: 1 to 1000 levels from 0
to 255, as many as the count says (GET /friends/{friend}/tracks/{id}/peaks). The
player uses it for a friend's track, so its bar is no longer flat.
2026-11-13 19:46:37 +01:00
squidd
1736fc5a29 Merge pull request 'The full-screen player fits the phone' (#157) from feat/ui-phone-player into main 2026-11-13 19:28:48 +01:00
tgiachi
3647c88723 feat(web): the full-screen player fits the phone
Close on the left, the friend in the middle and a queue button on the right;
a smaller cover, a smaller spectrogram and the controls spread across the
width, so they are in view without scrolling. The volume stays off a phone,
which has its own buttons. For a friend's track a note says the audio passes
through this server and the friend does not see who listens.
2026-11-13 19:28:17 +01:00
squidd
9c2c5ba884 Merge pull request 'Mixes as tiles of colour with the name big' (#155) from feat/ui-mixes into main 2026-11-13 19:22:39 +01:00
tgiachi
226ee72900 feat(web): mixes as tiles of colour with the name big
Each mix is a tile with its name and a note on where it comes from (my
listening or the genres of my files), in a colour that is always the same for
that mix. The tones of the missing covers are shared with the tiles.
2026-11-13 19:21:48 +01:00
squidd
d207787575 Merge pull request 'The Federation admin page like the mockup' (#153) from feat/ui-federation into main 2026-11-13 19:18:06 +01:00
tgiachi
69ec2abc1c feat(web): the Federation admin page like the mockup
Parts divided by lines instead of stacked blocks, the key of this server big
and in groups of four, the state of a friend as a pill in the friend colour,
two columns for the settings, the invites and the limits.
2026-11-13 19:17:04 +01:00
squidd
7a9aeab7d1 Merge pull request 'A bar of tabs at the bottom of the phone' (#151) from feat/ui-phone into main 2026-11-13 17:59:30 +01:00
tgiachi
35dabf48ef feat(web): a bar of tabs at the bottom of the phone
Home, Search, Library, Friends (only when there is a friend) and More,
under the player. The menu on the left stays on wide screens; on a phone
only the logo is left on top. New Library and More pages list the places
that do not fit in the bar.
2026-11-13 17:58:50 +01:00
squidd
cacb30d5ae Merge pull request 'Pages without boxes: rows, underlined tabs, one title style' (#149) from feat/ui-pages into main 2026-11-13 17:55:19 +01:00
tgiachi
1a03f70059 feat(web): pages without boxes: rows, underlined tabs, one title style
The fourth piece of the new look, first part.

- One component for the title of a page, larger than before; the greeting of
  Home is larger still.
- The cards of artists, albums, mixes, playlists and smart playlists are the
  picture and the words: no panel, no hover box, they still lift.
- The lists of the admin area (libraries, users, friends), of Discover (the
  suggestions and the wishlist) and of Friends are rows separated by a line.
  The providers, the jobs and the costs are sections divided by a line.
- The tabs of Discover, Admin and the music of a friend are underlined, in the
  colour of this server, or in the friend colour for a friend.
- The page of a friend has a band in the friend colour at its top edge.
- An artist with no picture is a quiet tile with its initial, not a loud one.
2026-11-13 17:54:25 +01:00
squidd
17a37b11f0 Merge pull request 'The seek bar shows the waveform of the track' (#147) from feat/ui-waveform into main 2026-11-13 17:36:10 +01:00
tgiachi
bfa3e6e458 feat: the seek bar shows the waveform of the track
The seek bar of the player is the shape of the track, with the part already
heard in colour, as in the approved mockups.

- GET /tracks/{id}/peaks gives 120 levels from 0 to 255 (the loudest part is
  255 whatever the volume). The server finds them by decoding the file, MP3 with
  go-mp3 and FLAC with eaburns/flac, both in pure Go. It 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 (migration 0025), worked out again
  if the size or the date of the file change, one track at a time so that a NAS
  is not kept busy, and a file that cannot be decoded is remembered as such. A
  track deleted while its file is being decoded is not an error.
- The seek bar of the player bar and of the full-screen player draws the shape
  and asks again every few seconds until it is there. Until then, and for a
  friend's track, which has none, the bar is flat. The heard part is teal, or
  the friend colour. It is still a native range input, 44 pixels high in the
  bar.
- OpenAPI path and schema, contract test, tests with real MP3 and FLAC files,
  and a real server checked: a 4-minute MP3 is ready in about a second and a
  half, a 12 MB FLAC in three, and asking again takes a millisecond.
2026-11-13 17:35:00 +01:00
squidd
f99d2bddcc Merge pull request 'New look of the web app, part 2: the player with a live spectrogram' (#145) from feat/ui-player into main 2026-11-13 17:19:29 +01:00
tgiachi
fdf1ebfabc feat(web): new look, part 2: the player with a live spectrogram
- A spectrogram drawn in the browser from the sound being played: the last
  seconds, time running to the right and ending now, low notes at the bottom,
  brighter where there is more energy. Small in the player bar, large in the
  full-screen player. It works the same for a friend's track, since its audio
  comes through this server.
- It is drawn only while something plays and the page is in view, and with
  reduced motion it is redrawn four times a second; where the browser has no
  Web Audio it stays empty and nothing else changes.
- The play button is round, in the colour of this server and in the friend
  colour for a friend's track.
- The bar and the full-screen player show the name of the friend whose server
  a track comes from, and nothing for this server's own music.
2026-11-13 17:17:57 +01:00
squidd
adc3aa2832 Merge pull request 'New look of the web app, part 1: palette, Figtree, menu, covers, controls' (#143) from feat/ui-foundation into main 2026-11-13 17:13:19 +01:00
tgiachi
945aaf1a05 feat(web): new look, part 1: palette, Figtree, menu, covers and controls
The first piece of the new look of the web app.

- The Sonda theme takes the new palette (a deep blue ground, a lighter tone
  for panels instead of shadows, teal for the action). Every theme gets a
  --friend colour for what comes from another Sonda server, checked for
  contrast on the page and on a panel and for a hue that is not the primary
  one.
- Figtree is the only font; Fraunces is gone, also from the full-screen
  player.
- The menu is words and a dot: the dot of the open page is the colour of this
  server, and the dot of Friends is always the colour of what comes from
  elsewhere. There is nothing to fold, so the fold button and its setting are
  removed.
- The shell is flat: the menu has a line on its right, the page has no panel
  around it, the player is a band under everything.
- A missing cover is the rings of Sonda on a colour taken from the album, the
  same one every time; a friend's album gets another colour than this
  server's album with the same id.
- The switch is a pill with a round knob and the outline button is a line.
2026-11-13 17:11:59 +01:00
squidd
9b81b6385a Merge pull request 'Federation: play a friend's music and show its covers through this server' (#141) from feat/federation-play into main 2026-11-13 16:13:18 +01:00
tgiachi
7f38ae038e feat(federation): play a friend's music and show its covers through this server
A listener can now play the music of a friend from the web app.

- GET /friends/{friend}/tracks/{id}/stream and /friends/{friend}/albums/{id}/cover,
  in the group that accepts the access token in the query, like the local ones.
  This server asks the friend with a signed request and passes the bytes on,
  forwarding Range and the conditional headers, so a player can seek. The
  friend sees this server and never the listener.
- Only audio (for a stream) and a JPEG (for a cover) are passed on, with a
  fixed set of headers: Content-Type, Content-Length, Content-Range,
  Accept-Ranges, Last-Modified and ETag. Anything else a friend sends, or
  what a listener's request carries (cookies, authorization), is not passed
  either way, so a friend cannot make this server serve anything else.
- The client of friends can open a streaming answer: no limit on its whole
  length, one only on its beginning, no redirect followed, and it ends when
  the listener leaves.
- The player holds a friend's track next to the local ones. It streams
  through this server, shows the friend's cover, links to the music of the
  friend and not to a local page, is told apart from a local track with the
  same id, and is never reported as a listen: it does not feed taste.
- The songs of a friend have play buttons, the albums their covers.
- OpenAPI paths, contract test, and two real servers checked end to end: the
  bytes of the file arrive unchanged, with ranges, and a song plays in a
  browser from the friend's server through the other one.
2026-11-13 16:11:59 +01:00
squidd
ae2ceb2190 Merge pull request 'Federation: browse and search a friend's catalogue' (#139) from feat/federation-browse into main 2026-11-13 16:00:48 +01:00
tgiachi
29bd46c3ba feat(federation): browse and search a friend's catalogue
A listener can now browse the music that a friend's server shares.

- GET /friends lists the friends both admins agreed to, by id and name; an
  address or a key is for the admin only. It is empty while federation is off.
- GET /friends/{friend}/artists, albums and tracks (q, limit, offset,
  artist_id, album_id) and the one-item routes: this server asks the friend
  with a request signed by its own key and passes the page on. The answer is
  read into this API's own types first, so what a friend adds is dropped and
  the shape is the one in the spec. Nothing is kept, and the ids are the
  friend's own.
- Only the three kinds of thing can be asked, and only the parameters their
  routes take: a listener cannot make this server ask a friend for anything
  else. The friend's address and what the connection said never reach a
  listener.
- A friend that cannot be reached, no longer takes this server for a friend,
  is busy or is not there is told in words, never as an error page.
- The client of friends gets a generic signed GET with a size limit.
- The web app has a Friends entry in the menu, shown only when there is a
  friend to browse, a list of friends and a page for each with artists,
  albums and songs, a search and links from an artist to its albums and from
  an album to its songs, in English and Italian.
- OpenAPI paths and schemas, contract test with a friend that is a whole
  server, and two real servers checked end to end.
2026-11-13 15:59:26 +01:00
squidd
8702ff9786 Merge pull request 'Federation: shared libraries and the signed read API for friends' (#137) from feat/federation-peer-api into main 2026-11-13 15:05:54 +01:00
tgiachi
89826fcd07 feat(federation): shared libraries and the signed read API for friends
A friend's server can now read what an admin chose to share.

- A library has a shared flag, off by default (migration 0024), set with
  PATCH /libraries/{id}. Changing it never waits for a scan.
- Requests between friends are signed with each server's Ed25519 key: the
  method, the path and query from /api/v1/peer on, a date, a nonce and the
  hash of the empty body. A date more than two minutes off, a nonce used
  before, an unknown or removed key and a bad signature all get the same
  401. A friend still waiting for approval gets 403, and while federation is
  off the routes are missing.
- Routes under /api/v1/peer: info, artists, albums, tracks, covers and
  streaming with Range. The catalogue, the counts and the format come from
  the shared libraries only, and the file served is the one in a shared
  library. No path, library id, listen, taste, user or provider data is part
  of an answer.
- A friend never makes this server build a cover, read an audio file or ask
  a provider: only covers already built from the audio files are served.
- Per-friend limits, set by the admin: parallel streams (default 3) and KiB
  a second (default 4096, 0 for none), shared by all the streams of a friend.
- A log of the last requests friends made (route, status, bytes; never the
  query), kept for 7 days, in GET /federation/requests.
- POST /federation/friends/{id}/check lets the side that pasted an invite
  find out that the other admin approved; a signed call from a friend this
  server is waiting for makes it active too.
- Admin: a Shared with friends switch on each library, which asks first, and
  limits, recent requests and a Check button in the Federation section, in
  English and Italian.
- OpenAPI paths and schemas, contract test, two real servers checked end to
  end with tagged audio files.
2026-11-13 15:04:07 +01:00
squidd
346466c621 Merge pull request 'Federation: keys, invites and pairing between Sonda servers' (#135) from feat/federation-pairing into main 2026-11-13 14:44:34 +01:00
tgiachi
695a012f6c feat(federation): keys, invites and pairing between Sonda servers
Two servers can become friends. Federation is off by default; turning it
on makes an Ed25519 key pair, kept in the database and never returned.

- Admin routes: GET and PUT /federation (on or off, name, public address),
  POST /federation/invites, POST /federation/friends (use an invite),
  POST /federation/friends/{id}/approve and DELETE /federation/friends/{id}.
- POST /api/v1/peer/pair, the one route without a login: the code of an
  invite is the proof. An invite works once and expires in 24 hours; only
  a hash of its code is stored. At most 10 attempts a minute.
- The server that uses an invite checks that the key it gets back is the
  one named in the invite. A friend is kept as incoming or outgoing until
  both admins have agreed.
- https only, except plain http on a network of one's own (private,
  loopback or link-local address, or a local name).
- A client of its own for friends, with no redirects, no proxy from the
  environment, a size limit and a time limit; the providers' client stays
  as it is.
- Migration 0023 for SQLite and PostgreSQL, OpenAPI paths and schemas,
  contract test with two real servers.
- Admin > Federation in the web app, in English and Italian, and a
  section in the README.
2026-11-13 14:43:48 +01:00
squidd
822f6094e5 Merge pull request 'feat(web): a Show photo button on the cards of Discover' (#133) from feat/discover-photos into main 2026-11-13 13:07:53 +01:00
tgiachi
3ade5e80d5 feat(web): a Show photo button on the cards of Discover
A suggested artist you do not have shows a letter, because a photo is a lookup at the providers. The card now has a button that asks for the photo of that one artist when it is pressed, says what it sends, and says so when there is no free photo.

Closes #132
2026-11-13 13:01:57 +01:00
squidd
cded6f063e Merge pull request 'Audit follow-ups: skip link, lighter player, lazy pages, small polish' (#131) from feat/audit-followups into main 2026-11-13 12:57:18 +01:00
tgiachi
f0135cc548 fix(web): tap targets of 44 px, a browser bar that follows the theme, shorter lines
- The switches and the seek bar of the player bar take a tap on 44 px (the switch is now one component).
- The colour of the browser bar follows the theme instead of staying dark blue.
- Paragraphs stop at 56 characters and no longer end on a lone word.

Closes #130
2026-11-13 12:56:26 +01:00
tgiachi
a423632632 perf(web): pages are fetched when first opened
Every page but Home is loaded on demand, so the first script goes from 728 kB to 345 kB (gzip 220 to 112 kB). The admin area and the smart playlist editor are no longer in the first download.
2026-11-13 12:46:56 +01:00
tgiachi
817b869af7 perf(web): the player parts follow only the state they show 2026-11-13 12:44:53 +01:00
tgiachi
a80ead7f2b feat(web): a skip link jumps over the sidebar to the page 2026-11-13 12:44:12 +01:00
squidd
3ac61faa88 Merge pull request 'fix(web): Gruvbox text and links reach 4.5:1 contrast' (#129) from fix/gruvbox-contrast into main 2026-11-13 12:39:50 +01:00
tgiachi
36dffc2ed1 fix(web): Gruvbox text and links reach 4.5:1 contrast
Muted text on the secondary surface was 4.05:1 in Gruvbox dark and 3.8:1 in Gruvbox light, and the link colour on cards was 4.46:1 in Gruvbox light. The tokens are adjusted and the contrast test now also checks muted text on secondary and the primary colour as text on background and card.

Closes #128
2026-11-13 12:39:15 +01:00
squidd
82f9ee39cc Merge pull request 'feat(web): the app can be installed and opens offline (PWA)' (#127) from feat/pwa into main 2026-11-13 12:24:58 +01:00
tgiachi
2217a12042 feat(web): the app can be installed and opens offline (PWA)
- A web app manifest with the name, the colours, the display mode and the icons (also a maskable one), so a browser offers to install it; Settings has an Install button where the browser lets the page ask.
- A service worker keeps the files of the app (the page, its scripts and styles, the manifest and the icons) so it opens at once, and shows its own page when the server cannot be reached. It never touches /api/: nothing from the API is kept, answered from a cache, or asked for by the worker. Files that failed, and anything that is not a file of the app, are not kept; the scripts it keeps are capped.
- A new version waits until the page says it may take over: a line says a new version is ready and its button reloads the page after the new worker took over.
- The server gives the manifest its type (application/manifest+json); the worker and the manifest are asked again every time, and the policy of the page needs no change.
2026-11-13 12:22:00 +01:00
squidd
f86b5a3d7b Merge pull request 'feat(web): the logo of Sonda, and a design pass' (#125) from feat/design-pass into main 2026-11-13 12:11:57 +01:00
tgiachi
7e46c38245 feat(web): the logo of Sonda, and a design pass
- The logo, sONDA with an O that is a sea wave, traced to vector paths: the s in the text colour and the rest in the accent colour of the theme, in the sidebar and on the sign-in page; folded, the sidebar shows the wave alone. The favicon, the touch icon and the 192 and 512 icons are the wave on the blue of the logo (the old favicon was left by the build tool).
- Touch targets: buttons, fields, icon buttons and small links are 44 pixels tall; the time of the player is 13 pixels; the seek bar has a taller hit area.
- A phone: the menu is one row that scrolls sideways and the player is two lines (what is playing and the controls, then the position), so the page keeps the screen.
- Cards that are links lift a little and their pictures grow inside the frame on hover, unless less motion is asked for.
- The provider cards have a ground of their own.
2026-11-13 12:10:54 +01:00
squidd
7e3e40a896 Merge pull request 'feat(smart): covers on the Smart playlists page' (#123) from feat/smart-covers into main 2026-11-13 11:42:13 +01:00
tgiachi
82b92eaf08 feat(smart): covers on the Smart playlists page
- GET /smart-playlists/{id}/covers and GET /smart-playlists/suggested/{key}/covers say which albums stand for a smart playlist: up to 4 albums that have a cover, in the order of the songs the rules give now (for the variant asked), each once. They are worked out apart from the songs, and the answer may be kept for a few minutes.
- The cards of the Smart playlists page are a grid with the collage. The list shows at once and each card asks for its own covers after that, showing the rings until they arrive or when they cannot be read.
- The pages of a smart playlist and of a suggested one use the same covers for the variant on screen, so only albums that have a cover are shown.
2026-11-13 11:41:23 +01:00
squidd
0d69ae48de Merge pull request 'feat: playlists with a cover, a collage of the covers of their albums' (#121) from feat/playlist-covers into main 2026-11-13 11:32:57 +01:00
tgiachi
a1e192066c feat: playlists with a cover, a collage of the covers of their albums
- A 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, read for a whole page of playlists in one query. An empty one has an empty list.
- The Playlists page is a grid of cards with the collage, and the page of a playlist shows it in its header. The pages of a smart playlist and of a suggested one show a collage of the albums of their first songs.
- Nothing is fetched for it: the covers are the ones the library already has.
2026-11-13 11:32:01 +01:00
squidd
75577e1fdb Merge pull request 'feat(naming): an admin section that shows what Claude costs' (#119) from feat/claude-costs into main 2026-11-13 11:15:43 +01:00
tgiachi
1b79a7370d feat(naming): an admin section that shows what Claude costs
- Every question asked of Claude is recorded: when, the kind of list, the model, the tokens read and written (also for an answer that was no name but was billed) and how it ended: a name made, a name taken from the kept ones, or a failure and why. Nothing of the facts that were sent is recorded. Records older than a year are removed (migration 0022).
- GET /providers/anthropic/usage (admin) gives the totals of the last days (1 to 365, 30 by default), a row for each day with calls and an estimate of the cost in dollars, worked out from the tokens and the price of the model. It says it is an estimate and flags calls to a model whose price is not known.
- A Costs section in the admin area shows the last 7, 30 or 90 days.
2026-11-13 11:14:45 +01:00
squidd
84b6937bbf Merge pull request 'feat(naming): playlists named by Claude by themselves when it is on' (#117) from feat/auto-names into main 2026-11-13 11:01:52 +01:00
tgiachi
0d8fadadf6 feat(naming): playlists named by Claude by themselves when it is on
- Keeping a mix, a smart playlist or a suggested smart playlist as a playlist with auto_name gives it the name and the line of description that Claude makes from its songs. The name sent stays the fallback when the provider is off, or Claude fails or declines, so a failure never stops a playlist from being made.
- A smart playlist can be made with no name when Claude is on: it names it from the songs the rules give. Without Claude a name is still needed.
- GET /naming says whether names are automatic, so the editor does not ask for a name that Claude will make.
- The web app always asks for an automatic name and sends the language of the page.
2026-11-13 11:00:23 +01:00
squidd
0dddfb741e Merge pull request 'feat(smart): the songs I play most, in rotation lately and over the year' (#115) from feat/on-rotation into main 2026-11-13 10:45:42 +01:00
tgiachi
bf5c108785 feat(smart): the songs I play most, in rotation lately and over the year
- A smart playlist rule, plays_within_days, that counts only the plays of the last N days where plays are counted: the minimum of plays and the most and least played orders. The other listening rules are not changed.
- Two more suggested smart playlists on it: on-rotation (the most played of the last 30 days, at least twice) and top-year (the same over 365 days). most-played stays as the plays of all time.
- The editor has the new rule and the page says it in words. Texts in English and Italian.
2026-11-13 10:44:55 +01:00
squidd
322b6e5530 Merge pull request 'feat(naming): names for playlists, with the Claude API as an option' (#113) from feat/naming into main 2026-11-13 10:34:49 +01:00
tgiachi
9e666d2b29 feat(web): a Suggest a name button
- Where a playlist is renamed, and where a smart playlist is edited, a button asks the server for a name in the language of the page. It fills the name, fills the description when it is empty, and says if the name came from Claude or from this server. A failed request says why and changes nothing.
- The Claude card in the providers page has a key, a test and the switch, but no contact and no data to take back.
2026-11-13 10:33:48 +01:00
tgiachi
23ae396430 feat(naming): names for playlists, with the Claude API as an option
- A pipeline over the facts about a list of songs (up to 5 genres, up to 8 artist names, how many songs, a few words about the rules of a smart playlist, the language). A local namer builds a name from the genres and the artists on this server and is always there; Claude is asked first only when an admin turned the new anthropic provider on with an API key. A failure or a refusal gives the local name. What Claude answers is kept under a hash of the facts, so the same question is not asked or paid twice.
- The anthropic provider: a write-only key (kept as typed, it is case-sensitive), a test that reads one model and sends no text, and a plain statement of what is sent. It uses the official Go SDK with nothing taken from the environment of the server (no key, profile, base URL or extra headers), no redirects, no system headers, and an answer that is cleaned and bounded.
- POST /playlists/{id}/suggest-name, POST /mixes/{id}/suggest-name and POST /smart-playlists/{id}/suggest-name answer with a name, a description and where it came from.
2026-11-13 10:33:48 +01:00
squidd
2b7635c936 Merge pull request 'feat(web): a sidebar that collapses' (#111) from feat/web-collapsible-sidebar into main 2026-11-13 10:11:21 +01:00
tgiachi
4810564aac feat(web): a sidebar that collapses
- A button in the sidebar folds it to a narrow bar with the icon of each page, and opens it again. The choice is remembered in the browser, which may refuse to keep it.
- Every link keeps its name for screen readers and gets a tooltip when only its icon shows.
- On a phone, where the sidebar is a row of links, nothing changes.
2026-11-13 10:10:25 +01:00
squidd
ca63fc4701 Merge pull request 'feat(smart): smart playlists made for everybody, without making them' (#109) from feat/suggested-smart into main 2026-11-13 10:07:45 +01:00
tgiachi
17f70d582d feat(smart): smart playlists made for everybody, without making them
- A fixed set that is there with no setup: recently added, never played, most played, not heard for a while, high quality files and long tracks. The rules are the same for everyone and are worked out on each one's own library and history, like the mixes; nothing is stored, so they follow the library.
- GET /smart-playlists/suggested, GET /smart-playlists/suggested/{key}/tracks and POST /smart-playlists/suggested/{key}/playlist.
- The Smart playlists page begins with them, with names and descriptions in the language of the page. A suggested one can be played, shuffled again, kept as a playlist, or made one's own: a copy of its rules opens in the editor.
2026-11-13 10:06:58 +01:00
squidd
b598842c6d Merge pull request 'feat(mixes): a picture for each mix, a collage of album covers' (#107) from feat/mix-covers into main 2026-11-13 09:58:56 +01:00
tgiachi
1ad0d718c8 feat(mixes): a picture for each mix, a collage of album covers
- The server says which albums stand for a mix (album_ids): up to 4 albums that have a cover, by different artists, with most of the songs the mix draws from. The list gives them for every mix and a mix gives its own.
- The Mixes page shows the collage on each card (a 2 by 2 collage with four covers, the first one alone with fewer, the rings with none), and the page of a mix shows it in its header.
- Nothing is fetched for it: a mix has a picture once the covers of its albums were looked up.
2026-11-13 09:58:04 +01:00
squidd
0e489bda1f Merge pull request 'feat(web): smart playlists, and the genres to choose from' (#105) from feat/web-smart-playlists into main 2026-11-13 09:46:48 +01:00
tgiachi
a2938f0f96 feat(web): smart playlists
- A Smart playlists page with the ones I made and a way to make a new one.
- A page for a smart playlist: its rules in words, its songs, Play, Shuffle again (for the random order), Save as playlist (keeps what is on screen), Edit and Delete.
- An editor for a new one and for one that exists, with a live preview of the songs the rules give: genres (chips, with the library's genres offered), file format and bitrate, when it was added, listening, taste, length, order and limit. What the editor has no field for (artists, albums, skipped lately, another format) is kept when a playlist is changed.
- Texts in English and Italian, and tests for the list, the page, the editor and the preview.
2026-11-13 09:46:03 +01:00
tgiachi
a607070149 feat(smart): GET /genres, the genres of the library to choose from
Each genre with the number of playable songs, the biggest first and by name among equals. The spellings the files have are one genre, written the way the rules compare them, and tags such as other or unknown are left out.
2026-11-13 09:46:03 +01:00
squidd
7981edacb6 Merge pull request 'feat(smart): smart playlists, playlists made of rules' (#103) from feat/smart-playlists into main 2026-11-13 09:37:57 +01:00
tgiachi
104e41d10a feat(smart): smart playlists, playlists made of rules
A smart playlist is a set of rules, an order and a limit, kept under a name and worked out again every time it is opened.

- Rules (all that are set must hold): genres, artists and albums (is, or is not), file formats and a minimum bitrate of the same file, added in the last N days, never played, played or not played in the last N days, played at least N times, skipped or not skipped lately, only liked artists or without the avoided ones, and the length of the song.
- Orders: random (the same all day, a variant gives another), most played, least played, recently added, by title. A limit of 50 by default, 500 at most.
- GET/POST /smart-playlists, GET/PATCH/DELETE /smart-playlists/{id}, GET /smart-playlists/{id}/tracks, POST /smart-playlists/preview to try rules without keeping them, and POST /smart-playlists/{id}/playlist to keep what is shown as a normal playlist.
- Only the rules are stored (migration 0020); the songs come from the files and from the owner's own history and taste. Nothing is sent to a provider, and a smart playlist is its owner's alone. A user can have 200.
- Mixes and smart playlists share the way a list of songs becomes a playlist.
2026-11-13 09:36:52 +01:00
tgiachi
25f41dd5fc test(mixes): remove a throwaway check against a local database
It was committed by mistake with the mixes: it reads a database from a path on one machine and prints, so it checks nothing.
2026-11-13 09:23:11 +01:00
squidd
4b3618fa07 Merge pull request 'fix(musicbrainz): follow the redirect of an id that was merged' (#101) from fix/musicbrainz-merged-ids into main 2026-11-12 19:35:49 +01:00
tgiachi
6b40ea06fa fix(musicbrainz): follow the redirect of an id that was merged
When MusicBrainz merges two entries, the old id answers with a redirect to the new one. The client refused every redirect, so the description of that artist failed at every run of the job.

The client for MusicBrainz now follows a redirect only to https://musicbrainz.org/ws/2/artist/<id> or /release-group/<id>, with no credentials or port. Any other redirect is still refused. The new id is used for that request only.
2026-11-12 19:34:59 +01:00
squidd
5b9f98d8ed Merge pull request 'feat(web): mixes page, shuffle again and save as playlist' (#99) from feat/web-mixes into main 2026-11-12 18:37:55 +01:00
tgiachi
19fa5ff9ce feat(web): mixes page, shuffle again and save as playlist
- A Mixes link in the sidebar and a page with one card for each mix: the ones made from listening first, then one for each genre.
- A page for a mix: its songs, Play, Shuffle again (the next variant, one at a time) and Save as playlist (keeps the variant on screen, named with the title, with a link to the new playlist).
- Mix names are translated from the kind and the genre, since the server title is always English.
- Texts in English and Italian; tests for the list, the page, shuffle, save and the errors.
2026-11-12 18:36:41 +01:00
squidd
16fda24ff5 Merge pull request 'feat(mixes): playlists made for a listener, by listening and by genre' (#97) from feat/mixes into main 2026-11-12 17:27:24 +01:00
tgiachi
94dbf57544 feat(mixes): playlists made for a listener, by listening and by genre
GET /mixes lists the mixes a listener has, GET /mixes/{id}?variant= gives one with its
songs, and POST /mixes/{id}/playlist keeps one as a playlist of their own.

- Genre mixes: one for each genre with at least 30 songs by 4 artists, the genres the
  listener plays most first. Spellings that differ by case or punctuation are one
  genre (jazz+funk, jazz-funk); other and unknown are not genres.
- Made for the listener: Your favourites, Rediscover (liked artists not played for a
  month; both need history) and New to you (songs never played).
- A mix has up to 50 songs, at most 3 by one artist, never two of an artist in a row,
  picked by weighted chance (artist preference, never-played, less if played lately;
  skipped lately and avoided artists are out). The seed is user, mix, day and variant,
  so a mix is steady for a day and another is one variant away.
- Worked out when asked, from the listener's own history and the genre tags; nothing is
  stored and nothing leaves the server.

internal/mixes holds the selection and the service, internal/storage/mixes.go the
queries (SQLite and PostgreSQL). Spec, contract test, README and web types follow;
the web app comes separately.

Closes #95
2026-11-12 17:25:49 +01:00
605 changed files with 65622 additions and 4363 deletions

View file

@ -0,0 +1,138 @@
# What happens at every merge into main:
# 1. semantic-release reads the commits since the last release (Conventional Commits), works out the next version,
# writes CHANGELOG.md, makes the release on the forge and tags it. A merge with nothing to release (docs, tests, ci)
# makes none.
# 2. When there is a release, the image is built from the tag, for amd64 and for arm64, and pushed to
# git.kmalloc.org/squid/sonda as X.Y.Z-ARCH; then X.Y.Z, X.Y and latest are made to point at both.
# The runner has no Docker and cannot emulate another architecture, so the images are built with kaniko, which needs no
# daemon, and the Dockerfile crosses to arm64 without running anything for it.
# Secret needed: FORGEJO_TOKEN, a token of the owner with the scopes write:repository and write:package.
name: release
on:
push:
branches: [main]
# One release at a time: two merges close together must not make two versions at once.
concurrency:
group: release
cancel-in-progress: false
jobs:
release:
runs-on: docker
# The commit that the release makes (CHANGELOG.md) says [skip ci]; this is the belt for those braces.
if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
outputs:
version: ${{ steps.version.outputs.version }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the whole history: the next version depends on every commit since the last tag
token: ${{ secrets.FORGEJO_TOKEN }}
- uses: actions/setup-node@v4
with:
node-version: 24
- name: Release
env:
GITEA_TOKEN: ${{ secrets.FORGEJO_TOKEN }}
GITEA_URL: https://git.kmalloc.org
GIT_AUTHOR_NAME: sonda-release
GIT_AUTHOR_EMAIL: squid@kmalloc.org
GIT_COMMITTER_NAME: sonda-release
GIT_COMMITTER_EMAIL: squid@kmalloc.org
run: >
npx --yes
-p semantic-release@25
-p @semantic-release/commit-analyzer@13.0.1
-p @semantic-release/release-notes-generator@14.1.1
-p @semantic-release/changelog@7.0.0
-p @semantic-release/git@11.0.1
-p conventional-changelog-conventionalcommits@8.0.0
-p @saithodev/semantic-release-gitea@2.1.0
semantic-release
- name: Which version was made, if any
id: version
run: |
# The tag of a release points at the commit the release made, which is where the checkout now is.
tag="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1 || true)"
echo "version=${tag#v}" >> "$GITHUB_OUTPUT"
echo "released: ${tag:-nothing}"
# The Alpine of the arm64 image, by digest: kaniko, which has no emulation here, takes the base of every stage for the
# platform of the runner, so the last stage is told which one to use.
base:
needs: release
if: ${{ needs.release.outputs.version != '' }}
runs-on: docker
container:
image: gcr.io/go-containerregistry/crane:debug
outputs:
arm64: ${{ steps.digest.outputs.arm64 }}
steps:
- id: digest
run: echo "arm64=alpine@$(crane digest --platform linux/arm64 alpine:3.22)" >> "$GITHUB_OUTPUT"
# One image for each architecture. The Go program crosses to the other one with no emulation, and the last stage of the
# Dockerfile runs no command (see the Dockerfile).
image:
needs: [release, base]
if: ${{ needs.release.outputs.version != '' }}
runs-on: docker
strategy:
matrix:
arch: [amd64, arm64]
container:
image: gcr.io/kaniko-project/executor:v1.23.2-debug
steps:
- name: Build the image from the tag and push it as X.Y.Z-ARCH
env:
VERSION: ${{ needs.release.outputs.version }}
ARCH: ${{ matrix.arch }}
ARM64_BASE: ${{ needs.base.outputs.arm64 }}
REGISTRY_USER: squid
REGISTRY_TOKEN: ${{ secrets.FORGEJO_TOKEN }}
run: |
set -eu
mkdir -p /kaniko/.docker
auth="$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_TOKEN" | base64 | tr -d '\n')"
printf '{"auths":{"git.kmalloc.org":{"auth":"%s"}}}' "$auth" > /kaniko/.docker/config.json
base=alpine:3.22
if [ "$ARCH" = arm64 ]; then base="$ARM64_BASE"; fi
/kaniko/executor \
--dockerfile Dockerfile \
--context "git://git.kmalloc.org/squid/sonda.git#refs/tags/v${VERSION}" \
--build-arg "VERSION=${VERSION}" \
--build-arg "SONDA_ARCH=${ARCH}" \
--build-arg "RUNTIME_BASE=${base}" \
--label "org.opencontainers.image.version=${VERSION}" \
--destination "git.kmalloc.org/squid/sonda:${VERSION}-${ARCH}" \
--verbosity info
# The tags that people use (X.Y.Z, X.Y, latest) point at a list of the two images, so that each machine takes its own.
manifest:
needs: [release, image]
if: ${{ needs.release.outputs.version != '' }}
runs-on: docker
container:
image: gcr.io/go-containerregistry/crane:debug
steps:
- name: Join the images under X.Y.Z, X.Y and latest
env:
VERSION: ${{ needs.release.outputs.version }}
REGISTRY_USER: squid
REGISTRY_TOKEN: ${{ secrets.FORGEJO_TOKEN }}
run: |
set -eu
image=git.kmalloc.org/squid/sonda
crane auth login git.kmalloc.org -u "$REGISTRY_USER" -p "$REGISTRY_TOKEN"
# Kaniko writes the architecture of the runner in both images: say the right one for each.
for arch in amd64 arm64; do
crane mutate "${image}:${VERSION}-${arch}" --set-platform "linux/${arch}" --tag "${image}:${VERSION}-${arch}"
done
crane index append \
--tag "${image}:${VERSION}" \
--manifest "${image}:${VERSION}-amd64" \
--manifest "${image}:${VERSION}-arm64"
crane tag "${image}:${VERSION}" "${VERSION%.*}"
crane tag "${image}:${VERSION}" latest

35
.releaserc.json Normal file
View file

@ -0,0 +1,35 @@
{
"branches": ["main"],
"tagFormat": "v${version}",
"plugins": [
["@semantic-release/commit-analyzer", { "preset": "conventionalcommits" }],
[
"@semantic-release/release-notes-generator",
{
"preset": "conventionalcommits",
"presetConfig": {
"types": [
{ "type": "feat", "section": "Features" },
{ "type": "fix", "section": "Bug fixes" },
{ "type": "perf", "section": "Performance" },
{ "type": "refactor", "section": "Refactoring" },
{ "type": "docs", "section": "Documentation" },
{ "type": "style", "hidden": true },
{ "type": "test", "hidden": true },
{ "type": "chore", "hidden": true },
{ "type": "ci", "hidden": true }
]
}
}
],
["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md", "changelogTitle": "# Changelog" }],
[
"@semantic-release/git",
{
"assets": ["CHANGELOG.md"],
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
}
],
["@saithodev/semantic-release-gitea", { "giteaUrl": "https://git.kmalloc.org" }]
]
}

46
CHANGELOG.md Normal file
View file

@ -0,0 +1,46 @@
# 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
* **web:** make the seek bar fit the width of a phone ([6220238](https://git.kmalloc.org/squid/sonda/commit/6220238068c446a97d1726697601f7ba5e126028)), closes [#45](https://git.kmalloc.org/squid/sonda/issues/45)
## [0.4.1](https://git.kmalloc.org/squid/sonda/compare/v0.4.0...v0.4.1) (2026-11-17)
### Bug fixes
* **web:** keep the controls of the full-screen player on screen on a phone ([a757743](https://git.kmalloc.org/squid/sonda/commit/a757743161ac3f7a348884a9f7b2490ab09b99e1)), closes [#43](https://git.kmalloc.org/squid/sonda/issues/43)
## [0.4.0](https://git.kmalloc.org/squid/sonda/compare/v0.3.0...v0.4.0) (2026-11-16)
### Features
* **web:** make Sonda feel like an app on a phone ([75a7898](https://git.kmalloc.org/squid/sonda/commit/75a7898c68ca65c8c4efa0f51b72d62ac9a4db6e))
### Documentation
* note that this repo moved to git.kmalloc.org ([ee31e0e](https://git.kmalloc.org/squid/sonda/commit/ee31e0ee7caf9e7510b7cfde1f4e096721966e90))
## [0.3.0](https://git.kmalloc.org/squid/sonda/compare/v0.2.0...v0.3.0) (2026-11-16)
### Features
* publish the Docker image for ARM as well ([b37e3db](https://git.kmalloc.org/squid/sonda/commit/b37e3db037a442af439c5183cf4937a9be630a14))
## [0.2.0](https://git.kmalloc.org/squid/sonda/compare/v0.1.0...v0.2.0) (2026-11-16)
### Features
* scan the libraries by themselves when their music changed ([89f1b52](https://git.kmalloc.org/squid/sonda/commit/89f1b5275a3f1d0115f1cdd22512daebebf964d2))

View file

@ -1,8 +1,11 @@
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
# RUNTIME_BASE is alpine:3.22 unless the CI release asks for another architecture, with the digest of that one.
ARG RUNTIME_BASE=alpine:3.22
# The web app: built once here, written (by its Vite config) to /src/internal/webui/dist, where the Go # The web app: built once here, written (by its Vite config) to /src/internal/webui/dist, where the Go
# build below embeds it. Nothing of Node reaches the final image. # build below embeds it. Nothing of Node reaches the final image.
FROM node:24-alpine AS web FROM --platform=$BUILDPLATFORM node:24-alpine AS web
WORKDIR /src/web WORKDIR /src/web
COPY web/package.json web/package-lock.json ./ COPY web/package.json web/package-lock.json ./
RUN npm ci RUN npm ci
@ -12,7 +15,13 @@ RUN npm run build
# Build: Sonda has no CGO (SQLite, PostgreSQL and the tag reader are pure Go), so the binary # Build: Sonda has no CGO (SQLite, PostgreSQL and the tag reader are pure Go), so the binary
# is static and the final image needs nothing but it and the CA certificates. The web app is inside it # is static and the final image needs nothing but it and the CA certificates. The web app is inside it
# (-tags webui), so sondad serves it on / and the API on /api. # (-tags webui), so sondad serves it on / and the API on /api.
FROM golang:1.27-alpine AS build FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS build
# Built on the machine that builds, for the machine that runs: Go crosses to another architecture with no emulation
# (TARGETOS and TARGETARCH come from the platform asked for).
ARG TARGETOS
ARG TARGETARCH
# SONDA_ARCH is for a builder that cannot say TARGETARCH (the CI release, see .forgejo/workflows/release.yml).
ARG SONDA_ARCH
WORKDIR /src WORKDIR /src
COPY go.mod go.sum ./ COPY go.mod go.sum ./
RUN go mod download RUN go mod download
@ -20,19 +29,28 @@ COPY cmd ./cmd
COPY internal ./internal COPY internal ./internal
COPY migrations ./migrations COPY migrations ./migrations
COPY --from=web /src/internal/webui/dist ./internal/webui/dist COPY --from=web /src/internal/webui/dist ./internal/webui/dist
RUN CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w" -o /out/sondad ./cmd/sondad # The version of the release (see .releaserc.json), as GET /version and the User-Agent of the providers say it.
ARG VERSION=dev
RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${SONDA_ARCH:-${TARGETARCH:-amd64}} go build -tags webui -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o /out/sondad ./cmd/sondad
FROM alpine:3.22 # What the image has besides the program (the zones of tzdata, the user, the folders) is made here, on the machine that
LABEL org.opencontainers.image.title="Sonda" \ # builds. The last stage then runs no command, so it can be built for another architecture with no emulation.
org.opencontainers.image.description="A privacy-first, self-hosted music server" \ FROM --platform=$BUILDPLATFORM alpine:3.22 AS rootfs
org.opencontainers.image.source="https://codeberg.org/squidd/sonda" RUN apk add --no-cache tzdata \
# ca-certificates: the providers an admin may switch on are reached over https.
# tzdata: log times in the zone the operator sets with TZ.
RUN apk add --no-cache ca-certificates tzdata \
&& addgroup -S -g 10001 sonda \ && addgroup -S -g 10001 sonda \
&& adduser -S -u 10001 -G sonda -h /data -H sonda \ && adduser -S -u 10001 -G sonda -h /data -H sonda \
&& mkdir -p /data /music \ && mkdir -p /out/data /out/music
&& chown sonda:sonda /data
FROM ${RUNTIME_BASE}
LABEL org.opencontainers.image.title="Sonda" \
org.opencontainers.image.description="A privacy-first, self-hosted music server" \
org.opencontainers.image.source="https://git.kmalloc.org/squid/sonda"
# The certificates of alpine (ca-certificates-bundle) are what the providers an admin may switch on are reached with,
# over https. tzdata is for the log times in the zone the operator sets with TZ.
COPY --from=rootfs /usr/share/zoneinfo /usr/share/zoneinfo
COPY --from=rootfs /etc/passwd /etc/group /etc/shadow /etc/
COPY --from=rootfs --chown=10001:10001 /out/data /data
COPY --from=rootfs /out/music /music
COPY --from=build /out/sondad /usr/local/bin/sondad COPY --from=build /out/sondad /usr/local/bin/sondad
# Everything Sonda writes is under /data: the database and the files it makes (covers, pictures). # Everything Sonda writes is under /data: the database and the files it makes (covers, pictures).

View file

@ -8,8 +8,11 @@
.PHONY: build web test .PHONY: build web test
# The version is the last release tag, and how far this checkout is from it (v1.2.3-4-gabcdef), or "dev" outside git.
VERSION ?= $(shell git describe --tags --always 2>/dev/null | sed 's/^v//' || echo dev)
build: web build: web
CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w" -o bin/sondad ./cmd/sondad CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w -X main.version=$(VERSION)" -o bin/sondad ./cmd/sondad
web: web:
cd web && npm ci && npm run build cd web && npm ci && npm run build

153
README.md
View file

@ -1,35 +1,53 @@
# Sonda # 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. 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. 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/`, 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). 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.
## What works today ## What works today
- **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. - **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. - **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. - **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 tracks, with paging, by library, artist or album. Only tracks you can actually play are listed. - **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 tracks 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. - **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. - **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. - **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. - **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. - **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 switched 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. - **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 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 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 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 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 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). - **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 switched 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 switched on the `coverartarchive` provider (see [External providers](#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 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). - **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 `<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 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).
- **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 tracks 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 tracks stay in the library). A track 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 track 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. A user can have 1000 playlists of up to 10000 tracks. Nothing is shared and nothing leaves your server. - **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. - **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. - **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). - **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 switched 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. - **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:<id>` 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 ## What is not there yet
Radio queues, OpenSubsonic compatibility, transcoding, 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. 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 ## Requirements
@ -51,22 +69,24 @@ A plain `go build -o bin/sondad ./cmd/sondad` needs no Node and gives the API on
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 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 ```bash
docker build -t sonda . docker pull git.kmalloc.org/squid/sonda:latest
(umask 077; echo "SONDA_JWT_SECRET=$(openssl rand -hex 32)" > sonda.env) # once: keep this file (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 \ docker run -d --name sonda --restart unless-stopped --stop-timeout 15 \
-p 127.0.0.1:8080:8080 \ -p 127.0.0.1:8080:8080 \
--env-file sonda.env \ --env-file sonda.env \
-v sonda-data:/data \ -v sonda-data:/data \
-v "$HOME/Music":/music:ro \ -v "$HOME/Music":/music:ro \
sonda 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. 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.
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. 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.
`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`. The image has a health check on `/api/v1/health`, which is logged at debug level when it succeeds. `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.
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. 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.
@ -88,6 +108,7 @@ Precedence is: built-in defaults, then the file, then environment variables. An
|---|---|---|---| |---|---|---|---|
| `server.listen` | `SONDA_LISTEN` | `127.0.0.1:8080` | Address to listen on. Localhost by default. | | `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.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. | | `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.driver` | `SONDA_DB_DRIVER` | `sqlite` | `sqlite` or `postgres`. |
| `database.path` | `SONDA_DB_PATH` | `sonda.db` | SQLite file (driver `sqlite`). | | `database.path` | `SONDA_DB_PATH` | `sonda.db` | SQLite file (driver `sqlite`). |
@ -116,7 +137,7 @@ Sonda creates and migrates its tables on start. The storage tests run against bo
## Demo ## Demo
This takes you from an empty database to streaming a track. Run the server in one terminal and the commands in another. 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: **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:
@ -169,7 +190,7 @@ curl -s "$BASE/albums" -H "$AUTH" | jq '.items[] | {id, title, artist: .artist.n
curl -s "$BASE/tracks?q=tone" -H "$AUTH" | jq '.items[] | {id, title, artists: [.artists[].name], format}' curl -s "$BASE/tracks?q=tone" -H "$AUTH" | jq '.items[] | {id, title, artists: [.artists[].name], format}'
``` ```
**6. Stream a track:** **6. Stream a song:**
```bash ```bash
TRACK=$(curl -s "$BASE/tracks?limit=1" -H "$AUTH" | jq -r '.items[0].id') TRACK=$(curl -s "$BASE/tracks?limit=1" -H "$AUTH" | jq -r '.items[0].id')
@ -193,7 +214,7 @@ curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\"
curl -s "$BASE/listens" -H "$AUTH" | jq '.items[] | {track: .track.title, event_type, duration_played_ms, counted}' 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. The answer to each report says whether it counts. A reported play time far beyond the length of the song (more than twice its length plus 10 seconds) is rejected.
**8. Refresh the session and log out:** **8. Refresh the session and log out:**
@ -221,7 +242,7 @@ curl -s -X POST $BASE/users -H "$AUTH" -d '{"email":"bob@example.org","password"
Sonda can ask Last.fm, MusicBrainz, Wikipedia, Wikimedia Commons and the Cover Art Archive about artists and albums, and can tell your own Lidarr which artist to add. 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. Sonda can ask Last.fm, MusicBrainz, Wikipedia, Wikimedia Commons and the Cover Art Archive about artists and albums, and can tell your own Lidarr which artist to add. 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. - **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. - **MusicBrainz** needs no key, but it asks every client to identify itself with a contact (a URL or an email 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: Set them up with `PUT /api/v1/providers/{name}` (admin), for example:
@ -256,20 +277,53 @@ The address can have a path if Lidarr runs under a URL base, and it cannot carry
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. 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, the MusicBrainz id of the artist (and, only for the covers of albums that have no id, the artist's name and the album's title: see **Covers**), your IP address and a `User-Agent` that carries your contact. Never your users, your listens 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 (and, for the albums whose files have no id, with MusicBrainz on, the artist and the title, one request a second); `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 the MusicBrainz release group id of an album, read from the tags of its own files, and only when the files have no picture. When the files have no id either and the MusicBrainz provider is on too, the name of the album's artist and its title go to MusicBrainz, which is asked for the release group: a result is taken only when MusicBrainz scores it 95 or more and its title and artist are the ones asked for (compared without case, accents or punctuation), and anything doubtful is no cover. A title that ends with a note about the disc or the edition (`(disc 2)`, `(bonus disc)`, `(Deluxe Edition)`) is asked as it is first and, if MusicBrainz is not sure, once more without the note, because a release group is named after the album and not after a disc. The id that comes back is used for that request and is not stored: it is not what your files say, and it is never used to read an artist or to send anything to Lidarr; 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`. **Lidarr** (your own server, at the address an admin set) gets the MusicBrainz id of an artist an admin sends, or of an artist someone opens `GET /artists/{id}/lidarr` for, and the API key, nothing else; asking it what it offers and testing the key send only the key. Never a name, your users, your listens or your files. What Lidarr then does is up to its own indexers and download clients. 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 (or, for Lidarr, the address and the key); it sends nothing but the key. **Claude (Anthropic)** is the one provider that names things: with it on, a playlist, a mix or a smart playlist can get a name and a line of description that fit its songs. An admin turns it on with an Anthropic API key (`PUT /providers/anthropic`, the key is write-only, and `POST /providers/anthropic/test` reads one model, which costs nothing and sends no text). `POST /playlists/{id}/suggest-name`, `POST /mixes/{id}/suggest-name` and `POST /smart-playlists/{id}/suggest-name` answer with a name, a description and a `source`. They are a pipeline: the facts about the list (up to 5 genres, up to 8 artist names, how many songs, for a smart playlist a few words about its rules, and the language) go to a namer. With the provider off, or when Claude fails or declines, the local namer builds a name from the genres and the artists on this server, and nothing leaves it. When Claude answers, the name is kept (under a hash of the facts, which holds no artist name), so the same facts are not asked, or paid, twice. A suggestion changes nothing: the client decides what to do with it, and the web app offers it where a playlist is renamed. With the provider on, names are also made by themselves: a mix, a smart playlist or a suggested smart playlist that is kept as a playlist with `auto_name` (the web app always sends it) gets Claude's name and line of description, with `name` as the fallback when Claude is off, fails or declines; a smart playlist can be made with no name at all and Claude names it from the songs its rules give (without Claude that is `invalid_input`); and `GET /naming` says whether names are automatic, so that the editor does not ask for one. Every question to Claude is counted (a made name, a name taken from the kept ones, a failure with its reason, and the tokens that were billed, also for a failure that was billed) and nothing of what was sent is kept; `GET /providers/anthropic/usage?days=30` (admin) gives the totals, a row for each day and an **estimate** of the cost in dollars, worked out from the tokens and the price of the model (the invoice of Anthropic is the truth), and the Costs section of the admin area shows it for 7, 30 or 90 days; records older than a year are removed. The model is `claude-opus-5-5`, at low effort; the key is never taken from the environment of the server, and a redirect is never followed.
**What leaves your server, when a provider is on:** to Anthropic, only when someone asks for a name, up to 5 genres and 8 artist names of that list, how many songs it has, a few words about the rules of a smart playlist, the language, your API key, your IP address and a User-Agent (never your users, your listens, song titles or file paths); to Last.fm, the artist name (or MusicBrainz id) being looked up, your API key, your IP address and the `User-Agent`; to MusicBrainz, the MusicBrainz id of the artist (and, only for the covers of albums that have no id, the artist's name and the album's title: see **Covers**), your IP address and a `User-Agent` that carries your contact. Never your users, your listens 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 (and, for the albums whose files have no id, with MusicBrainz on, the artist and the title, one request a second); `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. When MusicBrainz answers that an id was merged into another, Sonda follows that one redirect, and only to an artist or a release group of musicbrainz.org over https; the new id is used for that request and is not stored, and any other redirect is refused. **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 the MusicBrainz release group id of an album, read from the tags of its own files, and only when the files have no picture. When the files have no id either and the MusicBrainz provider is on too, the name of the album's artist and its title go to MusicBrainz, which is asked for the release group: a result is taken only when MusicBrainz scores it 95 or more and its title and artist are the ones asked for (compared without case, accents or punctuation), and anything doubtful is no cover. A title that ends with a note about the disc or the edition (`(disc 2)`, `(bonus disc)`, `(Deluxe Edition)`) is asked as it is first and, if MusicBrainz is not sure, once more without the note, because a release group is named after the album and not after a disc. The id that comes back is used for that request and is not stored: it is not what your files say, and it is never used to read an artist or to send anything to Lidarr; 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`. **Lidarr** (your own server, at the address an admin set) gets the MusicBrainz id of an artist an admin sends, or of an artist someone opens `GET /artists/{id}/lidarr` for, and the API key, nothing else; asking it what it offers and testing the key send only the key. Never a name, your users, your listens or your files. What Lidarr then does is up to its own indexers and download clients. 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 (or, for Lidarr, the address and the 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. **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. **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. **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 songs the artist is credited on, each weighted by how many songs 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 for an artist by name, because a search returns look-alikes and picking one would be a guess; the one search there is is for the cover of an album that has no id (see **Covers** below), and it takes a result only when it is sure. 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. **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 for an artist by name, because a search returns look-alikes and picking one would be a guess; the one search there is is for the cover of an album that has no id (see **Covers** below), and it takes a result only when it is sure. 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. **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 turned 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 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.
## Other apps (OpenSubsonic)
Sonda speaks [OpenSubsonic](https://opensubsonic.github.io/docs/) (Subsonic API 1.16.1 and its open extensions) at `/rest`, so the apps that speak it can play your music: Symfonium, Feishin, Amperfy, Supersonic, Tempus, Airsonic Refix and others.
**Connect an app.**
1. Open Settings, **Apps and devices**, give the app a name and press **Make password**. The password is shown once: copy it into the app.
2. In the app, give the address of your server, your email as the user name, and that password. An app that asks for an API key takes the same password as the key.
The API has the same: `POST /me/devices` makes a password (and returns it once), `GET /me/devices` lists them with when each was last used, and `DELETE /me/devices/{id}` takes one back. You can have 20.
A device password opens your music in that app and nothing else: it cannot sign in to Sonda, change your account or make other passwords, and the password of your account does not work in apps. Make one for each app, and take it back in Settings when you lose the phone: that app stops working at once. The passwords are kept sealed with a key derived from `auth.jwt_secret` (Subsonic's token login needs the server to know the password itself, so it cannot be kept as a hash), so changing that secret makes you make them again. An app sends the password in the address of each call: give Sonda a server address on `https`, and do not put these addresses in a log you share.
**What an app can do.** Calls are answered in JSON (`f=json`) or XML, and a web app on another address can read the answers (`Access-Control-Allow-Origin: *`; what opens a call is the password in it, never a cookie).
| Calls | What they do |
| --- | --- |
| `ping`, `getLicense`, `getOpenSubsonicExtensions`, `tokenInfo` | The server says who it is. The extensions need no login. |
| `getMusicFolders`, `getArtists`, `getArtist`, `getAlbum`, `getSong`, `getGenres` | Browse your libraries. |
| `getAlbumList2` | Random, newest, frequent, recent, by name, by artist, by year, by genre. |
| `getRandomSongs`, `getSongsByGenre`, `search3` | Find songs, albums and artists. |
| `stream`, `download`, `getCoverArt` | The original file (with Range), and covers of albums, artists and songs. |
| `getPlaylists`, `getPlaylist`, `createPlaylist`, `updatePlaylist`, `deletePlaylist` | Your playlists, the same ones as in the web app. After them, when you turned on *Show the radio stations in apps*, each station of the radio is a playlist (`rd-…`, *Radio · Rock*) with other songs every time it is opened; they cannot be changed or deleted. |
| `scrobble` | A listen is recorded like one made in the web app (and shared on Mastodon if you connected it). A "now playing" message is not recorded. |
| `star`, `unstar`, `getStarred2` | Your favourites (see **Favourites**): songs, albums and artists, with the `starred` date on each, and `getAlbumList2` of type `starred`. |
| `setRating`, `getNowPlaying` | Answered with nothing: there are no ratings, and what you play is nobody else's business. |
| `getUser` | Who the app is logged in as. It is always you, with the roles of an app: play, download, playlists, covers, and never admin. |
| `getArtistInfo`, `getArtistInfo2`, `getAlbumInfo`, `getAlbumInfo2`, `getTopSongs`, `getSimilarSongs`, `getSimilarSongs2`, `getLyrics`, `getLyricsBySongId`, `getInternetRadioStations`, `getScanStatus`, `startScan`, `getPlayQueue`, `savePlayQueue`, `getPlayQueueByIndex`, `savePlayQueueByIndex` | Answered with nothing (a saved queue is not kept), so that apps that ask them right after the login, like Feishin, work. A call Sonda does not know is an error `0` and shows in the server log. |
Sonda does not transcode: an app always gets the original file, whatever format or bit rate it asks for. The music of friends (federation) is not shown to apps.
## The API at a glance ## The API at a glance
Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"error":{"code":"...","message":"..."}}`. Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"error":{"code":"...","message":"..."}}`.
@ -279,10 +333,11 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er
| Who | Method and path | What it does | | Who | Method and path | What it does |
|---|---|---| |---|---|---|
| anyone | `GET /health` | Liveness check. | | anyone | `GET /health` | Liveness check. |
| signed in | `GET /version` | The version of Sonda and, when the binary knows it, the commit it was built from. The web app shows it under the menu and in Settings. |
| anyone | `POST /auth/register` | Create the first user (admin). Closed afterwards. | | 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. | | 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 /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`, `/albums`, `/tracks` and `/…/{id}` | Browse and search. Query: `q`, `limit` (default 50, max 200), `offset`, `library_id`, `artist_id`, `album_id`, and for `/albums` `sort=recent` (the albums added last first, by the date of their newest file; the default is by title). |
| 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 /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`, `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}/description` | What Wikipedia says about the artist, with its page and licence, from the Wikipedia provider when an admin switched it on. |
@ -290,10 +345,18 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er
| signed in | `GET`, `HEAD /tracks/{id}/stream` | Stream the original file. Also accepts `?access_token=`. | | 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 | `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 /listens` | Your own history, newest first, with `counted` per event. Query: `limit`, `offset`, `counted=true`. |
| signed in | `GET /stats/library`, `GET /stats/listening` | What the library holds; what you listened to, for all time or a period. Query of the second: `from`, `until`, `tz`. |
| 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 /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`, `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 /mixes`, `GET /mixes/{id}`, `POST /mixes/{id}/playlist` | Your mixes: list them, read one (query `variant`), keep one as a playlist. Made for you alone, from your history and your genres; nothing is stored. |
| signed in | `GET /genres` | The genres of the library with their number of songs, the biggest first, spellings merged: what the rules of a smart playlist choose from. |
| signed in | `GET /smart-playlists`, `POST /smart-playlists`, `GET`, `PATCH`, `DELETE /smart-playlists/{id}` | Your smart playlists: list them (query `limit`, `offset`), make one from rules, read, change or delete one. Never anybody else's. |
| signed in | `GET /naming` | Whether names are made by themselves (`auto`): true when the `anthropic` provider is on. |
| signed in | `POST /playlists/{id}/suggest-name`, `POST /mixes/{id}/suggest-name`, `POST /smart-playlists/{id}/suggest-name` | A name and a line of description for a list of songs (body: `lang`, `variant`): Claude's when an admin turned the `anthropic` provider on, a local one otherwise (`source`). |
| signed in | `GET /smart-playlists/suggested`, `GET /smart-playlists/suggested/{key}/tracks`, `POST /smart-playlists/suggested/{key}/playlist` | The smart playlists Sonda makes for everybody (a fixed set), their songs for you now (query `variant`), and one kept as a normal playlist. |
| signed in | `GET /smart-playlists/{id}/tracks`, `POST /smart-playlists/preview`, `POST /smart-playlists/{id}/playlist` | The songs the rules give now (query `variant`), a preview of rules that are not kept, and a smart playlist kept as a normal playlist. |
| signed in | `GET /playlists`, `POST /playlists`, `GET`, `PATCH`, `DELETE /playlists/{id}` | Your playlists: list them (query `limit`, `offset`), make one, read, rename or delete one. Never anybody else's. | | signed in | `GET /playlists`, `POST /playlists`, `GET`, `PATCH`, `DELETE /playlists/{id}` | Your playlists: list them (query `limit`, `offset`), make one, read, rename or delete one. Never anybody else's. |
| signed in | `GET /playlists/{id}/tracks`, `POST /playlists/{id}/tracks`, `PATCH`, `DELETE /playlists/{id}/tracks/{item}` | The tracks of a playlist: list them in order, add some (at the end or at a `position`), move or remove an item. | | signed in | `GET /playlists/{id}/tracks`, `POST /playlists/{id}/tracks`, `PATCH`, `DELETE /playlists/{id}/tracks/{item}` | The songs of a playlist: list them in order, add some (at the end or at a `position`), move or remove an item. |
| 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 /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 /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/taste` | The artists and tags Sonda learned you like, from your own listening. Query: `limit` (default 20, max 50). |
@ -305,6 +368,7 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er
| admin | `POST /library/scan`, `POST /libraries/{id}/scan` | Scan everything, or one library. `?full=true` reads every file again. | | admin | `POST /library/scan`, `POST /libraries/{id}/scan` | Scan everything, or one library. `?full=true` reads every file again. |
| admin | `GET /library/duplicates`; `POST`, `GET`, `DELETE /library/duplicates/check`; `POST /library/duplicates/clean` | Find the songs that are in more than one file, read their files to tell the identical ones, and delete the extra copies. See **Duplicates**. | | admin | `GET /library/duplicates`; `POST`, `GET`, `DELETE /library/duplicates/check`; `POST /library/duplicates/clean` | Find the songs that are in more than one file, read their files to tell the identical ones, and delete the extra copies. See **Duplicates**. |
| admin | `GET /providers`, `PUT /providers/{name}`, `POST /providers/{name}/test`, `DELETE /providers/{name}/data` | See, set up and check the providers (Last.fm, MusicBrainz, Wikipedia, Commons, the Cover Art Archive, Lidarr), and remove what they gave. The API key is write-only. | | admin | `GET /providers`, `PUT /providers/{name}`, `POST /providers/{name}/test`, `DELETE /providers/{name}/data` | See, set up and check the providers (Last.fm, MusicBrainz, Wikipedia, Commons, the Cover Art Archive, Lidarr), and remove what they gave. The API key is write-only. |
| admin | `GET /providers/anthropic/usage` | What the Claude provider costs over the last days (query `days`, 1 to 365): totals, a row for each day with calls and an estimate in dollars. |
| admin | `GET /providers/lidarr/options` | The profiles and root folders that Lidarr offers, to choose the ones artists are sent with. | | admin | `GET /providers/lidarr/options` | The profiles and root folders that Lidarr offers, to choose the ones artists are sent with. |
| admin | `POST /artists/{id}/lidarr` | Send an artist to your own Lidarr, by its MusicBrainz id, which then looks for the music. Never by name, never by itself. | | admin | `POST /artists/{id}/lidarr` | Send an artist to your own Lidarr, by its MusicBrainz id, which then looks for the music. Never by name, never by itself. |
| signed in | `GET /artists/{id}/lidarr` | Whether Lidarr has the artist and monitors it. | | signed in | `GET /artists/{id}/lidarr` | Whether Lidarr has the artist and monitors it. |
@ -330,7 +394,7 @@ Back up the database and `sonda.toml`. Your music stays wherever you keep it.
## Web app ## 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. 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`): 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`):
@ -340,10 +404,42 @@ npm install
SONDA_URL=http://127.0.0.1:8080 npm run dev # open http://localhost:5173, /api is proxied to Sonda 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, a volume slider with mute (remembered in the browser) 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. Playlists have a page of their own: make one, put a song in it with the button next to any song (or make a new playlist right there), play it, rename it, delete it, move a song up or down and take one out; a song whose files are gone is shown as not available and skipped when the playlist plays. Discover suggests artists from the ones you pick, or from your listening only after you allow it (a dialog says that their names go to Last.fm), explains each score, and keeps your wishlist and the artists you are not interested in. An admin who set up the `lidarr` provider gets a "Request on Lidarr" button on an artist's page and on the Discover cards: it asks first, then sends that one artist to their own Lidarr, which does the downloading (the web app downloads nothing; the page of an artist reads what Lidarr has, the cards ask nothing until you send). An admin also gets an Admin area to add, rename, move and remove libraries and to start a scan (of one library or all, optionally reading every file again) and follow it, and to manage accounts: add one by email, give or take away the admin role, reset a password (which ends that person's sessions) and delete an account. The last admin cannot be changed, and your own account has no buttons there. Providers have a card each that says what the provider is sent: turning one on asks first, the API key is write-only (never shown, and gone from the page once saved), and there are a test of the key, the contact or address, removing what a provider gave, and, for Lidarr, the profiles and root folder to use when an artist is added. The bulk jobs (album covers, artist pictures, artist descriptions) each have a card that says what the job sends and to whom: starting one asks first and says it goes through the whole library, reading everything again is a separate choice, a job whose providers are off cannot be started, and the page follows its progress and can stop it. There are six themes (Sonda, Tokyo Night, Gruvbox dark, Gruvbox light, Dracula and Neon) and two languages (English and Italian), both chosen in Settings. 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, a volume slider with mute (remembered in the browser), the volume evened out by the ReplayGain tags of your files (Settings: song by song, album by album or off; a quiet song is raised, but never so much that its loudest sample would clip, and one with no tags plays as it is) 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. Playlists have a page of their own, shown as cards with a collage of their covers (as the mixes and the smart playlists have): make one, put a song in it with the button next to any song (or make a new playlist right there), play it, rename it, delete it, move a song up or down and take one out; a song whose files are gone is shown as not available and skipped when the playlist plays. Mixes have a page too: a card for each mix, with a collage of the covers of its albums (the ones from your listening first, then one for each genre), and on a mix its songs, Play, Shuffle again (another set of songs) and Save as playlist, which keeps what you see as a playlist of your own. Where a playlist is renamed, and where a smart playlist is edited, a Suggest a name button asks for a name. Smart playlists have their own page too, which begins with the ones Sonda makes for you (ready to play, to keep as a playlist, or to make your own with a click), and then yours: make one with an editor of the rules (genres, format and bitrate, when it was added, your listening and taste, the length, the order and the limit) and a live preview of the songs it gives, play it, shuffle it again (for the random order), keep what you see as a playlist, edit it or delete it; rules by artist and album are in the API only, and an edit keeps them. Discover suggests artists from the ones you pick, or from your listening only after you allow it (a dialog says that their names go to Last.fm), explains each score, and keeps your wishlist and the artists you are not interested in. A suggested artist you do not have shows a letter, not a photo, because a photo is a lookup at the providers: a "Show photo" button on the card asks for that one artist when you press it (the card says it goes to Wikimedia Commons by MusicBrainz id, and says so when there is no free photo). An admin who set up the `lidarr` provider gets a "Request on Lidarr" button on an artist's page and on the Discover cards: it asks first, then sends that one artist to their own Lidarr, which does the downloading (the web app downloads nothing; the page of an artist reads what Lidarr has, the cards ask nothing until you send). An admin also gets an Admin area to add, rename, move and remove libraries and to start a scan (of one library or all, optionally reading every file again) and follow it, and to manage accounts: add one by email, give or take away the admin role, reset a password (which ends that person's sessions) and delete an account. The last admin cannot be changed, and your own account has no buttons there. Providers have a card each that says what the provider is sent: turning one on asks first, the API key is write-only (never shown, and gone from the page once saved), and there are a test of the key, the contact or address, removing what a provider gave, and, for Lidarr, the profiles and root folder to use when an artist is added. The bulk jobs (album covers, artist pictures, artist descriptions) each have a card that says what the job sends and to whom: starting one asks first and says it goes through the whole library, reading everything again is a separate choice, a job whose providers are off cannot be started, and the page follows its progress and can stop it. The web app is a PWA: it has a manifest and a service worker, so a browser can install it (Settings has an Install button where the browser lets a page ask) and it opens at once from its own icon, and shows its own page when the server cannot be reached. The worker keeps only the files of the app (the page, its scripts and styles, the manifest and the icons) and never anything from `/api/`: the catalog, the covers, the songs and what a person did are private and are not kept. A new version waits until you press Reload, so nothing changes under a song. It needs https, or localhost. The menu on the left folds to a narrow bar with the icons of the pages (a button in it, remembered in the browser; on a phone it stays a row of links). There are six themes (Sonda, Tokyo Night, Gruvbox dark, Gruvbox light, Dracula and Neon) 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). `npm run build` writes to `internal/webui/dist` (git-ignored), not to `web/dist`. 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). `npm run build` writes to `internal/webui/dist` (git-ignored), not to `web/dist`.
## Android app
`android/` holds a small Android app: a Capacitor shell that opens a Sonda server in a WebView, with its own icon and no browser bars. It is for a phone whose browser cannot install a PWA. It has no copy of the web app: it shows the one of your server, so a new version of the server is a new version of the app.
- The first time it asks for the address of the server (`music.example.org`, or `http://192.168.1.5:8080`) and remembers it. Settings has Change server, shown only inside the app.
- It trusts the certificate authorities installed on the phone, so a server behind a private CA opens once the CA is installed (Settings, Security, Install a certificate). It also opens a server on plain `http`.
- A WebView has no Media Session API, so the app keeps its own: a notification with the song, its cover and the buttons, and the lock screen and headset buttons work. The music goes on with the screen off. From Android 13 it asks to show notifications; without a yes the music still plays and only the notification is hidden.
To build it you need Node, a JDK 21 and the Android SDK (platform 36 and its build tools; set `ANDROID_HOME`):
```bash
cd android
npm ci
npm run apk # android/android/app/build/outputs/apk/debug/app-debug.apk
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```
The APK is signed with the debug key, which is fine for your own phone. It is not part of the release pipeline, because the runner has no Android SDK. `npm test` checks how an address typed by hand is read.
## Releases
Every merge into `main` can make a release, by itself (`.forgejo/workflows/release.yml`, [semantic-release](https://semantic-release.gitbook.io)). The next version comes from the messages of the commits since the last one, written as [Conventional Commits](https://www.conventionalcommits.org):
| Commit | Release |
|---|---|
| `fix: ...`, `perf: ...` | patch (0.2.0 to 0.2.1) |
| `feat: ...` | minor (0.2.0 to 0.3.0) |
| `feat!: ...`, or `BREAKING CHANGE:` in the body | major (0.2.0 to 1.0.0) |
| `docs:`, `test:`, `chore:`, `ci:`, `style:` | none by themselves |
A release adds its entry to [CHANGELOG.md](CHANGELOG.md), tags the commit (`v0.3.0`), makes the release on the forge, and the image is built from the tag and pushed to `git.kmalloc.org/squid/sonda` as `0.3.0`, `0.3` and `latest`. The version is inside the binary: `GET /version` and the User-Agent of the providers say it (a build that no release made says `dev`). The commit that writes `CHANGELOG.md` says `[skip ci]`. The image is made for amd64 and for arm64, and each tag points at both. The runner has no Docker and cannot emulate ARM, so the images are built with [kaniko](https://github.com/GoogleContainerTools/kaniko): the Go program is compiled for ARM with no emulation, the last stage of the Dockerfile runs no command, and a last job (with [crane](https://github.com/google/go-containerregistry)) says the architecture of each image and joins them. The workflow needs the secret `FORGEJO_TOKEN`: a token of the owner with the scopes `write:repository` and `write:package`.
## Development ## Development
```bash ```bash
@ -373,11 +469,14 @@ internal/library/ libraries, the scanner, the event hub, the tag reader
internal/about/ descriptions of artists, from Wikipedia through MusicBrainz and Wikidata internal/about/ descriptions of artists, from Wikipedia through MusicBrainz and Wikidata
internal/discovery/ similar artists: what the providers said, kept and refreshed internal/discovery/ similar artists: what the providers said, kept and refreshed
internal/providers/ external providers: settings, the outbound HTTP client, the clients of the providers internal/providers/ external providers: settings, the outbound HTTP client, the clients of the providers
internal/naming/ names for lists of songs: a local namer, and Claude when it is on
internal/listening/ listen events internal/listening/ listen events
internal/taste/ what the listener likes, learned from the listening history 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/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/feedback/ the wishlist and the artists a user is not interested in
internal/playlists/ the playlists of each user internal/playlists/ the playlists of each user
internal/mixes/ the mixes made for a listener, by genre and by listening
internal/smart/ smart playlists: rules that are worked out into songs
internal/images/ covers made from the pictures in the user's own files internal/images/ covers made from the pictures in the user's own files
internal/usersettings/ the settings that belong to one user internal/usersettings/ the settings that belong to one user
internal/storage/ SQLite and PostgreSQL through bun, the repositories internal/storage/ SQLite and PostgreSQL through bun, the repositories
@ -393,4 +492,4 @@ Migrations are plain SQL files in `migrations/sqlite` and `migrations/postgres`.
## Third-party code ## Third-party code
Audio tags are read with `go.senan.xyz/taglib`, which embeds [TagLib](https://github.com/taglib/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](https://github.com/swagger-api/swagger-ui) (Apache-2.0). The other dependencies are listed in `go.mod`. Audio tags are read with `go.senan.xyz/taglib`, which embeds [TagLib](https://github.com/taglib/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](https://github.com/swagger-api/swagger-ui) (Apache-2.0). The other dependencies are listed in `go.mod`. The Milkdrop pictures of the player are drawn by [butterchurn](https://github.com/jberg/butterchurn) and [butterchurn-presets](https://github.com/jberg/butterchurn-presets) (both MIT), bundled in the web app. The shape of a song is found with `github.com/hajimehoshi/go-mp3` (Apache-2.0) and `github.com/eaburns/flac` (MIT), two decoders written in Go.

14
android/.gitignore vendored Normal file
View file

@ -0,0 +1,14 @@
node_modules/
# Build output and local settings of the Android project
android/.gradle/
android/build/
android/app/build/
android/local.properties
android/.idea/
android/captures/
android/app/src/main/assets/public/
android/app/src/main/assets/capacitor.config.json
android/app/src/main/assets/capacitor.plugins.json
android/capacitor-cordova-android-plugins/
*.keystore
*.jks

101
android/android/.gitignore vendored Normal file
View file

@ -0,0 +1,101 @@
# Using Android gitignore template: https://github.com/github/gitignore/blob/HEAD/Android.gitignore
# Built application files
*.apk
*.aar
*.ap_
*.aab
# Files for the ART/Dalvik VM
*.dex
# Java class files
*.class
# Generated files
bin/
gen/
out/
# Uncomment the following line in case you need and you don't have the release build type files in your app
# release/
# Gradle files
.gradle/
build/
# Local configuration file (sdk path, etc)
local.properties
# Proguard folder generated by Eclipse
proguard/
# Log Files
*.log
# Android Studio Navigation editor temp files
.navigation/
# Android Studio captures folder
captures/
# IntelliJ
*.iml
.idea/workspace.xml
.idea/tasks.xml
.idea/gradle.xml
.idea/assetWizardSettings.xml
.idea/dictionaries
.idea/libraries
# Android Studio 3 in .gitignore file.
.idea/caches
.idea/modules.xml
# Comment next line if keeping position of elements in Navigation Editor is relevant for you
.idea/navEditor.xml
# Keystore files
# Uncomment the following lines if you do not want to check your keystore files in.
#*.jks
#*.keystore
# External native build folder generated in Android Studio 2.2 and later
.externalNativeBuild
.cxx/
# Google Services (e.g. APIs or Firebase)
# google-services.json
# Freeline
freeline.py
freeline/
freeline_project_description.json
# fastlane
fastlane/report.xml
fastlane/Preview.html
fastlane/screenshots
fastlane/test_output
fastlane/readme.md
# Version control
vcs.xml
# lint
lint/intermediates/
lint/generated/
lint/outputs/
lint/tmp/
# lint/reports/
# Android Profiling
*.hprof
# Cordova plugins for Capacitor
capacitor-cordova-android-plugins
# Copied web assets
app/src/main/assets/public
# Generated Config files
app/src/main/assets/capacitor.config.json
app/src/main/assets/capacitor.plugins.json
app/src/main/res/xml/config.xml

2
android/android/app/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
/build/*
!/build/.npmkeep

View file

@ -0,0 +1,55 @@
apply plugin: 'com.android.application'
android {
namespace = "app.sonda"
compileSdk = rootProject.ext.compileSdkVersion
defaultConfig {
applicationId "app.sonda"
minSdkVersion rootProject.ext.minSdkVersion
targetSdkVersion rootProject.ext.targetSdkVersion
versionCode 1
versionName "1.0"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
aaptOptions {
// Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
// Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
}
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
repositories {
flatDir{
dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
}
}
dependencies {
implementation fileTree(include: ['*.jar'], dir: 'libs')
implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
implementation "androidx.coordinatorlayout:coordinatorlayout:$androidxCoordinatorLayoutVersion"
implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
implementation "androidx.media:media:1.7.0"
implementation project(':capacitor-android')
testImplementation "junit:junit:$junitVersion"
androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
implementation project(':capacitor-cordova-android-plugins')
}
apply from: 'capacitor.build.gradle'
try {
def servicesJSON = file('google-services.json')
if (servicesJSON.text) {
apply plugin: 'com.google.gms.google-services'
}
} catch(Exception e) {
logger.info("google-services.json not found, google-services plugin not applied. Push Notifications won't work")
}

View file

@ -0,0 +1,19 @@
// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_21
targetCompatibility JavaVersion.VERSION_21
}
}
apply from: "../capacitor-cordova-android-plugins/cordova.variables.gradle"
dependencies {
implementation project(':capacitor-app')
}
if (hasProperty('postBuildExtras')) {
postBuildExtras()
}

21
android/android/app/proguard-rules.pro vendored Normal file
View file

@ -0,0 +1,21 @@
# Add project specific ProGuard rules here.
# You can control the set of applied configuration files using the
# proguardFiles setting in build.gradle.
#
# For more details, see
# http://developer.android.com/guide/developing/tools/proguard.html
# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
# public *;
#}
# Uncomment this to preserve the line number information for
# debugging stack traces.
#-keepattributes SourceFile,LineNumberTable
# If you keep the line number information, uncomment this to
# hide the original source file name.
#-renamesourcefileattribute SourceFile

View file

@ -0,0 +1,50 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:networkSecurityConfig="@xml/network_security_config"
android:supportsRtl="true"
android:theme="@style/AppTheme">
<activity
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"
android:name=".MainActivity"
android:label="@string/title_activity_main"
android:theme="@style/AppTheme.NoActionBarLaunch"
android:launchMode="singleTask"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<service
android:name=".MediaService"
android:exported="false"
android:foregroundServiceType="mediaPlayback" />
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_paths"></meta-data>
</provider>
</application>
<!-- Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
</manifest>

View file

@ -0,0 +1,24 @@
package app.sonda;
import android.os.Bundle;
import android.webkit.WebView;
import com.getcapacitor.BridgeActivity;
public class MainActivity extends BridgeActivity {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
WebView web = getBridge().getWebView();
web.addJavascriptInterface(new SondaNative(this), "SondaNative");
// The buttons of the notification and of the lock screen go back to the page.
MediaService.listener = (name, ms) -> web.post(() -> web.evaluateJavascript(
"window.sondaNativeAction && window.sondaNativeAction('" + name + "'," + ms + ")", null));
}
@Override
public void onDestroy() {
MediaService.listener = null;
if (isFinishing()) MediaService.end(this);
super.onDestroy();
}
}

View file

@ -0,0 +1,219 @@
package app.sonda;
import android.app.Notification;
import android.app.NotificationChannel;
import android.app.NotificationManager;
import android.app.PendingIntent;
import android.app.Service;
import android.content.Context;
import android.content.Intent;
import android.content.pm.ServiceInfo;
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
import android.os.Build;
import android.os.IBinder;
import android.support.v4.media.MediaMetadataCompat;
import android.support.v4.media.session.MediaSessionCompat;
import android.support.v4.media.session.PlaybackStateCompat;
import androidx.core.app.NotificationCompat;
import androidx.core.content.ContextCompat;
import androidx.media.app.NotificationCompat.MediaStyle;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
/**
* Keeps the playback alive while the screen is off or another app is in front, and shows what plays with its
* controls in a notification and on the lock screen. The web app does the playing; this only mirrors it, and
* passes the buttons back through {@link #listener}.
*/
public class MediaService extends Service {
/** Where a press of a button goes: the name is play, pause, next, previous or seekto. */
interface Listener {
void onAction(String name, long ms);
}
static volatile Listener listener;
private static final String CHANNEL = "playback";
private static final int NOTIFICATION_ID = 1;
private static final String PLAY = "app.sonda.PLAY";
private static final String PAUSE = "app.sonda.PAUSE";
private static final String NEXT = "app.sonda.NEXT";
private static final String PREVIOUS = "app.sonda.PREVIOUS";
// The latest word of the page, kept here because the service may start after it was said.
private static NowPlaying latest;
private static MediaService instance;
private MediaSessionCompat session;
private String artworkUrl = "";
private Bitmap artwork;
/** Shows what plays. The first time it starts the service; after that it only updates it. */
static void show(Context context, NowPlaying now) {
latest = now;
if (instance != null) {
instance.apply(now);
} else {
ContextCompat.startForegroundService(context, new Intent(context, MediaService.class));
}
}
/** Nothing plays any more: the notification goes. */
static void end(Context context) {
latest = null;
if (instance != null) instance.shutDown();
else context.stopService(new Intent(context, MediaService.class));
}
@Override
public void onCreate() {
super.onCreate();
instance = this;
createChannel();
session = new MediaSessionCompat(this, "Sonda");
session.setCallback(new MediaSessionCompat.Callback() {
@Override public void onPlay() { send("play", 0); }
@Override public void onPause() { send("pause", 0); }
@Override public void onSkipToNext() { send("next", 0); }
@Override public void onSkipToPrevious() { send("previous", 0); }
@Override public void onSeekTo(long pos) { send("seekto", pos); }
});
}
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
String action = intent == null ? null : intent.getAction();
if (PLAY.equals(action)) send("play", 0);
else if (PAUSE.equals(action)) send("pause", 0);
else if (NEXT.equals(action)) send("next", 0);
else if (PREVIOUS.equals(action)) send("previous", 0);
if (latest != null) {
apply(latest);
} else {
// Started with nothing to show, or after the app was killed: Android wants a notification anyway, then it goes.
startForeground(NOTIFICATION_ID, notification(null));
shutDown();
}
return START_NOT_STICKY;
}
/** The person swiped the app away: the page is gone, so the music and its notification go too. */
@Override
public void onTaskRemoved(Intent rootIntent) {
latest = null;
shutDown();
}
@Override
public void onDestroy() {
instance = null;
if (session != null) {
session.setActive(false);
session.release();
session = null;
}
super.onDestroy();
}
@Override
public IBinder onBind(Intent intent) {
return null;
}
private void send(String name, long ms) {
Listener l = listener;
if (l != null) l.onAction(name, ms);
}
private void shutDown() {
stopForeground(STOP_FOREGROUND_REMOVE);
stopSelf();
}
private void apply(NowPlaying now) {
session.setMetadata(
new MediaMetadataCompat.Builder()
.putString(MediaMetadataCompat.METADATA_KEY_TITLE, now.title)
.putString(MediaMetadataCompat.METADATA_KEY_ARTIST, now.artist)
.putString(MediaMetadataCompat.METADATA_KEY_ALBUM, now.album)
.putLong(MediaMetadataCompat.METADATA_KEY_DURATION, now.durationMs)
.putBitmap(MediaMetadataCompat.METADATA_KEY_ALBUM_ART, now.artworkUrl.equals(artworkUrl) ? artwork : null)
.build());
long actions = PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE | PlaybackStateCompat.ACTION_PLAY_PAUSE
| PlaybackStateCompat.ACTION_SKIP_TO_NEXT | PlaybackStateCompat.ACTION_SKIP_TO_PREVIOUS | PlaybackStateCompat.ACTION_SEEK_TO;
session.setPlaybackState(
new PlaybackStateCompat.Builder()
.setActions(actions)
.setState(now.playing ? PlaybackStateCompat.STATE_PLAYING : PlaybackStateCompat.STATE_PAUSED, now.positionNow(), now.playing ? 1f : 0f)
.build());
session.setActive(true);
Notification n = notification(now);
if (Build.VERSION.SDK_INT >= 29) {
startForeground(NOTIFICATION_ID, n, ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK);
} else {
startForeground(NOTIFICATION_ID, n);
}
if (!now.artworkUrl.isEmpty() && !now.artworkUrl.equals(artworkUrl)) fetchArtwork(now.artworkUrl);
}
private Notification notification(NowPlaying now) {
NotificationCompat.Builder b = new NotificationCompat.Builder(this, CHANNEL)
.setSmallIcon(R.drawable.ic_stat_sonda)
.setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
.setOnlyAlertOnce(true)
.setShowWhen(false)
.setContentIntent(PendingIntent.getActivity(
this, 0, new Intent(this, MainActivity.class).setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP), PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT));
if (now == null) return b.setContentTitle("Sonda").build();
b.setContentTitle(now.title).setContentText(now.artist).setSubText(now.album);
if (now.artworkUrl.equals(artworkUrl) && artwork != null) b.setLargeIcon(artwork);
b.addAction(android.R.drawable.ic_media_previous, getString(R.string.previous), button(PREVIOUS));
if (now.playing) b.addAction(android.R.drawable.ic_media_pause, getString(R.string.pause), button(PAUSE));
else b.addAction(android.R.drawable.ic_media_play, getString(R.string.play), button(PLAY));
b.addAction(android.R.drawable.ic_media_next, getString(R.string.next), button(NEXT));
b.setStyle(new MediaStyle().setMediaSession(session.getSessionToken()).setShowActionsInCompactView(0, 1, 2));
return b.build();
}
private PendingIntent button(String action) {
return PendingIntent.getService(
this, action.hashCode(), new Intent(this, MediaService.class).setAction(action), PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT);
}
private void createChannel() {
if (Build.VERSION.SDK_INT < 26) return;
NotificationChannel channel = new NotificationChannel(CHANNEL, getString(R.string.channel_playback), NotificationManager.IMPORTANCE_LOW);
channel.setShowBadge(false);
getSystemService(NotificationManager.class).createNotificationChannel(channel);
}
/** The cover comes from the server with the token in its address; a cover that does not come leaves the notification without one. */
private void fetchArtwork(String url) {
artworkUrl = url;
artwork = null;
new Thread(() -> {
Bitmap bitmap = null;
try {
HttpURLConnection c = (HttpURLConnection) new URL(url).openConnection();
c.setConnectTimeout(8000);
c.setReadTimeout(8000);
try (InputStream in = c.getInputStream()) {
bitmap = BitmapFactory.decodeStream(in);
} finally {
c.disconnect();
}
} catch (Exception ignored) {
// No cover: the notification stays as it is.
}
final Bitmap result = bitmap;
ContextCompat.getMainExecutor(this).execute(() -> {
if (instance != this || !url.equals(artworkUrl) || result == null) return;
artwork = result;
if (latest != null) apply(latest);
});
}).start();
}
}

View file

@ -0,0 +1,51 @@
package app.sonda;
import android.os.SystemClock;
import org.json.JSONException;
import org.json.JSONObject;
/** What the web app says is playing: the song, whether it plays and where it is. */
final class NowPlaying {
final String title;
final String artist;
final String album;
final String artworkUrl;
final boolean playing;
final long durationMs;
private final long positionMs;
private final long receivedAt;
private NowPlaying(String title, String artist, String album, String artworkUrl, boolean playing, long positionMs, long durationMs) {
this.title = title;
this.artist = artist;
this.album = album;
this.artworkUrl = artworkUrl;
this.playing = playing;
this.positionMs = positionMs;
this.durationMs = durationMs;
this.receivedAt = SystemClock.elapsedRealtime();
}
/** Where the song is now: what the page said, plus the time that has passed if it plays. */
long positionNow() {
long position = playing ? positionMs + (SystemClock.elapsedRealtime() - receivedAt) : positionMs;
return durationMs > 0 ? Math.min(position, durationMs) : position;
}
/** The JSON the page sends; null when it is not what was expected. */
static NowPlaying parse(String json) {
try {
JSONObject o = new JSONObject(json);
return new NowPlaying(
o.optString("title"),
o.optString("artist"),
o.optString("album"),
o.optString("artworkUrl"),
o.optBoolean("playing"),
Math.max(0, o.optLong("positionMs")),
Math.max(0, o.optLong("durationMs")));
} catch (JSONException e) {
return null;
}
}
}

View file

@ -0,0 +1,47 @@
package app.sonda;
import android.Manifest;
import android.app.Activity;
import android.content.pm.PackageManager;
import android.os.Build;
import android.webkit.JavascriptInterface;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
/**
* What the web page can ask of the app. A WebView has no Media Session API, so the page tells the app what plays
* and the app keeps a notification with the controls, and the playback alive while the screen is off.
* It is on every page the WebView loads, which is the server the person chose.
*/
final class SondaNative {
private final Activity activity;
private boolean askedForNotifications = false;
SondaNative(Activity activity) {
this.activity = activity;
}
@JavascriptInterface
public void update(String json) {
NowPlaying now = NowPlaying.parse(json);
if (now == null) return;
activity.runOnUiThread(() -> {
askForNotifications();
MediaService.show(activity, now);
});
}
@JavascriptInterface
public void stop() {
activity.runOnUiThread(() -> MediaService.end(activity));
}
/** From Android 13 a notification needs a yes. Without it the playback goes on, only the notification is hidden. */
private void askForNotifications() {
if (askedForNotifications || Build.VERSION.SDK_INT < 33) return;
askedForNotifications = true;
if (ContextCompat.checkSelfPermission(activity, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(activity, new String[] {Manifest.permission.POST_NOTIFICATIONS}, 1);
}
}
}

View file

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
android:width="24dp"
android:height="24dp"
android:viewportWidth="24"
android:viewportHeight="24">
<path
android:fillColor="#FFFFFFFF"
android:pathData="M12,3v10.55c-0.59,-0.34 -1.27,-0.55 -2,-0.55 -2.21,0 -4,1.79 -4,4s1.79,4 4,4 4,-1.79 4,-4V7h4V3h-6z" />
</vector>

View file

@ -0,0 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
<item>
<color android:color="#08161D" />
</item>
</layer-list>

View file

@ -0,0 +1,12 @@
<?xml version="1.0" encoding="utf-8"?>
<androidx.coordinatorlayout.widget.CoordinatorLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity">
<WebView
android:layout_width="match_parent"
android:layout_height="match_parent" />
</androidx.coordinatorlayout.widget.CoordinatorLayout>

Some files were not shown because too many files have changed in this diff Show more