3411 lines
144 KiB
YAML
3411 lines
144 KiB
YAML
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: 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.
|
||
|
||
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'}
|
||
|
||
/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'}
|
||
|
||
/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}/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/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]}
|
||
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]}
|
||
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]}
|
||
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'}
|
||
|
||
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` and `/artists/{id}/image`.
|
||
|
||
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}
|
||
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:
|
||
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'}
|
||
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, created_at]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
path: {type: string, description: Absolute directory on the server.}
|
||
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]
|
||
properties:
|
||
name: {type: string, minLength: 1, maxLength: 100}
|
||
path: {type: string}
|
||
|
||
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]}
|
||
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'}
|
||
|
||
Playlist:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, name, description, track_count, duration_ms, created_at, updated_at]
|
||
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."}
|
||
|
||
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}
|