sonda/docs/demo.md
tgiachi 11077f40e1
All checks were successful
release / release (push) Successful in 36s
release / base (push) Has been skipped
release / image (amd64) (push) Has been skipped
release / image (arm64) (push) Has been skipped
release / manifest (push) Has been skipped
docs: split the README into pages under docs/
The README had grown to about 500 lines. It now holds the intro, a quick
start and an index, and the rest lives in docs/.

- docs: add docs/README.md as the index of all pages
- docs: move install, configuration, demo, providers, OpenSubsonic, API,
  security and backups, web app, Android app and development/releases
  to their own pages, text unchanged
- docs: split the feature list into five pages under docs/features/
- docs: rewrite internal anchors as links between the new pages
- chore: add docs to .dockerignore, next to README.md
2026-11-17 14:50:52 +01:00

4.7 KiB

Demo

Docs · Sonda

This takes you from an empty database to streaming a song. Run the server in one terminal and the commands in another.

1. Get some music. Point MUSIC at a folder of MP3 or FLAC files. The path must be absolute. If you have none, generate two 30-second test tones:

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):

./bin/sondad

3. Check it is up, create the first user, and log in:

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:

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:

curl -s "$BASE/artists?limit=5" -H "$AUTH" | jq
curl -s "$BASE/albums" -H "$AUTH" | jq '.items[] | {id, title, artist: .artist.name, tracks: .track_count}'
curl -s "$BASE/tracks?q=tone" -H "$AUTH" | jq '.items[] | {id, title, artists: [.artists[].name], format}'

6. Stream a song:

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:

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 song (more than twice its length plus 10 seconds) is rejected.

8. Refresh the session and log out:

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):

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