diff --git a/.dockerignore b/.dockerignore index 60587d7..15c247d 100644 --- a/.dockerignore +++ b/.dockerignore @@ -17,7 +17,6 @@ Dockerfile .dockerignore compose.yaml README.md -docs # AI agent instruction files: never part of the project's files, wherever they are **/agent.md diff --git a/.forgejo/workflows/release.yml b/.forgejo/workflows/release.yml deleted file mode 100644 index 023f628..0000000 --- a/.forgejo/workflows/release.yml +++ /dev/null @@ -1,138 +0,0 @@ -# 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 diff --git a/.releaserc.json b/.releaserc.json deleted file mode 100644 index a042e35..0000000 --- a/.releaserc.json +++ /dev/null @@ -1,35 +0,0 @@ -{ - "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" }] - ] -} diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index c54bc8d..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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)) diff --git a/Dockerfile b/Dockerfile index 786dc20..802b1f8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,11 +1,8 @@ # 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 # build below embeds it. Nothing of Node reaches the final image. -FROM --platform=$BUILDPLATFORM node:24-alpine AS web +FROM node:24-alpine AS web WORKDIR /src/web COPY web/package.json web/package-lock.json ./ RUN npm ci @@ -15,13 +12,7 @@ RUN npm run build # 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 # (-tags webui), so sondad serves it on / and the API on /api. -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 +FROM golang:1.27-alpine AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download @@ -29,28 +20,19 @@ COPY cmd ./cmd COPY internal ./internal COPY migrations ./migrations COPY --from=web /src/internal/webui/dist ./internal/webui/dist -# 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 +RUN CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w" -o /out/sondad ./cmd/sondad -# What the image has besides the program (the zones of tzdata, the user, the folders) is made here, on the machine that -# builds. The last stage then runs no command, so it can be built for another architecture with no emulation. -FROM --platform=$BUILDPLATFORM alpine:3.22 AS rootfs -RUN apk add --no-cache tzdata \ - && addgroup -S -g 10001 sonda \ - && adduser -S -u 10001 -G sonda -h /data -H sonda \ - && mkdir -p /out/data /out/music - -FROM ${RUNTIME_BASE} +FROM alpine:3.22 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 + org.opencontainers.image.source="https://codeberg.org/squidd/sonda" +# 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 \ + && adduser -S -u 10001 -G sonda -h /data -H sonda \ + && mkdir -p /data /music \ + && chown sonda:sonda /data COPY --from=build /out/sondad /usr/local/bin/sondad # Everything Sonda writes is under /data: the database and the files it makes (covers, pictures). diff --git a/Makefile b/Makefile index 75ee9da..c2f008f 100644 --- a/Makefile +++ b/Makefile @@ -8,11 +8,8 @@ .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 - CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w -X main.version=$(VERSION)" -o bin/sondad ./cmd/sondad + CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w" -o bin/sondad ./cmd/sondad web: cd web && npm ci && npm run build diff --git a/README.md b/README.md index 2742a5e..301a895 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,393 @@ Sonda is a privacy-first, self-hosted music server written in Go. It streams the It is a single executable, one database (SQLite by default, PostgreSQL if you prefer) and the folders that hold your music. There is no Redis, no message broker and no cloud account. -> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Suggestions of new artists work too (Discover). Other apps can connect over OpenSubsonic (see [Other apps](docs/opensubsonic.md)), and the web client in `web/`, which `sondad` serves, is young (see [What is not there yet](docs/features/README.md#what-is-not-there-yet) and [Web app](docs/web-app.md)). The API may still change. +> **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. -## Quick start +## What works today -With Docker (the image is on the registry of git.kmalloc.org, for amd64 and arm64): +- **Accounts.** An account is an email address and a password. The first user to register becomes the admin and registration then closes; admins create the other users. The address only identifies the account: Sonda sends no mail, does not check that the address exists, and keeps it on your server. It is trimmed and lowercased, and unique. Accounts made before addresses were asked for keep the plain name they had as their login. Short-lived access tokens (JWT) plus rotating refresh tokens, so a stolen refresh token is detected. +- **Libraries.** A library is a name and a folder, managed through the API. Sonda only reads your music folders: it never writes or renames a file, and it deletes one only when an admin asks to remove the extra copy of a song and you turned on `library.allow_delete` (see **Duplicates**), which is off by default. +- **Scanner.** Reads MP3 and FLAC tags and audio properties with several workers in parallel. Rescans are incremental, renamed files keep their identity, vanished files are flagged (never deleted), and a library whose folder looks empty or unreadable (an unmounted NAS) is left alone instead of being wiped. Audio in other formats (m4a, ogg, opus, wav, wma and similar) is not read yet, but it is counted as `unsupported` in the scan result instead of disappearing silently. NAS housekeeping folders (`@Recycle`, `#recycle`, `@eaDir`, `.@__thumb`, `$RECYCLE.BIN`) are skipped. +- **Catalog.** Browse and search artists, albums and tracks, with paging, by library, artist or album. Only tracks 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. +- **Streaming.** `GET` and `HEAD` with `Range` support, so players can seek. Opening or prefetching a stream does not record a listen. +- **API documentation.** The full API is described in OpenAPI and browsable with Swagger UI, served by Sonda itself. The UI is embedded in the binary, so opening it contacts no other server. +- **Listening history.** Clients report explicit `play`, `complete` and `skip` events. An event counts as a listen when it is `complete`, or when it was played for at least 20 seconds (`listening.min_listen_seconds`); the rule is applied when the history is read, so changing it re-reads the past. You can read your own history, with a `counted` flag on every event. It stays in your database and is never sent anywhere. +- **Your taste.** `GET /me/taste` shows what Sonda has learned from your own listening: the artists you like and the kinds of music (tags) they have in common. A complete listen counts for more than a short one, a skip counts against the artist, and older listens weigh less (they halve every 90 days, `taste.half_life_days`; only the last ten half-lives are read). It is worked out on every request from data already in your database; nothing is sent to any provider. +- **Discover.** `GET /discover` suggests artists you may like, in your library or not, each with a score from 0 to 1 and the parts it is made of: how close it is to the artists you like (affinity), how close its tags are to yours (genre), what your listening says about it (preference) and a bonus for what you have not played (discovery). The weights are in `[scoring]` in the config. A part with no data is left out and the rest rescaled, and every answer says which seeds led to each suggestion. It starts from the artists you name with `?seed=`, or, only if you turned on `discover_from_listening`, from the artists you play most. It needs Last.fm to be 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. +- **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 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). +- **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 `` 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. +- **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. +- **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. + +## 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, the bulk jobs and the duplicates. + +## Requirements + +- Go 1.27 or newer to build. The binary needs nothing else: SQLite and the tag reader are compiled in, with no CGO and no system libraries. +- `curl` and [`jq`](https://jqlang.github.io/jq/) for the demo below. +- Optional: `ffmpeg`, only to generate a few test tones for the demo. + +## Build ```bash +make build # the web app (needs Node), then bin/sondad with the app inside +``` + +`make build` runs `npm ci` and `npm run build` in `web/`, which writes the app to `internal/webui/dist`, and then builds `sondad` with the tag `webui`, which embeds it: one program that serves the app on `/` and the API on `/api`. You can do the same by hand: `(cd web && npm ci && npm run build) && go build -tags webui -o bin/sondad ./cmd/sondad`. + +A plain `go build -o bin/sondad ./cmd/sondad` needs no Node and gives the API only; `/` then shows a page that says how to build the app. `make test` runs the Go tests and the web tests. + +### Docker + +The image holds `sondad` with the web app inside, and nothing else: it builds the app itself, so you need no Node on your machine. It runs as an ordinary user, keeps the database and the files Sonda makes under `/data`, listens on port 8080 inside the container, and does not start without `SONDA_JWT_SECRET`. + +```bash +docker build -t sonda . (umask 077; echo "SONDA_JWT_SECRET=$(openssl rand -hex 32)" > sonda.env) # once: keep this file docker run -d --name sonda --restart unless-stopped --stop-timeout 15 \ -p 127.0.0.1:8080:8080 \ --env-file sonda.env \ -v sonda-data:/data \ -v "$HOME/Music":/music:ro \ - git.kmalloc.org/squid/sonda:latest + sonda ``` -Open `http://127.0.0.1:8080`, create the first account (it becomes the admin), then add a library with the path `/music`. To build from source, or for Compose, see [Install](docs/install.md). +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. -## Documentation +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. -- **Set it up:** [Install](docs/install.md) · [Configuration](docs/configuration.md) · [Demo](docs/demo.md) · [Security and backups](docs/operations.md) -- **Use it:** [Features](docs/features/README.md) · [Web app](docs/web-app.md) · [Android app](docs/android.md) · [OpenSubsonic apps](docs/opensubsonic.md) · [External providers](docs/providers.md) -- **Build on it:** [The API at a glance](docs/api.md) · [Development and releases](docs/development.md) · [CHANGELOG](CHANGELOG.md) +`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. -The full API is also described in OpenAPI and served by Sonda itself at `/api/docs/`. +If you prefer a config file to environment variables (it can hold the secret and the other settings, so a Docker or Compose secret can provide it), put a `sonda.toml` in `/data` or pass `--config /run/secrets/sonda.toml`; the variables the image sets still win over the file. + +## Configure + +Sonda reads `./sonda.toml`, or the file given with `--config`. Every key has a default except the secret. + +```bash +cp sonda.example.toml sonda.toml +# Put a random secret in it (32 characters or more). Edit the file by hand if your sed differs. +sed -i "s|^jwt_secret = .*|jwt_secret = \"$(openssl rand -hex 32)\"|" sonda.toml +``` + +`sonda.toml` is git-ignored because it holds the secret. Keep it readable only by the user that runs Sonda (`chmod 600 sonda.toml`). + +Precedence is: built-in defaults, then the file, then environment variables. An unknown key in the file is an error, so a typo cannot be ignored silently. + +| Key | Environment variable | Default | Meaning | +|---|---|---|---| +| `server.listen` | `SONDA_LISTEN` | `127.0.0.1:8080` | Address to listen on. Localhost by default. | +| `library.scan_workers` | | `4` | Files whose tags are read in parallel during a scan. | +| `library.allow_delete` | `SONDA_ALLOW_DELETE` | `false` | Lets an admin delete the extra copy of a song from the music folders (see **Duplicates**). It is the one thing that makes Sonda write there, so it needs the folders mounted writable. A value that is not `true` or `false` is an error. | +| `database.driver` | `SONDA_DB_DRIVER` | `sqlite` | `sqlite` or `postgres`. | +| `database.path` | `SONDA_DB_PATH` | `sonda.db` | SQLite file (driver `sqlite`). | +| `database.dsn` | `SONDA_DB_DSN` | | Connection string (driver `postgres`). | +| `log.env` | `SONDA_ENV` | `production` | `production` logs JSON; `dev` logs readable text. | +| `auth.jwt_secret` | `SONDA_JWT_SECRET` | *(required)* | Signs access tokens. At least 32 characters. | +| `auth.access_ttl_minutes` | | `15` | Lifetime of an access token. | +| `auth.refresh_ttl_hours` | | `720` | Lifetime of a refresh token (30 days). | +| `listening.min_listen_seconds` | | `20` | A play counts as a listen after this long (1 to 3600), or when it is `complete`. | +| `taste.half_life_days` | | `90` | After this many days a listen weighs half as much when learning your taste (1 to 3650). | +| `wikipedia.languages` | | `["en"]` | Languages for artist descriptions, best first: one to five codes of two or three lower case letters. | +| `storage.data_dir` | `SONDA_DATA_DIR` | `data` next to the SQLite database (`data` in the working directory with PostgreSQL) | Where Sonda keeps the files it makes (covers). They are built from your music, so they need no backup. | +| `scoring.weight_affinity`, `weight_genre`, `weight_preference`, `weight_discovery` | | `0.40`, `0.25`, `0.25`, `0.10` | The weights of the parts of a Discover score (0 to 10 each, not all zero). Only their proportions matter. | + +Libraries and the external providers are not in the config: you set them up through the API (see the demo and [External providers](#external-providers)). + +### Using PostgreSQL + +```toml +[database] +driver = "postgres" +dsn = "postgres://user:password@localhost:5432/sonda?sslmode=disable" +``` + +Sonda creates and migrates its tables on start. The storage tests run against both databases. + +## Demo + +This takes you from an empty database to streaming a track. Run the server in one terminal and the commands in another. + +**1. Get some music.** Point `MUSIC` at a folder of MP3 or FLAC files. The path must be absolute. If you have none, generate two 30-second test tones: + +```bash +export MUSIC="$HOME/Music" +mkdir -p "$MUSIC/demo" +ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=440:duration=30" -metadata title="Tone A" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=1 "$MUSIC/demo/a.mp3" +ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=660:duration=30" -metadata title="Tone B" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=2 "$MUSIC/demo/b.flac" +``` + +**2. Start the server** (after the Build and Configure steps above): + +```bash +./bin/sondad +``` + +**3. Check it is up, create the first user, and log in:** + +```bash +BASE=http://127.0.0.1:8080/api/v1 + +curl -s $BASE/health + +# The first user becomes the admin; registration is then closed. +curl -s -X POST $BASE/auth/register -d '{"email":"alice@example.org","password":"correct horse battery"}' + +LOGIN=$(curl -s -X POST $BASE/auth/login -d '{"email":"alice@example.org","password":"correct horse battery"}') +TOKEN=$(echo "$LOGIN" | jq -r .access_token) +REFRESH=$(echo "$LOGIN" | jq -r .refresh_token) +AUTH="Authorization: Bearer $TOKEN" +``` + +**4. Add a library and scan it:** + +```bash +curl -s -X POST $BASE/libraries -H "$AUTH" -d "{\"name\":\"Music\",\"path\":\"$MUSIC\"}" | jq + +curl -s -X POST $BASE/library/scan -H "$AUTH" +until [ "$(curl -s $BASE/library/scan -H "$AUTH" | jq .running)" = false ]; do sleep 1; done +curl -s $BASE/library/scan -H "$AUTH" | jq .last +``` + +`found`, `added`, `unchanged`, `renamed`, `missing`, `failed` and `unsupported` tell you what the scan did. Run it again and everything is `unchanged`. + +**5. Browse and search:** + +```bash +curl -s "$BASE/artists?limit=5" -H "$AUTH" | jq +curl -s "$BASE/albums" -H "$AUTH" | jq '.items[] | {id, title, artist: .artist.name, tracks: .track_count}' +curl -s "$BASE/tracks?q=tone" -H "$AUTH" | jq '.items[] | {id, title, artists: [.artists[].name], format}' +``` + +**6. Stream a track:** + +```bash +TRACK=$(curl -s "$BASE/tracks?limit=1" -H "$AUTH" | jq -r '.items[0].id') + +# Ask for the first 100 bytes: the answer is 206 Partial Content with a Content-Range header. +curl -s -D - -o /dev/null -H "$AUTH" -H 'Range: bytes=0-99' $BASE/tracks/$TRACK/stream + +# The whole file. +curl -s -o track.audio -H "$AUTH" $BASE/tracks/$TRACK/stream +``` + +A browser `