feat: OpenSubsonic playlists and listens
Apps can use the playlists of a person and report what they listened to. - getPlaylists, getPlaylist, createPlaylist (with songs, or in place of an existing one), updatePlaylist (name, comment, songs to add, places to remove), deletePlaylist: the same playlists as the web app - scrobble records a complete listen once however many times an app tries again, and shares it on Mastodon when the person connected it; a now playing message records nothing; getNowPlaying answers with nothing - README section on connecting other apps
This commit is contained in:
parent
2cb67b1bdc
commit
a0dc4458ef
1 changed files with 838 additions and 3 deletions
34
README.md
34
README.md
|
|
@ -4,7 +4,7 @@ Sonda is a privacy-first, self-hosted music server written in Go. It streams the
|
|||
|
||||
It is a single executable, one database (SQLite by default, PostgreSQL if you prefer) and the folders that hold your music. There is no Redis, no message broker and no cloud account.
|
||||
|
||||
> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Suggestions of new artists work too (Discover). 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). Radio queues are not built yet, other apps can connect over OpenSubsonic (see [Other apps](#other-apps-opensubsonic)), 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.
|
||||
|
||||
## What works today
|
||||
|
||||
|
|
@ -37,9 +37,11 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr
|
|||
- **Similar artists.** With Last.fm turned 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.
|
||||
- **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](#other-apps-opensubsonic)).
|
||||
|
||||
## 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 and the bulk jobs.
|
||||
Radio queues, transcoding, stars (favourites), 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 and the bulk jobs.
|
||||
|
||||
## Requirements
|
||||
|
||||
|
|
@ -282,6 +284,34 @@ The key is stored in the database, in clear text, and is never returned by the A
|
|||
|
||||
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.
|
||||
|
||||
## Other apps (OpenSubsonic)
|
||||
|
||||
Sonda speaks [OpenSubsonic](https://opensubsonic.github.io/docs/) (Subsonic API 1.16.1 and its open extensions) at `/rest`, so the apps that speak it can play your music: Symfonium, Feishin, Amperfy, Supersonic, Tempus, Airsonic Refix and others.
|
||||
|
||||
**Connect an app.**
|
||||
|
||||
1. Open Settings, **Apps and devices**, give the app a name and press **Make password**. The password is shown once: copy it into the app.
|
||||
2. In the app, give the address of your server, your email as the user name, and that password. An app that asks for an API key takes the same password as the key.
|
||||
|
||||
The API has the same: `POST /me/devices` makes a password (and returns it once), `GET /me/devices` lists them with when each was last used, and `DELETE /me/devices/{id}` takes one back. You can have 20.
|
||||
|
||||
A device password opens your music in that app and nothing else: it cannot sign in to Sonda, change your account or make other passwords, and the password of your account does not work in apps. Make one for each app, and take it back in Settings when you lose the phone: that app stops working at once. The passwords are kept sealed with a key derived from `auth.jwt_secret` (Subsonic's token login needs the server to know the password itself, so it cannot be kept as a hash), so changing that secret makes you make them again. An app sends the password in the address of each call: give Sonda a server address on `https`, and do not put these addresses in a log you share.
|
||||
|
||||
**What an app can do.** Calls are answered in JSON (`f=json`) or XML, and a web app on another address can read the answers (`Access-Control-Allow-Origin: *`; what opens a call is the password in it, never a cookie).
|
||||
|
||||
| Calls | What they do |
|
||||
| --- | --- |
|
||||
| `ping`, `getLicense`, `getOpenSubsonicExtensions`, `tokenInfo` | The server says who it is. The extensions need no login. |
|
||||
| `getMusicFolders`, `getArtists`, `getArtist`, `getAlbum`, `getSong`, `getGenres` | Browse your libraries. |
|
||||
| `getAlbumList2` | Random, newest, frequent, recent, by name, by artist, by year, by genre. |
|
||||
| `getRandomSongs`, `getSongsByGenre`, `search3` | Find songs, albums and artists. |
|
||||
| `stream`, `download`, `getCoverArt` | The original file (with Range), and covers of albums, artists and songs. |
|
||||
| `getPlaylists`, `getPlaylist`, `createPlaylist`, `updatePlaylist`, `deletePlaylist` | Your playlists, the same ones as in the web app. |
|
||||
| `scrobble` | A listen is recorded like one made in the web app (and shared on Mastodon if you connected it). A "now playing" message is not recorded. |
|
||||
| `getStarred2`, `star`, `unstar`, `setRating`, `getNowPlaying` | Answered with nothing: there are no stars yet, and what you play is nobody else's business. |
|
||||
|
||||
Sonda does not transcode: an app always gets the original file, whatever format or bit rate it asks for. The music of friends (federation) is not shown to apps.
|
||||
|
||||
## The API at a glance
|
||||
|
||||
Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"error":{"code":"...","message":"..."}}`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue