- The scan reads the MusicBrainz release group id of an album from the tags of its
files (MUSICBRAINZ_RELEASEGROUPID, a vorbis comment or an ID3 frame) and stores it in
albums.mbid: it is taken only when the file has an album and exactly one valid id, an
album keeps the one it has, and an id that another album owns is not given twice. A full
rescan reads it for music that was already indexed.
- New provider "coverartarchive" (off by default, no key, contact in the User-Agent). When
an album has no picture in the user's own files, which always come first, its cover is
asked from the archive by that id and never by a title: only the id leaves the server.
The same GET /albums/{id}/cover; the record keeps the source. An outage is a 502
provider_unavailable and is not remembered, and an older cover is served in its place.
- The archive answers with three redirects (coverartarchive.org, archive.org, a data node
whose name changes). The outbound client can now follow redirects, but only the ones the
caller allows, up to a limit; here that is https on archive.org and its subdomains.
- A purge counter now guards the covers too: a read that started before the provider's data
was taken back is not kept. Removing the provider's data forgets the covers that came from
it and deletes their files, and leaves the ones from the user's files.
- Spec, contract and HTTP tests, README updated; the facts of the real archive are written down.
Closes #43
2331 lines
94 KiB
YAML
2331 lines
94 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: 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 username is taken (`username_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 username 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 username is taken (`username_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/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.
|
||
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'}
|
||
|
||
/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'}
|
||
|
||
/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}/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. 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 (never by title; a
|
||
full rescan reads that tag again for music indexed before); only that id leaves the server.
|
||
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'}
|
||
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."}
|
||
|
||
/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), 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/{name}:
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
required: true
|
||
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia, commons, coverartarchive]}
|
||
put:
|
||
tags: [Providers]
|
||
operationId: updateProvider
|
||
summary: Set up a provider
|
||
description: |
|
||
Admin only. Send any of `enabled`, `api_key` and `contact`; 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]}
|
||
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]}
|
||
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-insensitive substring of the name or title. Accented letters are matched ignoring
|
||
case (`BJÖRK` finds `Björk`), but accents are kept (`bjork` does not). 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'}
|
||
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: [username, password]
|
||
properties:
|
||
username:
|
||
type: string
|
||
minLength: 3
|
||
maxLength: 64
|
||
pattern: '^[A-Za-z0-9._-]+$'
|
||
password:
|
||
type: string
|
||
format: password
|
||
description: 8 to 256 bytes (UTF-8).
|
||
|
||
LoginRequest:
|
||
type: object
|
||
required: [username, password]
|
||
properties:
|
||
username: {type: string}
|
||
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, username, is_admin]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
username: {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, has_api_key, contact, sends, notes, updated_at]
|
||
properties:
|
||
name: {type: string, enum: [lastfm, musicbrainz, wikipedia, commons, coverartarchive]}
|
||
enabled: {type: boolean, description: Whether Sonda may contact this provider.}
|
||
needs_api_key: {type: boolean}
|
||
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.}
|
||
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.
|
||
|
||
ProviderUpdate:
|
||
type: object
|
||
anyOf:
|
||
- required: [enabled]
|
||
- required: [api_key]
|
||
- required: [contact]
|
||
properties:
|
||
enabled: {type: boolean}
|
||
api_key:
|
||
type: string
|
||
format: password
|
||
description: A Last.fm key is 32 hexadecimal characters. Empty clears it.
|
||
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, key_refused, rate_limited, unreachable, error]
|
||
description: |
|
||
`no_api_key`: none is stored, 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'}
|
||
|
||
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."}
|
||
|
||
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}
|