- A search key apart from the key that identifies artists, albums and tracks: lower case, accents taken off (Latin, Greek and Cyrillic marks only, so kana and Hangul stay intact), and letters like ß, æ, ø, ł written plain. - GET /artists, /albums and /tracks look in it, so "bjork" finds "Björk" and "strasse" finds "Straße". - "Beyoncé" and "Beyonce" stay two artists: the identity key keeps accents. - Migration 0016 adds the column on SQLite and PostgreSQL; RefreshMatchKeys fills it for existing rows at start. - golang.org/x/text is now a direct dependency.
2638 lines
109 KiB
YAML
2638 lines
109 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/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/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 (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 (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'}
|
||
'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), 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- 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'}
|
||
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."}
|
||
|
||
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."}
|
||
|
||
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}
|