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
4.3 KiB
Sharing and other apps
Everything here is off until you turn it on.
-
Sharing on Mastodon.
PUT /me/mastodonconnects your own Mastodon account (the address of your instance and an access token that can only write posts);GETshows which account is connected andDELETEforgets 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/mastodonsaysproblem: 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; plainhttponly on a network of your own); the server then makes its own Ed25519 key, kept in the database and never returned.POST /federation/invitesmakes an invite that works once and expires in 24 hours (only a hash of its code is kept). The other admin uses it withPOST /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 asoutgoinguntil the first admin approves it withPOST /federation/friends/{id}/approve(POST /federation/friends/{id}/checklets the waiting side find out). Either side can remove a friend withDELETE /federation/friends/{id}. Nothing is shared until an admin turns onsharedfor 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 withRange. 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 withGET /friends(the names of the friends whose friendship both admins agreed to, never an address or a key) andGET /friends/{friend}/artists,albumsandtrackswithq,limitandoffset, 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 withGET /friends/{friend}/tracks/{id}/streamand sees its covers withGET /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, forwardsRangeand the conditional headers, and passes on only audio (or a JPEG for a cover) withContent-Type,Content-Length,Content-Range,Accept-Ranges,Last-ModifiedandETag, 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).