Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
511c723041 | ||
|
|
11077f40e1 | ||
| e11ce89b21 | |||
| d57fbe3ef1 | |||
|
|
ba10b8ef7b | ||
|
|
995f2e5ae0 | ||
|
|
a2d6d2a925 | ||
| f6a3cd6b5e | |||
| 23845391d4 | |||
|
|
6220238068 | ||
| 85a1f9dc8a | |||
| 755220d08a | |||
|
|
a757743161 | ||
| 5eff98a639 | |||
| 95f9be70bd | |||
|
|
75a7898c68 | ||
|
|
ee31e0ee7c | ||
| 43200dda05 | |||
| 2e194da4e3 | |||
|
|
b37e3db037 | ||
| dae5118354 | |||
| 3490849837 | |||
|
|
9905c4788f | ||
|
|
a478c95536 | ||
| 985bd3ed13 | |||
|
|
89f1b5275a | ||
| 1b58f8412c | |||
|
|
482644a7bf | ||
| ab05ec081f | |||
|
|
ed32aac228 | ||
| 8e278f04c2 | |||
|
|
0b3bf8d49f | ||
| f146a94368 | |||
|
|
407b20334a | ||
| e37f1165ae | |||
|
|
d6064763e7 | ||
| e77b014437 | |||
|
|
4052ab8ce1 | ||
| ea2478b786 | |||
|
|
9bf6fd0039 | ||
| c5f548e74e | |||
|
|
ca5cbbf088 | ||
| 84b61ce6aa | |||
|
|
a93260af05 | ||
| f7c24fa6f4 | |||
|
|
74f683d26e | ||
| 17c134ef8b | |||
|
|
a0dc4458ef | ||
| 2cb67b1bdc | |||
|
|
ccee5e8719 | ||
| 90d1b7949f | |||
|
|
1ae8e77d81 | ||
| 32214127c9 | |||
|
|
010f2e5057 | ||
| 9451765861 | |||
|
|
08c83c948f | ||
| c52386f335 | |||
| e6af9a118e | |||
|
|
d51f155a4d | ||
|
|
0742ee88a9 | ||
|
|
14710c3a55 | ||
|
|
a880b87a9e | ||
|
|
00e5254fde | ||
|
|
69c85a7b52 | ||
|
|
c4982d85c3 | ||
|
|
9c636fa65a | ||
|
|
32dd307535 | ||
|
|
8be9e93551 | ||
|
|
78f3f7ec9e | ||
|
|
0fb57fe4f0 | ||
|
|
3512f0cbaa | ||
|
|
fee06e2bb9 | ||
|
|
af933ad9ea | ||
|
|
d31d4da1bd | ||
|
|
b2549336ba | ||
|
|
2b6e80fda6 | ||
|
|
9f63121028 | ||
|
|
9ce7beb42d | ||
|
|
7c961028bb | ||
|
|
7b18478fe4 | ||
|
|
3ba087bcc5 | ||
|
|
01cbab21be | ||
|
|
aa4883b955 | ||
|
|
83b578ea4c | ||
|
|
c08a234159 | ||
|
|
2bc74b2d26 | ||
|
|
a92326c1b4 | ||
|
|
e9f85c2f39 | ||
|
|
d29d824f56 | ||
|
|
a507741460 | ||
|
|
8263e0ca43 | ||
|
|
f3ab8f0c8e | ||
|
|
246cdc63d3 | ||
|
|
2f1a86dedb | ||
|
|
d3695d00d6 | ||
|
|
6028d8e686 | ||
|
|
a7a258464b | ||
|
|
2962698baa | ||
|
|
4ede6d4118 | ||
|
|
58a596c88e | ||
|
|
0dc7782028 | ||
|
|
7aa822f6bb | ||
|
|
1d19e014a3 | ||
|
|
f25d8f0dcf | ||
|
|
ce3c8598c8 | ||
|
|
f17d9eb66d | ||
|
|
7243fe7a04 | ||
|
|
1736fc5a29 | ||
|
|
3647c88723 | ||
|
|
9c2c5ba884 | ||
|
|
226ee72900 | ||
|
|
d207787575 | ||
|
|
69ec2abc1c | ||
|
|
7a9aeab7d1 | ||
|
|
35dabf48ef | ||
|
|
cacb30d5ae | ||
|
|
1a03f70059 | ||
|
|
17a37b11f0 | ||
|
|
bfa3e6e458 | ||
|
|
f99d2bddcc | ||
|
|
fdf1ebfabc | ||
|
|
adc3aa2832 | ||
|
|
945aaf1a05 | ||
|
|
9b81b6385a | ||
|
|
7f38ae038e | ||
|
|
ae2ceb2190 | ||
|
|
29bd46c3ba | ||
|
|
8702ff9786 | ||
|
|
89826fcd07 | ||
|
|
346466c621 | ||
|
|
695a012f6c | ||
|
|
822f6094e5 | ||
|
|
3ade5e80d5 | ||
|
|
cded6f063e | ||
|
|
f0135cc548 | ||
|
|
a423632632 | ||
|
|
817b869af7 | ||
|
|
a80ead7f2b | ||
|
|
3ac61faa88 | ||
|
|
36dffc2ed1 | ||
|
|
82f9ee39cc | ||
|
|
2217a12042 | ||
|
|
f86b5a3d7b | ||
|
|
7e46c38245 | ||
|
|
7e3e40a896 | ||
|
|
82b92eaf08 | ||
|
|
0d69ae48de | ||
|
|
a1e192066c | ||
|
|
75577e1fdb | ||
|
|
1b79a7370d | ||
|
|
84b6937bbf | ||
|
|
0d8fadadf6 | ||
|
|
0dddfb741e | ||
|
|
bf5c108785 | ||
|
|
322b6e5530 | ||
|
|
9e666d2b29 | ||
|
|
23ae396430 | ||
|
|
2b7635c936 | ||
|
|
4810564aac | ||
|
|
ca63fc4701 | ||
|
|
17f70d582d | ||
|
|
b598842c6d | ||
|
|
1ad0d718c8 | ||
|
|
0e489bda1f | ||
|
|
a2938f0f96 | ||
|
|
a607070149 | ||
|
|
7981edacb6 | ||
|
|
104e41d10a | ||
|
|
25f41dd5fc | ||
|
|
4b3618fa07 | ||
|
|
6b40ea06fa | ||
|
|
5b9f98d8ed | ||
|
|
19fa5ff9ce | ||
|
|
16fda24ff5 | ||
|
|
94dbf57544 |
629 changed files with 65640 additions and 5852 deletions
|
|
@ -17,6 +17,7 @@ Dockerfile
|
||||||
.dockerignore
|
.dockerignore
|
||||||
compose.yaml
|
compose.yaml
|
||||||
README.md
|
README.md
|
||||||
|
docs
|
||||||
|
|
||||||
# AI agent instruction files: never part of the project's files, wherever they are
|
# AI agent instruction files: never part of the project's files, wherever they are
|
||||||
**/agent.md
|
**/agent.md
|
||||||
|
|
|
||||||
138
.forgejo/workflows/release.yml
Normal file
138
.forgejo/workflows/release.yml
Normal 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
35
.releaserc.json
Normal 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
46
CHANGELOG.md
Normal 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))
|
||||||
42
Dockerfile
42
Dockerfile
|
|
@ -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).
|
||||||
|
|
|
||||||
5
Makefile
5
Makefile
|
|
@ -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
|
||||||
|
|
|
||||||
383
README.md
383
README.md
|
|
@ -4,393 +4,32 @@ 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.
|
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). Other apps can connect over OpenSubsonic (see [Other apps](docs/opensubsonic.md)), and the web client in `web/`, which `sondad` serves, is young (see [What is not there yet](docs/features/README.md#what-is-not-there-yet) and [Web app](docs/web-app.md)). The API may still change.
|
||||||
|
|
||||||
## What works today
|
## Quick start
|
||||||
|
|
||||||
- **Accounts.** An account is an email address and a password. The first user to register becomes the admin and registration then closes; admins create the other users. The address only identifies the account: Sonda sends no mail, does not check that the address exists, and keeps it on your server. It is trimmed and lowercased, and unique. Accounts made before addresses were asked for keep the plain name they had as their login. Short-lived access tokens (JWT) plus rotating refresh tokens, so a stolen refresh token is detected.
|
With Docker (the image is on the registry of git.kmalloc.org, for amd64 and arm64):
|
||||||
- **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 `<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.
|
|
||||||
- **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
|
```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
|
(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.
|
Open `http://127.0.0.1:8080`, create the first account (it becomes the admin), then add a library with the path `/music`. To build from source, or for Compose, see [Install](docs/install.md).
|
||||||
|
|
||||||
To keep the data in a folder of the host instead of a volume, run the container as the owner of that folder, or it cannot write there: add `--user "$(id -u):$(id -g)"` and `-v /path/to/sonda-data:/data`. Back up `sonda.db` (and treat the backup like a secret: it holds the API keys of the providers); the rest of `/data` is built from your music.
|
## Documentation
|
||||||
|
|
||||||
`compose.yaml` is the same as an example: put `SONDA_JWT_SECRET` and `MUSIC_DIR` (and `SONDA_PORT` if 8080 is taken) in a `.env` file next to it and run `docker compose up -d --build`. The image has a health check on `/api/v1/health`, which is logged at debug level when it succeeds.
|
- **Set it up:** [Install](docs/install.md) · [Configuration](docs/configuration.md) · [Demo](docs/demo.md) · [Security and backups](docs/operations.md)
|
||||||
|
- **Use it:** [Features](docs/features/README.md) · [Web app](docs/web-app.md) · [Android app](docs/android.md) · [OpenSubsonic apps](docs/opensubsonic.md) · [External providers](docs/providers.md)
|
||||||
|
- **Build on it:** [The API at a glance](docs/api.md) · [Development and releases](docs/development.md) · [CHANGELOG](CHANGELOG.md)
|
||||||
|
|
||||||
If you prefer a config file to environment variables (it can hold the secret and the other settings, so a Docker or Compose secret can provide it), put a `sonda.toml` in `/data` or pass `--config /run/secrets/sonda.toml`; the variables the image sets still win over the file.
|
The full API is also described in OpenAPI and served by Sonda itself at `/api/docs/`.
|
||||||
|
|
||||||
## 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 `<audio>` element cannot send headers, so the stream URL also accepts the access token in the query string: `$BASE/tracks/$TRACK/stream?access_token=$TOKEN`. That is the only route that does, and the query string is never logged.
|
|
||||||
|
|
||||||
**7. Report a listen.** Streaming never counts as a listen. The player reports one event per play, when the play ends or is abandoned, with the time actually played. Use one idempotency key per play: a retry with the same key is harmless, but a key that was already used is ignored even if the event differs, so an event cannot be upgraded later. An event counts as a listen when it is `complete` or lasted at least the configured minimum (20 seconds by default); a shorter play is stored too, but does not count:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"play\",\"duration_played_ms\":25000,\"idempotency_key\":\"demo-1\"}"
|
|
||||||
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"play\",\"duration_played_ms\":3000,\"idempotency_key\":\"demo-2\"}"
|
|
||||||
|
|
||||||
# Your history, newest first. Add ?counted=true to see only what counts.
|
|
||||||
curl -s "$BASE/listens" -H "$AUTH" | jq '.items[] | {track: .track.title, event_type, duration_played_ms, counted}'
|
|
||||||
```
|
|
||||||
|
|
||||||
The answer to each report says whether it counts. A reported play time far beyond the length of the track (more than twice its length plus 10 seconds) is rejected.
|
|
||||||
|
|
||||||
**8. Refresh the session and log out:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
NEW=$(curl -s -X POST $BASE/auth/refresh -d "{\"refresh_token\":\"$REFRESH\"}")
|
|
||||||
TOKEN=$(echo "$NEW" | jq -r .access_token)
|
|
||||||
REFRESH=$(echo "$NEW" | jq -r .refresh_token)
|
|
||||||
AUTH="Authorization: Bearer $TOKEN"
|
|
||||||
|
|
||||||
curl -s -X POST $BASE/auth/logout -d "{\"refresh_token\":\"$REFRESH\"}"
|
|
||||||
```
|
|
||||||
|
|
||||||
Each refresh token works once. Presenting a spent one again, more than ten seconds after it was used, ends every session of that user.
|
|
||||||
|
|
||||||
**9. Add another user** (admins only):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
TOKEN=$(curl -s -X POST $BASE/auth/login -d '{"email":"alice@example.org","password":"correct horse battery"}' | jq -r .access_token)
|
|
||||||
AUTH="Authorization: Bearer $TOKEN"
|
|
||||||
curl -s -X POST $BASE/users -H "$AUTH" -d '{"email":"bob@example.org","password":"another long password"}' | jq
|
|
||||||
```
|
|
||||||
|
|
||||||
## External providers
|
|
||||||
|
|
||||||
Sonda can ask Last.fm, MusicBrainz, Wikipedia, Wikimedia Commons and the Cover Art Archive about artists and albums, 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.
|
|
||||||
- **MusicBrainz** needs no key, but it asks every client to identify itself with a contact (a URL or an e-mail address) in the `User-Agent`. By default Sonda uses the address of the project, so no personal address is sent unless you choose to.
|
|
||||||
|
|
||||||
Set them up with `PUT /api/v1/providers/{name}` (admin), for example:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -s -X PUT $BASE/providers/lastfm -H "$AUTH" -d '{"api_key":"<your 32 character key>"}'
|
|
||||||
curl -s -X PUT $BASE/providers/lastfm -H "$AUTH" -d '{"enabled":true}'
|
|
||||||
curl -s $BASE/providers -H "$AUTH" | jq
|
|
||||||
curl -s -X POST $BASE/providers/lastfm/test -H "$AUTH" | jq # does the key work?
|
|
||||||
curl -s -X PUT $BASE/providers/musicbrainz -H "$AUTH" -d '{"enabled":true,"contact":"https://example.org/me"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Lidarr** is not a source of data but a server of your own that looks for and downloads music. Sonda never downloads, searches for or chooses music: with the `lidarr` provider an admin can send an artist, by its MusicBrainz id and never by name, to *your* Lidarr, which then does what you set it up to do. Nothing is sent by itself, and only an admin sends. It needs the address of your Lidarr and its API key (Settings, General), then you pick, once, from what Lidarr offers:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
curl -s -X PUT $BASE/providers/lidarr -H "$AUTH" -d '{"url":"http://orion:8686","api_key":"<the 32 character key of Lidarr>"}'
|
|
||||||
curl -s -X POST $BASE/providers/lidarr/test -H "$AUTH" | jq # does the key work?
|
|
||||||
curl -s $BASE/providers/lidarr/options -H "$AUTH" | jq # profiles and root folders to choose from
|
|
||||||
curl -s -X PUT $BASE/providers/lidarr -H "$AUTH" -d '{"lidarr":{"quality_profile_id":1,"metadata_profile_id":1,"root_folder_path":"/music","monitor":"all","search_missing":true}}'
|
|
||||||
curl -s -X PUT $BASE/providers/lidarr -H "$AUTH" -d '{"enabled":true}'
|
|
||||||
```
|
|
||||||
|
|
||||||
Then an admin sends an artist with one request, for any artist that has a MusicBrainz id, **including one that Sonda only learned of from Discover and that is not in your library**, which is the point: asking for music you do not have. Anyone signed in can see whether Lidarr has it:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
curl -s -X POST $BASE/artists/<id>/lidarr -H "$AUTH" | jq # {"status":"added"} or {"status":"already_added"}
|
|
||||||
curl -s $BASE/artists/<id>/lidarr -H "$AUTH" | jq # {"provider_status":"ok","in_lidarr":true,"monitored":true}
|
|
||||||
```
|
|
||||||
|
|
||||||
Sending is explicit, for one artist, never automatic, and can be repeated: an artist that Lidarr already has changes nothing. If Lidarr does not answer in time the artist may have been added all the same, so read it before sending again.
|
|
||||||
|
|
||||||
The address can have a path if Lidarr runs under a URL base, and it cannot carry a user, a password or a query: the key is sent in a header, never in the address, and Sonda never follows a redirect, so it cannot go anywhere else (if your `http://` address redirects to `https://`, set the `https://` one) and never goes through a proxy named by the environment, since Lidarr is on your own network. `lidarr` replaces all its options at once; what it leaves out is `monitor` `all` and `search_missing` `true`. The folder of an artist that Lidarr downloads shows up in Lidarr's root folder only with the first import: add that folder as a library of Sonda yourself, and a scan finds the new files.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**Similar artists.** `GET /api/v1/artists/{id}/similar` asks Last.fm for the artists similar to an artist (one of yours, or one Last.fm named earlier) and keeps the answer in your database: 7 days, or 1 day when Last.fm does not know the artist. Until then a second look costs nothing and sends nothing, and if Last.fm is down you still get the last answer, marked `stale`. If the provider is off the answer says `disabled` instead of failing. Each similar artist says whether you have it (`in_library`); the ones you do not have are stored as artists without files. They can be opened with `GET /artists/{id}` but are never part of your artist lists, and if you later add their music, the scan finds them there. Last.fm's `score` is relative to each answer (the best one is usually 1), so compare artists only inside one answer.
|
|
||||||
|
|
||||||
**Tags.** `GET /api/v1/artists/{id}/tags` asks each provider that is on, at the same time, and keeps the answers with the same rules (7 days, 1 for an unknown artist, old data if a provider fails). Each provider has its own entry with its own weights: Last.fm's are relative to the artist (1 to 100), MusicBrainz's are counts of votes, and they are never mixed. MusicBrainz also marks the tags it lists as genres. Its tags and genres are CC BY-NC-SA, so show the `attribution` that comes with them.
|
|
||||||
|
|
||||||
**Genres from your own files.** The scan also reads the genre tag of each file (several genres separated by `;`, at most five per file) and `GET /artists/{id}/tags` adds a `files` entry: the genres of the playable tracks the artist is credited on, each weighted by how many tracks have it. It needs no provider, asks nobody, and is always there.
|
|
||||||
|
|
||||||
**MusicBrainz ids come from your files, never from a guess.** If your files carry MusicBrainz artist ids in their tags (taggers like Picard write them), the scan reads them, offline, and keeps them on your artists, but only when each id can be paired with its artist for certain. MusicBrainz is asked only about artists whose id is known; for the others its entry says `no_id`. Sonda never searches MusicBrainz 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.
|
|
||||||
|
|
||||||
The artist is sent to Last.fm by its MusicBrainz id when your files gave one (if Last.fm does not know the id, by name), otherwise by its name exactly as it is written in your library, and Sonda never lets Last.fm correct it into another artist. Names and ids from Last.fm are never written onto your own artists.
|
|
||||||
|
|
||||||
## The API at a glance
|
|
||||||
|
|
||||||
Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"error":{"code":"...","message":"..."}}`.
|
|
||||||
|
|
||||||
**Interactive documentation:** open `http://127.0.0.1:8080/api/docs/` in a browser. Use *Authorize* with the `access_token` from the login to try the protected operations. The OpenAPI file itself is at `/api/v1/openapi.yaml`. Both are public, since they describe the API and contain no data.
|
|
||||||
|
|
||||||
| Who | Method and path | What it does |
|
|
||||||
|---|---|---|
|
|
||||||
| anyone | `GET /health` | Liveness check. |
|
|
||||||
| anyone | `POST /auth/register` | Create the first user (admin). Closed afterwards. |
|
|
||||||
| anyone | `POST /auth/login`, `/auth/refresh`, `/auth/logout` | Open, renew and end a session. |
|
|
||||||
| signed in | `GET /auth/me`, `POST /auth/password` | Your account; change your password (signs you out everywhere). |
|
|
||||||
| signed in | `GET /artists`, `/albums`, `/tracks` and `/…/{id}` | Browse and search. Query: `q`, `limit` (default 50, max 200), `offset`, `library_id`, `artist_id`, `album_id`. |
|
|
||||||
| signed in | `GET /artists/{id}/tags` | What Last.fm and MusicBrainz say about the artist's kind of music, from each provider that is on. |
|
|
||||||
| signed in | `GET`, `HEAD /artists/{id}/image`, `GET /artists/{id}/image/credit` | A free picture of the artist from Wikimedia Commons (query `size=small\|large`, also `?access_token=`) and its credit. |
|
|
||||||
| signed in | `GET /artists/{id}/description` | What Wikipedia says about the artist, with its page and licence, from the Wikipedia provider when an admin switched it on. |
|
|
||||||
| signed in | `GET /artists/{id}/similar` | Artists similar to one, from Last.fm when an admin switched it on. Query: `limit` (default 20, max 50). |
|
|
||||||
| signed in | `GET`, `HEAD /tracks/{id}/stream` | Stream the original file. Also accepts `?access_token=`. |
|
|
||||||
| signed in | `POST /listens` | Record a `play`, `complete` or `skip`; the answer says whether it counts as a listen. |
|
|
||||||
| signed in | `GET /listens` | Your own history, newest first, with `counted` per event. Query: `limit`, `offset`, `counted=true`. |
|
|
||||||
| signed in | `GET /discover` | Artists you may like, with a score and its parts. Query: `seed` (an artist id, up to 5 times), `limit` (default 20, max 30), `in_library=true\|false`. |
|
|
||||||
| signed in | `GET`, `HEAD /albums/{id}/cover` | The cover of an album, a JPEG made from your own files. Query: `size=small\|large`. Also accepts `?access_token=`. |
|
|
||||||
| signed in | `GET /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 /wishlist`, `PUT /wishlist/{id}`, `DELETE /wishlist/{id}` | Your wishlist: list it (query `limit`, `offset`), add an artist, take one off. |
|
|
||||||
| signed in | `GET /discover/dismissed`, `POST /discover/{id}/dismiss`, `DELETE /discover/{id}/dismiss` | The artists you are not interested in: list them, dismiss one, bring it back. |
|
|
||||||
| signed in | `GET /me/taste` | The artists and tags Sonda learned you like, from your own listening. Query: `limit` (default 20, max 50). |
|
|
||||||
| signed in | `GET /me/settings`, `PATCH /me/settings` | Your own settings (today: `discover_from_listening`, off by default). |
|
|
||||||
| signed in | `GET /library/covers`, `GET /library/artist-images`, `GET /library/descriptions` | Progress of the job that builds the covers, looks for the artist pictures or for the artist descriptions, and how the last one ended. |
|
|
||||||
| signed in | `GET /library/scan` | Scan status and the last result. |
|
|
||||||
| admin | `GET`, `POST /libraries`; `PATCH`, `DELETE /libraries/{id}` | Manage libraries. Deleting one removes its index entries, never your files. |
|
|
||||||
| admin | `POST`, `DELETE /library/covers`; `POST`, `DELETE /library/artist-images`; `POST`, `DELETE /library/descriptions` | Start, in the background, a job that builds the cover of every album, looks for the picture of every artist or for the description of every artist (`?refresh=true` for all), or stop it. One of each at a time. |
|
|
||||||
| admin | `POST /library/scan`, `POST /libraries/{id}/scan` | Scan everything, or one library. `?full=true` reads every file again. |
|
|
||||||
| admin | `GET /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/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. |
|
|
||||||
| signed in | `GET /artists/{id}/lidarr` | Whether Lidarr has the artist and monitors it. |
|
|
||||||
| admin | `GET`, `POST /users`; `PATCH`, `DELETE /users/{id}`; `PUT /users/{id}/password` | Manage users and the admin role. The last admin cannot be demoted or deleted. |
|
|
||||||
|
|
||||||
A library path must be an absolute, existing folder, never the filesystem root, and never inside or around another library. Search is a case- and accent-insensitive substring match: `bjork`, `BJORK` and `BJÖRK` all find `Björk`, and `strasse` finds `Straße`. Accents still tell artists apart: `Beyoncé` and `Beyonce` stay two artists, and a search for either finds both.
|
|
||||||
|
|
||||||
## Security notes
|
|
||||||
|
|
||||||
- Sonda listens on localhost only, unless you change `server.listen`. To use it from other machines, put it behind a reverse proxy that terminates HTTPS.
|
|
||||||
- Passwords are hashed with Argon2id. Refresh tokens are stored only as hashes. An access token is checked against the database on every request, so it stops working as soon as its account is deleted, even if the same user id is given to a new account.
|
|
||||||
- Music folders are read-only to Sonda, except for one thing that is off until you turn it on: deleting the extra copy of a song (`library.allow_delete`). Streaming and that deletion open files through `os.Root`, so a path can never leave its library, even if a symlink is swapped in later.
|
|
||||||
- File paths are never returned by the catalog, and audio file paths are not logged.
|
|
||||||
- Provider API keys are write-only through the API and never logged. They sit in the database, so protect your backups.
|
|
||||||
|
|
||||||
## Back up
|
|
||||||
|
|
||||||
Back up the database and `sonda.toml`. Your music stays wherever you keep it.
|
|
||||||
|
|
||||||
- **SQLite:** `sqlite3 sonda.db ".backup sonda-backup.db"` works while Sonda runs. Or stop Sonda and copy `sonda.db` (and `sonda.db-wal` if it exists).
|
|
||||||
- **PostgreSQL:** `pg_dump` the database.
|
|
||||||
- `sonda.toml` holds the secret that signs tokens; treat the copy like a password.
|
|
||||||
|
|
||||||
## Web app
|
|
||||||
|
|
||||||
A web client lives in `web/` (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. 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.
|
|
||||||
|
|
||||||
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`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd web
|
|
||||||
npm install
|
|
||||||
SONDA_URL=http://127.0.0.1:8080 npm run dev # open http://localhost:5173, /api is proxied to Sonda
|
|
||||||
```
|
|
||||||
|
|
||||||
What it does today: sign in (and create the first account of a new server), browse artists, albums and songs, search, and play with a queue, shuffle, repeat, media keys, 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. The Duplicates section lists the songs that are in more than one file, with a row for each copy (album, format, bitrate, size) and whether the files are byte for byte the same once the check has read them. The copy Sonda would keep is already chosen and you can choose another; "Delete the others" (one song) and "Clean all suggestions" (every song shown) ask first, list every file that stays and every file that goes with the space freed, and go song by song, stopping at the first refusal and saying why. With `library.allow_delete` off, which is the default, everything is shown and the delete buttons are disabled, and the page says how to turn it on. 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`.
|
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
```bash
|
|
||||||
go vet ./...
|
|
||||||
go test -race ./...
|
|
||||||
```
|
|
||||||
|
|
||||||
The default test run needs no network and uses SQLite only. To run the same storage tests against PostgreSQL as well, start a throwaway server and point the tests at it:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker run -d --rm --name sonda-test-pg -e POSTGRES_PASSWORD=sonda -e POSTGRES_DB=sonda -p 127.0.0.1:55432:5432 postgres:17-alpine
|
|
||||||
SONDA_TEST_POSTGRES_DSN='postgres://postgres:sonda@127.0.0.1:55432/sonda?sslmode=disable' go test -race ./...
|
|
||||||
docker rm -f sonda-test-pg
|
|
||||||
```
|
|
||||||
|
|
||||||
Tests that read real audio need `ffmpeg` and are skipped when it is missing.
|
|
||||||
|
|
||||||
Layout:
|
|
||||||
|
|
||||||
```
|
|
||||||
cmd/sondad/ the server: wiring, config, logging, shutdown
|
|
||||||
internal/api/http/ the REST API (thin handlers) and the docs routes
|
|
||||||
internal/api/openapi/ the OpenAPI spec, embedded in the binary
|
|
||||||
internal/auth/ users, roles, passwords, access and refresh tokens
|
|
||||||
internal/catalog/ browsing and searching artists, albums, tracks
|
|
||||||
internal/library/ libraries, the scanner, the event hub, the tag reader
|
|
||||||
internal/about/ descriptions of artists, from Wikipedia through MusicBrainz and Wikidata
|
|
||||||
internal/discovery/ similar artists: what the providers said, kept and refreshed
|
|
||||||
internal/providers/ external providers: settings, the outbound HTTP client, the clients of the providers
|
|
||||||
internal/listening/ listen events
|
|
||||||
internal/taste/ what the listener likes, learned from the listening history
|
|
||||||
internal/discover/ the score of an artist you may like, and the suggestions
|
|
||||||
internal/feedback/ the wishlist and the artists a user is not interested in
|
|
||||||
internal/playlists/ the playlists of each user
|
|
||||||
internal/images/ covers made from the pictures in the user's own files
|
|
||||||
internal/usersettings/ the settings that belong to one user
|
|
||||||
internal/storage/ SQLite and PostgreSQL through bun, the repositories
|
|
||||||
internal/streaming/ opening a track's file safely
|
|
||||||
migrations/ SQL migrations, one folder per database
|
|
||||||
web/ the web client (React, Vite, shadcn/ui)
|
|
||||||
Dockerfile, compose.yaml the image of sondad, and an example for Docker Compose
|
|
||||||
```
|
|
||||||
|
|
||||||
The API description is `internal/api/openapi/openapi.yaml`, written by hand and embedded in the binary. Two tests keep it in step with the code: one fails when a route and the spec disagree in either direction, and a contract test sends real requests through every operation and validates each response (status, headers, JSON body) against the spec. Adding or changing an endpoint therefore means updating the spec in the same change. Response objects are closed (`additionalProperties: false`), so a field added in the code and forgotten in the spec fails the build.
|
|
||||||
|
|
||||||
Migrations are plain SQL files in `migrations/sqlite` and `migrations/postgres`. They must describe the same schema, and a test checks that both folders hold the same files. Add a new numbered file to both whenever the schema changes.
|
|
||||||
|
|
||||||
## Third-party code
|
## 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
14
android/.gitignore
vendored
Normal 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
101
android/android/.gitignore
vendored
Normal 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
2
android/android/app/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
/build/*
|
||||||
|
!/build/.npmkeep
|
||||||
55
android/android/app/build.gradle
Normal file
55
android/android/app/build.gradle
Normal 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")
|
||||||
|
}
|
||||||
19
android/android/app/capacitor.build.gradle
Normal file
19
android/android/app/capacitor.build.gradle
Normal 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
21
android/android/app/proguard-rules.pro
vendored
Normal 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
|
||||||
50
android/android/app/src/main/AndroidManifest.xml
Normal file
50
android/android/app/src/main/AndroidManifest.xml
Normal 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>
|
||||||
|
|
@ -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();
|
||||||
|
}
|
||||||
|
}
|
||||||
219
android/android/app/src/main/java/app/sonda/MediaService.java
Normal file
219
android/android/app/src/main/java/app/sonda/MediaService.java
Normal 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();
|
||||||
|
}
|
||||||
|
}
|
||||||
51
android/android/app/src/main/java/app/sonda/NowPlaying.java
Normal file
51
android/android/app/src/main/java/app/sonda/NowPlaying.java
Normal 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;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
47
android/android/app/src/main/java/app/sonda/SondaNative.java
Normal file
47
android/android/app/src/main/java/app/sonda/SondaNative.java
Normal 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);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
10
android/android/app/src/main/res/drawable/ic_stat_sonda.xml
Normal file
10
android/android/app/src/main/res/drawable/ic_stat_sonda.xml
Normal 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>
|
||||||
6
android/android/app/src/main/res/drawable/splash.xml
Normal file
6
android/android/app/src/main/res/drawable/splash.xml
Normal 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>
|
||||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue