sonda/internal/api/openapi/openapi.yaml
tgiachi bfa3e6e458 feat: the seek bar shows the waveform of the track
The seek bar of the player is the shape of the track, with the part already
heard in colour, as in the approved mockups.

- GET /tracks/{id}/peaks gives 120 levels from 0 to 255 (the loudest part is
  255 whatever the volume). The server finds them by decoding the file, MP3 with
  go-mp3 and FLAC with eaburns/flac, both in pure Go. It takes a few seconds, so
  the first request starts the work in the background and answers 202 with
  Retry-After. It is done once for each file (migration 0025), worked out again
  if the size or the date of the file change, one track at a time so that a NAS
  is not kept busy, and a file that cannot be decoded is remembered as such. A
  track deleted while its file is being decoded is not an error.
- The seek bar of the player bar and of the full-screen player draws the shape
  and asks again every few seconds until it is there. Until then, and for a
  friend's track, which has none, the bar is flat. The heard part is teal, or
  the friend colour. It is still a native range input, 44 pixels high in the
  bar.
- OpenAPI path and schema, contract test, tests with real MP3 and FLAC files,
  and a real server checked: a 4-minute MP3 is ready in about a second and a
  half, a 12 MB FLAC in three, and asking again takes a millisecond.
2026-11-13 17:35:00 +01:00

5371 lines
231 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

openapi: 3.0.3
info:
title: Sonda API
version: 0.1.0
description: |
Sonda is a privacy-first, self-hosted music server. This is its first-party REST API.
**Authentication.** Log in with `POST /auth/login` and send the access token as
`Authorization: Bearer <token>`. Access tokens are short-lived; renew the session with
`POST /auth/refresh`. Each refresh token works once.
**Roles.** Operations marked *admin* need an account with the admin role. The first user
who registers is the admin.
**Errors.** Every error has the same shape: `{"error": {"code": "...", "message": "..."}}`.
The `code` is stable and meant for programs; the `message` is for people.
**Paging.** Lists take `limit` (default 50, at most 200; a larger value is lowered to 200)
and `offset`, and answer with `items`, `total`, `limit` and `offset`.
servers:
- url: /api/v1
tags:
- name: System
- name: Auth
description: Accounts and sessions.
- name: Users
description: User management (admin).
- name: Libraries
description: Named folders of music (admin).
- name: Scan
description: Indexing the libraries.
- name: Catalog
description: Browsing and searching what can be played.
- name: Playback
description: Streaming and listening history.
- name: Taste
description: What Sonda has learned from your listening, and the settings that are yours.
- name: Playlists
description: Ordered lists of tracks that belong to one user.
- name: Mixes
description: Playlists made for you, from what you listen to and from the genres of your music.
- name: Smart playlists
description: Playlists that are a set of rules, worked out again every time they are opened.
- name: Discovery
description: Music outside the library, from external providers an admin switched on, and suggestions scored for you.
- name: Providers
description: External services Sonda can ask about artists, set up by an admin.
- name: Federation
description: Friend Sonda servers, whose listeners can play the libraries an admin shares (admin).
- name: Friends
description: Browsing the music that a friend's server shares, for any signed-in listener.
paths:
/health:
get:
tags: [System]
operationId: getHealth
summary: Liveness check
responses:
'200':
description: The server is up.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [ok]}
/openapi.yaml:
get:
tags: [System]
operationId: getOpenAPI
summary: This document
responses:
'200':
description: The OpenAPI description of the API.
content:
application/yaml:
schema: {type: string}
/auth/register:
post:
tags: [Auth]
operationId: register
summary: Create the first user
description: |
Only works while no user exists. The new user is the admin. Afterwards registration is
closed and admins create accounts with `POST /users`.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Credentials'}
responses:
'201':
description: The admin account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'400': {$ref: '#/components/responses/InvalidInput'}
'403':
description: A user already exists (`registration_closed`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: The email is already registered (`email_taken`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/auth/login:
post:
tags: [Auth]
operationId: login
summary: Open a session
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/LoginRequest'}
responses:
'200':
description: A new session.
content:
application/json:
schema: {$ref: '#/components/schemas/Session'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401':
description: Wrong email or password (`invalid_credentials`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/auth/refresh:
post:
tags: [Auth]
operationId: refresh
summary: Renew a session
description: |
Exchanges a refresh token for a new access token and a new refresh token. The old refresh
token stops working. Presenting a spent one again, more than ten seconds after it was used,
ends every session of that user; inside those ten seconds it only fails, so two tabs
refreshing together do not log each other out. This holds for any spent token, including
one revoked by logout or by a password change.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RefreshRequest'}
responses:
'200':
description: A new session.
content:
application/json:
schema: {$ref: '#/components/schemas/Session'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401':
description: The refresh token is unknown, expired or already used (`invalid_refresh_token`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/auth/logout:
post:
tags: [Auth]
operationId: logout
summary: End a session
description: Revokes one refresh token. Always answers 204, so it never reveals whether the token existed.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RefreshRequest'}
responses:
'204': {description: Done.}
'400': {$ref: '#/components/responses/InvalidInput'}
/auth/me:
get:
tags: [Auth]
operationId: getMe
summary: The signed-in account
security: [{bearerAuth: []}]
responses:
'200':
description: Your account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'401': {$ref: '#/components/responses/Unauthorized'}
/auth/password:
post:
tags: [Auth]
operationId: changePassword
summary: Change your password
description: |
Revokes every refresh token of the account, so no session can be renewed. An access token
that was already issued keeps working until it expires (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/PasswordChange'}
responses:
'204': {description: Password changed.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403':
description: The current password is wrong (`invalid_credentials`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/users:
get:
tags: [Users]
operationId: listUsers
summary: List users
description: Admin only.
security: [{bearerAuth: []}]
responses:
'200':
description: Every account, oldest first.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [users]
properties:
users:
type: array
items: {$ref: '#/components/schemas/User'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
post:
tags: [Users]
operationId: createUser
summary: Create a user
description: Admin only.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreateUser'}
responses:
'201':
description: The new account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: The email is already registered (`email_taken`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/users/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
patch:
tags: [Users]
operationId: updateUser
summary: Grant or remove the admin role
description: Admin only. The last admin cannot be demoted.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [is_admin]
properties:
is_admin: {type: boolean}
responses:
'200':
description: The updated account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such user (`user_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: This is the last admin (`last_admin`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Users]
operationId: deleteUser
summary: Delete a user
description: |
Admin only. Removes the account and its refresh tokens. Access tokens already issued stop
working at once on admin routes, `/auth/me`, `/auth/password` and `/listens`; other routes
accept them until they expire (15 minutes by default). The last admin cannot be deleted.
security: [{bearerAuth: []}]
responses:
'204': {description: Deleted.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such user (`user_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: This is the last admin (`last_admin`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/users/{id}/password:
parameters:
- {$ref: '#/components/parameters/Id'}
put:
tags: [Users]
operationId: resetUserPassword
summary: Reset a user's password
description: |
Admin only. Revokes every refresh token of that user, so no session can be renewed. Access
tokens already issued keep working until they expire (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [password]
properties:
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
responses:
'204': {description: Password reset.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such user (`user_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/libraries:
get:
tags: [Libraries]
operationId: listLibraries
summary: List libraries
description: Admin only.
security: [{bearerAuth: []}]
responses:
'200':
description: Every library, oldest first.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [libraries]
properties:
libraries:
type: array
items: {$ref: '#/components/schemas/Library'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
post:
tags: [Libraries]
operationId: createLibrary
summary: Add a library
description: |
Admin only. The path must be an absolute, existing directory, never the filesystem root,
and never inside or around another library (a bad path or an overlap is `400 invalid_input`).
A name or path that another library already uses is `409 library_exists`. Names are unique
ignoring case.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/NewLibrary'}
responses:
'201':
description: The new library.
content:
application/json:
schema: {$ref: '#/components/schemas/Library'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: Another library has this name or path (`library_exists`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/libraries/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
patch:
tags: [Libraries]
operationId: updateLibrary
summary: Rename or move a library
description: |
Admin only. Send `name`, `path` or both. Files keep their identity when the path changes.
Changing the path is refused while a scan runs.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/LibraryUpdate'}
responses:
'200':
description: The updated library.
content:
application/json:
schema: {$ref: '#/components/schemas/Library'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404': {$ref: '#/components/responses/LibraryNotFound'}
'409':
description: The name or path is used by another library (`library_exists`), or a scan is running (`scan_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Libraries]
operationId: deleteLibrary
summary: Remove a library
description: |
Admin only. Removes the library and its index entries. Tracks and listening history stay;
the music on disk is never touched. Refused while a scan runs.
security: [{bearerAuth: []}]
responses:
'204': {description: Removed.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404': {$ref: '#/components/responses/LibraryNotFound'}
'409':
description: A scan is running (`scan_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/libraries/{id}/scan:
parameters:
- {$ref: '#/components/parameters/Id'}
post:
tags: [Scan]
operationId: scanLibrary
summary: Scan one library
description: |
Admin only. Starts a scan in the background; follow it with `GET /library/scan`. With
`full=true` every file is read again, not only the new or changed ones.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Full'}
responses:
'202': {$ref: '#/components/responses/ScanStarted'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404': {$ref: '#/components/responses/LibraryNotFound'}
'409':
description: A scan is already running (`scan_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/library/covers:
get:
tags: [Scan]
operationId: getCoversJob
summary: Progress of the job that builds the covers
description: |
Whether the job is running, how far it is (`progress`, only while it runs), and how the last one
ended. The job is described at `POST /library/covers`.
security: [{bearerAuth: []}]
responses:
'200':
description: The job.
content:
application/json:
schema: {$ref: '#/components/schemas/CoversJobStatus'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Scan]
operationId: startCoversJob
summary: Build all the covers in the background
description: |
Admin only. Starts, in the background and one at a time like a scan, a job that builds the
cover of every album that has something to play and no cover that is still good, instead of
waiting for each album to be opened; follow it with `GET /library/covers`. For each album it
does what `GET /albums/{id}/cover` does: the pictures in the user's own files first and, only
if the album has none and an admin switched the `coverartarchive` provider on, the Cover Art
Archive by the release group id of the album's tags. An album whose cover is still good (a
found one for a week, "no cover" for a day) is skipped; send `refresh=true` to search every
album again.
**This goes through the whole library.** With the archive on, it sends
the release group id of every album that has no picture in its files, one after the other and
spaced out. It gives up, and says why in `last_error`, when the provider fails for five albums
in a row, and also when the files cannot be read (an unmounted disk): it never turns that into
"no cover" and never replaces a cover that was built. A cover that came from the archive is kept
when the provider was switched off since, even with `refresh=true`; only taking its data back
(`DELETE /providers/coverartarchive/data`) removes those. `DELETE /library/covers` stops it.
security: [{bearerAuth: []}]
parameters:
- name: refresh
in: query
description: "`true` searches every album again, also those that have a good cover. `false` when absent."
schema: {type: boolean, default: false}
responses:
'202':
description: The job was started in the background.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [started]}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: The job is already running (`covers_job_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'500':
description: The albums could not be counted (`internal`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Scan]
operationId: stopCoversJob
summary: Stop the job that builds the covers
description: |
Admin only. Asks a running job to end after the album it is on (its requests to the provider may still finish); the covers already built stay.
It answers the same when no job is running.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when no job was running."}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/library/artist-images:
get:
tags: [Scan]
operationId: getArtistImagesJob
summary: Progress of the job that looks for the artist pictures
description: |
Whether the job is running, how far it is (`progress`, only while it runs), and how the last one
ended. The job is described at `POST /library/artist-images`.
security: [{bearerAuth: []}]
responses:
'200':
description: The job.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistJobStatus'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Scan]
operationId: startArtistImagesJob
summary: Look for all the artist pictures in the background
description: |
Admin only. Starts, in the background and one at a time like a scan, a job that looks for the
picture of every artist of the library that has a MusicBrainz id and no answer about its
picture that is still good, instead of waiting for each artist to be opened; follow it with
`GET /library/artist-images`. For each artist it does what `GET /artists/{id}/image` does, by
the artist's MusicBrainz id and never by name: MusicBrainz, Wikidata, then a free picture on
Wikimedia Commons. It needs an admin to have switched both the `commons` and the `musicbrainz`
providers on; with either off the job ends at once and says so in `last_error`. Artists with
no id are not touched. A picture is good for 30 days and "no picture" for a week; send
`refresh=true` to search every artist again. A refresh never replaces a stored picture by a
failure.
**This goes through the whole library.** It sends the MusicBrainz id
of every artist, one after the other and spaced out, to MusicBrainz, Wikidata and Commons. It
gives up, and says why in `last_error`, when the providers fail for five artists in a row.
`DELETE /library/artist-images` stops it.
security: [{bearerAuth: []}]
parameters:
- name: refresh
in: query
description: "`true` searches every artist again, also those with a good answer. `false` when absent."
schema: {type: boolean, default: false}
responses:
'202':
description: The job was started in the background.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [started]}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: The job is already running (`artist_images_job_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'500':
description: The artists could not be counted (`internal`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Scan]
operationId: stopArtistImagesJob
summary: Stop the job that looks for the artist pictures
description: |
Admin only. Asks a running job to end after the artist it is on (its requests to the providers may still finish); the pictures already found
stay. It answers the same when no job is running.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when no job was running."}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/library/descriptions:
get:
tags: [Scan]
operationId: getDescriptionsJob
summary: Progress of the job that looks for the artist descriptions
description: |
Whether the job is running, how far it is (`progress`, only while it runs), and how the last one
ended. The job is described at `POST /library/descriptions`.
security: [{bearerAuth: []}]
responses:
'200':
description: The job.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistJobStatus'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Scan]
operationId: startDescriptionsJob
summary: Look for all the artist descriptions in the background
description: |
Admin only. Starts, in the background and one at a time like a scan, a job that looks for the
description of every artist of the library that has a MusicBrainz id and no answer about its
description that is still good; follow it with `GET /library/descriptions`. For each artist it
does what `GET /artists/{id}/description` does, by the artist's MusicBrainz id and never by
name: MusicBrainz, Wikidata, then Wikipedia. It needs an admin to have switched both the
`wikipedia` and the `musicbrainz` providers on; with either off the job ends at once and says
so in `last_error`. Artists with no id are not touched. A description is good for 30 days and
"no description" for a day; send `refresh=true` to read every artist again. A refresh never
replaces a stored description by a failure.
**This goes through the whole library.** It sends the MusicBrainz id
of every artist, one after the other and spaced out, to MusicBrainz, Wikidata and Wikipedia.
It gives up, and says why in `last_error`, when the providers fail for five artists in a row.
`DELETE /library/descriptions` stops it.
security: [{bearerAuth: []}]
parameters:
- name: refresh
in: query
description: "`true` reads every artist again, also those with a good answer. `false` when absent."
schema: {type: boolean, default: false}
responses:
'202':
description: The job was started in the background.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [started]}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: The job is already running (`descriptions_job_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'500':
description: The artists could not be counted (`internal`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Scan]
operationId: stopDescriptionsJob
summary: Stop the job that looks for the artist descriptions
description: |
Admin only. Asks a running job to end after the artist it is on (its requests to the providers may still finish); the descriptions already
found stay. It answers the same when no job is running.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when no job was running."}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/library/duplicates:
get:
tags: [Scan]
operationId: listDuplicates
summary: The songs that are in more than one file
description: |
Admin only. Groups of files that are the same song by the same artists, worked out from the index and
never from the disk, so it is quick and touches no file. Two files are the same song when they have the
same set of main artists, the same title (the key Sonda matches titles by) and durations no more than
3 seconds apart, every pair in a group within that. A file with no duration or no artist never matches,
a file flagged as missing does not count, and a copy may be on a different album: `files` says which.
Each group says which copy Sonda would keep (`suggested_keep_track_id`): the one without loss (FLAC)
before one with loss, then the higher bitrate, then the bigger file, then the oldest. `hashed` is true when
every file of the group has been read by the check (`POST /library/duplicates/check`) and `identical` when,
besides, they are byte for byte the same. No file path is ever returned.
`deletion_allowed` says whether `POST /library/duplicates/clean` can work: with `library.allow_delete`
off (the default) the groups can still be seen.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of groups, in a fixed order (by title).
content:
application/json:
schema: {$ref: '#/components/schemas/DuplicatesPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/library/duplicates/check:
get:
tags: [Scan]
operationId: getDuplicatesCheck
summary: Progress of the check that reads the files of the duplicates
description: |
Whether the check is running, how far it is (`progress`, only while it runs), and how the last one ended.
The check is described at `POST /library/duplicates/check`.
security: [{bearerAuth: []}]
responses:
'200':
description: The job.
content:
application/json:
schema: {$ref: '#/components/schemas/DuplicatesCheckStatus'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
post:
tags: [Scan]
operationId: startDuplicatesCheck
summary: Read the files of the duplicates, to tell which are identical
description: |
Admin only. Starts, in the background and one at a time like a scan, a job that reads every file that is in
a group of copies and keeps its SHA-256, so that a group of files that are byte for byte the same can be
called `identical`. It only reads: nothing is removed or sent anywhere. **It reads whole files**, which on a
network drive takes a while, so it is started on purpose. A file that has a fingerprint is skipped, and the
fingerprint of a file is forgotten when a scan finds the file changed; send `refresh=true` to read every file
again. A file that changed since the scan is skipped. It gives up, and says why in `last_error`, when files
cannot be read five times in a row (a disk that is not mounted). `DELETE /library/duplicates/check` stops it.
security: [{bearerAuth: []}]
parameters:
- name: refresh
in: query
description: "`true` reads every file again, also those that have a fingerprint. `false` when absent."
schema: {type: boolean, default: false}
responses:
'202':
description: The check was started in the background.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [started]}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: The check is already running (`duplicates_check_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'500':
description: The groups could not be worked out (`internal`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Scan]
operationId: stopDuplicatesCheck
summary: Stop the check of the duplicates
description: |
Admin only. Asks a running check to end after the file it is on; the fingerprints already kept stay. It
answers the same when no check is running.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when no check was running."}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/library/duplicates/clean:
post:
tags: [Scan]
operationId: cleanDuplicates
summary: Delete the extra copies of one song
description: |
Admin only. **Deletes files from the music folder.** It is the one thing Sonda does that writes there, so it
is off until the operator turns on `library.allow_delete` (answer `deletion_disabled` otherwise), the folder
has to be writable (`library_read_only`), and it is never done by itself: one request removes the copies
`remove_track_ids` of one song and keeps `keep_track_id`.
The server decides again, whatever the client saw, and removes nothing unless every check passes: no scan is
running (`scan_running`); the tracks exist (`track_not_found`); they are copies of one song by the rule of
`GET /library/duplicates` (`invalid_input` otherwise, and also when the copy to keep is among those to
remove, a copy is named twice or there are none or more than 100); and the copy to keep and every copy to
remove are still the file the last scan saw, a regular file with the same size and date (`duplicate_changed`
for a file that changed, is gone, became a link or is outside the library: scan again). So the last copy of
a song is never removed. Every file is checked before the first is removed.
Each copy is removed from the disk through the library folder (a path cannot leave it, not even through a
link) and its track leaves the index; **the listens of the removed track become listens of the track that
stays**, so the taste is not lost. Folders are never removed, not even empty ones. If it fails part way (for
example the folder turns out to be read-only for the second file), what was removed stays removed.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CleanDuplicates'}
responses:
'200':
description: The extra copies were removed.
content:
application/json:
schema: {$ref: '#/components/schemas/DuplicatesCleaned'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: A track that was named does not exist (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: |
Deleting is not turned on (`deletion_disabled`), a scan is running (`scan_running`), a file is not what the last
scan saw (`duplicate_changed`), or the music folder cannot be written to (`library_read_only`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/library/scan:
get:
tags: [Scan]
operationId: getScanStatus
summary: Scan status
description: Whether a scan is running and how the last one ended.
security: [{bearerAuth: []}]
responses:
'200':
description: The current state.
content:
application/json:
schema: {$ref: '#/components/schemas/ScanStatus'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Scan]
operationId: scanAll
summary: Scan every library
description: |
Admin only. Starts a scan in the background. Only MP3 and FLAC files are read; other audio
formats are counted as `unsupported`. Housekeeping folders of NAS boxes (`@Recycle`,
`#recycle`, `@eaDir`, `.@__thumb`, `$RECYCLE.BIN`) are skipped.
A scan reads the tags of files that are new or changed. Send `full=true` to read every file
again: that is how MusicBrainz ids and genres reach music that was indexed before they were
read. Files keep their identity, so listening history is kept.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Full'}
responses:
'202': {$ref: '#/components/responses/ScanStarted'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: A scan is already running (`scan_running`), or there is no library yet (`no_libraries`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists:
get:
tags: [Catalog]
operationId: listArtists
summary: List artists
description: |
Artists credited on a playable track, or that are the album artist of an album with one.
Sorted by name.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/LibraryId'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/artists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getArtist
summary: One artist
security: [{bearerAuth: []}]
responses:
'200':
description: The artist.
content:
application/json:
schema: {$ref: '#/components/schemas/Artist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: |
No such artist (`artist_not_found`). An artist with nothing to play is not found either,
unless a provider named it as similar to another artist: those can be shown, with
`track_count` and `album_count` of 0, but they are never part of the lists.
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists/{id}/similar:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getSimilarArtists
summary: Artists similar to one
description: |
Artists an external provider (Last.fm) finds similar to this one, best first. Each says
whether it is in the library, and `id` works with `GET /artists/{id}`; one that is not in the
library has no files.
The provider is only asked when an admin switched it on and the stored answer is missing or
old (7 days; a "no such artist" answer is kept 1 day). What is sent is the artist's name or
MusicBrainz id and nothing about any user. Several requests for the same artist at once
make one call.
A provider that is off or failing is not an error: the answer is `200` and `provider_status`
says why. Then `items` holds whatever was stored before, if anything, and `stale` is true
when it is older than it should be.
`score` is the provider's own number between 0 and 1. It is relative to the list it came
in (the best one is usually 1), so it only compares artists inside one answer. `rank` is the
position. Show `attribution` where you show the data.
security: [{bearerAuth: []}]
parameters:
- name: limit
in: query
description: How many to return. 20 when absent or 0; values above 50 are lowered to 50, the most that is kept.
schema: {type: integer, minimum: 0, default: 20}
responses:
'200':
description: The similar artists.
content:
application/json:
schema: {$ref: '#/components/schemas/SimilarArtists'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists/{id}/tags:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistTags
summary: Tags of an artist, from each provider
description: |
What each provider says kind of music this artist plays: Last.fm's top tags and
MusicBrainz's tags and genres, and last the genres of the artist's own music files
(`provider` is `files`: the genre tags the scan read, each weighted by how many of the
playable tracks the artist is credited on have it; it asks nobody, is always `ok` and has a null `retrieved_at`). There is
always one entry for each, Last.fm first. The
weights are the providers' own numbers, kept as they came and never mixed: Last.fm's is
relative to the artist (1 to 100, the top tag is usually 100; a tag with no votes is dropped),
MusicBrainz's is a count of votes. `genre` is true for a MusicBrainz tag that it also lists among its curated genres, and for
every tag of the `files` entry, which are genres by definition.
A provider is only asked when an admin switched it on and its stored answer is missing or
old (7 days; a "no such artist" answer is kept 1 day), with the same rules as
`GET /artists/{id}/similar`. What is sent is the artist's name or MusicBrainz id to
Last.fm (its id when known), and only the MusicBrainz id to MusicBrainz: Sonda never looks
an id up by name. An artist's id comes from the tags in the music files, or from Last.fm
for an artist it named that is not in the library; for any other artist the MusicBrainz
entry says `no_id`. Show each `attribution` where you show the tags.
security: [{bearerAuth: []}]
responses:
'200':
description: One entry per provider.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistTags'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/discover:
get:
tags: [Discovery]
operationId: discover
summary: Artists you may like
description: |
Suggests artists, in your library or not, each with a `score` from 0 to 1 and the parts
it is made of, so every number can be explained.
**Where it starts.** From the artists you name with `seed` (one to five, repeat the
parameter), or, when you named none and turned on `discover_from_listening` in
`PATCH /me/settings`, from the up to 20 artists you play most. With neither the request
is refused (`seed_required`) and nothing is sent to anyone. For each seed, the similar
artists are the stored ones, or are asked from Last.fm when they are missing or old and
an admin switched Last.fm on (see `GET /artists/{id}/similar`). **What is sent**:
the name or MusicBrainz id of each seed, and, for the best candidates that have no tags
yet, the name of the candidate (tags are asked from Last.fm only, never from MusicBrainz).
The seeds from your listening are therefore sent only when you allowed it. A seed is never
suggested to itself, and nobody else's listening is read.
**The score** is `S = wA·A + wG·G + wP·P + wD·D` with the weights of the server's
`[scoring]` config (default 0.40, 0.25, 0.25, 0.10; only their proportions matter).
`a` is the affinity: 1 − Π(1 − weight·match) over the seeds that point at the artist, where
`match` is Last.fm's similarity (relative to each seed's own list) and `weight` is 1 for a
seed you named or your `preference` for one taken from your listening (see
`GET /me/taste`). `g` is how close the artist's tags are to the tags of the artists you like (cosine
of the tag vectors); it is `null` when there is nothing to compare, and then the score is
worked out without it, the other weights rescaled, so a missing part never counts as a bad
one. `p` is what your listening says about the artist, from `preference`
mapped to 0 to 1, and 0.5 for an artist you never played. `d` is a bonus for what you have
not played: `1 / (1 + listens)`.
Only the best candidates by affinity (at least 20) are scored, then the best `limit` by
score are returned; ties go to the higher affinity, then to the lower id. `because` names
up to three seeds that count most for the suggestion. The first request after a seed's data
gets old can take several seconds, because the provider is asked politely, a few at a time;
later ones are served from the database.
`provider_status` is `disabled` when something had to be asked from Last.fm (a seed's
similar artists are missing or old) and Last.fm is off or has no key; anything stored earlier
is still used, so the list can be empty. With every seed's data stored and fresh the status is `ok`
whether Last.fm is on or not. It is `error` when Last.fm failed for some seed (the
rest is still returned) and `ok` otherwise. Show `attribution` where you show the data.
**How many at once.** One Discover at a time for each listener (a second one answers 429
`discover_busy`), and at most three at the same time on the server: a request that finds them
busy waits for its turn (at most 30 seconds, then it answers 429 as well), and leaves without
doing any work if the client gives up. A request that waits for its turn counts as running.
security: [{bearerAuth: []}]
parameters:
- name: seed
in: query
description: An artist id to start from. Repeat up to 5 times. Without it, your listening is used if you allowed that.
schema: {type: array, items: {type: integer, format: int64}, maxItems: 5}
style: form
explode: true
- name: limit
in: query
description: How many suggestions to return. 20 when absent or 0; values above 30 are lowered to 30.
schema: {type: integer, minimum: 0, default: 20}
- name: in_library
in: query
description: "`true` keeps only artists you have, `false` only artists you do not. Absent keeps both."
schema: {type: boolean}
responses:
'200':
description: The suggestions, best first.
content:
application/json:
schema: {$ref: '#/components/schemas/Discover'}
'400':
description: A seed that is not an artist, too many seeds, a bad `limit` or `in_library` (`invalid_input`), or no seed and no permission to use your listening (`seed_required`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'401': {$ref: '#/components/responses/Unauthorized'}
'429':
description: "You already have a Discover running or waiting for its turn, or the server was too busy to give it one in 30 seconds (`discover_busy`). Ask again after `Retry-After` seconds."
headers:
Retry-After:
description: Seconds to wait before asking again.
schema: {type: integer}
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/discover/dismissed:
get:
tags: [Discovery]
operationId: listDismissed
summary: Artists you are not interested in
description: |
The artists you told Discover you are not interested in (`POST /discover/{id}/dismiss`),
newest first. Only yours; nobody else's choices are visible or affect your Discover.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/MarkedPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/discover/{id}/dismiss:
parameters:
- {$ref: '#/components/parameters/Id'}
post:
tags: [Discovery]
operationId: dismissArtist
summary: Not interested in this artist
description: |
Hides the artist from your Discover: it is never suggested again, and an artist taken
from your listening that you dismissed no longer seeds your suggestions. An artist is
dismissed or on your wishlist, never both: dismissing one that is on the wishlist takes
it off. Doing it twice is the same as once. Nothing is sent to anyone.
The artist can be one of yours or one a provider named. An artist that a provider named
and nobody else does is kept for as long as it is dismissed, so the choice survives a
new list from the provider; such an artist is listed for you, but other users cannot see
that it exists. When an admin takes a provider's data back (`DELETE
/providers/{name}/data`), what only that provider's lists named goes, your choice with it.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when it was already dismissed."}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Discovery]
operationId: undismissArtist
summary: Interested again
description: Lets Discover suggest the artist again. A wish on the wishlist is not touched.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when it was not dismissed."}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/mixes:
get:
tags: [Mixes]
operationId: listMixes
summary: Your mixes
description: |
Playlists that Sonda makes for you, from what you listen to and from the genres of your
music. First the ones made for you (`favourites`, `rediscover`: they need some listening
history, so they are missing without it; `unheard`, the songs you never played), then
one `genre` mix for each genre of the library that has at least 30 songs by at least 4
artists, the genres you play most first (and the biggest after them). Spellings of a genre
that differ only by case or punctuation are one genre, and `other` and `unknown` are not
genres. `title` is in English; a client may say it in its own words from `kind` and
`genre`. Nothing is stored and nothing is sent to a provider: a mix is worked out from your
own history and the genre tags of your files, for you alone.
security: [{bearerAuth: []}]
responses:
'200':
description: The mixes.
content:
application/json:
schema: {$ref: '#/components/schemas/MixList'}
'401': {$ref: '#/components/responses/Unauthorized'}
/mixes/{id}:
parameters:
- {$ref: '#/components/parameters/MixId'}
get:
tags: [Mixes]
operationId: getMix
summary: A mix and its songs
description: |
Up to 50 songs, at most 3 by one artist and never two by the same artist in a row. They
are picked by weighted chance: the artists you play weigh more, songs you never played
a bit more, songs played in the last days less, and songs you skipped in the last two weeks
and artists you avoid do not come at all. The same mix comes back all day: it changes
the next day, or when you ask for another `variant`. The id of a genre mix has the genre
in it (`genre:hard rock`), so it must be percent-encoded in the path. A mix you do not
have (a genre that is too small, `favourites` with no history) is `mix_not_found`.
security: [{bearerAuth: []}]
parameters:
- name: variant
in: query
description: Another mix of the same kind, from 0 (the mix of the day) up.
schema: {type: integer, minimum: 0, maximum: 1000000, default: 0}
responses:
'200':
description: The mix.
content:
application/json:
schema: {$ref: '#/components/schemas/MixWithTracks'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/MixNotFound'}
/mixes/{id}/playlist:
parameters:
- {$ref: '#/components/parameters/MixId'}
post:
tags: [Mixes]
operationId: saveMix
summary: Keep a mix as a playlist
description: |
Makes a playlist of your own with the songs that `variant` of the mix has now, in the
same order. The playlist is a copy: it does not change afterwards, and is yours to edit.
The body is optional.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SaveMix'}
responses:
'201':
description: The playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/MixNotFound'}
'409': {$ref: '#/components/responses/PlaylistLimit'}
'422':
description: The mix has no songs to save (`mix_empty`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/genres:
get:
tags: [Smart playlists]
operationId: listGenres
summary: The genres of the library
description: |
The genres of the playable songs, to choose from in the rules of a smart playlist: each with the number
of songs, the biggest first, and by name among equals. The spellings that the files have are one genre
(`jazz+funk` and `jazz-funk` are `jazz funk`), written the way the rules compare them; tags such as
`other` or `unknown` are left out.
security: [{bearerAuth: []}]
responses:
'200':
description: The genres.
content:
application/json:
schema: {$ref: '#/components/schemas/GenreList'}
'401': {$ref: '#/components/responses/Unauthorized'}
/smart-playlists:
get:
tags: [Smart playlists]
operationId: listSmartPlaylists
summary: Your smart playlists
description: |
The smart playlists you made, the one changed last first. Only yours. A smart playlist is a set
of rules: its songs come from `GET /smart-playlists/{id}/tracks`.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of smart playlists.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartPlaylistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Smart playlists]
operationId: createSmartPlaylist
summary: Make a smart playlist
description: |
Keeps a set of rules, an order and a limit under a name. Only that is stored: the songs are worked
out again every time. A user can have 200. Names can repeat. Use `POST /smart-playlists/preview`
to try the rules first.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreateSmartPlaylist'}
responses:
'201':
description: The smart playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartPlaylist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409':
description: A user can have 200 smart playlists (`limit_reached`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/smart-playlists/preview:
post:
tags: [Smart playlists]
operationId: previewSmartPlaylist
summary: Try rules without keeping them
description: |
Works the songs out for rules that are not kept, the way `GET /smart-playlists/{id}/tracks` would,
so they can be tried while they are written. Nothing is stored.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/PreviewSmartPlaylist'}
responses:
'200':
description: The songs.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartTracks'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/smart-playlists/suggested:
get:
tags: [Smart playlists]
operationId: listSuggestedSmartPlaylists
summary: The smart playlists Sonda makes for you
description: |
A fixed set that is there without anybody making it, the same rules for everyone and worked out on your
own library and history: `recently-added`, `on-rotation` (the songs you played most in the last 30 days, at
least twice), `top-year` (the same over 365 days), `most-played` (over all time), `never-played`, `forgotten`
(played once, but not in the last 90 days), `high-quality` (bitrate of 900 kbps or more) and `long-tracks`
(6 minutes or more).
Nothing is stored for them. A client says their names in its own language from the `key`. To change one,
make a smart playlist of your own from its rules with `POST /smart-playlists`.
security: [{bearerAuth: []}]
responses:
'200':
description: The suggested smart playlists.
content:
application/json:
schema: {$ref: '#/components/schemas/SuggestedSmartPlaylistList'}
'401': {$ref: '#/components/responses/Unauthorized'}
/smart-playlists/suggested/{key}/tracks:
parameters:
- {$ref: '#/components/parameters/SuggestedKey'}
get:
tags: [Smart playlists]
operationId: getSuggestedSmartPlaylistTracks
summary: The songs of a suggested smart playlist, now
description: |
Works the rules out for you, as `GET /smart-playlists/{id}/tracks` does for yours. With the random order
the songs stay the same all day, and another `variant` gives other ones.
security: [{bearerAuth: []}]
parameters:
- name: variant
in: query
description: Other songs for the random order, from 0 (the songs of the day) up.
schema: {type: integer, minimum: 0, maximum: 1000000, default: 0}
responses:
'200':
description: The songs.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartTracks'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SuggestedNotFound'}
/smart-playlists/suggested/{key}/covers:
parameters:
- {$ref: '#/components/parameters/SuggestedKey'}
get:
tags: [Smart playlists]
operationId: getSuggestedSmartPlaylistCovers
summary: The covers of a suggested smart playlist
description: |
Up to 4 albums that have a cover and stand for it, in the order of the songs the rules give now (the ones of
`variant`), each once: their covers (`GET /albums/{id}/cover`) make its picture. It is worked out apart from the
songs so that a list of smart playlists can show the rest without waiting for the rules of every one of them; the
answer may be kept by the client for a few minutes. Empty when none of the songs has an album with a cover.
security: [{bearerAuth: []}]
parameters:
- name: variant
in: query
description: The variant that is on screen, from 0 (the songs of the day) up.
schema: {type: integer, minimum: 0, maximum: 1000000, default: 0}
responses:
'200':
description: The albums.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartCovers'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SuggestedNotFound'}
/smart-playlists/suggested/{key}/playlist:
parameters:
- {$ref: '#/components/parameters/SuggestedKey'}
post:
tags: [Smart playlists]
operationId: saveSuggestedSmartPlaylist
summary: Keep a suggested smart playlist as a playlist
description: |
Makes a playlist of your own with the songs that `variant` gives now, in the same order. It is a copy,
and is yours to edit. The body is optional; without a name the playlist is called by the `key`.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SaveSmartPlaylist'}
responses:
'201':
description: The playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SuggestedNotFound'}
'409': {$ref: '#/components/responses/PlaylistLimit'}
'422':
description: The rules give no songs to save (`smart_playlist_empty`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/smart-playlists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Smart playlists]
operationId: getSmartPlaylist
summary: A smart playlist
description: |
Its name, rules, order and limit, without the songs. One of somebody else answers
`smart_playlist_not_found`.
security: [{bearerAuth: []}]
responses:
'200':
description: The smart playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartPlaylist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
patch:
tags: [Smart playlists]
operationId: updateSmartPlaylist
summary: Change a smart playlist
description: |
Changes what is given. The rules, when given, replace the old ones whole. An empty description clears
it; a name cannot be empty.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdateSmartPlaylist'}
responses:
'200':
description: The smart playlist as it is now.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartPlaylist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
delete:
tags: [Smart playlists]
operationId: deleteSmartPlaylist
summary: Delete a smart playlist
description: Deletes the rules. Playlists that were made from it with `POST /smart-playlists/{id}/playlist` stay.
security: [{bearerAuth: []}]
responses:
'204': {description: Deleted.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
/smart-playlists/{id}/tracks:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Smart playlists]
operationId: getSmartPlaylistTracks
summary: The songs of a smart playlist, now
description: |
Works the rules out on the playable songs of the library, with your own listening history and taste
for the rules that use them, puts them in the order and cuts the end at the limit. A song whose files
are gone is never offered. Nothing is stored, and nothing is asked of a provider. With the random
order the songs stay the same all day, and another `variant` gives other ones.
security: [{bearerAuth: []}]
parameters:
- name: variant
in: query
description: Other songs for the random order, from 0 (the songs of the day) up.
schema: {type: integer, minimum: 0, maximum: 1000000, default: 0}
responses:
'200':
description: The songs.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartTracks'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
/smart-playlists/{id}/covers:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Smart playlists]
operationId: getSmartPlaylistCovers
summary: The covers of a smart playlist
description: |
Up to 4 albums that have a cover and stand for it, in the order of the songs the rules give now (the ones of
`variant`), each once: their covers (`GET /albums/{id}/cover`) make its picture. It is worked out apart from the
songs so that a list of smart playlists can show the rest without waiting for the rules of every one of them; the
answer may be kept by the client for a few minutes. Empty when none of the songs has an album with a cover.
security: [{bearerAuth: []}]
parameters:
- name: variant
in: query
description: The variant that is on screen, from 0 (the songs of the day) up.
schema: {type: integer, minimum: 0, maximum: 1000000, default: 0}
responses:
'200':
description: The albums.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartCovers'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
/smart-playlists/{id}/playlist:
parameters:
- {$ref: '#/components/parameters/Id'}
post:
tags: [Smart playlists]
operationId: saveSmartPlaylist
summary: Keep a smart playlist as a playlist
description: |
Makes a playlist of your own with the songs that `variant` gives now, in the same order. The playlist
is a copy: it does not change afterwards, and is yours to edit. The body is optional.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SaveSmartPlaylist'}
responses:
'201':
description: The playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
'409': {$ref: '#/components/responses/PlaylistLimit'}
'422':
description: The rules give no songs to save (`smart_playlist_empty`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/playlists:
get:
tags: [Playlists]
operationId: listPlaylists
summary: Your playlists
description: |
The playlists you made, the one changed last first. Only yours: nobody else's are ever
listed.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of playlists.
content:
application/json:
schema: {$ref: '#/components/schemas/PlaylistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Playlists]
operationId: createPlaylist
summary: Make a playlist
description: |
Makes an empty playlist. A user can have 1000. Names can repeat.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreatePlaylist'}
responses:
'201':
description: The playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/PlaylistLimit'}
/playlists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Playlists]
operationId: getPlaylist
summary: A playlist
description: |
Its name, description, how many tracks it has and how long they are. The tracks come from
`GET /playlists/{id}/tracks`. A playlist of somebody else answers `playlist_not_found`.
security: [{bearerAuth: []}]
responses:
'200':
description: The playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/PlaylistNotFound'}
patch:
tags: [Playlists]
operationId: updatePlaylist
summary: Rename a playlist or change its description
description: |
Changes what is given. An empty description clears it; a name cannot be empty.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdatePlaylist'}
responses:
'200':
description: The playlist as it is now.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/PlaylistNotFound'}
delete:
tags: [Playlists]
operationId: deletePlaylist
summary: Delete a playlist
description: Deletes the playlist and its list of tracks. The tracks themselves stay in the library.
security: [{bearerAuth: []}]
responses:
'204': {description: Deleted.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/PlaylistNotFound'}
/naming:
get:
tags: [Smart playlists]
operationId: getNamingStatus
summary: Whether names are made by themselves
description: |
`auto` is true when the `anthropic` provider is on with its key: a playlist that is kept from a mix or a smart
playlist with `auto_name`, and a smart playlist made with no name, are then named by Claude. A page asks this so
that it does not ask for a name that Claude will make.
security: [{bearerAuth: []}]
responses:
'200':
description: The status.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [auto]
properties:
auto: {type: boolean}
'401': {$ref: '#/components/responses/Unauthorized'}
/playlists/{id}/suggest-name:
parameters:
- {$ref: '#/components/parameters/Id'}
post:
tags: [Playlists]
operationId: suggestPlaylistName
summary: Suggest a name for a playlist
description: |
Makes a suggestion and changes nothing: the client decides what to do with it. When an admin turned the
`anthropic` provider on with an API key, Claude is asked for the name, with only a few facts: up to 5 genres,
up to 8 artist names, how many songs there are, for a smart playlist a few words about its rules, and the
language. Never the user, a listen, a track title or a file path. What Claude answers is kept, so the same facts
are not asked twice. With the provider off, or when it fails or declines, a name is made on this server from the
genres and the artists and nothing leaves it: `source` says which it was. The body is optional.
The facts come from the first 200 songs of the playlist that can be played.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SuggestName'}
responses:
'200':
description: A name and a line of description.
content:
application/json:
schema: {$ref: '#/components/schemas/NameSuggestion'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/PlaylistNotFound'}
/mixes/{id}/suggest-name:
parameters:
- {$ref: '#/components/parameters/MixId'}
post:
tags: [Mixes]
operationId: suggestMixName
summary: Suggest a name for a mix
description: |
Makes a suggestion and changes nothing: the client decides what to do with it. When an admin turned the
`anthropic` provider on with an API key, Claude is asked for the name, with only a few facts: up to 5 genres,
up to 8 artist names, how many songs there are, for a smart playlist a few words about its rules, and the
language. Never the user, a listen, a track title or a file path. What Claude answers is kept, so the same facts
are not asked twice. With the provider off, or when it fails or declines, a name is made on this server from the
genres and the artists and nothing leaves it: `source` says which it was. The body is optional.
The facts come from the songs that `variant` of the mix has.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SuggestName'}
responses:
'200':
description: A name and a line of description.
content:
application/json:
schema: {$ref: '#/components/schemas/NameSuggestion'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/MixNotFound'}
/smart-playlists/{id}/suggest-name:
parameters:
- {$ref: '#/components/parameters/Id'}
post:
tags: [Smart playlists]
operationId: suggestSmartPlaylistName
summary: Suggest a name for a smart playlist
description: |
Makes a suggestion and changes nothing: the client decides what to do with it. When an admin turned the
`anthropic` provider on with an API key, Claude is asked for the name, with only a few facts: up to 5 genres,
up to 8 artist names, how many songs there are, for a smart playlist a few words about its rules, and the
language. Never the user, a listen, a track title or a file path. What Claude answers is kept, so the same facts
are not asked twice. With the provider off, or when it fails or declines, a name is made on this server from the
genres and the artists and nothing leaves it: `source` says which it was. The body is optional.
The facts come from the rules and from the songs that `variant` of it gives now.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SuggestName'}
responses:
'200':
description: A name and a line of description.
content:
application/json:
schema: {$ref: '#/components/schemas/NameSuggestion'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SmartPlaylistNotFound'}
/playlists/{id}/tracks:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Playlists]
operationId: listPlaylistTracks
summary: The tracks of a playlist
description: |
The items in order, each with its own `id` (a track can be in a playlist more than once),
its `position` (counted from 0, without gaps) and the track. A track whose files were
deleted or moved away stays in the playlist with `available` false: it is not lost, and
it plays again when the files are back and a scan has found them.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of items.
content:
application/json:
schema: {$ref: '#/components/schemas/PlaylistItemPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/PlaylistNotFound'}
post:
tags: [Playlists]
operationId: addPlaylistTracks
summary: Add tracks to a playlist
description: |
Puts 1 to 500 tracks, in the order given, at `position` (the tracks from there on move
down) or at the end when it is absent. A track can be added again. If one id is not a
track nothing is added. A playlist holds up to 10000 tracks.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/AddPlaylistTracks'}
responses:
'200':
description: The playlist as it is now.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400':
description: The request is malformed, or `position` is beyond the end (`invalid_position`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/PlaylistNotFound'}
'409': {$ref: '#/components/responses/PlaylistLimit'}
'422':
description: One of the tracks does not exist (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/playlists/{id}/tracks/{item}:
parameters:
- {$ref: '#/components/parameters/Id'}
- name: item
in: path
required: true
description: The `id` of the item, not of the track.
schema: {type: integer, format: int64, minimum: 1}
patch:
tags: [Playlists]
operationId: movePlaylistItem
summary: Move a track inside a playlist
description: |
Puts the item at `position`, from 0 to the number of items less one; the ones in between
shift by one.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/MovePlaylistItem'}
responses:
'204': {description: Moved.}
'400':
description: The request is malformed, or `position` is beyond the end (`invalid_position`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such playlist (`playlist_not_found`) or no such item in it (`item_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Playlists]
operationId: removePlaylistItem
summary: Take a track out of a playlist
description: Removes that one item; the ones after it move up by one.
security: [{bearerAuth: []}]
responses:
'204': {description: Removed.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such playlist (`playlist_not_found`) or no such item in it (`item_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/wishlist:
get:
tags: [Discovery]
operationId: listWishlist
summary: Your wishlist
description: |
The artists you want, newest first. It is a list for you: nothing is downloaded or
sent anywhere. `in_library` says whether there is music of the artist to play now, so a
client can hide the ones you already got. Only yours.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/MarkedPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/wishlist/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
put:
tags: [Discovery]
operationId: addToWishlist
summary: Put an artist on your wishlist
description: |
Adds the artist. An artist is on the wishlist or dismissed, never both: adding one you
dismissed lifts the dismissal. Doing it twice keeps the first date. The artist can be one
of yours or one a provider named; the latter is kept while it is on a wishlist (see
`POST /discover/{id}/dismiss` for what a purge does). Discover marks it `wishlisted`.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when it was already there."}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Discovery]
operationId: removeFromWishlist
summary: Take an artist off your wishlist
description: A dismissal of the artist is not touched.
security: [{bearerAuth: []}]
responses:
'204': {description: "Done, also when it was not there."}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/me/taste:
get:
tags: [Taste]
operationId: getMyTaste
summary: What Sonda has learned about your taste
description: |
Your taste, worked out from your own listening history every time you ask. It uses local
data only: nothing is sent to any provider, and nobody else's history is read.
Each event has a value: a `complete` listen +1, any other listen that counts +0.5 (see
`POST /listens`), a `skip` before that -1, and a play too short to mean anything 0. An
event weighs half as much for every 90 days (`taste.half_life_days`) that has passed, and
one dated after the moment of the request weighs as if it happened then. Only the last
ten half-lives are read (900 days by default); older events weigh less than a thousandth
and are left out, also from `listens`. For each artist the values add up, and `preference`
is `tanh(sum / 3)`: from -1 to 1, approaching both (a large sum rounds to exactly 1), so
one skip does not sink an artist and listening makes one loved at most. A track with
several artists credits each of them.
`artists` are the ones you like (a `preference` above 0), the most played first. They are
ordered by the sum itself, so artists whose `preference` rounds to 1 keep their order;
ties go to the lower id. `tags` are the kinds of music you like, at most 50: the tags of
those artists (the genres of your files that still exist, and what Last.fm and MusicBrainz
said earlier, if they were ever asked) added up, each artist weighing as much as its
`preference`, and scaled so the best tag is 1, best first. Tags are read from what is already stored; this
request never asks a provider. The tag profile is built from your 200 most liked artists.
security: [{bearerAuth: []}]
parameters:
- name: limit
in: query
description: How many artists to return. 20 when absent or 0; values above 50 are lowered to 50. It does not limit `tags`.
schema: {type: integer, minimum: 0, default: 20}
responses:
'200':
description: Your taste. Both lists are empty until you have listened to something.
content:
application/json:
schema: {$ref: '#/components/schemas/Taste'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/me/settings:
get:
tags: [Taste]
operationId: getMySettings
summary: Your own settings
description: |
Settings that belong to you, not to the server. Everyone starts with the private
defaults: anything that would send something about your taste to a provider is off.
security: [{bearerAuth: []}]
responses:
'200':
description: Your settings.
content:
application/json:
schema: {$ref: '#/components/schemas/UserSettings'}
'401': {$ref: '#/components/responses/Unauthorized'}
patch:
tags: [Taste]
operationId: updateMySettings
summary: Change your own settings
description: |
Changes the settings named in the body and leaves the others alone. An empty object
changes nothing. `null` is the same as leaving a field out. The body must be one JSON
object, with nothing after it, and the names must be spelt exactly: a setting that does
not exist is refused rather than ignored.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdateUserSettings'}
responses:
'200':
description: Your settings as they are now.
content:
application/json:
schema: {$ref: '#/components/schemas/UserSettings'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/artists/{id}/lidarr:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistInLidarr
summary: Whether Lidarr has an artist
description: |
Asks your own Lidarr, by the artist's MusicBrainz id and never by name, whether it has the artist and
whether it monitors it. Like the descriptions, whatever stops the answer is a status and not an error:
`disabled` when the `lidarr` provider is off (nobody is asked), `no_id` when the artist has no MusicBrainz id,
`not_configured` when Lidarr has no address or key, `error` when it could not be asked now. Only the id and
the API key go out, to the address an admin set.
security: [{bearerAuth: []}]
responses:
'200':
description: Whether Lidarr has the artist.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistInLidarr'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
post:
tags: [Discovery]
operationId: sendArtistToLidarr
summary: Send an artist to Lidarr
description: |
Admin only. Adds the artist to your own Lidarr, which then looks for and downloads the music by itself:
Sonda downloads nothing, and does this only when an admin asks, for one artist, never by itself. It works
for any artist that has a MusicBrainz id, also one that Sonda only learned of from a list of similar
artists, which is the point: asking for music you do not have. It never looks an id up by name.
It uses what an admin set in `PUT /providers/lidarr`: the quality profile, the metadata profile, the root
folder, which of the albums to monitor and whether Lidarr starts searching at once. It needs the provider
switched on and those chosen. An artist that Lidarr already has is not an error (`already_added`, nothing
changes), so the call can be repeated. If Lidarr does not answer in time, the artist may have been added
all the same: read it with `GET /artists/{id}/lidarr`. Only the MusicBrainz id and the API key go out,
to the address an admin set.
security: [{bearerAuth: []}]
responses:
'200':
description: The artist is in Lidarr.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status:
type: string
enum: [added, already_added]
description: "`added` now, or `already_added` when Lidarr had it."
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: The provider is switched off (`lidarr_disabled`), or has no address or key, or the profiles and the folder were not chosen (`lidarr_not_configured`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'422':
description: The artist has no MusicBrainz id (`no_musicbrainz_id`), Lidarr does not know the id (`lidarr_unknown_artist`), or it refused the artist (`lidarr_rejected`, with its reason).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: Lidarr refused the key (`lidarr_key_refused`), or could not be asked or did not answer in time (`lidarr_unavailable`; the artist may have been added).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists/{id}/description:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistDescription
summary: What Wikipedia says about an artist
description: |
A short text about the artist from Wikipedia, with the page it comes from. The way to it
is a chain of identifiers, never a search by 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 the server's languages (`[wikipedia] languages`, the code of the Wikipedia:
`it`, `en`, `no` for Norwegian; a language with no Wikipedia finds nothing) that has one. A page is used
only if it is an article about that same item (not a page of disambiguation). An artist
with no MusicBrainz id answers `no_id`: Sonda does not look an id up by name.
It needs the `wikipedia` provider and also the `musicbrainz` one, because the link to
Wikidata comes from MusicBrainz; an admin switches them on, and nothing is sent while
either is off (`disabled`, also when an answer is stored). What is sent: the MusicBrainz id
to MusicBrainz (with the contact set for MusicBrainz), the Wikidata item to Wikidata and the
title of the page to Wikipedia (with the contact set for Wikipedia), and your server's IP
address with them. The answer is stored: 30 days, or a
day when there was nothing to find, and an old one is returned as `stale` if Wikipedia
fails. When there is nothing to show, `description` is `null` and `provider_status` is
`ok`.
The text is CC BY-SA 4.0. Where you show it, name the page (`title`), link to it (`url`) and
give the licence (`license`, `license_url`), and say if you changed it.
security: [{bearerAuth: []}]
responses:
'200':
description: The description, or `null` with the status that says why.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistDescription'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists/{id}/image:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistImage
summary: A free picture of an artist
description: |
A JPEG made from a picture of the artist on Wikimedia Commons, only when its licence is
free: public domain, CC0, CC BY or CC BY-SA. Non-commercial, no-derivatives, fair use and
unknown licences are refused, because Sonda keeps a copy. **Where you show it, show its
credit** (`GET /artists/{id}/image/credit`): the author, the licence and the page of the file.
The way to it is a chain of identifiers, never a search by name: the artist's MusicBrainz
id, the Wikidata item MusicBrainz links to it, the picture Wikidata names for it, and Commons
for its licence and a copy. It needs the `commons` provider and the `musicbrainz` one, which
an admin switches on. It is built the first time it is asked for (that request can take a few
seconds), scaled to fit, saved in the data folder, and served from there afterwards: for 30
days, or a week when there is no free picture; an older copy is served when Commons cannot
be reached. What is sent: the MusicBrainz id to MusicBrainz, the Wikidata item to Wikidata,
the name of the file to Commons, and the address of a copy to Wikimedia, with your server's
IP address and a `User-Agent` with a contact.
An `<img>` element cannot send headers, so, like the stream and the covers, this accepts
the access token as the `access_token` query parameter. A header, when present, always wins.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: size
in: query
description: "`small` (300 pixels at most on the longest side) or `large` (1000). Large when absent."
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
- name: Range
in: header
required: false
schema: {type: string}
responses:
'200':
description: The picture.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
image/jpeg:
schema: {type: string, format: binary}
'206':
description: The requested byte range of the picture.
headers:
Content-Range:
schema: {type: string}
content:
image/jpeg:
schema: {type: string, format: binary}
'304': {description: Not modified since the `ETag` sent.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: |
No such artist (`artist_not_found`), no free picture of it (`image_not_found`), the
provider is off (`provider_disabled`), or the artist has no MusicBrainz id
(`no_musicbrainz_id`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: The picture provider could not be reached (`provider_unavailable`). Try again later.
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
head:
tags: [Discovery]
operationId: headArtistImage
summary: Headers of a picture
description: Same as `GET`, without the body.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: size
in: query
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
responses:
'200':
description: Headers of the picture.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
'304': {description: Not modified since the `ETag` sent.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: "No such artist, no free picture, the provider is off or the artist has no MusicBrainz id."}
'502': {description: "The picture provider could not be reached."}
/artists/{id}/image/credit:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistImageCredit
summary: The credit of a picture of an artist
description: |
Whose the picture is and under which licence, to be shown next to it (the licences ask for
it). The author is plain text and may be empty; `license_url` may be empty when the licence
has no address; `page_url` is the page of the file on Commons, where everything is.
It answers like `GET /artists/{id}/image` (same errors), because the credit exists only with a
picture: the first request for an artist can take as long as the picture does (several seconds).
security: [{bearerAuth: []}]
responses:
'200':
description: The credit.
content:
application/json:
schema: {$ref: '#/components/schemas/PictureCredit'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`), no free picture (`image_not_found`), the provider is off (`provider_disabled`) or the artist has no MusicBrainz id (`no_musicbrainz_id`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: The picture provider could not be reached (`provider_unavailable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/albums:
get:
tags: [Catalog]
operationId: listAlbums
summary: List albums
description: |
Albums with a playable track, sorted by title. `artist_id` matches the albums an artist
owns plus those where it is credited on a playable track, the same set as its `album_count`.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/LibraryId'}
- {$ref: '#/components/parameters/ArtistId'}
responses:
'200':
description: A page of albums.
content:
application/json:
schema: {$ref: '#/components/schemas/AlbumPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/albums/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getAlbum
summary: One album
security: [{bearerAuth: []}]
responses:
'200':
description: The album.
content:
application/json:
schema: {$ref: '#/components/schemas/Album'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such album, or nothing of it can be played (`album_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/albums/{id}/cover:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getAlbumCover
summary: The cover of an album
description: |
A JPEG made from the picture in the album's own files: the picture embedded in one of
its first files, or else a `cover`, `folder`, `front`, `album` or `albumart` image
(`.jpg`, `.jpeg` or `.png`, any case) in the album's folder, in that order of names. It
is built the first time it is asked for (that request can take a moment), scaled to fit
and saved in the server's data folder, and served from there afterwards. It never
contacts anybody (unless the `coverartarchive` provider is on, see below). Pictures that are too big (over 20 MB or 16 million pixels) or are not
pictures are ignored, and only files inside the library are read.
For an album split in folders named like `CD1` or `Disc 2`, the picture in the folder
above them is used too. When the 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 (a full rescan reads
that tag again for music indexed before); 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: the id is taken only when MusicBrainz is sure (an exact
match of both names; a title that ends with a note like `(disc 2)` or `(Deluxe Edition)` is
tried again without it), is used for that request and is not stored.
The files of the user always come first. That request can take several seconds and may
answer `provider_unavailable`. At most a couple of covers are built at the same time, so a
client that asks for many at once may wait.
An album with no picture answers `cover_not_found`, and the server does not look again
for a day; a new or changed file of the album, or a full rescan, makes it look again.
A cover that was found is checked again after a week, so a picture replaced in the
folder is noticed.
The picture is `private` for an hour in caches and has an `ETag`: send it back as
`If-None-Match`.
An `<img>` element cannot send headers, so, like the stream, this also accepts the access
token as the `access_token` query parameter. A header, when present, always wins.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: size
in: query
description: "`small` (300 pixels at most on the longest side) or `large` (1000). Large when absent. Never enlarged: a small picture stays as it is."
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
- name: Range
in: header
required: false
schema: {type: string}
responses:
'200':
description: The cover.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
image/jpeg:
schema: {type: string, format: binary}
'206':
description: The requested byte range of the cover.
headers:
Content-Range:
schema: {type: string}
content:
image/jpeg:
schema: {type: string, format: binary}
'304': {description: Not modified since the `ETag` sent.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such album (`album_not_found`), or it has no cover (`cover_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: The cover provider could not be reached (`provider_unavailable`). Try again later.
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'503':
description: |
None of the album's files or folders could be read, for example because the disk is not
mounted (`files_unreadable`). That says nothing about whether there is a picture, so it is
not remembered as "no cover" and nothing already built is touched. Try again later.
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
head:
tags: [Catalog]
operationId: headAlbumCover
summary: Headers of a cover
description: Same as `GET`, without the body.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: size
in: query
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
responses:
'200':
description: Headers of the cover.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
'304': {description: Not modified since the `ETag` sent.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: "No such album, or it has no cover."}
'502': {description: "The cover provider could not be reached."}
'503': {description: "None of the album's files could be read."}
/tracks:
get:
tags: [Catalog]
operationId: listTracks
summary: List tracks
description: |
Tracks with at least one file that is not flagged missing; a track with several files
appears once. Grouped by album, then disc and track number.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/LibraryId'}
- {$ref: '#/components/parameters/ArtistId'}
- {$ref: '#/components/parameters/AlbumId'}
responses:
'200':
description: A page of tracks.
content:
application/json:
schema: {$ref: '#/components/schemas/TrackPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/tracks/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getTrack
summary: One track
security: [{bearerAuth: []}]
responses:
'200':
description: The track.
content:
application/json:
schema: {$ref: '#/components/schemas/Track'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track, or it has no playable file (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/tracks/{id}/peaks:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Playback]
operationId: getTrackPeaks
summary: The shape of a track, for the seek bar
description: |
How loud the track is along its length, as 120 levels from 0 to 255: the loudest part is 255 whatever the volume of
the track. The server finds it by decoding the file (MP3 and FLAC, no extra program needed), which takes a few
seconds, so the first request for a track starts the work in the background and answers `202` with `Retry-After`;
ask again then. It is done once for each file and worked out again if the size or the date of the file change. One
track is worked out at a time. A file that cannot be decoded (another format, or damaged) is `waveform_unavailable`,
and that is kept too, so it is not tried at every request.
security: [{bearerAuth: []}]
responses:
'200':
description: The shape.
content:
application/json:
schema: {$ref: '#/components/schemas/Peaks'}
'202':
description: The shape is being worked out. Ask again after `Retry-After` seconds.
headers:
Retry-After:
description: Seconds to wait.
schema: {type: integer}
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [working]}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track (`track_not_found`), its file is not available (`file_missing`), or its shape cannot be worked out (`waveform_unavailable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/tracks/{id}/stream:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Playback]
operationId: streamTrack
summary: Stream a track
description: |
Serves the original audio file. Supports `Range` requests, so players can seek, and
conditional requests. Streaming never records a listen; report one with `POST /listens`.
An `<audio>` element cannot send headers, so this is the only operation that also accepts
the access token as the `access_token` query parameter. A header, when present, always wins.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: Range
in: header
required: false
description: A byte range, for example `bytes=0-99`.
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'206':
description: |
The requested byte range. Several ranges in one request are answered as
`multipart/byteranges`.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`. Absent for a multipart answer.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
multipart/byteranges:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track (`track_not_found`), or its file is not available (`file_missing`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'416':
description: The range cannot be satisfied.
headers:
Content-Range:
description: '`bytes */<size of the file>`.'
schema: {type: string}
head:
tags: [Playback]
operationId: headTrackStream
summary: Headers of a stream
description: Same as `GET`, without the body.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: Range
in: header
required: false
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: Headers of the whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
'206':
description: Headers of the requested range.
headers:
Content-Range:
schema: {type: string}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: No such track or file.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'416': {description: The range cannot be satisfied.}
/providers:
get:
tags: [Providers]
operationId: listProviders
summary: List the external providers
description: |
Admin only. Every provider Sonda knows (Last.fm, MusicBrainz, Wikipedia, Commons, the Cover Art Archive and Lidarr), with whether it is on and
what it would send. Providers are off by default: nothing leaves the server until an admin
enables one. The API key is never returned; `has_api_key` says whether one is stored.
security: [{bearerAuth: []}]
responses:
'200':
description: The providers, in a fixed order.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [providers]
properties:
providers:
type: array
items: {$ref: '#/components/schemas/Provider'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/providers/anthropic/usage:
get:
tags: [Providers]
operationId: getClaudeUsage
summary: What the Claude provider costs
description: |
Admin only. Every question that Sonda asked of Claude is counted: what it made, what was taken from the names
that were kept (which cost nothing), what failed, and the tokens that were billed, also for a failure that was
billed. From them it works out an **estimate** of the cost in dollars, with the price of the model: the invoice
of Anthropic is the truth. `unpriced` says that some calls were to a model whose price is not known and are not
in the cost. A day is a day in UTC and only the days that had calls are listed, the newest first. Nothing of what
was sent (no artist, no genre, no name) is kept, and records older than a year are removed.
security: [{bearerAuth: []}]
parameters:
- name: days
in: query
description: How many days back, from 1 to 365. 30 when absent or 0.
schema: {type: integer, minimum: 0, maximum: 365, default: 30}
responses:
'200':
description: The totals and the days.
content:
application/json:
schema: {$ref: '#/components/schemas/ClaudeUsage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/providers/lidarr/options:
get:
tags: [Providers]
operationId: getLidarrOptions
summary: What Lidarr offers to choose from
description: |
Admin only. Reads Lidarr's quality profiles, metadata profiles and root folders, so an admin can pick
the ones to send artists with (`PUT /providers/lidarr`, field `lidarr`). It works whether Lidarr is
switched on or not, since it is needed to finish setting it up, and it sends nothing but the API key,
to the address set for Lidarr, which is your own server.
security: [{bearerAuth: []}]
responses:
'200':
description: What Lidarr offers.
content:
application/json:
schema: {$ref: '#/components/schemas/LidarrOffers'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: Lidarr has no address or no API key yet (`lidarr_not_configured`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: Lidarr refused the key (`lidarr_key_refused`), or could not be asked or answered something unexpected (`lidarr_unavailable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/providers/{name}:
parameters:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia, commons, coverartarchive, lidarr, anthropic]}
put:
tags: [Providers]
operationId: updateProvider
summary: Set up a provider
description: |
Admin only. Send any of `enabled`, `api_key`, `contact`, `url` and `lidarr`; fields you leave out are kept.
The key is write-only: it is never returned and never logged. Sending an empty `api_key`
clears it, and turns a provider that needs a key (Last.fm) off; a provider that needs none
(MusicBrainz) is not affected. A provider that needs a key cannot be enabled without one. `contact` goes into the User-Agent sent to the provider (MusicBrainz
asks for a URL or an e-mail address); empty means the project address.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ProviderUpdate'}
responses:
'200':
description: The provider as it is now.
content:
application/json:
schema: {$ref: '#/components/schemas/Provider'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such provider (`provider_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/providers/{name}/test:
parameters:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia, commons, coverartarchive, lidarr, anthropic]}
post:
tags: [Providers]
operationId: testProvider
summary: Check a provider's API key
description: |
Admin only. Asks the provider one cheap question with the stored key, to find out whether
it works. It works whether the provider is on or off, so you can check before switching it on.
It is the only request Sonda makes at an admin's command rather than for a listener, and it
sends nothing but the key. A provider that cannot be reached or refuses the key is not an
error here: the answer is `200` with `ok` false and the reason in `status`.
MusicBrainz has no key: its test only asks whether the service answers. A provider that
has no test is a `400`.
security: [{bearerAuth: []}]
responses:
'200':
description: The outcome of the check.
content:
application/json:
schema: {$ref: '#/components/schemas/ProviderTest'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such provider (`provider_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/providers/{name}/data:
parameters:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia, commons, coverartarchive, lidarr, anthropic]}
delete:
tags: [Providers]
operationId: purgeProviderData
summary: Remove what a provider gave
description: |
Admin only. Removes everything the provider told Sonda: its lists of similar artists, its
tags and the records of when it was asked, and then the artists that only that data named
and that nobody has files for. Last.fm's terms ask for exactly this when an agreement ends.
Your own artists, music, listens and settings are not touched, and the provider is not
switched off: if it is still on, it is asked again when someone asks. The answer counts what
was removed; doing it again removes nothing.
security: [{bearerAuth: []}]
responses:
'200':
description: What was removed.
content:
application/json:
schema: {$ref: '#/components/schemas/ProviderPurge'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such provider (`provider_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/listens:
get:
tags: [Playback]
operationId: listListens
summary: Your listening history
description: |
The events you reported, newest first, each with `counted`: whether it counts as a listen
under the current rule (see `POST /listens`). Nobody else's history is visible.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- name: counted
in: query
description: Send `true` to list only the events that count as a listen.
schema: {type: boolean, enum: [true]}
responses:
'200':
description: A page of events.
content:
application/json:
schema: {$ref: '#/components/schemas/ListenPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Playback]
operationId: recordListen
summary: Record a listen
description: |
Clients report what the listener did: **one event per play**, when the play ends or is
abandoned, with the time actually played (`complete` if it finished, `skip` if the listener
moved on, `play` if it simply stopped).
Use **one `idempotency_key` per play**. A retry with the same key from the same user is
recorded once and answered with `duplicate`. An event cannot be upgraded afterwards: a later
event with a key that was already used is ignored, even if its type or duration differ, and
sending it with a new key would count the same play twice.
**What counts as a listen.** An event counts when its type is `complete`, or when
`duration_played_ms` is at least `listening.min_listen_seconds` (20 seconds by default).
A `play` or `skip` shorter than that is stored but does not count. The rule is applied when
the history is read, so changing the setting re-reads the past. The answer says whether this
event counts; for a `duplicate` it describes the event you sent.
**Plausibility.** When the length of the track is known, `duration_played_ms` may not exceed
twice that length plus 10 seconds (a listener can seek back and loop). Streaming a file never
records anything on its own.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Listen'}
responses:
'201':
description: Recorded.
content:
application/json:
schema: {$ref: '#/components/schemas/ListenResult'}
'200':
description: Already recorded (same `idempotency_key`).
content:
application/json:
schema: {$ref: '#/components/schemas/ListenResult'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation:
get:
tags: [Federation]
operationId: getFederation
summary: Federation, its key and its friends
description: |
Admin only. Federation is off until an admin turns it on. `sends` says in plain words what a friend's server is
sent. `key_id` names the key of this server (the first 16 hex characters of the SHA-256 of its public key); it is
empty until federation was first turned on. The private key is never returned. `name` is the one saved, or the
host name.
security: [{bearerAuth: []}]
responses:
'200':
description: The settings and the friends, oldest first.
content:
application/json:
schema: {$ref: '#/components/schemas/Federation'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
put:
tags: [Federation]
operationId: updateFederation
summary: Turn federation on or off, name this server, give its address
description: |
Admin only. Fields you leave out are kept. The key pair is made the first time `enabled` becomes true and is kept
after that, so turning it off and on again does not change the key. `address` is where friends reach this server:
`https://`, or `http://` only on a network of your own (a private, loopback or link-local address, or a name that
is local: no dot, or ending `.local`, `.lan`, `.home.arpa`); without user, query or fragment. A closing slash is
dropped; an empty address clears it. An empty `name` goes back to the host name (at most 60 characters).
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/FederationUpdate'}
responses:
'200':
description: The settings as they are now.
content:
application/json:
schema: {$ref: '#/components/schemas/Federation'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/federation/invites:
post:
tags: [Federation]
operationId: createFederationInvite
summary: Make an invite for another server
description: |
Admin only. The invite is one piece of text to give to the other admin, who pastes it into
`POST /federation/friends`. It works once and expires in 24 hours; only a hash of its code is kept here. It needs
federation on (`federation_off`) and an address (`address_required`).
security: [{bearerAuth: []}]
responses:
'201':
description: The invite.
content:
application/json:
schema: {$ref: '#/components/schemas/FederationInvite'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: Federation is off (`federation_off`) or this server has no address yet (`address_required`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/friends:
post:
tags: [Federation]
operationId: useFederationInvite
summary: Use an invite made by another server
description: |
Admin only. Asks the server the invite came from to accept this one, checks that the key it answers with is the one
the invite names, and keeps it as a friend in state `outgoing`: it waits for the other admin to approve. This is
the only request federation sends at an admin's command, and it sends this server's name, address and public key
and the code of the invite. It needs federation on and an address, like making an invite.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/FederationUseInvite'}
responses:
'201':
description: The new friend, waiting for approval.
content:
application/json:
schema: {$ref: '#/components/schemas/FederationFriend'}
'400':
description: Malformed body (`invalid_input`) or not an invite of a Sonda server (`invalid_invite`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: Federation is off (`federation_off`), no address (`address_required`) or the server is already a friend (`already_friends`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'422':
description: "The other server turned the invite down: used, expired, or federation off there (`invite_refused`)."
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'429':
description: The other server asked to slow down (`too_many_requests`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: The other server could not be reached or did not answer as a Sonda server (`friend_unreachable`), or its key is not the one in the invite (`key_mismatch`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/friends/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
delete:
tags: [Federation]
operationId: removeFederationFriend
summary: Decline, withdraw or end a friendship
description: |
Admin only. Removes the friend of any state. The other server is not told: its requests are no longer answered.
The same server can be invited again afterwards.
security: [{bearerAuth: []}]
responses:
'204': {description: Removed.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such friend (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/friends/{id}/approve:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
post:
tags: [Federation]
operationId: approveFederationFriend
summary: Approve a server that used an invite of this one
description: |
Admin only. The second confirmation: a friend in state `incoming` becomes `active`. A friend in any other state
is a `409` (`not_waiting`).
security: [{bearerAuth: []}]
responses:
'200':
description: The friend, now active.
content:
application/json:
schema: {$ref: '#/components/schemas/FederationFriend'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such friend (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: The friend is not waiting for approval (`not_waiting`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/pair:
post:
tags: [Federation]
operationId: peerPair
summary: Pair with this server (called by another Sonda server)
description: |
Not for people: another Sonda server calls this when its admin pastes an invite made here. There is no login: the
code of the invite is the proof, and it works once. The other server is kept as a friend in state `incoming`
until an admin here approves it. While federation is off, or has no address, the route answers `404 not_found`,
as a missing route does. At most 10 attempts a minute, from anyone.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/PeerPairRequest'}
responses:
'200':
description: This server's name, address and public key.
content:
application/json:
schema: {$ref: '#/components/schemas/PeerPairReply'}
'400': {$ref: '#/components/responses/InvalidInput'}
'403':
description: The code is unknown, used or expired (`invalid_invite`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'404':
description: Federation is off here (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: This key is already a friend (`already_friends`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'429':
description: Too many attempts (`too_many_requests`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/friends/{id}/check:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
post:
tags: [Federation]
operationId: checkFederationFriend
summary: Ask a friend whether it approved
description: |
Admin only. Sends the friend one signed request (`GET /peer/info`). An answer means it approved, and a friend that
was `outgoing` becomes `active`. The friend is returned. A friend in state `incoming` is a `409` (`not_waiting`):
it waits for this server's admin, not the other way round.
security: [{bearerAuth: []}]
responses:
'200':
description: The friend, active when it answered.
content:
application/json:
schema: {$ref: '#/components/schemas/FederationFriend'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such friend (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: |
Federation is off (`federation_off`), the friend is not waiting for the other admin (`not_waiting`), the other
admin has not approved yet (`not_approved`), or the other server does not take this one for a friend any more
(`friend_gone`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: The other server could not be reached or did not answer as a Sonda server (`friend_unreachable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/requests:
get:
tags: [Federation]
operationId: listFederationRequests
summary: The last requests friends made
description: |
Admin only. The last 50 requests that friends made to this server, newest first, kept for 7 days: when, which
friend, which route (the pattern, never the query, so what was searched for is not kept), the status and how many
bytes were sent.
security: [{bearerAuth: []}]
responses:
'200':
description: The requests.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [requests]
properties:
requests:
type: array
items: {$ref: '#/components/schemas/FederationRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/peer/info:
get:
tags: [Federation]
operationId: peerInfo
summary: Who this server is (called by a friend)
description: |
Not for people: a friend's server calls this, signed (see the `friendSignature` scheme), and also to find out whether
this server's admin approved it. Says the name of this server and how many libraries are shared.
security: [{friendSignature: []}]
responses:
'200':
description: The name and the number of shared libraries.
content:
application/json:
schema: {$ref: '#/components/schemas/PeerInfo'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/artists:
get:
tags: [Federation]
operationId: peerListArtists
summary: The artists of the shared libraries (called by a friend)
description: |
Like `GET /artists`, over the libraries that are shared and nothing else: an artist is listed only when it has a
playable track in one of them, and the counts are of those tracks. Paths, library ids and everything that providers
said are never part of it. Signed like every `/peer` route.
security: [{friendSignature: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/artists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetArtist
summary: One artist of the shared libraries (called by a friend)
security: [{friendSignature: []}]
responses:
'200':
description: The artist.
content:
application/json:
schema: {$ref: '#/components/schemas/Artist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such artist among the shared libraries (`artist_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/albums:
get:
tags: [Federation]
operationId: peerListAlbums
summary: The albums of the shared libraries (called by a friend)
description: Like `GET /albums`, over the libraries that are shared. Signed like every `/peer` route.
security: [{friendSignature: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/ArtistId'}
responses:
'200':
description: A page of albums.
content:
application/json:
schema: {$ref: '#/components/schemas/AlbumPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/albums/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetAlbum
summary: One album of the shared libraries (called by a friend)
security: [{friendSignature: []}]
responses:
'200':
description: The album.
content:
application/json:
schema: {$ref: '#/components/schemas/Album'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such album among the shared libraries (`album_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/albums/{id}/cover:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetAlbumCover
summary: The cover of an album of the shared libraries (called by a friend)
description: |
Only a cover that this server already built from the audio files of the album: a friend never makes this server
build one, read an audio file or ask a provider. A cover that came from the Cover Art Archive is not given. Any other
album answers `cover_not_found`. The bytes go out within the friend's allowance.
security: [{friendSignature: []}]
parameters:
- name: size
in: query
description: "`small` or `large`. Large when absent."
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
responses:
'200':
description: The cover.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
content:
image/jpeg:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-None-Match`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such album among the shared libraries (`album_not_found`), no cover built (`cover_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/tracks:
get:
tags: [Federation]
operationId: peerListTracks
summary: The tracks of the shared libraries (called by a friend)
description: Like `GET /tracks`, over the libraries that are shared. Signed like every `/peer` route.
security: [{friendSignature: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/ArtistId'}
- {$ref: '#/components/parameters/AlbumId'}
responses:
'200':
description: A page of tracks.
content:
application/json:
schema: {$ref: '#/components/schemas/TrackPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/tracks/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetTrack
summary: One track of the shared libraries (called by a friend)
security: [{friendSignature: []}]
responses:
'200':
description: The track.
content:
application/json:
schema: {$ref: '#/components/schemas/Track'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such track among the shared libraries (`track_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/tracks/{id}/stream:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerStreamTrack
summary: Stream a track of the shared libraries (called by a friend)
description: |
The file of the track that lives in a shared library, with `Range` support, as a listener would get it. A track that is
only in libraries that are not shared is `track_not_found`. A friend has a few streams open at a time and a number
of bytes a second to share among them, both set by the admin (`max_streams`, `max_kib_per_sec`): one stream too many
is a `429` (`too_many_streams`) with `Retry-After`.
security: [{friendSignature: []}]
parameters:
- name: Range
in: header
required: false
description: A byte range, for example `bytes=0-99`.
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'206':
description: The requested byte range.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
multipart/byteranges:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such track among the shared libraries (`track_not_found`), its file is not available (`file_missing`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'416':
description: The range cannot be satisfied.
headers:
Content-Range:
description: '`bytes */<size of the file>`.'
schema: {type: string}
'429':
description: The friend already has as many streams open as allowed (`too_many_streams`).
headers:
Retry-After:
description: Seconds to wait.
schema: {type: integer}
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends:
get:
tags: [Friends]
operationId: listFriends
summary: The friends whose music can be browsed
description: |
The friends that both admins agreed to, by name. A listener never sees an address or a key: those are for the
admin (`GET /federation`). Empty while federation is off.
security: [{bearerAuth: []}]
responses:
'200':
description: The friends, oldest first.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [friends]
properties:
friends:
type: array
items: {$ref: '#/components/schemas/FriendRef'}
'401': {$ref: '#/components/responses/Unauthorized'}
/friends/{friend}/artists:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
get:
tags: [Friends]
operationId: listFriendArtists
summary: The artists a friend shares
description: |
This server asks the friend, with a request signed by its own key, and passes the page on after checking its
shape; nothing is kept. Only what the friend shares is there. `q`, `limit` and `offset` are the same as in
`GET /artists`. A friend that cannot be reached is `502` (`friend_unreachable`); one that no longer takes this
server for a friend is `409` (`friend_gone`).
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
'404':
description: No such friend, or it is not active (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends/{friend}/artists/{id}:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
- {$ref: '#/components/parameters/Id'}
get:
tags: [Friends]
operationId: getFriendArtist
summary: One artist of a friend
security: [{bearerAuth: []}]
responses:
'200':
description: The artist.
content:
application/json:
schema: {$ref: '#/components/schemas/Artist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
'404':
description: No such friend, or it is not active (`friend_not_found`) or the friend has no such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends/{friend}/albums:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
get:
tags: [Friends]
operationId: listFriendAlbums
summary: The albums a friend shares
description: Like `GET /friends/{friend}/artists`, for albums; `artist_id` is the friend's own id of an artist.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/ArtistId'}
responses:
'200':
description: A page of albums.
content:
application/json:
schema: {$ref: '#/components/schemas/AlbumPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
'404':
description: No such friend, or it is not active (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends/{friend}/albums/{id}:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
- {$ref: '#/components/parameters/Id'}
get:
tags: [Friends]
operationId: getFriendAlbum
summary: One album of a friend
security: [{bearerAuth: []}]
responses:
'200':
description: The album.
content:
application/json:
schema: {$ref: '#/components/schemas/Album'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
'404':
description: No such friend, or it is not active (`friend_not_found`) or the friend has no such album (`album_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends/{friend}/tracks:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
get:
tags: [Friends]
operationId: listFriendTracks
summary: The tracks a friend shares
description: |
Like `GET /friends/{friend}/artists`, for tracks; `artist_id` and `album_id` are the friend's own ids. The ids in
every answer are the friend's, never this server's: a listener keeps the friend and the id together.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/ArtistId'}
- {$ref: '#/components/parameters/AlbumId'}
responses:
'200':
description: A page of tracks.
content:
application/json:
schema: {$ref: '#/components/schemas/TrackPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
'404':
description: No such friend, or it is not active (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends/{friend}/tracks/{id}:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
- {$ref: '#/components/parameters/Id'}
get:
tags: [Friends]
operationId: getFriendTrack
summary: One track of a friend
security: [{bearerAuth: []}]
responses:
'200':
description: The track.
content:
application/json:
schema: {$ref: '#/components/schemas/Track'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
'404':
description: No such friend, or it is not active (`friend_not_found`) or the friend has no such track (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/friends/{friend}/tracks/{id}/stream:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
- {$ref: '#/components/parameters/Id'}
get:
tags: [Friends]
operationId: streamFriendTrack
summary: Stream a track of a friend
description: |
The audio of a track that a friend shares, passed on by this server: it asks the friend with a request signed by its
own key and sends the bytes on, so the listener's browser talks to this server only, and the friend sees this server
and nothing of the listener. `Range` and the conditional headers are passed to the friend, so a player can seek.
Only audio is passed on, with `Content-Type`, `Content-Length`, `Content-Range`, `Accept-Ranges` and `Last-Modified`
and nothing else of what the friend sends. Streaming never records a listen here, and a friend's track never counts
for taste. The track id is the friend's own.
Like the stream of a local track, this accepts the access token as the `access_token` query parameter. A header, when
present, always wins. A friend that already has as many streams open as its admin allows is a `429`
(`friend_busy`).
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: Range
in: header
required: false
description: A byte range, for example `bytes=0-99`.
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'206':
description: The requested byte range.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such friend, or it is not active (`friend_not_found`), or the friend has no such track among what it shares (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409': {$ref: '#/components/responses/FriendGone'}
'416':
description: The range cannot be satisfied.
headers:
Content-Range:
description: '`bytes */<size of the file>`.'
schema: {type: string}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
/friends/{friend}/albums/{id}/cover:
parameters:
- {name: friend, in: path, required: true, description: The id from `GET /friends`., schema: {type: integer, format: int64, minimum: 1}}
- {$ref: '#/components/parameters/Id'}
get:
tags: [Friends]
operationId: getFriendAlbumCover
summary: The cover of an album of a friend
description: |
The cover of an album that a friend shares, passed on like the stream. Only a JPEG is passed on. The friend gives a
cover only once it was built on its server from the audio files of the album, so an album may have none yet
(`cover_not_found`): the listener then sees the usual placeholder. Accepts the access token as the `access_token`
query parameter, like the cover of a local album.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: size
in: query
description: "`small` or `large`. Large when absent."
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
responses:
'200':
description: The cover.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
content:
image/jpeg:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-None-Match`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such friend, or it is not active (`friend_not_found`), or no such album or no cover built there yet (`cover_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409': {$ref: '#/components/responses/FriendGone'}
'429': {$ref: '#/components/responses/FriendBusy'}
'502': {$ref: '#/components/responses/FriendUnreachable'}
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: The `access_token` from `POST /auth/login` or `POST /auth/refresh`.
streamQueryToken:
type: apiKey
in: query
name: access_token
description: The same access token, for stream URLs used by an `<audio>` element. Accepted only on `/tracks/{id}/stream`, `/albums/{id}/cover`, `/artists/{id}/image` and the same two of a friend under `/friends/{friend}`.
friendSignature:
type: apiKey
in: header
name: Sonda-Signature
description: |
For the routes under `/peer`, which only another Sonda server calls. Each request carries four headers:
`Sonda-Key-Id` (the first 16 hex characters of the SHA-256 of the sender's public key), `Sonda-Date` (unix
seconds, at most two minutes from the receiver's clock), `Sonda-Nonce` (16 to 64 characters of `A-Za-z0-9_-`, never
used twice) and `Sonda-Signature` (the Ed25519 signature, base64url without padding, of these five lines:
the method, the path from `/api/v1/peer` on with the query as sent, the date, the nonce and the SHA-256 in hex of
the body, which is empty). Anything that is not properly signed gets the same `401`.
parameters:
Id:
name: id
in: path
required: true
schema: {type: integer, format: int64, minimum: 1}
Q:
name: q
in: query
description: |
Case- and accent-insensitive substring of the name or title: `bjork`, `BJORK` and `BJÖRK` all
find `Björk`, and `strasse` finds `Straße`. At most 200 characters.
schema: {type: string, maxLength: 200}
Full:
name: full
in: query
description: "`true` reads every file again, not only the new or changed ones. Only `true` and `false` are accepted."
schema: {type: boolean, default: false}
Limit:
name: limit
in: query
description: Page size. 50 when absent or 0; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0, default: 50}
Offset:
name: offset
in: query
schema: {type: integer, minimum: 0, default: 0}
SuggestedKey:
name: key
in: path
required: true
description: A key from `GET /smart-playlists/suggested`.
schema: {type: string, enum: [recently-added, on-rotation, top-year, most-played, never-played, forgotten, high-quality, long-tracks]}
MixId:
name: id
in: path
required: true
description: "`favourites`, `rediscover`, `unheard` or `genre:<name>` (percent-encoded)."
schema: {type: string}
LibraryId:
name: library_id
in: query
description: Only items with a playable file in this library.
schema: {type: integer, format: int64, minimum: 1}
ArtistId:
name: artist_id
in: query
schema: {type: integer, format: int64, minimum: 1}
AlbumId:
name: album_id
in: query
schema: {type: integer, format: int64, minimum: 1}
headers:
ETag:
description: Identifies the stored picture, in quotes.
schema: {type: string}
CacheControl:
description: "`private, max-age=3600`."
schema: {type: string}
AcceptRanges:
description: Always `bytes`.
schema: {type: string}
ContentLength:
schema: {type: integer}
LastModified:
schema: {type: string}
responses:
FriendUnauthorized:
description: "The request is not signed by a friend: no signature, a bad one, an old date, a nonce used before or an unknown key, all the same answer (`unauthorized`)."
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FriendNotApproved:
description: The signature is good but the admin of this server has not approved the friend yet (`not_approved`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FriendGone:
description: The friend no longer takes this server for a friend (`friend_gone`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FriendBusy:
description: The friend is busy (`friend_busy`). Try again after `Retry-After` seconds.
headers:
Retry-After:
description: Seconds to wait.
schema: {type: integer}
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FriendUnreachable:
description: The friend could not be reached, or sent something that is not a catalogue page (`friend_unreachable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FederationOff:
description: Federation is off on this server, so the route is as good as missing (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
InvalidInput:
description: The request is malformed or a value is out of range (`invalid_input`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
Unauthorized:
description: The access token is missing, invalid or expired, or the account it belongs to no longer exists (`unauthorized`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
AdminRequired:
description: The account is not an admin (`admin_required`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
MixNotFound:
description: No such mix, or you do not have it (`mix_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
SuggestedNotFound:
description: No such suggested smart playlist (`suggested_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
SmartPlaylistNotFound:
description: No such smart playlist, or it is somebody else's (`smart_playlist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
PlaylistNotFound:
description: No such playlist, or it is somebody else's (`playlist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
PlaylistLimit:
description: A limit was reached, 1000 playlists for a user or 10000 tracks in a playlist (`limit_reached`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
LibraryNotFound:
description: No such library (`library_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
ScanStarted:
description: The scan was started in the background.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [started]}
schemas:
Error:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code, message]
properties:
code:
type: string
description: |
A stable identifier, for example `invalid_input`, `unauthorized`, `admin_required`,
`user_not_found`, `last_admin`, `library_exists`, `scan_running`, `track_not_found`.
message: {type: string}
Credentials:
type: object
required: [email, password]
properties:
email:
type: string
maxLength: 254
description: |
An address like `name@example.org`, with no display name. It is trimmed and lowercased,
and it is unique. Sonda sends no mail and does not check that the address exists.
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
LoginRequest:
type: object
required: [email, password]
properties:
email:
type: string
description: |
The address of the account, in any case. An account made before addresses were asked
for logs in with the plain name it has.
password: {type: string, format: password}
CreateUser:
allOf:
- $ref: '#/components/schemas/Credentials'
- type: object
properties:
is_admin: {type: boolean, default: false}
User:
type: object
additionalProperties: false
required: [id, email, is_admin]
properties:
id: {type: integer, format: int64}
email: {type: string}
is_admin: {type: boolean}
Session:
type: object
additionalProperties: false
required: [access_token, access_expires_at, refresh_token, refresh_expires_at, user]
properties:
access_token: {type: string}
access_expires_at: {type: string, format: date-time}
refresh_token: {type: string, description: Works once.}
refresh_expires_at: {type: string, format: date-time}
user: {$ref: '#/components/schemas/User'}
RefreshRequest:
type: object
required: [refresh_token]
properties:
refresh_token: {type: string}
PasswordChange:
type: object
required: [current_password, new_password]
properties:
current_password: {type: string, format: password}
new_password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
Library:
type: object
additionalProperties: false
required: [id, name, path, shared, created_at]
properties:
id: {type: integer, format: int64}
name: {type: string}
path: {type: string, description: Absolute directory on the server.}
shared: {type: boolean, description: Whether friends (federation) may read this library. Off until an admin turns it on.}
created_at: {type: string, format: date-time}
NewLibrary:
type: object
required: [name, path]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string, description: "Absolute, existing directory."}
LibraryUpdate:
type: object
anyOf:
- required: [name]
- required: [path]
- required: [shared]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string}
shared: {type: boolean, description: "Whether friends may read this library. Changing it never needs a scan and never waits for one."}
ScanSummary:
type: object
additionalProperties: false
required: [libraries, found, added, updated, unchanged, renamed, restored, missing, failed, skipped, unsupported]
properties:
libraries: {type: integer, description: Libraries covered by the scan.}
found: {type: integer, description: Audio files seen on disk (MP3 and FLAC).}
added: {type: integer}
updated: {type: integer}
unchanged: {type: integer}
renamed: {type: integer, description: Files that moved; they keep their track.}
restored: {type: integer, description: Files that were missing and are back.}
missing: {type: integer, description: Files newly flagged as missing. They are never deleted.}
failed: {type: integer, description: Files that could not be read.}
skipped: {type: integer, description: Symlinks and special files.}
unsupported: {type: integer, description: "Audio files in formats Sonda cannot read yet, such as m4a, ogg or wav."}
ScanStatus:
type: object
additionalProperties: false
required: [running]
properties:
running: {type: boolean}
started_at: {type: string, format: date-time}
last_finished_at: {type: string, format: date-time}
last: {$ref: '#/components/schemas/ScanSummary'}
last_error: {type: string}
ArtistRef:
type: object
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64}
name: {type: string}
AlbumRef:
type: object
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
Artist:
type: object
additionalProperties: false
required: [id, name, album_count, track_count]
properties:
id: {type: integer, format: int64}
name: {type: string}
album_count: {type: integer}
track_count: {type: integer, description: Playable tracks the artist is credited on.}
Album:
type: object
additionalProperties: false
required: [id, title, artist, track_count, duration_ms]
properties:
id: {type: integer, format: int64}
title: {type: string}
artist:
type: object
nullable: true
description: The album artist; null when the album has none.
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64}
name: {type: string}
track_count: {type: integer}
duration_ms: {type: integer, format: int64}
Track:
type: object
additionalProperties: false
required: [id, title, duration_ms, track_no, disc_no, album, artists, format]
properties:
id: {type: integer, format: int64}
title: {type: string}
duration_ms: {type: integer, format: int64}
track_no: {type: integer, description: 0 when unknown.}
disc_no: {type: integer, description: 0 when unknown.}
album:
type: object
nullable: true
description: The album; null for a track that belongs to none.
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
artists:
type: array
items: {$ref: '#/components/schemas/ArtistRef'}
format: {type: string, description: 'Format of the first playable file, for example `mp3` or `flac`.'}
ArtistPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Artist'}
total: {type: integer, description: "Size of the whole result, not of this page."}
limit: {type: integer}
offset: {type: integer}
AlbumPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Album'}
total: {type: integer}
limit: {type: integer}
offset: {type: integer}
TrackPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Track'}
total: {type: integer}
limit: {type: integer}
offset: {type: integer}
Listen:
type: object
required: [track_id, event_type, idempotency_key]
properties:
track_id: {type: integer, format: int64, minimum: 1}
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time, description: Defaults to now.}
duration_played_ms:
type: integer
format: int64
minimum: 0
description: Milliseconds actually played. Up to twice the track length plus 10 seconds when that length is known.
idempotency_key: {type: string, description: "One per play, 1 to 128 bytes (UTF-8). A key that was already used is ignored."}
Provider:
type: object
additionalProperties: false
required: [name, enabled, needs_api_key, needs_url, has_api_key, contact, url, sends, notes, updated_at]
properties:
name: {type: string, enum: [lastfm, musicbrainz, wikipedia, commons, coverartarchive, lidarr, anthropic]}
enabled: {type: boolean, description: Whether Sonda may contact this provider.}
needs_api_key: {type: boolean}
needs_url: {type: boolean, description: "Whether the provider is a server of your own that needs an address (only Lidarr)."}
has_api_key: {type: boolean, description: Whether a key is stored. The key itself is never returned.}
contact: {type: string, description: Contact in the User-Agent; empty means the project address.}
url: {type: string, description: "Where your own server is, without a closing slash. Empty for the providers that have none."}
lidarr: {$ref: '#/components/schemas/LidarrOptions'}
sends: {type: string, description: "Plain statement of what is sent to the provider, and what never is."}
notes: {type: string, description: Terms of use and attribution that apply to the provider's data.}
updated_at:
type: string
format: date-time
nullable: true
description: When the settings last changed; null if they never did.
LidarrOptions:
type: object
additionalProperties: false
description: |
Only for `lidarr`: what is sent to Lidarr when an artist is added, chosen once by an admin from
`GET /providers/lidarr/options`. Until they are saved, `monitor` is `all`, `search_missing` is
true and the rest is empty or 0, which is not enough to add an artist.
required: [quality_profile_id, metadata_profile_id, root_folder_path, monitor, search_missing]
properties:
quality_profile_id: {type: integer, minimum: 0, description: "Lidarr's quality profile; 0 when none is chosen."}
metadata_profile_id: {type: integer, minimum: 0, description: "Lidarr's metadata profile; 0 when none is chosen."}
root_folder_path: {type: string, maxLength: 500, description: "One of Lidarr's root folders; empty when none is chosen."}
monitor:
type: string
enum: [all, future, missing, existing, latest, first, none]
description: "Which of the artist's albums Lidarr monitors when it is added. `none` also stops new albums from being monitored."
search_missing: {type: boolean, description: Whether Lidarr starts looking for the albums as soon as the artist is added.}
LidarrOffers:
type: object
additionalProperties: false
required: [quality_profiles, metadata_profiles, root_folders]
properties:
quality_profiles:
type: array
items: {$ref: '#/components/schemas/LidarrProfile'}
metadata_profiles:
type: array
items: {$ref: '#/components/schemas/LidarrProfile'}
root_folders:
type: array
items:
type: object
additionalProperties: false
required: [path, accessible]
properties:
path: {type: string}
accessible: {type: boolean, description: Whether Lidarr can use the folder now.}
ArtistInLidarr:
type: object
additionalProperties: false
required: [provider_status, in_lidarr, monitored]
properties:
provider_status:
type: string
enum: [ok, disabled, no_id, not_configured, error]
description: "`ok` when Lidarr was asked (and `in_lidarr` is its answer); the others say why it was not."
in_lidarr: {type: boolean}
monitored: {type: boolean, description: Whether Lidarr monitors the artist; false when it does not have it.}
LidarrProfile:
type: object
additionalProperties: false
required: [id, name]
properties:
id: {type: integer}
name: {type: string}
ProviderUpdate:
type: object
anyOf:
- required: [enabled]
- required: [api_key]
- required: [contact]
- required: [url]
- required: [lidarr]
properties:
enabled: {type: boolean}
api_key:
type: string
format: password
description: A Last.fm or Lidarr key is 32 hexadecimal characters. Empty clears it.
url:
type: string
maxLength: 300
description: |
Only for Lidarr: where your own server is, `http://` or `https://`, with a port and a path if it
has them, and without user and password, query or fragment. A closing slash is dropped. Empty
clears it, and turns Lidarr off. Lidarr cannot be enabled without an address and a key.
lidarr:
description: "Only for Lidarr. Replaces all its options at once: what is left out is the default (`monitor` all, `search_missing` true, the rest empty or 0)."
type: object
additionalProperties: false
properties:
quality_profile_id: {type: integer, minimum: 0}
metadata_profile_id: {type: integer, minimum: 0}
root_folder_path: {type: string, maxLength: 500}
monitor: {type: string, enum: [all, future, missing, existing, latest, first, none]}
search_missing: {type: boolean}
contact:
type: string
maxLength: 200
description: A URL or e-mail address, without parentheses. Empty restores the default.
ArtistDescription:
type: object
additionalProperties: false
required: [provider, provider_status, stale, retrieved_at, attribution, description]
properties:
provider: {type: string, enum: [wikipedia]}
provider_status:
type: string
enum: [ok, disabled, error, no_id]
description: |
`ok` when the stored answer is as fresh as it needs to be (which can be "nothing found");
`disabled` when the provider is off; `error` when Wikipedia could not be asked; `no_id`
when the artist has no MusicBrainz id.
stale: {type: boolean, description: True when the description is older than it should be because Wikipedia could not be asked.}
retrieved_at: {type: string, format: date-time, nullable: true, description: When it was read; null when nothing is known.}
attribution: {type: string, description: What to show where the text is shown.}
description:
type: object
nullable: true
allOf:
- {$ref: '#/components/schemas/Description'}
Description:
type: object
additionalProperties: false
required: [text, short, language, title, url, license, license_url]
properties:
text: {type: string, description: "The first paragraph of the article, plain text, at most 4000 characters."}
short: {type: string, description: "One line, like \"gruppo musicale inglese\". May be empty."}
language: {type: string, description: "The language of the page, like `it`."}
title: {type: string, description: "The title of the page."}
url: {type: string, format: uri, description: "The page, on Wikipedia."}
license: {type: string, description: "The licence of the text."}
license_url: {type: string, format: uri}
PictureCredit:
type: object
additionalProperties: false
required: [source, author, license, license_url, page_url]
properties:
source: {type: string, description: "Where the picture comes from: `Wikimedia Commons`."}
author: {type: string, description: "Plain text. May be empty."}
license: {type: string, description: "Like `CC BY-SA 4.0`."}
license_url: {type: string, description: "The licence, on creativecommons.org. May be empty."}
page_url: {type: string, format: uri, description: The page of the file on Commons.}
ProviderPurge:
type: object
additionalProperties: false
required: [similar_artists, tags, descriptions, images, artists]
properties:
similar_artists: {type: integer, description: Similar-artist links removed.}
descriptions: {type: integer, description: Artist descriptions removed (only the data of Wikipedia has any).}
images: {type: integer, description: "Pictures removed: the photos of artists for Commons, the covers that came from the archive for the Cover Art Archive."}
tags: {type: integer, description: Tags removed.}
artists: {type: integer, description: "Artists removed because only the removed data named them and nobody has files for them."}
ProviderTest:
type: object
additionalProperties: false
required: [ok, status]
properties:
ok: {type: boolean}
status:
type: string
enum: [ok, no_api_key, no_address, key_refused, rate_limited, unreachable, error]
description: |
`no_api_key`: none is stored, so nobody was asked. `no_address`: Lidarr has no address yet, so nobody was asked. `key_refused`: the provider does not accept
it. `rate_limited`: try again later. `unreachable`: the provider did not answer. `error`: anything else.
ArtistTags:
type: object
additionalProperties: false
required: [sources]
properties:
sources:
type: array
items:
type: object
additionalProperties: false
required: [provider, provider_status, stale, retrieved_at, attribution, tags]
properties:
provider: {type: string, enum: [lastfm, musicbrainz, files]}
provider_status:
type: string
enum: [ok, disabled, error, no_id]
description: |
`ok`: the data is as fresh as it needs to be. `disabled`: the provider is off or has no
key, so it was not asked. `error`: it was asked and failed. `no_id`: it needs the
MusicBrainz id of the artist, which is not known, so it was not asked.
stale: {type: boolean, description: "True when `tags` are older than they should be because the provider could not be asked."}
retrieved_at:
type: string
format: date-time
nullable: true
description: When the provider was last read for this artist; null if never.
attribution: {type: string, description: Credit to show where the tags are shown.}
tags:
type: array
description: The heaviest tags first, at most 50.
items:
type: object
additionalProperties: false
required: [name, weight, genre]
properties:
name: {type: string, description: Lower case.}
weight: {type: number, description: "The provider's own number; see the operation."}
genre: {type: boolean}
SimilarArtists:
type: object
additionalProperties: false
required: [provider, provider_status, stale, retrieved_at, attribution, items]
properties:
provider: {type: string, enum: [lastfm]}
provider_status:
type: string
enum: [ok, disabled, error]
description: |
`ok`: the data is as fresh as it needs to be. `disabled`: the provider is off or has no key,
so it was not asked. `error`: it was asked and failed.
stale: {type: boolean, description: "True when `items` are older than they should be because the provider could not be asked."}
retrieved_at:
type: string
format: date-time
nullable: true
description: When the provider was last read for this artist; null if never.
attribution: {type: string, description: Credit to show where the data is shown.}
items:
type: array
items:
type: object
additionalProperties: false
required: [artist, in_library, score, rank]
properties:
artist: {$ref: '#/components/schemas/ArtistRef'}
in_library: {type: boolean, description: Whether the artist has something playable in the library.}
score: {type: number, minimum: 0, maximum: 1, description: "The provider's own number, relative to this list."}
rank: {type: integer, minimum: 1, description: "Position in the provider's list, 1 first."}
ListenResult:
type: object
additionalProperties: false
required: [status, counted]
properties:
status: {type: string, enum: [recorded, duplicate]}
counted: {type: boolean, description: Whether the event counts as a listen.}
ListenItem:
type: object
additionalProperties: false
required: [id, track, event_type, occurred_at, duration_played_ms, counted]
properties:
id: {type: integer, format: int64}
track:
type: object
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time}
duration_played_ms: {type: integer, format: int64}
counted: {type: boolean, description: Whether the event counts as a listen under the current rule.}
Taste:
type: object
additionalProperties: false
required: [artists, tags]
properties:
artists:
type: array
items: {$ref: '#/components/schemas/TasteArtist'}
tags:
type: array
items: {$ref: '#/components/schemas/TasteTag'}
Discover:
type: object
additionalProperties: false
required: [provider_status, attribution, from_listening, seeds, items]
properties:
provider_status: {type: string, enum: [ok, disabled, error]}
attribution: {type: string, description: What to show where the data is shown.}
from_listening: {type: boolean, description: "True when the seeds were taken from your listening, false when you named them."}
seeds:
type: array
items: {$ref: '#/components/schemas/DiscoverSeed'}
items:
type: array
items: {$ref: '#/components/schemas/Suggestion'}
Mix:
type: object
additionalProperties: false
required: [id, kind, title, genre, artists, album_ids]
properties:
id: {type: string, description: "`favourites`, `rediscover`, `unheard` or `genre:<name>`."}
kind: {type: string, enum: [genre, favourites, rediscover, unheard]}
title: {type: string, description: In English.}
genre: {type: string, nullable: true, description: "The genre, for a genre mix; null for the others."}
artists: {type: array, items: {type: string}, description: "A few of the artists it has, up to 3."}
album_ids:
type: array
maxItems: 4
items: {type: integer, format: int64}
description: |
Up to 4 albums that have a cover and stand for the mix, by different artists, the ones with most songs
among those the mix draws from: their covers (`GET /albums/{id}/cover`) make the picture of the mix.
Empty when none has a cover.
MixList:
type: object
additionalProperties: false
required: [items]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Mix'}
MixWithTracks:
type: object
additionalProperties: false
required: [id, kind, title, genre, artists, album_ids, variant, tracks]
properties:
id: {type: string}
kind: {type: string, enum: [genre, favourites, rediscover, unheard]}
title: {type: string}
genre: {type: string, nullable: true}
artists: {type: array, items: {type: string}}
album_ids: {type: array, maxItems: 4, items: {type: integer, format: int64}, description: "As in the list of mixes."}
variant: {type: integer, minimum: 0}
tracks:
type: array
description: In the order to play them. Fewer than 50 when the library has fewer to give.
items: {$ref: '#/components/schemas/Track'}
SaveMix:
type: object
additionalProperties: false
properties:
name: {type: string, maxLength: 200, description: "The name of the playlist; blank or absent means the title of the mix."}
variant: {type: integer, minimum: 0, maximum: 1000000, description: "The variant the client showed; absent means the mix of the day."}
auto_name: {type: boolean, default: false, description: "When true and the Claude provider is on, the playlist is named by Claude from its songs (with a line of description), and `name` is only the name to give it when Claude is off, fails or declines."}
lang: {type: string, maxLength: 16, description: "The language of a name that Claude makes: `en` or `it`. Absent or another: English."}
GenreList:
type: object
additionalProperties: false
required: [items]
properties:
items:
type: array
items:
type: object
additionalProperties: false
required: [name, tracks]
properties:
name: {type: string}
tracks: {type: integer, description: Playable songs that have the genre.}
ClaudeUsageTotals:
type: object
additionalProperties: false
required: [names_made, names_kept, failures, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_usd]
properties:
names_made: {type: integer, description: Names that Claude made.}
names_kept: {type: integer, description: "Names taken from the ones kept, which cost nothing."}
failures: {type: integer, description: Questions that gave no name.}
input_tokens: {type: integer, format: int64}
output_tokens: {type: integer, format: int64}
cache_read_tokens: {type: integer, format: int64}
cache_write_tokens: {type: integer, format: int64}
cost_usd: {type: number, description: "An estimate in dollars, worked out from the tokens and the price of the model."}
ClaudeUsageDay:
type: object
additionalProperties: false
required: [date, names_made, names_kept, failures, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_usd]
properties:
date: {type: string, format: date, description: "The day, in UTC."}
names_made: {type: integer}
names_kept: {type: integer}
failures: {type: integer}
input_tokens: {type: integer, format: int64}
output_tokens: {type: integer, format: int64}
cache_read_tokens: {type: integer, format: int64}
cache_write_tokens: {type: integer, format: int64}
cost_usd: {type: number, description: "An estimate in dollars."}
ClaudeUsage:
type: object
additionalProperties: false
required: [days, model, estimate, unpriced, totals, daily]
properties:
days: {type: integer}
model: {type: string, description: The model that is asked now.}
estimate: {type: boolean, description: "Always true: the cost is worked out from the tokens, it is not the invoice."}
unpriced: {type: boolean, description: "Some calls were to a model whose price is not known and are not in the cost."}
totals: {$ref: '#/components/schemas/ClaudeUsageTotals'}
daily:
type: array
items: {$ref: '#/components/schemas/ClaudeUsageDay'}
SuggestName:
type: object
additionalProperties: false
properties:
lang: {type: string, maxLength: 16, description: "The language of the name: `en` or `it`. Absent or another: English."}
variant: {type: integer, minimum: 0, maximum: 1000000, default: 0, description: "For a mix or a smart playlist: the variant that is on screen."}
NameSuggestion:
type: object
additionalProperties: false
required: [name, description, source]
properties:
name: {type: string}
description: {type: string, description: One short sentence.}
source: {type: string, enum: [claude, local], description: "`claude` when the Claude provider made it, `local` when it was made on this server."}
SmartRules:
type: object
additionalProperties: false
description: |
Every rule that is set must hold; one that is absent, empty, false or 0 does not count. Of a list rule a
song needs to match one item.
properties:
genres: {type: array, maxItems: 50, items: {type: string}, description: "Kept lower case, with `+`, `-`, `_` and `/` taken for spaces: `jazz+funk` and `jazz-funk` are one genre."}
not_genres: {type: array, maxItems: 50, items: {type: string}, description: Leaves out songs of these genres.}
artist_ids: {type: array, maxItems: 50, items: {type: integer, format: int64, minimum: 1}, description: Songs whose main artist is one of these.}
not_artist_ids: {type: array, maxItems: 50, items: {type: integer, format: int64, minimum: 1}}
album_ids: {type: array, maxItems: 50, items: {type: integer, format: int64, minimum: 1}}
not_album_ids: {type: array, maxItems: 50, items: {type: integer, format: int64, minimum: 1}}
formats: {type: array, maxItems: 50, items: {type: string}, description: "File formats in lower case (`flac`, `mpeg`). A song counts when a file of it that is not missing has one of them."}
min_bitrate_kbps: {type: integer, minimum: 0, maximum: 100000, description: Needs a file of the song with this bitrate or more (the same file as `formats`).}
added_within_days: {type: integer, minimum: 0, maximum: 36500, description: "About the date of the file, which is the best the index knows."}
never_played: {type: boolean, description: Songs you never listened to.}
played_within_days: {type: integer, minimum: 0, maximum: 36500}
not_played_within_days: {type: integer, minimum: 0, maximum: 36500, description: Songs not played for this many days (the ones never played too).}
min_plays: {type: integer, minimum: 0, maximum: 1000000}
plays_within_days: {type: integer, minimum: 0, maximum: 36500, description: "Counts only the plays of the last N days where plays are counted: `min_plays` and the `most_played` and `least_played` orders. The other listening rules are not changed."}
skipped_within_days: {type: integer, minimum: 0, maximum: 36500}
not_skipped_within_days: {type: integer, minimum: 0, maximum: 36500, description: Leaves out songs skipped in the last days.}
liked_artists_only: {type: boolean, description: Only songs by artists you like.}
without_avoided_artists: {type: boolean, description: Leaves out songs by artists you avoid.}
min_duration_sec: {type: integer, minimum: 0, maximum: 86400}
max_duration_sec: {type: integer, minimum: 0, maximum: 86400}
SuggestedSmartPlaylist:
type: object
additionalProperties: false
required: [key, rules, sort, limit]
properties:
key: {type: string, enum: [recently-added, on-rotation, top-year, most-played, never-played, forgotten, high-quality, long-tracks]}
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500}
SuggestedSmartPlaylistList:
type: object
additionalProperties: false
required: [items]
properties:
items:
type: array
items: {$ref: '#/components/schemas/SuggestedSmartPlaylist'}
SmartSort:
type: string
enum: [random, most_played, least_played, recently_added, title]
description: A tie always goes to the lower song id.
SmartPlaylist:
type: object
additionalProperties: false
required: [id, name, description, rules, sort, limit, created_at, updated_at]
properties:
id: {type: integer, format: int64}
name: {type: string}
description: {type: string}
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500, description: The most songs it gives.}
created_at: {type: string, format: date-time}
updated_at: {type: string, format: date-time}
SmartPlaylistPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/SmartPlaylist'}
total: {type: integer}
limit: {type: integer}
offset: {type: integer}
CreateSmartPlaylist:
type: object
additionalProperties: false
properties:
name: {type: string, maxLength: 200, description: "Trimmed. It can be blank or absent only when the Claude provider is on (see `GET /naming`): Claude then names the playlist from the songs its rules give, and a failure is `invalid_input`."}
lang: {type: string, maxLength: 16, description: "The language of a name that Claude makes: `en` or `it`. Absent or another: English."}
description: {type: string, maxLength: 2000}
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500, default: 50}
UpdateSmartPlaylist:
type: object
additionalProperties: false
description: What is given changes; the rules replace the old ones whole.
properties:
name: {type: string, minLength: 1, maxLength: 200}
description: {type: string, maxLength: 2000}
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500}
PreviewSmartPlaylist:
type: object
additionalProperties: false
properties:
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500, default: 50}
variant: {type: integer, minimum: 0, maximum: 1000000, default: 0}
SmartCovers:
type: object
additionalProperties: false
required: [album_ids]
properties:
album_ids: {type: array, maxItems: 4, items: {type: integer, format: int64}}
SmartTracks:
type: object
additionalProperties: false
required: [variant, tracks]
properties:
variant: {type: integer, minimum: 0}
tracks:
type: array
description: In the order of the playlist. Empty when no song meets the rules.
items: {$ref: '#/components/schemas/Track'}
SaveSmartPlaylist:
type: object
additionalProperties: false
properties:
name: {type: string, maxLength: 200, description: "The name of the playlist; blank or absent means the name of the smart playlist."}
variant: {type: integer, minimum: 0, maximum: 1000000, description: "The variant the client showed; absent means the songs of the day."}
auto_name: {type: boolean, default: false, description: "When true and the Claude provider is on, the playlist is named by Claude from its songs (with a line of description), and `name` is only the name to give it when Claude is off, fails or declines."}
lang: {type: string, maxLength: 16, description: "The language of a name that Claude makes: `en` or `it`. Absent or another: English."}
Playlist:
type: object
additionalProperties: false
required: [id, name, description, track_count, duration_ms, created_at, updated_at, album_ids]
properties:
id: {type: integer, format: int64}
name: {type: string}
description: {type: string}
track_count: {type: integer, description: "Items in the playlist, available or not."}
duration_ms: {type: integer, format: int64, description: "Their total length."}
created_at: {type: string, format: date-time}
updated_at: {type: string, format: date-time, description: "When it was last changed, tracks included."}
album_ids:
type: array
maxItems: 4
items: {type: integer, format: int64}
description: |
Up to 4 albums that have a cover and stand for the playlist, in the order they first appear in it, each once:
their covers (`GET /albums/{id}/cover`) make the picture of the playlist. Empty when none of its songs has
an album with a cover.
PlaylistPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Playlist'}
total: {type: integer, description: "Size of the whole list, not of this page."}
limit: {type: integer}
offset: {type: integer}
PlaylistItem:
type: object
additionalProperties: false
required: [id, position, available, added_at, track]
properties:
id: {type: integer, format: int64, description: "Identifies this place of the playlist; the track may be there twice."}
position: {type: integer, minimum: 0}
available: {type: boolean, description: "False when the track has no file to play now."}
added_at: {type: string, format: date-time}
track: {$ref: '#/components/schemas/Track'}
PlaylistItemPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/PlaylistItem'}
total: {type: integer, description: "Items in the whole playlist."}
limit: {type: integer}
offset: {type: integer}
CreatePlaylist:
type: object
additionalProperties: false
required: [name]
properties:
name: {type: string, minLength: 1, maxLength: 200, description: Trimmed.}
description: {type: string, maxLength: 2000}
UpdatePlaylist:
type: object
additionalProperties: false
description: At least one of the two.
properties:
name: {type: string, minLength: 1, maxLength: 200}
description: {type: string, maxLength: 2000, description: "An empty one clears it."}
AddPlaylistTracks:
type: object
additionalProperties: false
required: [track_ids]
properties:
track_ids:
type: array
minItems: 1
maxItems: 500
items: {type: integer, format: int64, minimum: 1}
position: {type: integer, minimum: 0, description: "Where the first one goes, up to the number of items; absent means the end."}
MovePlaylistItem:
type: object
additionalProperties: false
required: [position]
properties:
position: {type: integer, minimum: 0}
MarkedPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/MarkedArtist'}
total: {type: integer, description: "Size of the whole list, not of this page."}
limit: {type: integer}
offset: {type: integer}
MarkedArtist:
type: object
additionalProperties: false
required: [artist, in_library, marked_at]
properties:
artist: {$ref: '#/components/schemas/ArtistRef'}
in_library: {type: boolean, description: Whether there is music of the artist to play.}
marked_at: {type: string, format: date-time}
DiscoverSeed:
type: object
additionalProperties: false
required: [id, name, weight]
properties:
id: {type: integer, format: int64}
name: {type: string}
weight: {type: number, minimum: 0, maximum: 1, description: "1 for a seed you named, your preference for one taken from your listening."}
Suggestion:
type: object
additionalProperties: false
required: [artist, in_library, wishlisted, score, components, because]
properties:
artist: {$ref: '#/components/schemas/ArtistRef'}
in_library: {type: boolean}
wishlisted: {type: boolean, description: True when the artist is on your wishlist.}
score: {type: number, minimum: 0, maximum: 1}
components: {$ref: '#/components/schemas/ScoreParts'}
because:
type: array
description: Up to three seeds that count most for this suggestion, strongest first.
items: {$ref: '#/components/schemas/SuggestionReason'}
ScoreParts:
type: object
additionalProperties: false
required: [a, g, p, d]
properties:
a: {type: number, minimum: 0, maximum: 1, description: Affinity.}
g: {type: number, minimum: 0, maximum: 1, nullable: true, description: "Genre. Null when the artist has no tags or you have no taste to compare with; the score is then worked out without it."}
p: {type: number, minimum: 0, maximum: 1, description: Preference. 0.5 for an artist you never played.}
d: {type: number, minimum: 0, maximum: 1, description: Discovery bonus.}
SuggestionReason:
type: object
additionalProperties: false
required: [artist, match]
properties:
artist: {$ref: '#/components/schemas/ArtistRef'}
match: {type: number, minimum: 0, maximum: 1, description: "Last.fm's similarity of the suggestion to this seed, relative to the seed's own list."}
CoversJobStatus:
type: object
additionalProperties: false
required: [running]
properties:
running: {type: boolean}
started_at: {type: string, format: date-time, description: "When the last job started."}
last_finished_at: {type: string, format: date-time}
progress:
type: object
description: Only while the job runs.
additionalProperties: false
required: [done, total]
properties:
done: {type: integer}
total: {type: integer, description: "Albums the job set out to do."}
last:
type: object
description: How the last finished job ended.
additionalProperties: false
required: [checked, from_files, from_archive, none, skipped, failed, stopped]
properties:
checked: {type: integer, description: "Albums looked at."}
from_files: {type: integer, description: "Covers found in the user's own files."}
from_archive: {type: integer, description: "Covers from the Cover Art Archive."}
none: {type: integer, description: "Albums with no cover anywhere."}
skipped: {type: integer, description: "Albums that vanished while the job ran."}
failed: {type: integer, description: "Albums whose cover could not be built just then."}
stopped: {type: boolean, description: "It was stopped, or the application was."}
last_error: {type: string, description: "Why the last job ended before the end, for example that the provider kept failing."}
ArtistJobStatus:
type: object
additionalProperties: false
required: [running]
properties:
running: {type: boolean}
started_at: {type: string, format: date-time, description: "When the last job started."}
last_finished_at: {type: string, format: date-time}
progress:
type: object
description: Only while the job runs.
additionalProperties: false
required: [done, total]
properties:
done: {type: integer}
total: {type: integer, description: "Artists the job set out to do."}
last:
type: object
description: How the last finished job ended.
additionalProperties: false
required: [checked, found, none, skipped, failed, stopped]
properties:
checked: {type: integer, description: "Artists looked at."}
found: {type: integer, description: "Artists for which a picture, or a description, was found."}
none: {type: integer, description: "Artists for which the provider has nothing."}
skipped: {type: integer, description: "Artists that vanished, or lost their id, while the job ran."}
failed: {type: integer, description: "Artists that could not be looked up just then."}
stopped: {type: boolean, description: "It was stopped, or the application was."}
last_error: {type: string, description: "Why the last job ended before the end, for example that a provider is off or kept failing."}
DuplicatesPage:
type: object
additionalProperties: false
required: [deletion_allowed, total, limit, offset, groups]
properties:
deletion_allowed: {type: boolean, description: "Whether `POST /library/duplicates/clean` can work (`library.allow_delete`)."}
total: {type: integer, description: "Groups in all, not in this page."}
limit: {type: integer}
offset: {type: integer}
groups:
type: array
items: {$ref: '#/components/schemas/DuplicateGroup'}
DuplicateGroup:
type: object
additionalProperties: false
required: [title, artists, files, hashed, identical, suggested_keep_track_id, freed_bytes]
properties:
title: {type: string}
artists:
type: array
description: The main artists the copies share.
items: {$ref: '#/components/schemas/ArtistRef'}
files:
type: array
description: The copies, by track id; at least two.
items: {$ref: '#/components/schemas/DuplicateFile'}
hashed: {type: boolean, description: "Every file of the group has been read by the check."}
identical: {type: boolean, description: "Hashed, and byte for byte the same."}
suggested_keep_track_id: {type: integer, format: int64, description: "The copy Sonda would keep: without loss first, then the higher bitrate, then the bigger file, then the oldest."}
freed_bytes: {type: integer, format: int64, description: "The size of every copy but the one to keep."}
DuplicateFile:
type: object
additionalProperties: false
required: [track_id, album, format, bitrate, size_bytes, duration_ms, hashed]
properties:
track_id: {type: integer, format: int64}
album:
type: object
nullable: true
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
format: {type: string, description: "`mp3`, `flac`..."}
bitrate: {type: integer, description: "0 when unknown."}
size_bytes: {type: integer, format: int64}
duration_ms: {type: integer, format: int64}
hashed: {type: boolean, description: "This file has been read by the check."}
CleanDuplicates:
type: object
additionalProperties: false
required: [keep_track_id, remove_track_ids]
properties:
keep_track_id: {type: integer, format: int64, minimum: 1, description: "The copy that stays."}
remove_track_ids:
type: array
minItems: 1
maxItems: 100
description: "The copies to delete, of the same song as the one that stays, none twice."
items: {type: integer, format: int64, minimum: 1}
DuplicatesCleaned:
type: object
additionalProperties: false
required: [removed, freed_bytes]
properties:
removed: {type: integer, description: "Files deleted."}
freed_bytes: {type: integer, format: int64}
DuplicatesCheckStatus:
type: object
additionalProperties: false
required: [running]
properties:
running: {type: boolean}
started_at: {type: string, format: date-time, description: "When the last check started."}
last_finished_at: {type: string, format: date-time}
progress:
type: object
description: Only while the check runs.
additionalProperties: false
required: [done, total]
properties:
done: {type: integer}
total: {type: integer, description: "Files the check set out to read."}
last:
type: object
description: How the last finished check ended.
additionalProperties: false
required: [checked, hashed, skipped, failed, stopped]
properties:
checked: {type: integer, description: "Files looked at."}
hashed: {type: integer, description: "Files read and fingerprinted."}
skipped: {type: integer, description: "Files that changed since the scan, or are gone."}
failed: {type: integer, description: "Files that could not be read just then."}
stopped: {type: boolean, description: "It was stopped, or the application was."}
last_error: {type: string, description: "Why the last check ended before the end, for example that the disk is not mounted."}
UserSettings:
type: object
additionalProperties: false
required: [discover_from_listening]
properties:
discover_from_listening:
type: boolean
description: |
When true, Discover may start from the artists you listen to most. That sends their
names to Last.fm, which is asked for artists similar to each one (only when an admin
switched Last.fm on). When false, Discover starts only from artists you name yourself.
False until you turn it on. What Last.fm answers is stored like any other lookup and is
shared: another user can see from `retrieved_at` in `GET /artists/{id}/similar` that
somebody looked an artist up, but not who.
UpdateUserSettings:
type: object
additionalProperties: false
properties:
discover_from_listening: {type: boolean, nullable: true}
TasteArtist:
type: object
additionalProperties: false
required: [id, name, preference, listens, last_listened_at]
properties:
id: {type: integer, format: int64}
name: {type: string}
preference: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 1, description: How much you like the artist. Only artists above 0 are listed.}
listens: {type: integer, description: "Events that count as a listen, with no decay, within the period that is read (ten half-lives)."}
last_listened_at: {type: string, format: date-time, description: The most recent listen that counted.}
TasteTag:
type: object
additionalProperties: false
required: [tag, weight]
properties:
tag: {type: string, description: Lower case.}
weight: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 1, description: "How much the tag matters to you; the best one is 1."}
ListenPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/ListenItem'}
total: {type: integer, description: "Size of the whole result, not of this page."}
limit: {type: integer}
offset: {type: integer}
Federation:
type: object
additionalProperties: false
required: [enabled, name, address, key_id, sends, max_streams, max_kib_per_sec, friends]
properties:
enabled: {type: boolean, description: Whether this server may pair with others. Off by default.}
name: {type: string, description: How friends see this server.}
address: {type: string, description: Where friends reach this server; empty until set.}
key_id: {type: string, description: "Names this server's key; empty until federation was first turned on. Compare it with the one the other admin sees."}
sends: {type: string, description: "What a friend's server is sent, and what it never learns."}
max_streams: {type: integer, minimum: 1, maximum: 20, description: Streams one friend may have open at a time.}
max_kib_per_sec: {type: integer, minimum: 0, maximum: 102400, description: "KiB a second one friend may take over all its streams; 0 means no limit. Otherwise at least 64."}
friends:
type: array
items: {$ref: '#/components/schemas/FederationFriend'}
FederationUpdate:
type: object
additionalProperties: false
anyOf:
- required: [enabled]
- required: [name]
- required: [address]
- required: [max_streams]
- required: [max_kib_per_sec]
properties:
enabled: {type: boolean}
max_streams: {type: integer}
max_kib_per_sec: {type: integer}
name: {type: string, maxLength: 240, description: "At most 60 characters, no control characters. Empty goes back to the host name."}
address: {type: string, maxLength: 300}
FederationRequest:
type: object
additionalProperties: false
required: [at, friend_id, friend, route, status, bytes]
properties:
at: {type: string, format: date-time}
friend_id: {type: integer}
friend: {type: string, description: The name of the friend.}
route: {type: string, description: "The route pattern, like `/api/v1/peer/tracks/:id/stream`. Never the query."}
status: {type: integer}
bytes: {type: integer, format: int64, description: Bytes of the answer.}
Peaks:
type: object
additionalProperties: false
required: [count, peaks]
properties:
count: {type: integer, description: How many levels there are (120).}
peaks:
type: array
items: {type: integer, minimum: 0, maximum: 255}
description: From the start of the track to its end.
FriendRef:
type: object
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64, description: Names the friend in the routes under `/friends`.}
name: {type: string}
PeerInfo:
type: object
additionalProperties: false
required: [name, shared_libraries]
properties:
name: {type: string}
shared_libraries: {type: integer, description: How many libraries are shared with friends.}
FederationInvite:
type: object
additionalProperties: false
required: [invite, expires_at]
properties:
invite: {type: string, description: One piece of text to give to the other admin. Starts with `sonda1.`.}
expires_at: {type: string, format: date-time}
FederationUseInvite:
type: object
additionalProperties: false
required: [invite]
properties:
invite: {type: string, maxLength: 1000}
FederationFriend:
type: object
additionalProperties: false
required: [id, name, address, key_id, state, created_at, approved_at]
properties:
id: {type: integer}
name: {type: string}
address: {type: string}
key_id: {type: string, description: Names the friend's key.}
state:
type: string
enum: [incoming, outgoing, active]
description: |
`incoming`: it used an invite of this server and waits for approval here. `outgoing`: this server used its invite
and waits for it. `active`: both agreed.
created_at: {type: string, format: date-time}
approved_at: {type: string, format: date-time, nullable: true}
PeerPairRequest:
type: object
additionalProperties: false
required: [code, name, address, public_key]
properties:
code: {type: string, maxLength: 64}
name: {type: string, maxLength: 240}
address: {type: string, maxLength: 300}
public_key: {type: string, description: "The Ed25519 public key, 32 bytes, base64url without padding."}
PeerPairReply:
type: object
additionalProperties: false
required: [name, address, public_key]
properties:
name: {type: string}
address: {type: string}
public_key: {type: string, description: "The Ed25519 public key, 32 bytes, base64url without padding."}