sonda/docs/features/sharing.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.3 KiB

Sharing and other apps

Features · Sonda

Everything here is off until you turn it on.

  • Sharing on Mastodon. PUT /me/mastodon connects your own Mastodon account (the address of your instance and an access token that can only write posts); GET shows which account is connected and DELETE forgets it and the token. Nothing is connected by default. Once it is, each song of this server that counts as a listen is posted to your account as an unlisted status with the title, artists, album and #NowPlaying, and no link: at most one post a minute, never music of a friend. The token stays on the server and is never sent back. If the instance refuses the token on a post (it was revoked or expired), GET /me/mastodon says problem: token_refused, Settings shows it, and nothing is posted until you connect again with a new token. The address of the instance must be a domain name on https, and the server never connects to a private, loopback or link-local address for it, never follows a redirect and ignores proxy settings.

  • Friends (federation). Two Sonda servers can become friends, and the listeners of one can read what the other chose to share. PUT /federation (admin) turns federation on, which is off by default, and gives this server a name and a public address (https; plain http only on a network of your own); the server then makes its own Ed25519 key, kept in the database and never returned. POST /federation/invites makes an invite that works once and expires in 24 hours (only a hash of its code is kept). The other admin uses it with POST /federation/friends: that server is asked to accept this one, the key it answers with must be the one named in the invite, and the friend waits as outgoing until the first admin approves it with POST /federation/friends/{id}/approve (POST /federation/friends/{id}/check lets the waiting side find out). Either side can remove a friend with DELETE /federation/friends/{id}. Nothing is shared until an admin turns on shared for a library (PATCH /libraries/{id}). A friend's server then reads, with requests signed by its key (the method, the path and query, a date, a nonce and the hash of the body), the routes under /peer: the artists, albums and songs that have a file in a shared library, their covers once they are built, and the audio itself with Range. A friend never sees a path, a library id, a listen, a taste or a user, never makes this server build a cover or ask a provider, and has a few streams at a time and a number of KiB a second to share (max_streams, max_kib_per_sec); the admin sees the last requests it made (GET /federation/requests, the route and the size, never what was searched for). Sharing a library lets friends play it and, in practice, copy its files. A listener browses the music of a friend with GET /friends (the names of the friends whose friendship both admins agreed to, never an address or a key) and GET /friends/{friend}/artists, albums and tracks with q, limit and offset, and one item at a time: this server asks the friend with a signed request, checks the shape of the answer and passes it on, and nothing is kept; the ids are the friend's own. A friend that cannot be reached or no longer takes this server for a friend is told in words. The web app has a Friends section for it, shown only when there is a friend to browse. A listener plays it with GET /friends/{friend}/tracks/{id}/stream and sees its covers with GET /friends/{friend}/albums/{id}/cover, which accept the access token in the query like the local ones: this server asks the friend with a signed request, forwards Range and the conditional headers, and passes on only audio (or a JPEG for a cover) with Content-Type, Content-Length, Content-Range, Accept-Ranges, Last-Modified and ETag, so the friend sees this server and never the listener, and a friend cannot make this server serve anything else. A friend's song plays in the same player as the others but is never reported as a listen and does not feed taste. The admin area has a Federation section for all of it.

  • Other apps. Apps that speak OpenSubsonic (Symfonium, Feishin, Amperfy, Supersonic and others) can browse, search, play, show covers, use your playlists and report what you listened to, with a password of their own for each app (see Other apps).